Creating containers on demand with Azure Container Instances

Azure Container Instances (ACI) is a relatively new service in Azure. It allows the easiest possible deployment of containers to the cloud. The idea behind it is called “Serverless Containers”. The meaning is that your container(s) will be deployed to a random server you have no control of and no need to manage (which is great).

This concept is suited for short-lived containers since the billing is more expensive (per second) than a VM. One possible use case for ACI is to create additional microservices in burst times. Alternatively, you might need a container that does a certain job and then dies. Much like Azure Functions, when a function just isn’t enough.

Since I recently did a big project with ACI, I’ll share with you everything I learned about creating containers dynamically in code.

Getting Started

To get started with docker containers, you should have a prepared container image in a container registry.

With ACI, you will be creating Container Groups. A Container Group consists of one or more containers deployed on a single machine, that can securely communicate with each other. To the outside world, the container group can expose a single public IP and a single port. So one of the containers can act as a server.

There are several ways to create a Container Group. Whatever way you choose, you’ll have to specify:

  • Information on the container registry, including username and password if it’s private
  • Information on the container image within the container registry
  • Os Type – ACI supports both Windows and Linux containers
  • Number of CPU cores – affects billing
  • Memory (in GB) – affects billing

There are a bunch of other parameters as well.

We can create container groups in these ways:

  1. With Azure Resource Manager (ARM) template.
  2. In Azure Portal
  3. With Azure Cloud Shell or Azure CLI. For example:
  4. In code with REST API.

Create containers programmatically with REST API

First of all, let’s talk a bit about Azure security. Azure doesn’t allow just anyone to be able to create containers on your Azure subscription. You need to be authorized to create Azure resources for that. Azure uses OAuth2.0 authorization with “Bearer” access tokens. This means that each HTTP request should contain an Authorization header with a valid Access Token.

Once you have obtained a valid access token, you can use Azure Container Instances Rest API to create containers.

Let’s see exactly how to do those things.

Source Code Available! I created a helper library with the code I used for ACI. It’s available on GitHub and has methods for everything you’re about to read.

Get an Access Token

There are 2 ways to get an Access Token:

  1. If your service is an Azure App Service or Azure Function, the simplest way is to use Azure Managed Service Identity.
  2. For App Service or anything else, you can use an Application Registration to Azure Active Directory. Then, use the application’s Id and Secret to get an access token.

Using Azure Managed Service Identity (MSI)

There’s a good documentation on using MSI, which I won’t repeat here, except to give you a general idea on what should be done to start getting access tokens.

In your App Service, you’ll need to turn on managed-service-identity. This can be done in the portal, in Azure CLI or with ARM Template. Once turned on, you’ll have to give your App Service permissions to the Resource Group where you are going to create containers (see below).

When permissions are given, you can get a valid access token in code by:

  1. Add a reference to the Microsoft.Azure.Services.AppAuthentication NuGet package
  2. Add the following code:
This will return the access token string and will take care to cache and reuse it internally.

If you’re not using .NET, or want to do it manually with REST, you can.

Using Active Directory Application Registration

There’s great documentation on application registration, which I also won’t repeat here, except to give you the general idea.

You’ll need to follow these steps:

  1. Create an Application Registration in Azure active directory. This can be done in the portal. Save the application ID (AKA ‘clientId’).
  2. Add to the application a Key and save its Value (AKA ‘clientSecret’).
  3. Give the application permissions to create containers (see below).
  4. Use the application’s ID and Key to get OAuth access tokens. you’ll need to send an HTTP POST request in the following format:
The result will be a JSON document with the access token and expiration data. For example:
There’s code to get these access token on my GitHub repository, including logic to cache and refresh the token when expired. Feel free to use the library or just copy the relevant code.

Give Permissions to modify the Resource Group

Whether you used Managed Service Identity or Application Registration, you need to give the proper permissions to create containers in the Resource Group.

Here’s the documentation on giving permissions to an application in Azure portal. The general idea is:

