Working with environment variables

Learn how to work with environment variables (env variables) in Code Engine. You can set environment variables as key-value pairs that can be used by your application, job, or function.

Creating and updating environment variables

Create and manage environment variables with Code Engine.

You can define environment variables as literal values or you can reference an existing secret or configmap. Code Engine uses environment variables to enable secrets or configmaps to be used by your job, application, or function.

Creating environment variables from the console

Create and update environment variables with the Code Engine console.

You can define environment variables when you create or update your app, job, or function from the console.

Before you begin

You must create your project and the project must be in active status.
Determine whether you want to create a literal environment variable or create an environment variable that references an existing secret or configmap. If you want your environment variable to fully reference an existing secret or configmap or reference individual keys in an existing secret or configmap, the secret or configmap must exist. See create a secret or create a configmap to define your secret or configmap before proceeding.

To open the dialog to define your environment variable on the Add environment variable page, complete one of the following choices.
- If you are creating an app, from the Create application page, expand the Environment variables (optional) section. You can add one or more environment variables to the app that you are creating. Click Add to open the Add environment variable page.
- If you are creating a job, from the Create job page, expand the Environment variables (optional) section. Click Add to open the Add environment variable page.
- If you are creating a function, from the Create function page, expand the Environment variables (optional) section. Click Add to open the Add environment variable page.
- If you are updating an existing workload to add environment variables, go to the existing app, job, or function. From the Configuration tab, click Environment variables. For apps, jobs and functions, click Add environment variable to open the Add environment variable page.
From the Add environment variable page, create an environment variable in one of the following ways,
- To create a literal environment variable, choose Literal value, specify the name for the literal environment variable, and provide a value. Notice that the Resulting definition section displays the name of the environment variable and its value.
- To create an environment variable that fully references a configmap, choose Reference full configmap, and then select the existing configmap. For this case, all keys of the selected configmap are referenced as part of the environment variable. Notice that the Resulting definition section displays the name of the keys in the configmap, but does not display the actual values of the keys that are referenced within the configmap.
- To create an environment variable that references an individual key of a defined configmap, choose Reference key in configmap, select the existing configmap that you want, and then select the key to reference as part of the environment variable. After you select the individual key in the configmap that you want to reference, notice that the Resulting definition section displays the name of the selected key in the configmap, but does not display the actual value of the key that is referenced within the configmap.
- To create an environment variable that fully references a secret, choose Reference full secret, and then select the existing secret. For this case, all keys of the selected secret are referenced as part of the environment variable. Notice that the Resulting definition section displays the name of the keys in the secret, but does not display the actual values of the keys that are referenced within the secret.
- To create an environment variable that references an individual key of a defined secret, choose Reference key in secret, select the existing secret that you want, and then select the key to reference as part of the environment variable. After you select the individual key in the secret that you want to reference, notice that the Resulting definition section displays the name of the selected key in the secret, but does not display the actual value of the key that is referenced within the secret.
From the console, you can reference only one individual key of a defined configmap or secret per environment variable. If you need to reference more than one key of a configmap or secret, then repeat the steps to define another environment variable that references a different key.
Click Done to save your changes. This action adds your environment variable to the table on the Environment variables tab. To continue adding environment variables, click Add.
Complete the create or update for your app, job, or function with the defined environment variable.
- If you are creating a workload, when you click Create, the app, job, or function is deployed with your environment variables.
- If you are updating an existing app, job, or function to add an environment variable, click Save and deploy to update the app or click Save to update your job or function with the new environment variables.
When your app, job, or function is in Ready state, it is updated with your environment variables.

The following table describes information about your environment variables.

Table of environment variables
Heading	Description
`Name`	The name of your environment variable.
`Defined by`	Specifies whether the environment variable is of type `literal`, or whether the environment variable is a fully referenced configmap or secret, or whether specific keys of a secret or configmap are referenced.
`Value or reference`	Displays the literal value, the fully referenced configmap or secret, or the referenced keys of a configmap or secret.

For example, let's create an app and set environment variables for the app.

