Scoped Variables

Scoped variables provide a environment-level configurations for multiple containers simultaneously. They can be configured to provide environment variables, configuration files, or Internal API secrets.

Scoped variables are often used in conjunction with deployments, where a configuration needs to be retained between multiple running copies of an application.

Scoped Variable Sources

The value of a scoped variable can be set manually, or fetched from a remote source. When set manually, a plain-text value is set on the scoped variable and passed to the container via one of the available access methods.

Raw Sources

A 'raw' source is a scoped variable where the value is set manually and stored on the scoped variable.

Remote Sources

A scoped variable can be set dynamically from an external URL. The value will be fetched and set when the container starts. The endpoint must accept a GET request, and return a text response over HTTP(S), the value of which will be set as the value of the scoped variable.

Managing Secrets

Secrets are generally sensative information such as passwords, tokens, or keys. Often this sensitive information cannot be stored in a Dockerfile, stack file, or environment variable and should not be visible to everyone. Scoped variables fall under an environment's ACL, so visibility to other members on your team can be dictated through their role, and access to specific environments can be restricted.

However, when using scoped variables, the values are not encrypted (hence the term raw). It is up to the application to be able to decrypt encrypted values stored in scoped variables. That said, Cycle provides some helpful tools when dealing with sensitive data. Follow these guidelines for managing sensitive data:

1. If possible, use remote sources for your encrypted variables. Encrypting secrets remotely and sending them over HTTPS will provide additional security.
2. If using a raw source, pre-encrypt the variables and decode them on the application.
3. Utilize Internal API access for time-restricting secrets access within the container.
4. Utilize the local encrypt and decrypt options from within the portal.

Container Scope

Scoped variables can be restricted to specific containers, container identifiers, or applied globally to all containers within the environment. When utilizing deployments, it is recommended to use container identifiers to associate it with all containers sharing an identifier, preserving access to relevant containers between deployments.

Accessing Scoped Variables

Accessing scoped variables from within a container can be done several different ways, and can even be combined depending on need. Each method of accessing a scoped variable has certain strengths.

Environment Variable Access

Environment variables act as global variables within a container. This is the most ubiquitous way of storing configurations. Environment variables are limited to single line values and have no restriction on access from within the container.

echo $VARIABLE

File Access

Scoped variables can be injected as files within the container on start. The files can be found within the container at the following path by default:

/var/run/cycle/variables/<variable>

where <variable> is replaced with the filename set on the scoped variable file access property.

File-type scoped variables are stored in a read-only volume mounted at /var/run/cycle/variables within the container. If desired, this path can be changed on a per-scoped-variable basis. If the directories leading to the file do not exist on the container, they will be created.

Executable Files

Files that end in the .sh file extension will be set as executable in the filesystem when mounted.

Preserve Formatting

To preserve formatting, ensure the blob option is enabled for the scoped variable.

Decode Option

File-type scoped variables can be set to be automatically decoded from base64 when injected into the container. This saves the need to install base64 tooling into the container. Base64 may be necessary for certain types of data, i.e. binary data, to be correcly inserted into the container.

Internal API Access

The Internal API is a special API accessible via a unix socket mounted within the container. When access via Internal API is enabled, the process within the container can make a request over the socket to retrieve the variable.

Example:

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 return a JSON response similar to the following:

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

Time-Based Access

One of the advantages of using the Internal API for accessing scoped variables is the ability to limit the amount of time the variable can be requested. By setting a duration on the scoped variable Internal API access, the value will only be returned successfully during the specified duration after the container starts. This ensures that even in the case of malicious code execution within the container, secrets remain safe.

Set Up Scoped Variables on Cycle

See our dedicated, interface-specific documentation for setting up scoped variables on Cycle:

• Portal
• API