We’ll need to add permissions to the Resource Group where the containers are to be created (I used Owner, but Contributor might also work). In the portal, go to Resource Groups -> [The relevant resource group] -> Access Control (IAM). In the IAM, add either the registered application or the App Service (if used MSI) and assign the desired role (like Owner).

If the container registry is in a different resource group, you might need to add permissions for that as well.
If you want to add permissions in ARM template, it’s possible to do for  Managed Identity, but not for a registered application – That can be done only in Azure portal or a PowerShell script after deployment. Please inform me if it changes.

Create, query and delete Container Groups in code

Now that all the authorization preparations are done, we can create containers in code. We will actually be creating Container Groups, with a single container in each. The name of the container group will be the same as the container’s name.

For all operations, we will use this link:

With parameters Subscription IDResource Group and Container Group Name.

For reasons unknown to me, the container name can’t be in Pascal case, or you’ll get a BadRequest response. Kebab case worked for me – e.g ‘my-neat-container’

Remember to include Authorization header with the Access Token we received before. The key should be “Authorization” and the value “Bearer [access-token]”.

Now there are 3 main operations: Create a container groupDelete container group, Query container group, Which are done by PUT, DELETE and GET operations respectively.

The full API can be viewed here.

Example C# code to Create a Container Group

Instead of writing JSON in code as in the example, you’ll probably want to be serializing and deserializing a Container class. Or you can copy that code from my class library on GitHub.

Note all the hard-coded parameters used here: mySubscription, myResourceGroup, container-name, port 12345, cpu 2 and memory 8GB.

Example code to query container info

The response will be a JSON string in the same format as before. Here’s an example response:

Example code to delete a container

Is there an SDK I can use for this?

I created a class library, available on GitHub with the code I used for ACI. It has all the basic ACI management including the authorization code in both methods (MSI and app registration).

Here’s some sample code creating a container using the library:

Microsoft has a full-blown SDK, which you can use as well. Here’s a sample with Azure Container Instances.

Container Group Lifecycle

When a container group is created, it appears as a resource immediately and billing starts. The first thing that happens is the container will pull the image from the container registry. This can be as long as 1 minute for Linux containers or 5-6 minutes for Windows containers. During that stage, the container’s state is Waiting.

After pulling and executing whatever command needed, the container will change to Running state.

When the exec command finished, or the process in the container crashed, the following action depends on the Restart Policy that you can specify when creating the container. This can be set to Always, OnFailure or Never. If the container isn’t restarted, the state will change to Terminated. The resource will not disappear so you can still get logs and console output.

Get container logs and/or console output

When something goes wrong, there are several things we can do.

We can get logs with this Azure CLI / Azure Shell command:

We can get standard output with:

I don’t fully understand the difference between logs and attach. Both seem to show standard output, though attach also shows container state before the command, like when image pulling started and when it finished.

Communicating securely with our containers

The container now exposes a public IP, so anyone can communicate with it. In the future, a private Virtual Network will be available, but right now we have to use some kind of authorization infrastructure to communicate securely with the container.

In our project, we used IdentityServer to create an OAuth authentication, but I think the easiest way to provide security is to use Azure’s service-to-service client credentials authentication.


ACI offers an easy way to deploy containers. It has a straightforward API and allows you to get started with deployed containers as quickly as possible (so far).

Other upsides of “Serverless Containers” are that you don’t have to manage the running VM and there’s minimal upkeep/development needed.

The billing is per second, which makes it perfect for temporary containers.

There are several downsides I can see:

  • ACI doesn’t offer any sort of automatic scaling. 
  • There are some security issues due to the public IP exposed (These might be solved in the future with VNet support) and you’ll have to develop your own authentication system.
  • The billing is more expensive than a VM or App Service you might have when running 24/7.

It’s still unclear to me on how much real-world needs ACI can resolve. In my current project though, ACI fitted beautifully.


Enjoy the blog? I would love you to subscribe! Performance Optimizations in C#: 10 Best Practices (exclusive article)

Want to become an expert problem fixer? Check out a chapter from my book Practical Debugging for .NET Developers