ocis/tests/ociswrapper/README.md

oCIS Wrapper

A tool that wraps the oCIS binary and provides a way to re-configure the running oCIS instance.

When run, ociswrapper starts an API server that exposes some endpoints to re-configure the oCIS server.

Usage

1. Build

   make build
   

2. Run

   ./bin/ociswrapper serve --bin=<path-to-ocis-binary>
   

   To check other available options:

   ./bin/ociswrapper serve --help
   

    --url string              oCIS server url (default "https://localhost:9200")
    --retry string            Number of retries to start oCIS server (default "5")
    -p, --port string         Wrapper API server port (default "5200")
    --admin-username string   admin username for oCIS server
    --admin-password string   admin password for oCIS server
   

Access the API server at http://localhost:5200.

Also, see ./bin/ociswrapper help for more information.

API

ociswrapper exposes two endpoints:

1. PUT /config

   Updates the configuration of the running oCIS instance. Body of the request should be a JSON object with the following structure:

   {
     "ENV_KEY1": "value1",
     "ENV_KEY2": "value2"
   }
   

   Returns:

   • 200 OK - oCIS is successfully reconfigured
   • 400 Bad Request - request body is not a valid JSON object
   • 500 Internal Server Error - oCIS server is not running

2. DELETE /rollback

   Rolls back the configuration to the starting point.

   Returns:

   • 200 OK - rollback is successful
   • 500 Internal Server Error - oCIS server is not running

3. POST /command

   Executes the provided command on the oCIS server. The body of the request should be a JSON object with the following structure:

   {
     "command": "<ocis-command>", # without the ocis binary. e.g. "list"
   }
   

   If the command requires user input, the body of the request should be a JSON object with the following structure:

   {
     "command": "<ocis-command>",
     "inputs": ["value1"]
   }
   

   Returns:

   {
     "status": "OK",
     "exitCode": 0,
     "message": "<command output>"
   }
   OR
   {
     "status": "ERROR",
     "exitCode": <error-exit-code>,
     "message": "<command output>"
   }
   

   • 200 OK - command is successfully executed
   • 400 Bad Request - request body is not a valid JSON object
   • 500 Internal Server Error

4. POST /start

   Starts the oCIS server.

   Returns:

   • 200 OK - oCIS server is started
   • 409 Conflict - oCIS server is already running
   • 500 Internal Server Error - Unable to start oCIS server

5. POST /stop

   Stops the oCIS server.

   Returns:

   • 200 OK - oCIS server is stopped
   • 500 Internal Server Error - Unable to stop oCIS server

6. POST /services/{service-name}

   Restart oCIS instances without specified service and start that service independently (not covered by the oCIS supervisor).

   Body of the request should be a JSON object with the following structure:

   {
     "ENV_KEY1": "value1",
     "ENV_KEY2": "value2"
   }
   

   ⚠️ Note:

   You need to set the proper addresses to access the service from other steps in the CI pipeline.

   {SERVICE-NAME}_DEBUG_ADDR=0.0.0.0:{DEBUG_PORT}

   {SERVICE-NAME}_HTTP_ADDR=0.0.0.0:{HTTP_PORT}

   Returns:

   • 200 OK - oCIS service started successfully
   • 400 Bad Request - request body is not a valid JSON object
   • 500 Internal Server Error - Failed to start oCIS service audit

7. DELETE /services/{service-name}

   Stop individually running oCIS service

   Returns:

   • 200 OK - oCIS service stopped successfully
   • 500 Internal Server Error - Unable to stop oCIS service

8. PATCH /services/{service-name}

   Updates the configuration of the running service instance. Body of the request should be a JSON object with the following structure:

   {
     "ENV_KEY1": "value1",
     "ENV_KEY2": "value2"
   }
   

   Returns:

   • 200 OK - service is successfully reconfigured
   • 500 Internal Server Error - service is not running

9. DELETE /services/rollback

   Stop and rollback all service configurations to the starting point.

   Returns:

   • 200 OK - rollback is successful
   • 500 Internal Server Error - oCIS server is not running