Skip to content

Commit d42bce7

Browse files
jautorjautor
authored
Merge pull request #108 from DMTF/readme
Reference Swordfish API Emulator
2 parents 2f1b340 + 50c0ca7 commit d42bce7

1 file changed

Lines changed: 130 additions & 47 deletions

File tree

‎README.md‎

Lines changed: 130 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright 2016-2019 DMTF. All rights reserved.
1+
Copyright 2016-2022 DMTF. All rights reserved.
22

33
# Redfish Interface Emulator
44

@@ -10,30 +10,52 @@ Dynamic emulator is accomplished by creating the Python files. The code for an
1010

1111
The Swordfish model has been emulate using this emulator. The repository is available at [Swordfish API Emulator](https://github.com/SNIA/Swordfish-API-Emulator). The repository provides a good example of the Python files for dynamic resources.
1212

13-
The emulator is structure so it can be hosted on a standalone system or multiple instances in a Cloud Foundry. Note: the cloud foundry method has be successful within a company internal cloud foundry service. It has not be attempted on a public cloud foundry service.
13+
The program has been verified on 3.5.2 and 3.9.1. Use the packet sets to install the correct packages.
1414

15-
This program is a python35 program. The program has been verified on 3.5.2.
15+
The emulator is structure so it can be ran locally, in a Cloud Foundry, or as a Docker file.
1616

17-
## Installation
17+
## Execute Locally
1818

19-
Before the emulator can be executed locally, specific Python packages need to be installed.
19+
When executing the Emulator locally, the Redfish service appears at port 5000, by default. The Redfish client uses the following URL to access the emulator Redfish server - http://localhost:5000. To run a second instance must a different 'port'. The port number can be changed via the command line parameters or the config.json file.
2020

21-
### Local Standalone
21+
### Package Installation
2222

23-
The required python packages for a local environment are listed in the file **./packageSets/Env-Local-Python3.5.2_requirements.txt**. The file lists the Python package and revision.
23+
The required python packages are listed in the files in the **./packageSets** directory.
2424

2525
The 'pip' command can be used to install the environment.
2626

2727
pip install -r [packageSet]
2828

29-
The 'pip freeze' command can be used to display the installed packages and their revision.
29+
If you are able to execute this emulator on later versions of Python, please issue the 'pip freeze' command. Then place the output into a Github issue. We can add the package set to this repository.
3030

31-
### Cloud
31+
### Invocation
32+
33+
Edit the emulator-config.json file and set **"MODE": "Local"**, then start the emulator.
34+
35+
python emulator.py
36+
37+
## Execute on a Cloud Foundry
38+
39+
The cloud foundry method has be successful within a company internal cloud foundry service. It has not be attempted on a public cloud foundry service.
40+
41+
### Package Installation
3242

3343
The required python packages for a Cloud Foundry environment are listed in the file **./requirements.txt**. The file lists the Python package, without the revision.
3444
The packages will be installed automatically during invocation.
3545

36-
### Docker
46+
The cloud foundry makes use of the following files: requirements.txt, runtime.txt, and Profile. So they should exists in the same directory as emulator.py.
47+
48+
### Invocation
49+
50+
Edit the emulator-config.json file and set **"MODE": "Cloud"**, then push the emulator to the foundry.
51+
52+
cf push [foundry-app-name]
53+
54+
The **foundry-app-name** determines the URL for the Redfish service.
55+
56+
## Execute via Docker
57+
58+
### Installation
3759

3860
Use one of these actions to pull or build the container:
3961

@@ -53,25 +75,7 @@ Use one of these actions to pull or build the container:
5375
docker build -t dmtf/redfish-interface-emulator:latest https://github.com/DMTF/Redfish-Interface-Emulator.git
5476
```
5577

56-
## Invocation
57-
58-
### Standalone
59-
60-
Edit the emulator-config.json file and set **"MODE": "Local"**, then start the emulator.
61-
62-
python emulator.py
63-
64-
### Cloud Foundry
65-
66-
Edit the emulator-config.json file and set **"MODE": "Cloud"**, then push the emulator to the foundry.
67-
68-
cf push [foundry-app-name]
69-
70-
The **foundry-app-name** determines the URL for the Redfish service.
71-
72-
The cloud foundry makes use of the following files: requirements.txt, runtime.txt, and Profile. So they should exists in the same directory as emulator.py.
73-
74-
### Docker
78+
### Invocation
7579

7680
This command runs the container with the built-in mockup:
7781

@@ -133,31 +137,33 @@ When HTTPS is enabled, the emulator looks for the files: **server.crt** and **se
133137

134138
## Static emulation of a mockup
135139

136-
The emulator can be used to support mockups, statically. The means on HTTP GETs will work. This can be done by just copying the mockup hierarchy to the ./static folder.
140+
The emulator can be used to support static mockups. In a static mock, only HTTP GETs will work. Other Redfish simulators support static mockups.
137141

138-
The static mockup is found in the directory ./api_emulator/redfish/static. The emulator comes with a sample Redfish mockup. This can be replaced with any mockup folder. The Redfish Forum has posted several of their mockups in [DSP2043](https://www.dmtf.org/sites/default/files/DSP2043_1.2.0.zip).
142+
The static mockup is found in the directory ./api_emulator/redfish/static. The emulator comes with a sample Redfish mockup already in the directory. This can be replaced with any mockup folder hierarchy. The Redfish Forum has posted several of their mockups in [DSP2043](https://www.dmtf.org/sites/default/files/DSP2043_1.2.0.zip).
139143

140144
Note: If the new mockup has additional resources in the ServiceRoot, then modifications need to be made in static_resource_emulator.py to adds these new resources.
141145

142146
## Dynamic emulation
143-
The emulator was designed to support dynamic resources. This requires that Python code exists for each dynamic resource. Resources can be incremental recasted as dynamic, so one can straddle static vs dynamic emulation, with some resources static while others are dynamic.
147+
The emulator was designed to support dynamic resources. This requires that Python code exists for each dynamic resource. Resources which are static and dynamic can co-exist in an emulator. This means one can straddle static vs dynamic emulation, with some resources static while others are dynamic.
148+
149+
Dynamic resource implementations which have been implemented are provided in the Appendix.
144150

145-
The following outlines the overall process. More complete documentation is in a Word document in the ./doc directory. An example for the Chassis resource is included in the source code.
151+
The following outlines the overall process. More complete documentation is in a Word document in the ./doc directory. To expedite the creation of the API-file and template file, the code generators for both files are described.
146152

147-
1. Create an API file (e.g. Chassis\_api.py)
148-
* The file is placed in the ./api\_emulator/Redfish directory
149-
* The file contain the behavior of each HTTP command, of interest
150-
* The file contains the API for both the singleton resource and the collection resource (if collection exists)
151-
2. Create a template file (e.g. Chassis.py)
152-
* The file is placed in ./api\_emulator/Redfish/template directory
153-
* The file should contain the same properties as the mockup file for the resource
154-
3. Edit ./api\_emulator/resource\_emulator.py file
155-
* Comment out the line which loads the static mockup for the Chassis resource
156-
* Add the line to add the resource API defined in chassis_api.py
153+
### Manually creating a dynamic resource
154+
A dynamic resource is made by creating a template-file and an API-file for the resource.
157155

158-
To automate step #1 and #2, above, a code generator exists in the ./codegen directory.
156+
* The template-file contain the properties of the resource. The file is used when a new instance of the resource is created.
157+
* The API-file contain the behavior of the resource for each HTTP command. If there is an associated collection resource, the file also contains the behavior of the collection resource.
159158

160-
#### Auto-generate the API file
159+
Once the files are created, they are placed in the emulator directory structure.
160+
161+
* The template-file is placed in the directory ./api\_emulator/Redfish/template
162+
* The API-file is placed in the directory ./api\_emulator/Redfish
163+
* If the resource in the Service Root, the the emulator.py file needs to be edited.
164+
* If the dynamic resource replaces a static resource, then replace the line which loads the static mockup with the line to add to dynamic resource API.
165+
166+
### Auto-generate the API file
161167
To generate a API file, execute the following command
162168

163169
codegen_api [mockup] [outputdir]
@@ -172,7 +178,7 @@ The generated code supports the HTTP GET, PATCH, POST and DELETE commands
172178

173179
If the resource has subordinate resources that need to be instantiated when this resource is instantiated, that code will need to be manually added.
174180

175-
#### Auto-generate the template file
181+
### Auto-generate the template file
176182
To generate a template file, execute the following command
177183

178184
codegen_template [mockup] [outputdir]
@@ -187,7 +193,7 @@ Where
187193

188194
The codegen_template source file contains a dictionary with the names of Redfish collections and their corresponding wildcard. This dictionary needs to be manually updated to the keep in sync with Redfish modeling.
189195

190-
## Populating the dynamic emulator - INFRAGEN Module
196+
## Auto-populating the dynamic emulator
191197

192198
Once a resource is made dynamic, the emulator can either start up with no members in its collections or some initial set of members.
193199

@@ -308,3 +314,80 @@ sh release.sh <NewVersion>
308314
```
309315
310316
Enter the release notes when prompted; an empty line signifies no more notes to add.
317+
318+
# Appendix - Available Dynamic Resources implementations
319+
320+
The emulator is made dynamic by added python code to emulate a resources RESTful behavior, call the API-file.
321+
322+
Dynamic resources implementations can be found in the Redfish Interface Emulator repository and the SNIA API Emulator repository.
323+
324+
The repository also had the codegen_api code generator for creating an API-file for a resource with some default behaviors. The code generator takes a mockup file as input.
325+
326+
## Redfish Interface Emulator
327+
328+
The Redfish Interface Emulator comes with a small set of API-files to demonstrate the code structure. The repository also had the codegen_api code generator for creating an API-file for a resource with some default behaviors. The code generator takes a mockup file as input.
329+
330+
These dynamic resources are available in the [Redfish Interface Emulator repository](https://github.com/dmtf/Redfish-Interface-Emulator) in the api_emulator/redfish directory.
331+
332+
| Resource | API-file
333+
| :--- | :---
334+
| ./CompositionService | CompositionService_api.py
335+
| ./EventService | event_service.py
336+
| ./SessionService |
337+
| ./SessionService/Sessions/{id} | sessions_api.py
338+
| ./Chassis/{id} | Chassis_api.py
339+
| ./Chassis/{id}/Thermal | thermal_api.py
340+
| ./Chassis/{id}/Power | power_api.py
341+
| ./Systems/{id} | ComputerSystem_api.py
342+
| ./Systems/{id}/Memory | memory.py
343+
| ./Systems/{id}/Processors/{id} | processor.py
344+
| ./Systems/{id}/SimpleStorage/{id} | simple_storage.py
345+
| ./Managers/{id} | Manager_api.py
346+
347+
348+
## SNIA API Emulator
349+
350+
The Swordfish API Emulator added the API-files to emulate the Swordfish schema.
351+
352+
These dynamic resources are available in the [SNIA API Emulator repository](https://github.com/SNIA/Swordfish-API-Emulator) in the api_emulator/redfish directory.
353+
354+
| API-file | Resource
355+
| :--- | :---
356+
| . | serviceroot_api
357+
| ./EventService/Subscriptions | Subscriptions.py
358+
| ./Chassis/{id} | Chassis_api.py
359+
| ./Chassis/{id}/Memory | c_memory
360+
| ./Chassis/{id}/Drives/{id} | drives_api.py
361+
| ./Chassis/{id}/MediaController | MediaControllers_api.py
362+
| ./Chassis/{id}/MediaControllers/{id}/Ports| mc_ports_api.py
363+
| ./Chassis/{id}/NetworkAdapters | networkadapaters_api.py
364+
| ./Chassis/{id}/NetworkAdapters/{id}/NetworkDeviceFunctions/{id} | networkdevicefunctions_api.py
365+
| ./Chassis/{id}/NetworkAdapters/{id}/Ports/{id} | nwports_api\.py
366+
| ./Systems/{id} | ComputerSystem_api.py
367+
| ./Systems/{id}/Storage/{id}/Volumes/{id} | volumes_api
368+
| ./Systems/{id}/Storage/{id}/StoragePools/{id} | storagepools_api.py
369+
| ./Systems/{id}/Memory/{id} | memory.py
370+
| ./Systems/{id}/Memory/{id}/MemoryDomains/{id} | memory_domains_api.py
371+
| ./Systems/{id}/Memory/{id}/MemoryDomains/{id}/MemoryChunks/{id} | md_chunks_api.py
372+
| ./Fabrics/{id}/Connections/{id} | f_connections.py
373+
| ./Fabrics/{id}/EndpointGroups/{id} | f_endpointgroups.py
374+
| ./Fabrics/{id}/Endpoints/{id} | f_endpoints.py
375+
| ./Fabrics/{id}/Switches/{id} | f_switches.py
376+
| ./Fabrics/{id}/Switches/{id}/Ports/{id} | f_switch_ports_api.py
377+
| ./Fabrics/{id}/Zones/{id} | f_zones_api.py
378+
| ./Fabrics/{id}/FabricAdapters/{id} | fabricadapters.py
379+
| ./Fabrics/{id}/FabricAdapters/{id}/Ports/{id} | fa_ports_api.py
380+
| ./Storage | storage_api.py
381+
| ./Storage/{id}/Controllers/{id} | storagecontrollers_api
382+
| ./Storage/{id}/FileSystems | filesystems_api.py
383+
| ./Storage/{id}/StorageGroups | storagegroups_api.py
384+
| ./StorageSystems/{id} | storagesystems_api.py
385+
| ./StorageServices/{id}/ClassesOfService | classofservice_api.py
386+
| ./StorageServices/{id}/DataProtectionLoSCapabilities | dataprotectionloscapabilities_api.py
387+
| ./StorageServices/{id}/DataSecurityLoSCapabilities | datasecurityloscapabilities_api.py
388+
| ./StorageServices/{id}/DataStorageLoSCapabilities| datastorageloscapabilities_api.py
389+
| ./StorageServices/{id}/EndpointGroups | EndpointGroups_api.py
390+
| ./StorageServices/{id}/Endpoints | Endpoints_api.py
391+
| ./StorageServices/{id}/IOConnectivityLoSCapabilities | IOConnectivityLOSCapabilities_api.py
392+
| ./StorageServices/{id}/IOPerformanceLoSCapabilities | IOPerformanceLOSCapabilities_api.py
393+

0 commit comments

Comments
 (0)