Accessing a Secret in a Capsule

Attaching a Secret to a Capsule

1. Click on environment to display the Environment editor in a Capsule.

2. Scroll down to see the Secrets section.

3. Click on + Attach secret to capsule, and a drop-down menu that contains the secret list from your account settings page will appear.

4. Select the secret(s) you want to attach.

If there are no secrets configured on your account page, the + Attach secret to Capsule button will be disabled with a reminder message below. To attach the secret, you must set up your secret in the account settings page first.

Automated Implementation of AWS Credentials in Capsules

When accessing an external Data Asset created from a private S3 bucket during a Capsule run, Code Ocean will automatically check the user's Secrets or Assumable Roles and use the appropriate credentials. This also works if there are multiple Data Assets attached to the Capsule that each require different credentials -- Code Ocean will automatically use all appropriate credentials/roles that have been configured for the user allowing them to access the Data Assets.

Edit the Title of the Attached Secret

After you selected the secret, you can verify the secret type and the secret's title in the drop-down menu and the secret's title above it. The secret's title is the same as its name by default. To edit the title, click on the pencil icon.

When sharing a Capsule with other users, the secret's title should help them to easily identify and pick the right secret to use in the Capsule.

Using a Secret as an Environment Variable

After attaching a secret in the environment editor, the system will save the secret as environment variables and save only the variable names in the environment.yml file.

Understand the environment.yml

The system will generate the environment.yml automatically when you attach secrets in the Capsule.

The content depends on the secret's type and is associated with the required field during set up.

• type: there are four types, corresponding to the four types of secrets.

• id: a random alphanumeric string.

• description: the secret's title for identification on the environment page.

• specific fields: depend on the secret's type.

Here are example screenshots of each type of secret:

AWS

Database

API

Custom Key

The specific fields are all in upper case with an underscore in between. These are the environment variables that can be referred to in the script.

If you attach a few secrets of the same type, a number will be added to the specific fields of the same secret type to differentiate them.

Here is an example of two custom keys:

If your application requires specific variable names for your secrets, they can be edited in the environment.yml file, which will change the names to which the secrets are copied over from the default names.

Use a Secret in the Script

After you attach the secret in the Capsule, the system will save the encrypted secrets in the database. When you run the Capsule, the secret will be set as environment variables in the computation. To visualize this, you can print out your secret in the script by retrieving the environment variable.

Different programming languages have different commands to retrieve the environment variable. Below are examples for calling a custom key in Bash (run script), Python, and R. In this example, we added a custom secret to the capsule. The value is demo, and it is saved in the CUSTOM_KEY environment variable.

Bash (run script)

In Bash, use ${VAR} to retrieve the specific variable ({VAR} is the variable name).

Python

In Python, use the getenv function in os module to get the environment variable.

R

In R, use Sys.getenv('VAR') to get the environment variable.

You can access a secret as an environment variable from a Cloud Workstation as well.

Printing out secrets is not usually a good practice. The code in this section is for demonstration purposes. If you use the print command to verify the accessibility of the attached secret. Remember to remove the print command.

Use a Secret during the Build Time

User Secrets (AWS Cloud Credentials, Database Credentials, API Credentials, and Custom Keys) are available during environment builds with the values accessible in the Dockerfile and postInstall under their typical environment variable names.

Note: To make secrets available at build time, make sure to commit changes in your capsule before attaching the secrets.