The SaladCloud Instance Metadata Service (IMDS) provides your container instances with data and operations that you can use to configure and manage your applications.

IMDS is a REST API available at the non-routable IPv4 address 169.254.169.254 on port 80. IMDS is only accessible from within a running container instance on SaladCloud, and the requests never leave the SaladCloud Node. HTTP clients in your container instances must bypass any web proxies when calling IMDS.

Access IMDS

To access IMDS, create a Container Group through the SaladCloud API or the SaladCloud Portal, open a terminal to a running container instance through the SaladCloud Portal, and use the following sample.

The /v1/status endpoint can be used to get the health statuses of the running container instance. Call the endpoint from the terminal using curl:

curl -s -H "Metadata: true" --noproxy "*" http://169.254.169.254/v1/status

You can learn more about this command and its arguments on the awesome https://explainshell.com website.

This returns the health statuses of the running container instance as a JSON string. This example response is pretty-printed for readability.

{
  "ready": true,
  "started": true
}

Other endpoints are provided to get an identity token for the running container instance and to reallocate the container instance to another SaladCloud Node. Refer to the IMDS API Reference for more details.

IMDS SDKs

We provide SDKs to facilitate IMDS integrations from your applications. We strongly encourage the use of the IMDS SDKs over custom HTTP client integrations whenever possible. Refer to the package READMEs for more details on installation and configuration.

The following samples demonstrate using the SDKs to get the health statuses of the running container instance.

Security and Authentication

IMDS is only accessible from within a running container instance on SaladCloud, and the requests never leave the Salad Node. IMDS requests sent to web proxies will fail, and you should explicitly configure your HTTP client to disable any web proxies (manually configured or automatically discovered).

To prevent unintended or unwanted redirection of requests, requests to IMDS must contain the custom header Metadata: true and must not contain any X-Forwarded-For, X-Forwarded-Host, or X-Forwarded-Proto headers. Any requests missing the custom header Metadata: true or containing the X-Forwarded-For, X-Forwarded-Host, or X-Forwarded-Proto headers are rejected with a 403 Forbidden response.