Referencing secrets and configmaps with environment variables (CLI)

In Code Engine, after you create secrets and configmaps, the information that is stored as key-value pairs can be consumed by your app, job, or function workload as an environment variable by referencing the full secret or configmap or by referencing individual keys.

Working with secrets as environment variables is similar to working with configmaps as environment variables. When you work with secrets, the data is encoded.

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.

For basic information about referencing configmaps or secrets with the CLI, see Referencing configmaps with the CLI and Referencing secrets with the CLI.

The following scenarios can be completed for secrets or configmaps.

Referencing a full secret with the CLI

Secrets and configmaps are made up of key-value pairs. Environment variables are the result of providing an entry per key when referencing the full secret or configmap. If multiple secrets (or configmaps) contain the same named key, then you only get one of the keys in the referenced secret or configmap.

In this scenario, create a secret, which contains key-value pairs for a username and password, and then reference the full secret when you run a job. You can update the secret to add a key and then demonstrate the use of the new key in a job. While this scenario uses a secret, you can use the same steps to fully reference a configmap by substituting configmap for secret in the commands.

Create the mydatabasesec secret and specify the key-value pairs for a username and password by using the --from-literal option.
```
ibmcloud ce secret create -n mydatabasesec --from-literal username=reader --from-literal password=abcd
```

View details about the mydatabasesec secret by using the secret get command. The values for the password and username keys of the secret are encoded.

ibmcloud ce secret get -n mydatabasesec

Example output

Getting generic secret 'mydatabasesec'...
OK

Name:          mydatabasesec
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           17s
Created:       2020-10-14 14:07:59 -0400 EDT

Data:
---
password: YWJjZA==
username: cmVhZGVy

Set an environment variable on a job to reference the full mydatabasesec secret. In this example, let's use the --env-from-secret PREFIX=NAME option where PREFIX=NAME specifies to reference the full configmap where each key is prefixed with PREFIX. By using the read_ prefix, each key is prefixed with read_. Because the busybox image does not print any output by default, the -c env option specifies to print all the environment variables in the container.
```
ibmcloud ce job create -n demo -i busybox -c env --env-from-secret read_=mydatabasesec 
```
Consider using a prefix to help make sure that all your environment variables in your job or app are unique. For example, if you have a secret with keys, a, b, and c, these environment variables display as a, b, and c. However, if you add a prefix such as read_, then the keys display with the prefix, such as read_a, read_b, and read_c. Using a prefix also groups your environment variables in the referencing app, job, or jobrun, and helps you avoid duplicates of keys in configmaps or secrets.

(Optional) View the details of the demo job. The output displays the full reference to the mydatabasesec secret.

ibmcloud ce job get -n demo

Example output

Getting job 'demo'...
OK

Name:          demo
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           6s
Created:      2022-05-04T15:04:16-04:00

Commands:                 
    env  
Environment Variables:    
    Type                   Name                   Value
    Secret full reference  read_=mydatabasesec
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Run a job that uses the configuration of the demo job.
```
ibmcloud ce jobrun submit --name demo1 --job demo
```
Display the logs of the job run. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. In this example, display the logs of the demo1 job run. Notice in the log output that the keys of the full secret mydatabasesec are displayed with the prefix read_. Secret values are added to the environment decoded.
```
ibmcloud ce jobrun logs --jobrun demo1
```
Example output
```
Getting logs for all instances of job run 'demo1'...
Getting jobrun 'demo1'...
Getting instances of jobrun 'demo1'...
[...]

HOSTNAME=demo1-0-0
read_username=reader
read_password=abcd
JOB_INDEX=0
CE_SUBDOMAIN=8aaon2dfwa0
CE_JOBRUN=demo1
[...]
```
Update the mydatabasesec secret to add a key by using --from-file option. This option uses the format --from-file FILE or --from-file KEY=FILE. In the following command, certificate is the key and cert.pem is the name of the file.
```
ibmcloud ce secret update -n mydatabasesec --from-file certificate=cert.pem
```

View details about the updated mydatabasesec secret by using the secret get command. The secret now contains three keys, certificate, password, and username. Secret values are encoded.

ibmcloud ce secret get -n mydatabasesec

Example output

Getting generic secret 'mydatabasesec'...
OK

Name:          mydatabasesec
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m13s
Created:       2020-10-14 13:35:43 -0400 EDT

Data:
---
certificate: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tLS0tDQphc2RmO2Frc2pkZmxrYWpzZGZsa2phc2xka2ZqYWxza2RqZmxha3NqZGZsaw0KLS0tLS1FTkQgQ0VSVEZJQ0lBVEUtLS0tLS0tLS0t
password: YWJjZA==
username: cmVhZGVy