Create an app that is named myapp, which uses the icr.io/codeengine/codeengine image. This hello-world app includes the TARGET environment variable, and the app prints Hello ${TARGET} from Code Engine and prints a listing of environment variables. If the TARGETenvironment variable is empty, Hello World from Code Engine is returned.
Go to this app in the console.
When the app is in Ready state, you can test your app. Click Test application and then click Send request in the Test application pane. To open the application in a web page, click Application URL. The myapp app returns a Hello World from Code Engine response and prints the environment variables that are included in this app.
Click the Environment variables tab.
Create the following environment variables.
- Click Add to open the Add environment variable page and create a literal environment variable. For example, create a literal environment variable with the name literalenvvar and with the value of This is my literal. Click Done to save your changes.
- Click Add to open the Add environment variable page and create an environment variable that fully references a configmap. Before you can reference a configmap, it must exist. For this example, a configmap with the name mycolorconfigmap exists and contains the following key-value pairs: key1=blue, key2=green, and key3=yellow. Create an environment variable that fully references the mycolorconfigmap configmap, including all its key-value pairs. Notice that the Resulting definition section displays the name of the keys in the configmap, but does not display the actual values of the keys that are referenced within the configmap. Click Done to save your changes.
- Click Add to open the Add environment variable page and create another environment variable that references an individual key of a defined secret. Before you can reference a secret, it must exist. For this example, a secret with the name mynewsecret exists and contains the following key-value pairs: newsec1=mynewsecret1, newsec2=mynewsecret2, and newsec3=mynewsecret3. Create an environment variable that references the newsec2 key of the mynewsecret secret. Notice the Resulting definition section displays the name of the selected key in the secret, but does not display the actual value of the key that is referenced within the secret. Click Done to save your changes.
Click Save and create to update the app with the new environment variables.
When the app is in Ready state, your app is updated with your environment variables.
To test your app, click Test application and then click Send request in the Test application pane. To open the application in a web page, click Application URL. With this app revision, this app outputs Hello World from Code Engine and the output includes the names of the environment variables, which were added in the previous steps.

When you set environment variables in your workload, this action adds a new environment variable or overrides an existing environment variable. If you have an environment variable with the same Name, and specify a different value than the previously defined environment variable, then the updated environment variable overrides the existing value. For example, if you have a defined environment variable that is named envvar1 and its value is myenvar1, and you define another environment variable that is also named envvar1 and specify its value as mynewenvvar1, then after you save and deploy your updated app or you save your updated job, your running app, or job uses the envvar1 environment variable with value mynewenvvar1.

Updating environment variables from the console

To update an existing environment variable, go to your app, job, or function that includes the environment variable that you want to change and click the Environment variables tab to display your table of environment variables.
From the table of environment variables, click the environment variable that you want to update.
From the Edit environment variable page, make your update and click Done to save your changes. When you edit your environment variable, you can change the Defined by value and its corresponding required fields.
Click Save and deploy to deploy your application with your changes or click Save to run your job with your changes. When your app or job is in Ready state, your app or job is updated with your environment variables.

Creating and updating environment variables with the CLI

Create and manage environment variables with the Code Engine CLI.

You can define environment variables when you create or update your app, job, or function with the CLI.

When you create an environment variable with the CLI, you can reference configmaps or secrets, or you can create a literal environment variable. These instructions describe creating and updating literal environment variables with the CLI.

For detailed scenarios about referencing full secrets and configmaps as environment variables, overriding references, and removing references in the CLI, see Referencing secrets and configmaps.

Before you begin

Set up your Code Engine CLI environment.
Create and work with a project.

Create and update environment variables for your app

Create and update environment variables for your app as follows,

To create and set an environment variable for your app, use the --env option with the app create or app update command. The following example creates the myapp application that uses the icr.io/codeengine/codeengine image, and defines the envA and envB environment variables.
```
ibmcloud ce application create --name myapp --image icr.io/codeengine/codeengine --env envA=A --env envB=B
```
To update environment variables for an existing application, use the --env option with the app update command. The following example updates the myapp application to overwrite the value of envA and adds the envC environment variable.
```
ibmcloud ce application update --name myapp  --env envA=AA --env envC=C
```

Create and update environment variables for your job

Set and update environment variables for your job as follows,

To create and set an environment variable for your job, use the --env option with the job create, job update, jobrun submit, or jobrun resubmit command. The following example creates the myjob job that uses the icr.io/codeengine/codeengine image, and defines the envA environment variable.
```
ibmcloud ce job create --name myjob --image icr.io/codeengine/codeengine --env envA=A 
```
To update environment variables for an existing job, use the --env option with the job update, jobrun submit, or jobrun resubmit command.

Example 1

The following example updates the myjob job to overwrite the value of envA and adds the envB environment variable.

ibmcloud ce job update --name myjob  --env envA=AA --env envB=B

Run the job get command to display details of the job, including its environment variables.

ibmcloud ce job get --name myjob

Example output

Getting job 'myjob'...
OK

Name:          myjob
[...]
Environment Variables:
    Type     Name  Value
    Literal  envA  AA
    Literal  envB  B
Image:                  icr.io/codeengine/codeengine
[...]

Example 2

The following example runs the myjob job, overwrites the value of envA, and adds the envD environment variable for this job run.

