Deploy a blueprint

Every deploy needs blueprints/read on the boundary and containerinstance/write in the resource group. A blueprint with secrets or a database needs more; the wizard checks all of it before anything is created — see Preflight checks, and Permissions for the full list.

Find a blueprint

Open Blueprints in the sidebar of the portal at https://portal.example.com. Each card shows the blueprint's icon, name, description, category, version, a few of its tags, how many components it has, and a Deploy button — shown only to people who hold containerinstance/write on the boundary. A blueprint published from one of your boundary's repositories also shows that repository.

• Search blueprints… matches names, descriptions, categories and tags; every word you type must match.
• The row of tags filters the catalog. Choosing several tags shows blueprints that carry any of them; Clear filters resets the search and the tags.
• When the catalog has more than one category, tabs across the top narrow it to one; All shows everything.
• Blueprints tagged stackship lead under Spotlight, with a Stackship badge. The rest follow under More blueprints.

Choose Deploy on a card. The wizard, Deploy <blueprint>, has five steps.

Overview

The blueprint's description, category, version and tags, and a link to its documentation. When the blueprint provisions managed resources, What this creates lists each of them and the components that read it.

Name and placement

Basic Configuration asks for:

• Instance Name — 3 to 50 lowercase letters, digits and hyphens. Start it with a letter and end it with a letter or digit, even though the field accepts a leading digit or a hyphen at either end: each component is reached at <instance>-<component>, which is a Kubernetes Service name and must start with a letter, and a name with a hyphen at either end passes the checks but fails the deploy when its first resource is created. The name must be free in the resource group. It becomes the container instance's name and prefixes everything else the blueprint creates — <instance>-secrets for the vault, <instance>-<resource> for each managed resource.
• Boundary, Cluster and Resource group — where the instance and everything the blueprint creates will live. Each is filled in for you when there is only one choice.

Caution

Only the instance name is checked for being free. A vault named <instance>-secrets or a database named <instance>-<resource> that already exists in the resource group is used as it is, not refused: the deploy writes its secrets into that vault as new versions of any keys already there, gives the new instance's identity Secrets Reader on the whole vault — so it can read every secret already in it, not only the blueprint's — and gives the new instance that database's connection details. Check the resource group for those names before you deploy.

Parameters

Configuration shows the blueprint's parameters, each as a field of its type:

• A field you leave empty takes the blueprint's default.
• Parameters the blueprint marks as advanced, and secrets it can generate, are collapsed under Advanced settings. Unless you open it and set them, the defaults apply and the secrets are generated.
• Values the platform composes itself — signed keys, connection strings built from a generated password — are not fields at all. A line under the form says how many of them are generated on deploy and stored in the instance's vault.

Secret values are written to the instance's vault, never into the container instance itself. Every attribute a parameter can have is described in Parameters.

Compute

Compute has one row per component, with its Compute Plan and Replicas prefilled with the blueprint's defaults. Plans are listed with their CPU and memory.

• When the boundary's compute plan policy does not permit a component's default plan, its row starts empty and says so; choose one of the plans the policy permits.
• When the blueprint sets a minimum plan for a component, its row says Minimum: <plan>, and plans with less CPU or less memory are listed as Below this blueprint's minimum and cannot be chosen. The deploy refuses a smaller plan too, before it creates anything.
• Replicas can be 0 to 10, and a component with a persistent volume runs at most one. The field does not stop a higher number; the deploy then fails at Create the container instance, after the vault and any database have been created.

Preflight checks

Review & Deploy summarises the instance name, resource group and parameters. Secrets you entered show as Provided; secrets that will be generated show as Will be generated.

Under Before you deploy, the platform checks everything the deploy will need, in the order it will need it, and without creating anything. The checks run again when you change the name or the resource group, and Submit is disabled while any of them fails.

A refused permission says Ask an owner for <action> at <scope>. An Owner of that scope can assign you a role that includes it, or you can ask for a role for a few hours with Just-in-time access.

The vault grant has its remedy in place: Request temporary access files a request for Owner on the new vault, and the box follows it. Once an owner has approved it, choose Activate access; the checks run again and Submit becomes available.

Important

The grant itself is made only by someone who holds Owner or Platform Owner at or above the vault, assigned to them directly or activated through just-in-time access. Owner held through a group, or a custom role that carries rbac/members/write, passes the check but not the grant: the deploy then fails at Create the container instance or Grant the instance access to its vault, after the vault, its secrets and any database have been created, and files the Owner request for you. Activate it and retry.