Run a job that uses the demo job. Previously, you referenced the full secret mydatabasesec from the demo job. For a job to use the updated secret with the added certificate key-value pair, submit a new job run. To update an app to use the updated secret, restart the app.
```
ibmcloud ce jobrun submit --name demo2 --job demo
```
Display the logs of the job run by using the ibmcloud ce jobrun logs command. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. To display the logs of a specific instance of the job run, use the --instance option with the jobrun logs command. If needed, use the jobrun get --name demo2 command to display details of this job run, including the instances of the job run. In this example, display the logs of the running instance of demo2-0-0 where demo2 is the name of the job run, 0 is the arrayindex, and 0 is the retryindex. Notice in the output that the certificate, username, and password keys of the full secret mydatabasesec are displayed. Secret values are added to the environment decoded.
```
ibmcloud ce jobrun logs --instance demo2-0-0
```
Example output
```
Getting logs for job run instance 'demo2-0-0'...
[...]

read_certificate=-----BEGIN CERTIFICATE--------
asdf;aksjdflkajsdflkjasldkfjalskdjflaksjdflk
-----END CERTFICIATE----------
read_password=abcd
read_username=reader
```

Referencing individual keys of a configmap with the CLI

In this scenario, let's create a configmap that contains multiple key-value pairs and then reference specific keys in a job. While this scenario uses a configmap, you can use the same general steps to reference individual keys with a secret by substituting secret for configmap in the commands.

Create the mydatabase configmap and specify the key-value pairs for a name and a URL by using the --from-literal KEY=VALUE option.
```
ibmcloud ce configmap create -n mydatabasecm --from-literal name=myname --from-literal url=myurl
```

View details about the mydatabasecm configmap by using the configmap get command.

ibmcloud ce configmap get -n mydatabasecm

Example output

Getting configmap 'mydatabasecm'...
OK

Name:          mydatabasecm
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           16s
Created:       2020-10-14 13:31:19 -0400 EDT

Data:
---
name: myname
url: myurl

Set an environment variable on a job to reference the url key in the mydatabasecm configmap. Use the --env-from-configmap NAME:KEY_A,KEY_B option where NAME:KEY_A specifies to reference the KEY_A of the configmap.
```
ibmcloud ce job create --name keydemo --image busybox --command env --env-from-configmap mydatabasecm:url 
```

Run a job that uses the keydemo job.

ibmcloud ce jobrun submit --name keydemo1 --job keydemo

Display the logs of the job run by using the ibmcloud ce jobrun logs command. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. To display the logs of a specific instance of the job run, use the --instance option with the jobrun logs command. If needed, use the jobrun get --name keydemo1 command to display details of this job run, including the instances of the job run. Notice in the output that url is the only referenced key and that the name key is not referenced by the job.
```
ibmcloud ce jobrun logs --instance keydemo1-0-0
```
Example output
```
Getting logs for job run instance 'keydemo1-0-0'...
[...]

url=myurl
[...]
```

Overriding references with the CLI

You can override referenced secrets and configmaps. The following scenarios can be completed for secrets or configmaps.

Scenario A. Override a fully referenced secret with another fully referenced secret

In this scenario, let's create a new mydatabasesec-writer secret with the username and password keys and then override username and password keys in the previously created mydatabasesec secret. The mydatabasesec secret contains the username=reader and password=abcd keys.

Full references override other full references in the order in which they are set (the last referenced set overrides the first set).

Set an environment variable on the writerjob job to reference the full mydatabasesec secret, which was created previously. The mydatabasesec secret contains the username=reader and password=abcd keys.
```
ibmcloud ce job create -n writerjob -i busybox -c env --env-from-secret mydatabasesec 
```

(Optional) View the details of the writerjob job. The output displays the full reference to the mydatabasesec secret.

ibmcloud ce job get -n writerjob

Example output

Getting job 'writerjob'...
OK

Name:          writerjob
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           17s
Created:       2021-02-12T07:12:08-06:00
[...]

Commands:                 
    env  
Environment Variables:    
    Type                   Name           Value  
    Secret full reference  mydatabasesec    
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Run a job that uses the writerjob job.

ibmcloud ce jobrun submit --name writerjob1 --job writerjob

Display the logs of the job run. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. In this example, display the logs of the writerjob1 job run. Notice in the output that the username and password keys of the full secret mydatabasesec are displayed. Secret values are added to the environment decoded.
```
ibmcloud ce jobrun logs --jobrun writerjob1
```
Example output
```
Getting jobrun 'writerjob1'...
Getting instances of jobrun 'writerjob1'...
Getting logs for all instances of job run 'writerjob1'...
OK
[...]

certificate=-----BEGIN CERTIFICATE--------
asdf;aksjdflkajsdflkjasldkfjalskdjflaksjdflk
-----END CERTFICIATE----------
password=abcd
username=reader
[...]
```
Create the mydatabasesec-writer secret and specify the key-value pairs for a username and password by using the --from-literal option.
```
ibmcloud ce secret create --name mydatabasesec-writer --from-literal username=writer --from-literal password=wxyz
```