ibmcloud ce jobrun submit --job myjob  --name myjobrun1 --env envB=BB --env envC=C

Run the jobrun get command to display details of the job run, including its environment variables.

ibmcloud ce jobrun get --name myjobrun1

Example output

[...]
Name:          myjobrun1
[...]
Job Ref:                myjob
Environment Variables:
    Type     Name  Value
    Literal  envA  AA
    Literal  envB  BB
    Literal  envC  C
Image:                  icr.io/codeengine/codeengine
[...]

Instances:
Name           Running  Status   Restarts  Age
myjobrun1-0-0  0/1      Succeeded  0         17s

Create and update environment variables for your function

Set and update environment variables for your function as follows.

To create and set an environment variable for your function, use the --env option with the function create or the function update command. The following example creates the myfunction function that uses the https://github.com/IBM/CodeEngine source code, and defines the envA environment variable.
```
ibmcloud ce function create --name myfunction --runtime nodejs-18 --build-source https://github.com/IBM/CodeEngine --build-context-dir /helloworld-samples/function-nodejs  --env envA=A
```
Example output from the fn get command.
```
Environment Variables:    
Type     Name  Value  
Literal  envA  A
```
To update environment variables for an existing function, use the --env option with the function update command. The following example updates the myfunction function to overwrite the value of envA and adds the envC environment variable.
```
ibmcloud ce fn update --name myfunction  --env envA=AA --env envC=C
```
Example output from the fn get command.
```
Environment Variables:    
Type     Name  Value  
Literal  envA  AA
Literal  envC  C
```

Considerations for updating workloads with environment variables

Consider the following information when you update an app, job, or function that has an environment variable that references configmaps or secrets.

When you update an app, job, or function that has an environment variable that fully references a configmap (or secret) to fully reference a different configmap (or secret), full references override other full references in the order in which they are set (the last referenced set overrides the first set).
When you update an app, job, or function that has an environment variable that references a key in one configmap (or secret) to reference the same key in a different configmap (or secret), then the last referenced key is used.
When you update an app, job, or function that has an environment variable that fully references a configmap (or secret) to add a reference to a specific key, then the specific key reference overrides the full configmap (or secret) reference.

Deleting environment variables

When you no longer need an environment variable, you can delete it.

Deleting environment variables from the console

From the console, go to the app, job, or function that has the environment variable that you want to delete. Click the Environment variables tab.
From the table of environment variables, delete the environment variable that you want to remove from the app, job, or function.
Click Save and deploy to update the app or click Save to update your job or function with the new environment variables. When your app, job, or function is in Ready state, it is updated with your current environment variables.

Deleting environment variables with the CLI

When you work with environment variables with the CLI, you can reference existing configmaps or secrets, or you can work with literal environment variables. These instructions describe deleting literal environment variables with the CLI.

For detailed scenarios about removing references to full secrets and configmaps in the CLI, see Referencing secrets and configmaps.

Delete environment variables for your app

To remove an environment variable for your app, use the --env-rm option with the app update command. The following example updates the myapp application to delete the envA environment variable.

ibmcloud ce application update --name myapp --env-rm envA

Delete environment variables for your job

To remove an environment variable for your job, use the --env-rm option with the job update or jobrun resubmit command.

Use the --env-rm option with the job update command to remove environment variables set on the job. Use the --env-rm option with the jobrun resubmit command to remove environment variables set on a specified job run.

The following example updates the myjob job to delete the envA environment variable.
```
ibmcloud ce job update --name myjob  --env-rm envA 
```
Use the job get command to display details of the job, including its environment variables.

The following example resubmits the myjobrun1 job run and deletes the envC environment variable.

ibmcloud ce jobrun resubmit --jobrun myjobrun1  --name jobrun2resuba--env-rm envC

Run the jobrun get command to display details of the job run, including its environment variables.

ibmcloud ce jobrun get --name jobrun2resuba

Example output

Getting jobrun 'jobrun2resuba'...
Getting instances of jobrun 'jobrun2resuba'...
Getting events of jobrun 'jobrun2resuba'...
[...]

Name:          jobrun2resuba
[...]
Job Ref:                myjob
Environment Variables:
    Type     Name  Value
    Literal  envB  BB
Image:                  icr.io/codeengine/codeengine
[...]

Instances:
Name               Running  Status     Restarts  Age
jobrun2resuba-0-0  0/1      Succeeded  0         21s

Delete environment variables for your function

To remove an environment variable for your function, use the --env-rm option with the function update command. The following example updates the myfunction function to delete the envA environment variable.

ibmcloud ce function update --name myfunction --env-rm envA