Template format

Document

A template is one YAML or JSON document. Unknown fields are errors.

A minimal template:

apiVersion: blueprints.stackship.se/v2
kind: BlueprintTemplate

metadata:
  slug: hello
  title: Hello
  version: "1.0.0"
  category: Tools
  tags: [example]

parameters:
  - name: ingress_host
    type: String
    label: Public Hostname
    default: "[%name%].{{domain_suffix}}"

instance:
  components:
    - name: web
      computePlan: small
      containers:
        - name: web
          image: docker.io/nginxinc/nginx-unprivileged
          tag: "1.31-alpine"
          ports:
            - name: http
              port: 8080
          probes:
            readiness:
              type: http
              port: http
              path: /
  endpoints:
    - name: web
      component: web
      port: http
      hostname: "[%ingress_host%]"

Metadata

Managed resources

Each entry in resources asks the platform to provision a resource before the container instance is created, and to write its connection details into the instance vault. Every field accepts tokens.

A postgres resource exposes these outputs:

The deploy waits up to five minutes for the database to accept connections before it creates the container instance. A container reads a detail through a secretRef to the instance vault:

resources:
  - name: db
    type: postgres
    availability: "[%db_availability%]"
    storage: 10Gi
    exposes:
      - output: connectionString
        vaultKey: connectionstring_db

env:
  - name: ConnectionStrings__Default
    secretRef: { vault: "[%instance_vault%]", key: connectionstring_db }

Outputs

Each entry in outputs has a name, a label, a description, a type — string (the default) or url — a secret flag, and a value with tokens. Outputs are stored with the template, but the portal does not show them anywhere today.

Instance

instance is the container instance to create: components and endpoints, in the shape the Container Instances API accepts. What each setting does is described with container instances — see Create a container instance and Endpoints. The instance's own rules, such as at most 16 components and 0 to 10 replicas, are applied when the deploy creates it.

• sourceRef names a private registry connected to the boundary that the image is pulled through — usually a DeploymentSource parameter, sourceRef: "[%registry%]". Empty means a public image.
• A container reads a secret through secretRef with vault: "[%instance_vault%]" and the parameter's name, or the vaultKey of a resource output, as key. vault must be exactly "[%instance_vault%]"; a template that names any other vault is rejected.
• The deployer's Compute step sets computePlan and replicas per component; the template's values are the defaults it shows.
• minComputePlan is the smallest plan a component runs on. The Compute step disables plans with less CPU or less memory, and the deploy refuses them. Set it for components that fail on a small plan, so a deployer who does not know the sizes cannot pick one.

Conditions

condition on a component, a container, an init container or an endpoint names a Boolean parameter. Unless that parameter is true, the element is left out before anything else is rendered, and an endpoint whose component was left out goes with it. A condition naming a parameter that does not exist counts as off.

Warning

The portal's Compute step sends settings for every component the template declares. When a component's condition leaves it out, a deploy from the portal fails at Create the container instance with The template has no component named '<component>'. Gate containers, init containers or endpoints rather than whole components where you can.

Tokens

[%parameter%] in any string of instance and resources — keys of a files volume included — is replaced at deploy time.

• [%name%] is the instance name and [%instance_vault%] the instance vault's name. A template that declares parameters with these names is rejected.
• [%parameter:type:default%] uses default when there is no parameter of that name.
• [%parameter_urlencoded%] is the parameter's value URL-encoded, for building URIs from generated passwords.
• Parameter defaults may contain tokens too, such as default: "[%name%].example.com".
• A token with nothing to fill it is left in place exactly as written.

A token puts the value into the container instance's own settings as plain text, readable by anyone who can read the instance. Pass secrets through secretRef, never as a token in an env value.

Platform values

When the platform reads a template from a repository — the platform catalog or a catalog source — it replaces two values in parameter defaults, output values and endpoint hostnames and issuers:

A template saved through the API is stored as sent: write these values out in full there.

Repository layout

A repository publishes one blueprint per directory, under the folder the source or the platform catalog points at:

blueprints/
  my-app/
    template.yaml
    icon.svg
  my-db/
    template.yaml

• The directory name is the blueprint's slug, whatever metadata.slug says.
• The icon is the first of icon.svg, icon.png, icon.jpg or icon.webp found next to template.yaml. Without one, metadata.icon is used.
• Every directory is read as a blueprint. One without a template.yaml, or with one that does not parse, is skipped and the others still load.
• Submodules are not cloned.