View details about the mydatabasesec-writer secret by using the secret get command. The values for the password and username keys of the secret are encoded.

ibmcloud ce secret get -n mydatabasesec-writer

Example output

Getting generic secret 'mydatabasesec-writer'...
OK

Name:          mydatabasesec-writer
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           14s
Created:       2020-10-14 13:44:16 -0400 EDT

Data:
---
password: d3h5eg==
username: d3JpdGVy

Update the writerjob job to reference the full mydatabasesec-writer secret and use the write_ prefix.
```
ibmcloud ce job update --name writerjob --env-from-secret write_=mydatabasesec-writer
```

(Optional) View details of the updated writerjob job. The job fully references the mydatabasesec and the mydatabase-writer secrets.

ibmcloud ce job get -n writerjob

Example output

Getting job 'writerjob'...
OK

Name:          writerjob
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m2s
Created:       2021-02-12T07:12:08-06:00
[...]

Commands:                 
    env  
Environment Variables:    
    Type                   Name                          Value  
    Secret full reference  mydatabasesec           
    Secret full reference  write_=mydatabasesec-writer   
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Run a job that uses the writerjob job. Because the writerjob job was updated to reference both the mydatabasesec secret and the mydatabasesec-writer secret and both of these secrets include keys for username and password, the last referenced full secret mydatabasesec-writer overrides the mydatabasesec secret.

For a job run to use the updated configuration of a job with the updates to its fully referenced secrets, run a new job. To update an app to use the updated secret, restart the app.
```
ibmcloud ce jobrun submit --name writerjob2 --job writerjob
```
Display the logs of the job run by using the ibmcloud ce jobrun logs command. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. To display the logs of all the instances of a job, use the --jobrun option with the jobrun logs command. To display the logs of a specific instance of the job run, use the --instance option with the jobrun logs command. If needed, use the jobrun get --name writerjob2 command to display details of this job run, including the instances of the job run. Notice in the output that the username and password keys of the mydatabasesec-writer secret overrode the keys of the mydatabasesec secret. Also, in the log output, the keys of the full secret mydatabasesec-writer are displayed with the prefix write_.Secret values are added to the environment decoded.
```
ibmcloud ce jobrun logs --instance writerjob2-0-0
```
Example output
```
Getting logs for job run instance 'writerjob2-0-0'...
[...]

certificate=-----BEGIN CERTIFICATE--------
asdf;aksjdflkajsdflkjasldkfjalskdjflaksjdflk
-----END CERTFICIATE----------
password=abcd
username=reader
write_password=wxyz
write_username=writer
[...]
```

Scenario B. Override a fully referenced secret with a key reference

References to a key in a secret or configmap always overrides a full reference to a secret or configmap when the key that is used resides in a fully referenced secret or configmap, without regard for order.

In this scenario, let's use the previously created mydatabasesec and mydatabasesec-writer secrets and reference keys within the secrets from a job.

Set an environment variable on a writerpic job to reference specific keys in the mydatabasesec and mydatabasesec-writer secrets. The mydatabasesec secret contains the username=reader, password=abcd, and certificate=cert.pem keys. The mydatabasesec-writer secret contains the username=writer and password=wxyz keys.
```
ibmcloud ce job create -n writerpick -i busybox -c env --env-from-secret mydatabasesec-writer:username --env-from-secret mydatabasesec-writer:password --env-from-secret mydatabasesec 
```

(Optional) View the details of the writerpick job. The output displays the full reference to the mydatabasesec secret and the key reference to the password and username keys of the mydatabasesec-writer secret.

ibmcloud ce job get -n writerpick

Example output

Getting job 'writerpick'...
OK

Name:          writerpick
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           107s
Created:       2021-02-12T07:16:46-06:00  
[...]

Commands:                 
    env  
Environment Variables:    
    Type                   Name           Value  
    Secret full reference  mydatabasesec    
    Secret key reference   password       mydatabasesec-writer.password  
    Secret key reference   username       mydatabasesec-writer.username  
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Run a job that uses the writerpick job.

ibmcloud ce jobrun submit --name writerpick1 --job writerpick

