Deploy Containers to Azure Container Instances

You've built a container image locally, tested it, and maybe even pushed it to a registry. But now comes the moment of truth: getting that container running in Azure without spinning up a full Kubernetes cluster or managing virtual machines. Azure Container Instances (ACI) is the fastest, simplest way to deploy containers to Azure Container Instances — no infrastructure to manage, no orchestrator to learn, just a container and a URL. In this lesson, you'll master ACI from core concepts to hands-on deployment, and you'll be ready to integrate it into real-world workflows.

The problem this lesson solves

Traditional container deployment on Azure often feels like overkill for a simple service. You could provision a Virtual Machine (VM), install Docker, and run your container — but then you're responsible for patching the OS, securing the network, and keeping the VM alive. Alternatively, Azure Kubernetes Service (AKS) gives you powerful orchestration, but it comes with a steep learning curve and operational overhead. For a single container, a background job, or a quick test environment, both options are heavy.

Azure Container Instances solves this by abstracting away the host. You don't see or manage the underlying VMs. You provide an image, configure resources, and ACI runs your container in seconds. Billing is per second, and you can scale out by simply increasing the number of container instances. This is perfect for scenarios like running a one-off data migration script, hosting a small API, or executing a periodic job.

The pain is real: many developers spend hours wrestling with cluster configuration when all they needed was a simple docker run. This lesson shows you how to deploy containers to Azure Container Instances with minimal effort, so you can focus on your code, not the plumbing.

Core concept / mental model

Think of ACI as the "serverless" version of a container runtime. With Docker, you run containers on a local daemon. With ACI, Azure runs that same container for you in a managed environment.

Analogy: Imagine renting a single room in a hotel instead of leasing an entire apartment. You get the bed (your container), the room is cleaned (managed by Azure), and you only pay for the nights you stay (per-second billing). No lease, no maintenance.

Here are the key definitions to hold in your head:

• Container group: Billing and lifecycle are tied to a container group. A group can hold one or more containers that share a network and storage. For a single container, the group is just a wrapper.
• Image: The Docker image you push to Azure Container Registry (ACR) or any public registry like Docker Hub.
• Resource requirements: You specify CPU and memory for each container. ACI provisions exactly that, so you pay only for those resources.
• Restart policy: Controls what happens when the container exits — Always, OnFailure, or Never.
• Environment variables: You can pass secrets and configuration without baking them into the image.

ACI is not a full orchestrator. It doesn't scale automatically across multiple nodes in a cluster (unless you use the orchestration integrations). Instead, you get one or more containers that start fast, run, and stop — perfect for many modern workloads.

How it works step by step

Deploying a container to ACI follows a logical sequence. Here's the high-level flow:

1. Prepare your container image — Dockerfile, build, tag, push to a registry.
2. Create a resource group — A logical container for all your Azure resources.
3. Choose a deployment method — Azure CLI, PowerShell, Azure portal, or an ARM/Bicep template.
4. Run the container — Provide image, resource limits, environment variables, and restart policy.
5. Access the container — Get the public IP or FQDN and use it.
6. Monitor and manage — View logs, restart, or delete when done.

The cause-and-effect here is simple: you provide the image and requirements, ACI does the rest. Under the hood, Azure orchestrates the placement on a host, sets up networking (public IP or VNet), and mounts storage if you need it. This is why deployment takes seconds — no OS boot, no agent install.

Hands-on walkthrough

Let's deploy a real container in about 10 minutes. We'll use the Azure CLI, which you should have installed and configured (if not, review earlier lessons).

Step 1: Create a resource group

First, log in and create a resource group in a region near you.

az login
# Pick a region like eastus
az group create --name my-aci-rg --location eastus

Expected output (condensed):

{
  "id": "/subscriptions/.../resourceGroups/my-aci-rg",
  "location": "eastus",
  "name": "my-aci-rg",
  "type": "Microsoft.Resources/resourceGroups"
}

Step 2: Deploy a simple web container

We'll use the official mcr.microsoft.com/azuredocs/aci-helloworld image, which runs a small web app.

az container create \
  --resource-group my-aci-rg \
  --name my-hello-world \
  --image mcr.microsoft.com/azuredocs/aci-helloworld \
  --cpu 1 \
  --memory 1 \
  --ports 80 \
  --dns-name-label my-hello-world-unique \
  --location eastus

Expected output: The command waits until the container is running and prints a JSON block with the container's properties, including ipAddress and fqdn. Wait a few seconds and then:

