Environment Scoped Variables

Working with scoped variables in portal is done through the scoped variables page in environments.

To get there:

1. Click the Environments tab from the main, left-hand navigation.
2. Select the environment from the first column.
3. Select Scoped Variables from the horizontal navigation on the environment dashboard.

Scoped Variables List

Existing scoped variables will show up on the scoped variables table. If a value is marked secret it will be obfuscated and there will be a lock icon in the row.

Encrypted values will show a binary lock icon and require a password to decrypt.

Create and Update

The create wizard is accessed by using the Create Variable button at the bottom or the page.

Updating is done by clicking the icon at the end of the row for a given scoped variable entry.

Both the wizard and the update form are very similar and feature these fields.

General

In the general section the form containers information about the identifier, which most resembles an environment variable key, the source type, and the source. Something to note is the URL type will return the response body of a GET request to the url provided. This url must be using http(s).

URL types that fail to return will show empty strings as their source

Raw Source Options

There are 4 options next to the raw type's source value.

Scope

Scoped variables can be applied to all containers in an environment or specifically to a mutable list of containers or container identifiers.

The Global checkbox being checked signifies that every container in the environment should inherit the variable.

Selecting options from the Existing Containers dropdown will allow the user to associate the scoped variable with a single existing container.

The Container Identifiers form field allows for the user to enter container identifier(s) that may or may not match an existing container. This is really useful for associating a scoped variable with containers that will be part of deployments.

Example - Container Identifiers

A user has a deployment that always has three containers: api, worker, frontend. The api container needs access to a scoped variable, but future versions of that api container don't exist yet.

Using the container identifiers option, the user sets the scope to api because the container identifier for the api container is always api in this case. The future versions of the api container in the deployment will have access to the scoped variable because the container identifier scope setting has a match for the container identifier.

Access

The Access section of the form defines where the scoped variable should be accessible from.

If the Environment Variable checkbox is selected, the scoped variable will be accessible as a runtime environment variable.

echo $VARIABLE_IDENTIFIER

If the Internal API checkbox is selected, the scoped variable will be available through the Internal API endpoint.

curl --unix-socket /var/run/cycle/api/api.sock \
  http://internal.cycle/v1/environment/scoped-variables \
  -H "x-cycle-token: $CYCLE_API_TOKEN"

This will be returned as a data object in JSON holding all environment variables set to internal API for the given container.

{"data":{"INTERNAL_SCOPED_VAR":"VALUE"}}

If a duration value is set, the value will only be accessible for the first "duration" of the container instances runtime. Resets each stop/start cycle.

If the File checkbox is selected, the scoped variable will be available through a file at the following endpoint.

/var/run/cycle/variables/<myVariable>

This is facilitated by mounting a read only volume to /var/run/cycle/variables in the container instance. This volume is only updated upon restart of the container.

With the Path option, the file will be mounted to the path given in the path. The full path, including the name for the file is required. If the directories leading to the file do not exist on the container they will be created.

The Decode checkbox will automatically decode a based64 encoded file on read.

Any, all, or some of the checkboxes in the access section can be selected for a given scoped variable. If all boxes are selected, for example, a user can use any of the access methods to retrieve the value.