Provisioning a Container Instance

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

2. Create a Resource Group

Next we can create the Resource Group using the Azure CLI, which we can do in a new tab/window in the terminal by running:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

With the Resource Group created, we can confirm it exists via:

and we should see:

[
  {
    "note": "some fields skipped for brevity",

    "id": "/subscriptions/07a602cc-fbac-427d-8eaa-9cb80ae6f50d/resourceGroups/sample-resources",
    "location": "berlin",
    "name": "sample-resources",
    "properties": {
      "provisioningState": "Succeeded"
    },
    "type": "Microsoft.Resources/resourceGroups"
  }
]

3. Create the Container Group

Next we can create the Container Group within this Resource Group. For the purposes of this guide we're going to use the image traefik/whoami which echoes the request details back, but you can pick any container image:

Which when provisioned should show:

{
  "note": "some fields skipped for brevity",

  "id": "/subscriptions/07a602cc-fbac-427d-8eaa-9cb80ae6f50d/resourceGroups/sample-resources/providers/Microsoft.ContainerInstance/containerGroups/sample-aci",
  "ipAddress": {
    "dnsNameLabel": "sample-aci",
    "fqdn": "sample-aci-berlin.gondola.locally",
    "type": "Public"
  },
  "name": "sample-aci",
  "provisioningState": "Succeeded",
  "type": "Microsoft.ContainerInstance/containerGroups"
}

4. Find it in the Dashboard

We can find that resource in the Locally Dashboard too:

With the Container Instance provisioned, we can retrieve it again at any point using az container show:

Which returns the same Container Group we just created:

{
  "note": "some fields skipped for brevity",

  "containers": [
    {
      "image": "traefik/whoami:latest",
      "name": "sample-aci"
    }
  ],
  "id": "/subscriptions/07a602cc-fbac-427d-8eaa-9cb80ae6f50d/resourceGroups/sample-resources/providers/Microsoft.ContainerInstance/containerGroups/sample-aci",
  "ipAddress": {
    "fqdn": "sample-aci-berlin.gondola.locally"
  },
  "name": "sample-aci",
  "provisioningState": "Succeeded"
}

5. Reach the running container

Locally actually runs the container, rather than just recording that you asked for one - so we can make a request to it and get a response back.

To find the address it's listening on, start with the hostname, which is in the Container Group's ipAddress.fqdn:

Which gives us:

sample-aci-berlin.gondola.locally

Two things worth knowing about that address:

1. The hostname comes from the --dns-name-label we passed, combined with the location. Locally runs its own DNS server, which is what resolves it on your machine - there's no hosts file to edit, and nothing to configure beyond having run Locally Setup.
2. The port is assigned when the container starts, so it can differ from the 80 we asked for, and will change if you recreate the Container Group. You'll find it on the Container Group's resource page in the Locally Dashboard - see the Container Instances Emulator for where.

Since traefik/whoami echoes back the details of whatever request it receives, we can make a request to the container, using the port from the Dashboard:

And the container answers:

Hostname: sample-aci-sample-aci-berlin
IP: 127.0.0.1
IP: ::1
IP: 10.88.0.4
RemoteAddr: 10.88.0.4:34176
GET / HTTP/1.1
Host: sample-aci-berlin.gondola.locally:53606
User-Agent: curl/8.7.1
Accept: */*

If you get a connection error on the first try, give it a few seconds - the container image may still be being pulled - and try again.

6. List the Container Groups

We can also list every Container Group within the Resource Group, which is useful once you've got more than one of them:

Since the full JSON is a little verbose, it's often easier to pick out just the fields you care about using the Azure CLI's --query argument:

Which gives us:

Name        Location    State
----------  ----------  ---------
sample-aci  berlin      Succeeded

7. Tidy up

Finally, we can tidy up after ourselves. To remove just the Container Group:

Or to remove the Resource Group and everything within it:

There's nothing billable to clean up, since everything ran on your machine, but it's still worth checking your teardown scripts work here before you run them against Azure.

We can confirm the Resource Group is gone with:

Which should now return an empty list:

[]

Doing this with other tooling

Whilst this guide used the Azure CLI, Container Instances work the same way through any of the tooling that Locally supports - a Microsoft.ContainerInstance/containerGroups resource in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way, with only the location changed.

Next steps

The Container Instances Emulator covers what runs and what's accepted but ignored. To run your own images, push them to a Container Registry, or see Container Apps.

Should you encounter any issues, please take a look at the troubleshooting section.