Set environment variables in container instances

Setting environment variables in your container instances allows you to provide dynamic configuration of the application or script run by the container. This is similar to the --env command-line argument to docker run.

To set environment variables in a container, specify them when you create a container instance. This article shows examples of setting environment variables when you start a container with the Azure CLI, Azure PowerShell, and the Azure portal.

For example, if you run the Microsoft aci-wordcount container image, you can modify its behavior by specifying the following environment variables:

NumWords: The number of words sent to STDOUT.

MinLength: The minimum number of characters in a word for it to be counted. A higher number ignores common words like "of" and "the."

If you need to pass secrets as environment variables, Azure Container Instances supports secure values for both Windows and Linux containers.

Note

We recommend that you use the Azure Az PowerShell module to interact with Azure. See Install Azure PowerShell to get started. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Azure CLI example

To see the default output of the aci-wordcount container, run it first with this az container create command (no environment variables specified):

az container create \
    --resource-group myResourceGroup \
    --name mycontainer1 \
    --image mcr.microsoft.com/azuredocs/aci-wordcount:latest \
    --restart-policy OnFailure

To modify the output, start a second container with the --environment-variables argument added, specifying values for the NumWords and MinLength variables. (This example assume you are running the CLI in a Bash shell or Azure Cloud Shell. If you use the Windows Command Prompt, specify the variables with double-quotes, such as --environment-variables "NumWords"="5" "MinLength"="8".)

az container create \
    --resource-group myResourceGroup \
    --name mycontainer2 \
    --image mcr.microsoft.com/azuredocs/aci-wordcount:latest \
    --restart-policy OnFailure \
    --environment-variables 'NumWords'='5' 'MinLength'='8'

Once both containers' state shows as Terminated (use az container show to check state), display their logs with az container logs to see the output.

az container logs --resource-group myResourceGroup --name mycontainer1
az container logs --resource-group myResourceGroup --name mycontainer2

The outputs of the containers show how you've modified the second container's script behavior by setting environment variables.

mycontainer1

[('the', 990),
 ('and', 702),
 ('of', 628),
 ('to', 610),
 ('I', 544),
 ('you', 495),
 ('a', 453),
 ('my', 441),
 ('in', 399),
 ('HAMLET', 386)]

mycontainer2

[('CLAUDIUS', 120),
 ('POLONIUS', 113),
 ('GERTRUDE', 82),
 ('ROSENCRANTZ', 69),
 ('GUILDENSTERN', 54)]

Azure PowerShell example

Setting environment variables in PowerShell is similar to the CLI, but uses the -EnvironmentVariable command-line argument.

First, launch the aci-wordcount container in its default configuration with this New-AzContainerGroup command:

New-AzContainerGroup `
    -ResourceGroupName myResourceGroup `
    -Name mycontainer1 `
    -Image mcr.microsoft.com/azuredocs/aci-wordcount:latest

Now run the following New-AzContainerGroup command. This one specifies the NumWords and MinLength environment variables after populating an array variable, envVars:

$envVars = @(
    New-AzContainerInstanceEnvironmentVariableObject -Name "NumWords" -Value "5"
    New-AzContainerInstanceEnvironmentVariableObject -Name "MinLength" -Value "8"
)

$containerGroup = New-AzContainerGroup -ResourceGroupName "myResourceGroup" `
    -Name "mycontainer2" `
    -Image "mcr.microsoft.com/azuredocs/aci-wordcount:latest" `
    -RestartPolicy "OnFailure" `
    -Container @(
        New-AzContainerGroupContainer -Name "mycontainer2" `
            -EnvironmentVariable $envVars
    )

Once both containers' state is Terminated (use Get-AzContainerInstanceLog to check state), pull their logs with the Get-AzContainerInstanceLog command.