az container show --resource-group my-aci-rg --name my-hello-world --query "{FQDN:ipAddress.fqdn,IP:ipAddress.ip}" --output json

You should see something like:

{
  "FQDN": "my-hello-world-unique.eastus.azurecontainer.io",
  "IP": "52.167.12.34"
}

Open the FQDN in your browser to see the "Hello World" page.

Step 3: Pass environment variables

Containers are useless without configuration. Here's how to pass environment variables using the CLI:

az container create \
  --resource-group my-aci-rg \
  --name my-env-container \
  --image mcr.microsoft.com/azuredocs/aci-helloworld \
  --environment-variables 'MESSAGE=Hello from ACI' 'SECRET_KEY=xyz' \
  --restart-policy Never

For secrets, use --secure-environment-variables to hide values from logs and az container show output.

Step 4: Use a private Azure Container Registry image

If your image is private, you need to authenticate. The easiest way is to use ACR admin credentials or a managed identity. With the CLI:

az container create \
  --resource-group my-aci-rg \
  --name my-private-app \
  --image myregistry.azurecr.io/myapp:v1 \
  --registry-login-server myregistry.azurecr.io \
  --registry-username myregistry \
  --registry-password $(az acr credential show --name myregistry --query passwords[0].value --output tsv)

Pro tip: For production, prefer a managed identity instead of hard-coding registry credentials. It's more secure and avoids password rotation headaches.

Step 5: View logs

Debugging is crucial. To see output from a running or stopped container:

az container logs --resource-group my-aci-rg --name my-hello-world

If your container exits, use az container attach for interactive output.

Compare options / when to choose what

ACI is not the only way to run containers in Azure. Here's how it stacks up against common alternatives:

When to choose ACI: - You have one or a few containers that don't need dynamic scaling. - You want per-second billing with no cluster management. - You need to run a batch job or a CI/CD test container. - You want to quickly test an image in production-like settings.

When to consider alternatives: - If you need zero-downtime rolling updates and autoscaling, AKS is better. - If you're building a typical web app with deployment slots, App Service may be simpler.

Troubleshooting & edge cases

Even with a simple service, issues happen. Here are common errors and fixes:

• Error: The resource type Microsoft.ContainerInstance/containerGroups could not be found — This usually means the region doesn't support ACI. Check the region in your resource group or use a supported region like eastus, westeurope, or southeastasia.

• Container exits immediately with CrashLoopBackOff — If your container crashes because the entrypoint fails, check logs with az container logs. The restart policy OnFailure or Never lets you inspect the state after the crash. For example, if a script needs an environment variable, you'll see a missing variable error in the logs.

• DNS name label already taken — ACI requires globally unique DNS labels (FQDN). If you get The DNS name label 'xyz' is not available, change the label to something unique or use an IP address instead of an FQDN.

• Cannot pull private image — An InaccessibleImage error means ACI can't authenticate. Double-check your registry credentials or the admin user on ACR. If you use a managed identity, ensure you assigned it during deployment.

• Resource limits too low — If your container needs more than the defaults, specify --cpu and --memory explicitly. ACI charges only for what you allocate — there's no reason to run with 0.5 CPU if you actually need 2.

• Public IP vs FQDN confusion — The IP address is assigned at creation time and remains unless you delete the container group. If you need a stable hostname, use the DNS label; otherwise, you'll have to update DNS records each time you recreate the group.

What you learned & what's next

In this lesson, you've learned how to deploy containers to Azure Container Instances — from the core mental model (serverless containers) to creating a container group with the CLI, passing environment variables, using private registries, and troubleshooting common issues. You now know how to explain the core idea behind ACI (objective 1) and complete a practical deployment exercise (objective 2).

Key takeaways to remember: - ACI is the fastest way to run a container in Azure with zero infrastructure management. - You control CPU, memory, and restart policy at deployment time. - Environment variables (including secure ones) make images reusable. - Private images require authentication — use managed identity for production. - Logs are your first tool for debugging; restart policy controls post-exit behavior.

What's next: In the next lesson, you'll learn how to integrate ACI with Azure Container Registry for a complete CI/CD pipeline — building, pushing, and deploying in one flow. This will connect the container lifecycle from code to production.

Practice recap: To solidify your learning, deploy the aci-helloworld container in a new resource group, pass a custom environment variable, and verify it appears on the web page. Then, create a container from your own Docker image pushed to ACR (even a simple Python script that prints a message) and collect its logs.

Now you have a reliable, fast path to container deployment in Azure. Go deploy something!