Create a container instance

Creating an instance needs the containerinstance/write permission in the resource group; the Owner, Contributor, Apps Operator and Blueprints Operator roles have it.

Open the wizard

In the portal at https://portal.example.com, open Container Instances in the sidebar and choose Create Container Instances. The Create Container Instance wizard has six steps: Basics, Image, Runtime, Compute, Networking and Review. Next checks a step before it moves on, and Submit on the last step creates the instance.

The wizard creates one component, main, with one container. More components, containers, endpoints and volumes can be added once the instance exists.

Basics

• Instance name — 3 to 50 characters: lowercase letters, digits and hyphens, not starting or ending with a hyphen, and unique in the resource group. Start it with a letter: a name that starts with a digit is accepted, but Kubernetes refuses the in-cluster name of a component with ports, and the instance ends in Error without a message that says why. The name cannot be changed later; it is part of the instance's in-cluster names and of its default hostname.
• Boundary, Cluster and Resource group — where the instance runs. Each is filled in for you when there is only one choice.

Image

• Image — the repository, without a tag or digest: ghcr.io/acme/worker. Lowercase; the registry host may carry a port, as in registry.example.com:5000/team/worker.
• Tag — a tag such as 1.4.2 (the default is latest), or a digest written sha256: followed by 64 hexadecimal characters. A tag is turned into a digest when the instance is deployed, so a newer image pushed under the same tag is not picked up until you re-deploy — see Images and updates. A digest pins the image exactly.
• Private registry — keep Public image — no credentials needed for a public image. For a private image, choose the registry to pull through. The list shows the private registries connected as deployment sources in the boundary; connect one first under Deployment sources — see Private registry. The instance stores only which source to use, never the credentials. Using a source needs kernel/deployments/read on the boundary; without it the platform refuses to create the instance, and later to save changes to it.

Runtime

• Environment variables — choose Add variable, give it a Name and pick its Source: Literal with a Value, or Vault secret with a vault and a key. A literal value is stored in plain text and shows in the revision history, so use a vault secret for anything sensitive. Import .env replaces the literal variables with the contents of a .env file and keeps the vault-backed ones.
• Command and Arguments — Command replaces the image's ENTRYPOINT, Arguments its CMD. Leave both empty to run the image as it was built.

A container that uses a vault secret must declare its command — the image's ENTRYPOINT — because the platform delivers the values by wrapping it; the step says so when it is missing. See Declare the command.

Creating the instance gives its identity Secrets Reader on every vault a variable references, using your permissions: you need the Owner role on the vault, its resource group or the boundary, assigned to you directly or activated through just-in-time access. If you do not have it, the step offers to request temporary access, and the platform refuses the create until you have it — see When it happens for you. Every later save of the instance makes the same grant again, so it needs the same role — see Permissions.

Compute

• Compute plan — how much CPU and memory the component gets; each card shows the plan's name, CPU and memory. The plans are listed in Compute plans. When the boundary restricts which plans may be used, the others are shown but cannot be chosen, with the reason.
• Replicas — how many copies of the component to run, 0 to 10. With 0 the instance is created stopped.

Networking

• Ports — the ports the container listens on, each with a Name, a Port number and a Protocol (TCP or UDP). The wizard starts with one TCP port named http on 8080. A port name is up to 15 lowercase letters, digits or hyphens, starting with a letter. A worker that listens on nothing can have no ports. A declared port is reachable inside the boundary whether or not it is exposed — see How an instance is reached.
• Expose publicly — off by default, which keeps the instance internal. Turned on, the instance gets an HTTPS endpoint named web.
• Port to expose — shown when the container has more than one TCP port: the port the endpoint sends traffic to. A UDP port cannot be exposed here.
• Custom hostname (optional) — leave it empty to use the platform hostname shown under Public URL, or enter your own domain, which needs a DNS record pointing at the platform before its certificate can be issued. See Hostnames.

Load balancer endpoints, path routing and sign-in protection are added later, on the Endpoints tab.

Review

Review shows the image, compute, networking and runtime settings. Submit creates the instance and returns to the list. The instance is Creating until its pods are ready and then Running; follow it on the instance's Operations tab — see Operations.

With the CLI

The CLI and the API take the instance as the platform stores it: a list of components and a list of endpoints. Save the definition as a file:

{
  "components": [
    {
      "name": "main",
      "replicas": 1,
      "startupOrder": 1,
      "computePlan": "small",
      "containers": [
        {
          "name": "main",
          "image": "ghcr.io/acme/worker",
          "tag": "1.4.2",
          "ports": [{ "name": "http", "port": 8080, "protocol": "TCP" }]
        }
      ]
    }
  ],
  "endpoints": [
    { "name": "web", "component": "main", "port": "http", "expose": "ingress" }
  ]
}

and create the instance from it:

stsh ci create worker -g my-resource-group -c my-cluster --file instance.json

A container pulls through a private registry when its sourceRef is the id of that deployment source. An ingress endpoint without a hostname gets the platform hostname.

Next steps

• Add an endpoint
• Manage components
• View logs and open a terminal