Display the logs of the writerpick1 job run by using the ibmcloud ce jobrun logs command. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. To display the logs of a specific instance of the job run, use the --instance option with the jobrun logs command. If needed, use the jobrun get --name writerpick1 command to display details of this job run, including the instances of the job run. Because the writerpick job was updated to reference specific keys in the mydatabasesec-writer secret and to reference the full mydatabasesec secret, the reference to the username and password keys in the mydatabasesec-writer secret overrides the reference to the full secret. Secret values are added to the environment decoded.
```
ibmcloud ce jobrun logs --instance writerpick1-0-0
```
Example output
```
Getting logs for job run instance 'writerpick1-0-0'...
[...]

username=writer
certificate=-----BEGIN CERTIFICATE--------
asdf;aksjdflkajsdflkjasldkfjalskdjflaksjdflk
-----END CERTFICIATE----------
password=wxyz
[...]
```

Scenario C. Override key references with new keys

You can update the reference to a specific key in a secret or configmap and override the value with a new value.

In this scenario, let's use the previously created mydatabasecm configmap, which contains the url:myurl key to update the value of the key.

Set an environment variable on a keyref job to reference a specific key in the mydatabasecm configmap.
```
ibmcloud ce job create -n keyref -i busybox -c env --env-from-configmap mydatabasecm:url
```

(Optional) View the details of the keyref job. The output displays the key reference to the url key in the mydatabasecm configmap.

ibmcloud ce job get -n keyref

Example output

Getting job 'keyref'...
OK

Name:          keyref
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           65s
Created:       2021-02-12T07:18:44-06:00  
[...]

Commands:                 
    env  
Environment Variables:    
    Type                     Name  Value  
    ConfigMap key reference  url   mydatabasecm.url  
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Run a job that uses the keyref job.

ibmcloud ce jobrun submit --name keyref1 --job keyref

Display the logs of a running instance of the keyref1 job run by using the ibmcloud ce jobrun logs command. You can display logs of all the instances of a job run or display logs of a specific instance of a job run. To display the logs of a specific instance of the job run, use the --instance option with the jobrun logs command. If needed, use the jobrun get --name keyref1 command to display details of this job run, including the instances of the job run. The job run used the url=myurl key reference.
```
ibmcloud ce jobrun logs --instance keyref1-0-0
```
Example output
```
Getting logs for job run instance 'keyref1-0-0'...
[...]

url=myurl
[...]
```
Update the keyref job to override the url=myurl with a new key. Use the --env option to update the url key. The --env option on the job update command sets environment variables for the job in NAME=VALUE format.
```
ibmcloud ce job update --name keyref --env url=newurl  
```

(Optional) View the details of the keyref job. The output displays the key reference to the url key in the mydatabasecm configmap.

ibmcloud ce job get -n keyref

Example output

Getting job 'keyref'...
OK

Name:          keyref
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           3m6s
Created:       2021-02-12T07:18:44-06:00  

Commands:                 
    env  
Environment Variables:    
    Type     Name  Value  
    Literal  url   newurl  
Image:                  busybox  
Resource Allocation:      
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Removing fully referenced secrets or configmaps with the CLI

You can remove a fully referenced secret or configmap from a job or app.

In this scenario, let's remove the fully referenced mydatabasesec secret from the demo job.

Update the demo job to remove the reference to the mydatabasesec secret.

ibmcloud ce job update -n demo --env-from-secret-rm mydatabasesec

View the details of the demo job. The output illustrates that the reference to the mydatabasesec secret is removed.

ibmcloud ce job get -n demo

Example output

Getting job 'demo'...
OK

Name:          demo
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           19m
Created:       2021-02-12T07:05:23-06:00  
[...]

Commands:               
    env  
Image:                busybox    
Resource Allocation:    
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3

Removing key references with the CLI

You can remove a referenced key in a secret or configmap from a job or app.

In this scenario, let's remove the url key from the keyref job.

Even though the --env-from-configmap option was used on a job to reference the url key in the mydatabasecm configmap, you can use the --env-rm option to remove individual keys. You can use the --env-rm option with the job update or app update commands to remove key references regardless of whether the keys are individual key references in a secret or configmap, or whether the keys were directly set on a job or app with the --env option.

Update the keydef job to remove the reference to the url key.
```
ibmcloud ce job update --name keyref --env-rm url 
```

View the details of the keyref job. The output illustrates that the reference to the url key is removed.

ibmcloud ce job get -n keyref

Example output

Getting job 'keyref'...
OK

Name:          keyref
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           6m27s
Created:       2021-02-12T07:18:44-06:00  
[...]

Commands:               
    env  
Image:                busybox  
Resource Allocation:    
    CPU:     1  
    Memory:  4G  

Runtime:
    Mode:                  task
    Array Indices:         0
    Array Size:            1
    Max Execution Time:    7200
    Retry Limit:           3