Deployments

Using the Runtime API, you can automate deployments between Runtime instances.

Configuring For Automated Deployments

If you haven't already, read the Architecture & Requirements article first to familiarize yourself with Images and how they work in Sanbox.

For deploying images directly in Lumisan Sanbox Designer, visit the Runtime Connections article.

Automating deployments between Runtime instances for your CI/CD process is easy with the Runtime API - an internal RESTful API in the Sanbox Runtime. The Runtime API exposes methods to download the image on a Runtime, upload and deploy an image file, and push an image from one Runtime to another. In order to use the system, you must make the following config changes.

1. Update Image config section.

Set AllowDeployments to true

"Image": {
"ImageFilePath": "runtimeImage.sbimg",
"DoBackups": false,
"BackupFrequency": "@midnight",
"BackupRetentionCount": 10,
"BackupDirectory": "RuntimeBackups",
"AllowDeployments": true
}

2. Update RuntimeAPI config section.

  • Set Enabled to true

  • Set APIKey to a unguessable random string at least 36 characters long. This is the API Key to be used to authenticate requests to the Runtime API. We recommend maybe using an online API key generator tool to create your key.

"RuntimeAPI": {
"Enabled": false,
"APIKey": "RANDOM STRING HERE"
}

For your security, please do not copy and paste the example configuration.

Using Runtime API For Automated Deployments

The Runtime API uses the same web server configuration settings under the HttpWebServer config section with the exception of GlobalHeaders.

You must authenticate with the Runtime API by using either basic or bearer authentication with the configured API Key.

  • For basic authentication use key for the user name and your API Key as the password.

  • For bearer authentication use your API Key as the bearer token. Example header: Authorization: bearer myapikey

For added security against potential replay attacks, you can add a header to your request named Date with value set to a utc date time string of today's date/time. This date/time can be formatted in ISO format. If the Date header is present, the Runtime will validate it against the current date time with a 5 minute skew. This feature remains optional because many tools cannot produce this header dynamically.

Even though Sanbox does not force you to use HTTPS when using the Runtime API, it is strongly recommended that you use HTTPS unless the trouble of procuring a certificate outweigh the risks. E.g. - your Runtime is internal and traffic doesn't go through the internet.

When not using HTTPS your API Key is transferred in plain or base64 text, creating an attack vector for potential middle-man hackers.

For the following examples - example.org is used. Change example.org to the address of your Runtime.

get
Retrieve Image

https://example.org/runtime/image
Retrieves the current image. This responds with the current image file.
Request
Response
Request
Headers
Authorization
required
string
See above on authentication
Date
optional
string
Today's date expressed as UTC
Response
200: OK
Serves the current Runtime image as a file
-- IMAGE FILE --
401: Unauthorized
Returned when the request is not authorized because of incorrect authentication on the request
Error message as string
404: Not Found
Returned when RuntimeAPI.Enabled is false
-- NO BODY --
500: Internal Server Error
Returned when an error occurred, returns what went wrong as a string
Error message as string
503: Service Unavailable
Returned when Image.AllowDeployments is false
Error message as string

post
Deploy Image

https://example.org/runtime/image
Deploys an image file to the Runtime. When the deploy is completed, the Runtime restarts immediately. You can attach the image file to the request as a form file upload, or send the image directly in the request body.
Request
Response
Request
Headers
Authorization
required
string
See above on authentication
Date
optional
string
Today's date expressed as UTC
Form Data Parameters
Image
required
object
The image file.
Response
202: Accepted
Returned when the deployment of the image is staged. The Runtime will restart immediately after this response is sent with the new image loaded.
-- NO BODY --
401: Unauthorized
Returned when the request is not authorized because of incorrect authentication on the request.
Error message as string
404: Not Found
Returned when RuntimeAPI.Enabled is false
-- NO BODY --
500: Internal Server Error
Returned when an error occurred, returns what went wrong as a string
Error message as string
503: Service Unavailable
Returned when Image.AllowDeployments is false
Error message as string

put
Push Image

https://example.org/runtime/image
Deploys the image from the current Runtime to a target Runtime. Takes a JSON object as a request body.
Request
Response
Request
Headers
Authorization
required
string
See above on authentication
Date
optional
string
Today's date expressed as UTC
Body Parameters
targetAPIKey
required
string
Runtime API Key for the target Runtime
targetUrl
required
string
URL of Runtime to push image to
Response
202: Accepted
Returned when the image has been pushed to the target Runtime. The target Runtime will restart immediately with the new image.
-- NO BODY --
401: Unauthorized
Returned when the request is not authorized because of incorrect authentication on the request.
-- NO BODY --
404: Not Found
Returned when RuntimeAPI.Enabled is false
-- NO BODY --
500: Internal Server Error
Returned when an error occurred, returns what went wrong as a string.
-- NO BODY --
503: Service Unavailable
Returned when Image.AllowDeployments is false
-- NO BODY --

Example Push Request Body

{
"targetUrl": "https://192.168.1.45",
"targetAPIKey": "49d9f5b0-4f46-44ea-ae40-e11c94b06167",
}