The checks cover permissions and names, not the rest of the configuration. Reading a managed database's connection details also needs postgrescluster/readSecrets on it, which is not checked in advance, and the container instance's own rules — replicas, plans, ports — are applied when it is created. When the checks cannot be run at all, the page says The checks could not be run and Submit stays available; the deploy runs the same checks and refuses if anything is missing.

A blueprint's containers read secrets only from the instance vault. A template that names any other vault is rejected when it is published, and one stored before that rule is refused by the checks and by the deploy, before anything is created.

Caution

A blueprint from a catalog source or the templates API is written by whoever can publish to the boundary, and its images run with read access to the instance vault, granted with your permissions. Review its template before you deploy it.

Deploy and follow it

Choose Submit. The deploy is accepted at once and you land on its page, Deploying <instance>:

• Summary — the attempt number, Resource group, Instance, who started it (Started by), when it was Accepted and Finished, and on a retry, a link to the previous attempt.
• Steps — each step as it runs, updated live.
• Outcome — success, or Failed at <step> with the error.

When the deploy succeeds, Open instance takes you to the container instance. The deploy is also recorded among the boundary's operations.

Retry a failed deploy

Retry deploy runs a failed deploy again as a new attempt of the same deploy: the same instance name, parameters and compute, with the blueprint as it is in the catalog now. The vault and any database the failed attempt created are reused, not created again. The secrets are written again: values you entered stay the same, and values the platform generates are generated afresh and stored as new versions.

When the failure was the vault grant, the page shows the same Request temporary access box as the wizard, and Retry deploy becomes available once your access is active.

A retry cannot change the inputs. To change them, deploy the blueprint again with the same instance name: what the failed attempt left in the resource group is reused in the same way. If you give up instead, delete what was left.

Important

Deploys are listed per boundary. Anyone with blueprints/read on the boundary can see every deploy in it, whatever the resource group, with its error, and can retry any failed one. A retry skips the checks above, runs with the permissions of whoever retries it, and reuses the original deployer's parameters — secret values they entered included, which are written into the vault again.

With the CLI

stsh blueprint catalog                          # the catalog
stsh blueprint catalog supabase                 # one blueprint, with its parameters
stsh blueprint deploy supabase my-supabase -g my-resource-group -c my-cluster --dry-run
stsh blueprint deploy pocketbase my-pocketbase -g my-resource-group -c my-cluster --set storage_size=10Gi
stsh blueprint deploys list
stsh blueprint deploys get <deployment-id>
stsh blueprint deploys retry <deployment-id>

• deploy takes the blueprint's slug and the instance name. Set parameters with --set name=value, repeated, or from a JSON object with --file. A value that reads as JSON is sent as JSON, while parameters are strings — quote such values: --set theme_enabled='"true"'.
• The CLI deploys every component with the blueprint's own compute defaults.
• --dry-run prints the preflight checks and exits without creating anything. When the vault grant is refused, it offers to file the access request for you.
• --wait-for-access files that request if it is needed, waits for an owner to approve it, asks before activating it, and then deploys in the same run.
• deploy and deploys retry follow the operation until it finishes; --no-wait returns as soon as the deploy is accepted.

deploy_not_accepted

503 on these routes:

Every deploy is followed as an operation, and a deploy that cannot be followed is not started: this code means the operation could not be opened, so the deploy was not accepted. Nothing was created and no deploy was recorded; on a retry, the failed deploy stays as it was. A dry run never returns it, and a deploy returns it only after every preflight check has passed.

A production platform replaces the body of every 5xx answer, so the body names only the code and the advice is here rather than in the answer:

{
  "error": "An internal error occurred.",
  "code": "deploy_not_accepted",
  "module": "blueprints",
  "correlationId": "3f2b9c1e-6d4a-4e0b-9a51-2c7d8e0f4b6a"
}

Try again: submit the deploy again, or retry the failed deploy again — see Retry a failed deploy. That is safe, because nothing was started. If the operation was opened but its answer did not arrive, the boundary's operations show an extra deploy operation for the instance, which becomes Superseded when you try again. If the code keeps coming back, report it with the correlationId.

Next steps

• After a deploy — the instance, its vault and its databases
• Permissions