Get-AzContainerInstanceLog -ResourceGroupName myResourceGroup -ContainerGroupName mycontainer1
Get-AzContainerInstanceLog -ResourceGroupName myResourceGroup -ContainerGroupName mycontainer2

The output for each container shows how you've modified the script run by the container by setting environment variables.

PS Azure:\> Get-AzContainerInstanceLog -ResourceGroupName myResourceGroup -ContainerGroupName mycontainer1
[('the', 990),
 ('and', 702),
 ('of', 628),
 ('to', 610),
 ('I', 544),
 ('you', 495),
 ('a', 453),
 ('my', 441),
 ('in', 399),
 ('HAMLET', 386)]

Azure:\
PS Azure:\> Get-AzContainerInstanceLog -ResourceGroupName myResourceGroup -ContainerGroupName mycontainer2
[('CLAUDIUS', 120),
 ('POLONIUS', 113),
 ('GERTRUDE', 82),
 ('ROSENCRANTZ', 69),
 ('GUILDENSTERN', 54)]

Azure:\

Azure portal example

To set environment variables when you start a container in the Azure portal, specify them in the Advanced page when you create the container.

1. On the Advanced page, set the Restart policy to On failure
2. Under Environment variables, enter NumWords with a value of 5 for the first variable, and enter MinLength with a value of 8 for the second variable.
3. Select Review + create to verify and then deploy the container.

To view the container's logs, under Settings select Containers, then Logs. Similar to the output shown in the previous CLI and PowerShell sections, you can see how the script's behavior has been modified by the environment variables. Only five words are displayed, each with a minimum length of eight characters.

Secure values

Objects with secure values are intended to hold sensitive information like passwords or keys for your application. Using secure values for environment variables is both safer and more flexible than including it in your container's image. Another option is to use secret volumes, described in Mount a secret volume in Azure Container Instances.

Environment variables with secure values aren't visible in your container's properties--their values can be accessed only from within the container. For example, container properties viewed in the Azure portal or Azure CLI display only a secure variable's name, not its value.

Set a secure environment variable by specifying the secureValue property instead of the regular value for the variable's type. The two variables defined in the following YAML demonstrate the two variable types.

YAML deployment

Create a secure-env.yaml file with the following snippet.

apiVersion: 2019-12-01
location: eastus
name: securetest
properties:
  containers:
  - name: mycontainer
    properties:
      environmentVariables:
        - name: 'NOTSECRET'
          value: 'my-exposed-value'
        - name: 'SECRET'
          secureValue: 'my-secret-value'
      image: mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
      ports: []
      resources:
        requests:
          cpu: 1.0
          memoryInGB: 1.5
  osType: Linux
  restartPolicy: Always
tags: null
type: Microsoft.ContainerInstance/containerGroups

Run the following command to deploy the container group with YAML (adjust the resource group name as necessary):

az container create --resource-group myResourceGroup --file secure-env.yaml

Verify environment variables

Run the az container show command to query your container's environment variables:

az container show --resource-group myResourceGroup --name securetest --query 'containers[].environmentVariables'

The JSON response shows both the insecure environment variable's key and value, but only the name of the secure environment variable:

[
  [
    {
      "name": "NOTSECRET",
      "secureValue": null,
      "value": "my-exposed-value"
    },
    {
      "name": "SECRET",
      "secureValue": null,
      "value": null
    }
  ]
]

With the az container exec command, which enables executing a command in a running container, you can verify that the secure environment variable has been set. Run the following command to start an interactive bash session in the container:

az container exec --resource-group myResourceGroup --name securetest --exec-command "/bin/sh"

Once you've opened an interactive shell within the container, you can access the SECRET variable's value:

root@caas-ef3ee231482549629ac8a40c0d3807fd-3881559887-5374l:/# echo $SECRET
my-secret-value

Next steps

Task-based scenarios, such as batch processing a large dataset with several containers, can benefit from custom environment variables at runtime. For more information about running task-based containers, see Run containerized tasks with restart policies.