Run containerized tasks with restart policies

The ease and speed of deploying containers in Azure Container Instances provides a compelling platform for executing run-once tasks like build, test, and image rendering in a container instance.

With a configurable restart policy, you can specify that your containers are stopped when their processes have completed. Because container instances are billed by the second, you're charged only for the compute resources used while the container executing your task is running.

The examples presented in this article use the Azure CLI. You must have Azure CLI version 2.0.21 or greater installed locally, or use the CLI in the Azure Cloud Shell.

Container restart policy

When you create a container group in Azure Container Instances, you can specify one of three restart policy settings.

Restart policy Description
Always Containers in the container group are always restarted. This is the default setting applied when no restart policy is specified at container creation.
Never Containers in the container group are never restarted. The containers run at most once.
OnFailure Containers in the container group are restarted only when the process executed in the container fails (when it terminates with a nonzero exit code). The containers are run at least once.

Specify a restart policy

How you specify a restart policy depends on how you create your container instances, such as with the Azure CLI, Azure PowerShell cmdlets, or in the Azure portal. In the Azure CLI, specify the --restart-policy parameter when you call az container create.

az container create \
    --resource-group myResourceGroup \
    --name mycontainer \
    --image mycontainerimage \
    --restart-policy OnFailure

Run to completion example

To see the restart policy in action, create a container instance from the microsoft/aci-wordcount image, and specify the OnFailure restart policy. This example container runs a Python script that, by default, analyzes the text of Shakespeare's Hamlet, writes the 10 most common words to STDOUT, and then exits.

Run the example container with the following az container create command:

az container create \
    --resource-group myResourceGroup \
    --name mycontainer \
    --image microsoft/aci-wordcount:latest \
    --restart-policy OnFailure

Azure Container Instances starts the container, and then stops it when its application (or script, in this case) exits. When Azure Container Instances stops a container whose restart policy is Never or OnFailure, the container's status is set to Terminated. You can check a container's status with the az container show command:

az container show --resource-group myResourceGroup --name mycontainer --query containers[0].instanceView.currentState.state

Example output:


Once the example container's status shows Terminated, you can see its task output by viewing the container logs. Run the az container logs command to view the script's output:

az container logs --resource-group myResourceGroup --name mycontainer


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

This example shows the output that the script sent to STDOUT. Your containerized tasks, however, might instead write their output to persistent storage for later retrieval. For example, to an Azure file share.

Manually stop and start a container group

Regardless of the restart policy configured for a container group, you might want to manually stop or start a container group.

  • Stop - You can manually stop a running container group at any time - for example, by using the az container stop command. For certain container workloads, you might want to stop a container group after a defined period to save on costs.

    Stopping a container group terminates and recycles the containers in the group; it does not preserve container state.

  • Start - When a container group is stopped - either because the containers terminated on their own or you manually stopped the group - you can use the container start API or Azure portal to manually start the containers in the group. If the container image for any container is updated, a new image is pulled.

    Starting a container group begins a new deployment with the same container configuration. This action can help you quickly reuse a known container group configuration that works as you expect. You don't have to create a new container group to run the same workload.

  • Restart - You can restart a container group while it is running - for example, using the az container restart command. This action restarts all containers in the container group. If the container image for any container is updated, a new image is pulled.

    Restarting a container group is helpful when you want to troubleshoot a deployment problem. For example, if a temporary resource limitation prevents your containers from running successfully, restarting the group might solve the problem.

After you manually start or restart a container group, the container group runs according to the configured restart policy.

Configure containers at runtime

When you create a container instance, you can set its environment variables, as well as specify a custom command line to execute when the container is started. You can use these settings in your batch jobs to prepare each container with task-specific configuration.

Environment variables

Set environment variables in your container 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.

For example, you can modify the behavior of the script in the example container by specifying the following environment variables when you create the container instance:

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."

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

By specifying NumWords=5 and MinLength=8 for the container's environment variables, the container logs should display different output. Once the container status shows as Terminated (use az container show to check its status), display its logs to see the new output:

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


[('CLAUDIUS', 120),
 ('POLONIUS', 113),
 ('GERTRUDE', 82),

Command line override

Specify a command line when you create a container instance to override the command line baked into the container image. This is similar to the --entrypoint command-line argument to docker run.

For instance, you can have the example container analyze text other than Hamlet by specifying a different command line. The Python script executed by the container,, accepts a URL as an argument, and will process that page's content instead of the default.

For example, to determine the top 3 five-letter words in Romeo and Juliet:

az container create \
    --resource-group myResourceGroup \
    --name mycontainer3 \
    --image microsoft/aci-wordcount:latest \
    --restart-policy OnFailure \
    --environment-variables NumWords=3 MinLength=5 \
    --command-line "python"

Again, once the container is Terminated, view the output by showing the container's logs:

az container logs --resource-group myResourceGroup --name mycontainer3


[('ROMEO', 177), ('JULIET', 134), ('CAPULET', 119)]

Next steps

Persist task output

For details on how to persist the output of your containers that run to completion, see Mounting an Azure file share with Azure Container Instances.