Blueprint - Ryvn

Blueprints package multiple services together as a reusable deployment unit with configurable inputs. They enable you to create templates for common deployment patterns and allow customization at install time.

# backend-stack.blueprint.yaml
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Blueprint
metadata:
  name: backend-stack
spec:
  description: "Backend API and worker services"
  displayName: "Backend Stack"
  installations:
    - service: api
    - service: worker
  inputs:
    - name: replicas
      type: number
      displayName: "Number of Replicas"
      description: "How many instances to run"
      default: 2

# backend-stack-production.blueprintinstallation.yaml
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: BlueprintInstallation
metadata:
  name: backend-stack-production
spec:
  blueprint: backend-stack
  environment: production
  inputs:
    - name: replicas
      value: 5

Blueprint functions

Blueprints support special functions for accessing user inputs and environment properties during configuration.

For generic template functions like toYaml, lower, join, etc., see Template Functions.

`input`

Access user-provided blueprint input values.

config: |
  replicas: {{ input "replicas" }}
  storage_size: {{ input "storage_size" }}
  api_key: {{ input "api_key" }}

Environment functions

These functions provide information about the target environment during blueprint installation:

`EnvironmentName`

Returns the name of the environment where the blueprint is being installed.

config: |
  environment: {{ EnvironmentName }}
  log_prefix: {{ EnvironmentName }}-app

`EnvironmentProviderType`

Returns the cloud provider type: "aws", "gcp", or "azure".

condition: '{{ eq EnvironmentProviderType "aws" }}'

`EnvironmentOrgId`

Returns the organization ID.

config: |
  org_id: {{ EnvironmentOrgId }}

`EnvironmentNamespace`

Returns the default namespace for the environment, which is named after the environment. Use it inside config and other templated fields. The installations[].namespace field itself is a literal and is not templated; omit it to install into the default namespace.

config: |
  target_namespace: {{ EnvironmentNamespace }}

`EnvironmentReleaseChannel`

Returns the release channel (e.g., “stable”, “beta”).

config: |
  release_channel: {{ EnvironmentReleaseChannel }}
  enable_experimental: {{ ne EnvironmentReleaseChannel "stable" }}

Conditionals

Blueprints support conditionals for dynamic configuration based on user inputs and environment properties.

Important: Blueprint functions (input, Environment*) are evaluated when blueprint is installed or when blueprint inputs are changed, while .ryvn references are evaluated at deploy-time. You cannot mix blueprint functions and .ryvn syntax in the same conditional statement.

# (✓) Supported - Using only blueprint functions
{{ if eq EnvironmentProviderType "aws" }}

# (✓) Supported - Using only .ryvn syntax
{{ if eq .ryvn.env.provider.type "aws" }}

# (x) Not supported - Mixing both in same conditional
{{ if and (eq EnvironmentProviderType "aws") (eq .ryvn.env.name "production") }}

Conditional installations

Control which services are installed based on inputs or environment:

installations:
  # Only install on AWS
  - service: aws-specific-service
    condition: '{{ eq EnvironmentProviderType "aws" }}'

  # Only install when feature is enabled
  - service: optional-feature
    condition: '{{ eq (input "enable_feature") "true" }}'

  # Complex condition combining multiple checks
  - service: advanced-monitoring
    condition: '{{ and (eq (input "tier") "enterprise") (ne EnvironmentProviderType "gcp") }}'

Conditional configuration

Use conditionals within configuration blocks:

installations:
  - service: database
    config: |
      replicas: {{ input "replicas" }}
      {{ if eq EnvironmentProviderType "aws" }}
      storage_class: gp3
      availability_zones:
        - us-east-1a
        - us-east-1b
      {{ else if eq EnvironmentProviderType "gcp" }}
      storage_class: pd-ssd
      availability_zones:
        - us-central1-a
        - us-central1-b
      {{ else if eq EnvironmentProviderType "azure" }}
      storage_class: managed-premium
      availability_zones:
        - eastus-1
        - eastus-2
      {{ end }}

Conditional inputs

Show inputs based on other input values:

inputs:
  - name: database_type
    type: string
    displayName: "Database Type"
    default: "internal"

  # Only show when external database is selected
  - name: external_host
    type: string
    displayName: "External Host"
    condition: '{{ eq (input "database_type") "external" }}'

  # Only show for premium tier
  - name: ha_enabled
    type: boolean
    displayName: "High Availability"
    condition: '{{ eq (input "tier") "premium" }}'

Branch deployments

Add a branches list to give each git branch its own release line. A push to a listed branch produces a release on the auto-created branch:{name} channel; pushes to unlisted branches don’t produce a release.

spec:
  branches:
    - name: main
    - name: develop

Each branch’s releases are versioned independently (e.g. 1.0.0-main, 1.0.0-develop). To install, set the BlueprintInstallation’s branch to the branch you want to track.

Release versions

By default Ryvn numbers blueprint releases automatically: every sync that changes the blueprint definition bumps the version according to the detected change class, and a sync that leaves the definition unchanged produces no release. Set spec.version to publish a release under an exact version you choose instead:

spec:
  version: 1.4.0

The value is an exact SemVer version X.Y.Z with an optional pre-release suffix such as 1.4.0-rc.1. A v prefix, ranges, partial versions like 1.4, build metadata (+...) and preview.* pre-releases are rejected.
Omit spec.version to keep automatic numbering. ryvn get blueprint <name> -o yaml returns the stored source, so spec.version in that output tells you whether a blueprint uses an exact version; ryvn describe blueprint and the blueprint definition page show the version of the latest release.
Publishing identical content under a version that already exists reuses that release (unchanged). Publishing different content under an existing version is refused as a conflict, and a version that has been retired is refused as retired. Neither falls back to an automatic number: fix or change spec.version and sync again.
ryvn plan lists the release as a BlueprintRelease entry named by the requested version under the blueprint: create when the version is free, unchanged when an identical release already holds it, or blocked with the reason when it cannot be published as-is (a different definition holds the version, or the version is retired). Changing spec.version without changing the definition is still shown as a change. After a sync, the published release appears the same way under the blueprint in CLI output and on the Git Sync pages, with its version, action and release ID.
Pull request previews keep their generated -preview.* identity and never consume the stable version; spec.version is published only when the pull request merges to the source branch.
Maintenance versions are allowed: publishing 1.4.3 after 2.0.0 exists creates the release, but it does not become the head of a channel that already carries a higher version.
Git sync converges on the current commit: when several commits land before a pull sync runs, intermediate commits may be skipped and only the resulting spec.version is published.
Any service, release channel, promotion pipeline or blueprint referenced by the source must already exist. A blueprint that first appears in a pull request has no existing blueprint to preview against, so the pull request check reports it as skipped and its first release is published when the pull request merges.

Publishing from source versus importing a release

Setting spec.version publishes from the synced source. To bring an existing release to another hub without a source repository, export it and import the document as-is:

ryvn get blueprint-release 1.4.0 -b redis -o json > redis-1.4.0.json
ryvn create blueprint-release -f redis-1.4.0.json

The document names the blueprint and the exact version and carries the full definition:

{
  "blueprint": "redis",
  "version": "1.4.0",
  "definition": {
    "description": "Redis cache",
    "inputs": [{ "name": "replicas", "type": "number", "default": 1 }],
    "installations": [
      { "name": "cache", "service": "redis", "releaseChannel": "stable" }
    ]
  }
}

The import follows the same rules as source publishing: identical content is unchanged, different content under the same version is a conflict. It never activates a channel or installation; promote the release afterwards with ryvn promote release --blueprint=redis --version=1.4.0 --target=<channel>. A blueprint whose releases are created or imported this way must stay outside the paths that git sync manages, because a synced source would otherwise republish and overwrite the manual definition.

Composing blueprints

An installations entry is either a service (service:) or another blueprint (blueprint:). A blueprint: entry installs the named blueprint as a child, so you can assemble a bundle from smaller reusable blueprints instead of re-declaring their services. Consumers install the parent like any other blueprint (see BlueprintInstallation); the children come with it.

kind: Blueprint
metadata:
  name: langfuse
spec:
  description: "Langfuse with a managed Postgres child"
  inputs:
    - name: tier
      type: string
      default: small
    - name: postgres_password
      type: string
      isSecret: true
      generated:
        type: random-string
        length: 32
  installations:
    # Nested blueprint child
    - blueprint: postgres
      alias: db
      name: '{{ ParentInstallationName }}-db'
      releaseChannel: stable
      inputs:
        - name: database_name
          value: langfuse
        - name: size
          valueFromInput: tier
        - name: password
          valueFromInput: postgres_password  # secret input flows down

    # Sibling service consuming a child output
    - service: langfuse-app
      name: '{{ ParentInstallationName }}'
      env:
        - key: DATABASE_URL
          valueFromOutput:
            blueprintInstallation: db
            name: connectionString

Passing inputs down

Each entry in a child’s inputs list sets one of the child blueprint’s inputs, using either a literal value or valueFromInput to forward one of the parent’s inputs. Forwarded secret inputs stay in the secrets system end to end; a secret parent input cannot feed a non-secret child input. valueFromOutput is not supported as a child input source. If a child needs a value produced by another installation, re-expose that value through the producing blueprint’s outputs and consume it from there.

Consuming child outputs

Sibling installations read a child’s outputs with valueFromOutput and blueprintInstallation: <alias>, as in the example above. Non-secret outputs are also available in templates as {{ (blueprintInstallation "db").outputs.<name> }}. The parent can re-expose a child output in its own outputs:

outputs:
  - name: db_host
    type: string
    from: '{{ (blueprintInstallation "db").outputs.host }}'

Release selection

A child follows the head of a release channel. The channel is resolved in order: the child entry’s releaseChannel (or branch), then the channel the parent installation is on, then the environment’s default channel. Blueprints from the marketplace or another organization’s catalog follow that organization’s stable channel, and a private blueprint owned by another organization requires an accepted share.

Naming

The child installation gets the name you set (default: the blueprint’s name), with no automatic prefix. All service installations in an environment share one name namespace and a collision fails the install, so template child names with {{ ParentInstallationName }} to keep each parent’s children unique.

Lifecycle

Children install, upgrade, and uninstall with the parent. Each child is its own blueprint installation, linked to its parent in the dashboard and in ryvn describe blueprint-installation. Editing a child installation directly excludes it from future parent updates; it shows as “excluded from blueprint updates”.

Blueprints can nest up to 3 levels deep, and cycles are rejected. On a child entry, releaseChannel and branch are mutually exclusive.

Properties

`name`

string — required Unique identifier for this blueprint. Used to reference the blueprint from environments.

name: backend-stack

`description`

string — required Detailed description of what this blueprint provides and its purpose.

description: "Backend API and worker services"

`displayName`

string — optional Human-readable name displayed in the UI. If not provided, the name is used.

displayName: "Backend Stack"

`distribution`

string — optional, default private How the blueprint is published. One of:

private: visible only to the owning organization. Share it with other organizations through a resource share; consumers install it on the release channel the share names.
marketplace-unmanaged: listed in the Blueprint Marketplace without Ryvn maintenance guarantees.
marketplace-managed: listed in the marketplace and maintained by Ryvn.

distribution: private

`version`

string — optional Exact SemVer version (X.Y.Z with an optional pre-release suffix) to publish the next release under. Omit to number releases automatically. See Release versions.

version: 1.4.0

`promotionPipeline`

string — optional Name of the promotion pipeline to apply to this blueprint. All releases of this blueprint will follow the pipeline’s promotion paths.

promotionPipeline: main-pipeline

`branches`

array — optional Configures per-branch release lines. See Branch deployments.

branches:
  - name: main
  - name: develop

`branches[].name`

string — required Name of the git branch. Each entry auto-creates a corresponding branch:{name} release channel; subscribe a BlueprintInstallation via its branch field.

- name: main

`installations`

array — required List of installations included in this blueprint. Each entry installs either a service (service) or a nested blueprint (blueprint). See Composing blueprints.

installations:
  - service: api
    config: |
      replicas: '{{ input "replicas" }}'
  - blueprint: postgres
    alias: db

`installations[].service`

string — required for service entries Name of the service to include in this blueprint.

service: api

`installations[].blueprint`

string — required for blueprint children Name of the blueprint to install as a nested child. See Composing blueprints.

blueprint: postgres

`installations[].releaseChannel`

string — optional, blueprint children only Release channel the child follows. If not set, the child uses the parent installation’s channel, then the environment’s default channel. Mutually exclusive with branch.

releaseChannel: stable

`installations[].branch`

string — optional, blueprint children only Branch release line the child follows (see Branch deployments). Mutually exclusive with releaseChannel.

branch: develop

`installations[].inputs`

array — optional, blueprint children only Values for the child blueprint’s inputs. Each entry has a name and exactly one of value (a literal) or valueFromInput (forward a parent input).

inputs:
  - name: database_name
    value: langfuse
  - name: password
    valueFromInput: postgres_password

`installations[].excludedInstallations`

array — optional, blueprint children only Names of installations inside the child blueprint to skip, like excludedInstallations on a BlueprintInstallation.

excludedInstallations:
  - name: metrics-exporter

`installations[].name`

string — optional Custom name for this installation. If not provided, the service or blueprint name is used.

name: api-server

`installations[].alias`

string — optional A stable reference handle for this installation within the blueprint, used by sibling valueFromOutput references and serviceInstallation / blueprintInstallation template functions. Defaults to name (or the service name when name is not set). Use alias when the installation name is dynamic (contains template expressions) or when conditional installations (e.g. different Terraform modules per cloud provider) should be referenced the same way by siblings:

installations:
  # Each provider-specific installation shares the same alias
  - service: postgres-rds
    name: '{{ ParentInstallationName }}'
    alias: postgres
    condition: '{{ eq EnvironmentProviderType "aws" }}'
    # ... provider-specific config

  - service: postgres-cloudsql
    name: '{{ ParentInstallationName }}'
    alias: postgres
    condition: '{{ eq EnvironmentProviderType "gcp" }}'
    # ... provider-specific config

  - service: postgres-flexible
    name: '{{ ParentInstallationName }}'
    alias: postgres
    condition: '{{ eq EnvironmentProviderType "azure" }}'
    # ... provider-specific config

  # Sibling references the stable alias — works regardless of provider
  - service: postgres-user-provisioner
    name: '{{ ParentInstallationName }}-users'
    env:
      - key: MASTER_HOST
        valueFromOutput:
          serviceInstallation: postgres
          name: host
      - key: MASTER_PASSWORD
        isSecret: true
        valueFromOutput:
          serviceInstallation: postgres
          name: password

Without alias, each conditional installation would have a different reference handle, forcing consumers to duplicate the provider condition in every reference.

`installations[].namespace`

string — optional Kubernetes namespace to install the service into. If not provided, uses the environment’s default namespace, which has the same name as the environment. Cannot be changed after install. See Namespaces.

namespace: backend

`installations[].condition`

string — optional Condition expression that determines whether this installation should be created. Supports template syntax with comparison operators.

condition: '{{ eq (input "storage_type") "s3" }}'

`installations[].config`

string or array — optional Configuration for the service installation. Can be a YAML string or array of config items. Supports templating with blueprint inputs.

config: |
  replicas: '{{ input "replicas" }}'
  storage:
    type: '{{ input "storage_type" }}'

`installations[].lifecycle`

object — optional Lifecycle hooks for an installation declared inside this blueprint. See Job installation › lifecycle for the full field reference.

Lifecycle hook targets must be job installations in the same environment, and only one hook is allowed per phase.

installations:
  - service: api
    name: api
    lifecycle:
      postInstall:
        - run: db-migrations
      postUpgrade:
        - run: db-migrations
      postUpdate:
        - run: db-migrations
  - service: db-migrations
    name: db-migrations

`installations[].dependencies`

array — optional Installation dependencies for a service child. The child’s first install waits until each entry is ready. Entries use the same serviceInstallation and service keys as a standalone installation (see server › dependencies); a serviceInstallation value may be a sibling child’s alias or name, which resolves to that child’s installation name. Values support blueprint templating. Not supported on nested blueprint: children. See Installation Dependencies.

installations:
  - service: postgres
    alias: db
    name: '{{ ParentInstallationName }}-db'
  - service: web
    name: '{{ ParentInstallationName }}'
    dependencies:
      - serviceInstallation: db  # sibling child, by alias
      - service: redis           # any ready redis installation in the environment

`installations[].secrets`

array — optional List of secrets for the service installation. Secrets can be generated or populated from blueprint inputs.

For server and job service types, prefer using secret environment variables via the env property instead of secrets, as they may conflict.

installations:
  - service: database
    secrets:
      - name: db-credentials
        generated:
          type: random-string
          length: 32

`installations[].secrets[].name`

string — required The name of the Kubernetes secret to create.

name: db-credentials

`installations[].secrets[].generated`

object — optional Configuration for auto-generating secret values. Cannot be used with values.

generated:
  type: random-string
  length: 32

Available generation types:

random-string — Generate a random alphanumeric string
random-bytes — Generate random bytes (base64 encoded)
rsa-key — Generate an RSA key pair
ec-key — Generate an EC key pair

The length property is only applicable for random-string and random-bytes types.

`installations[].secrets[].values`

array — optional List of individual secret key-value pairs. Each value can reference a blueprint input or generated input.

secrets:
  - name: external-db
    values:
      - key: password
        valueFromInput: db_password
      - key: username
        valueFromInput: db_username

  # Using a generated input
  - name: api-credentials
    values:
      - key: token
        valueFromInput: api_token  # References a generated input

`installations[].secrets[].valueFromInput`

string or object — optional Reference the entire secret value from a blueprint input. The input must be of type map and marked with isSecret: true. For generated string inputs, use values instead.

# As a string (shorthand)
secrets:
  - name: custom-credentials
    valueFromInput: credentials_map

# As an object
secrets:
  - name: custom-credentials
    valueFromInput:
      name: credentials_map

`installations[].env`

array — optional List of environment variables to pass to the service at runtime.

installations:
  - service: api
    env:
      - key: LOG_LEVEL
        value: debug
      - key: API_KEY
        valueFromInput: api_key

`installations[].env[].key`

string — required The name of the environment variable.

key: DATABASE_URL

`installations[].env[].value`

string — optional The static value of the environment variable.

env:
  - key: LOG_LEVEL
    value: info

`installations[].env[].valueFromInput`

string or object — optional Reference the value from a blueprint input.

env:
  - key: REPLICAS
    valueFromInput: replicas

  # Or as an object
  - key: REGION
    valueFromInput:
      name: aws_region

`installations[].env[].valueFromOutput`

object — optional Reference an output value from a sibling service installation or blueprint installation within the same blueprint. Use the sibling’s alias (or name) as the reference handle.

env:
  - key: DATABASE_URL
    valueFromOutput:
      serviceInstallation: postgres
      name: connection_string

  - key: CACHE_URL
    valueFromOutput:
      blueprintInstallation: redis-stack
      name: endpoint

Property	Type	Description
`serviceInstallation`	`string`	Name or alias of the sibling service installation
`blueprintInstallation`	`string`	Name or alias of the sibling blueprint installation
`name`	`string`	The output key to reference

Exactly one of serviceInstallation or blueprintInstallation must be specified.

`inputs`

array — optional List of input parameters that can be configured when installing the blueprint.

inputs:
  - name: replicas
    type: number
    displayName: "Number of Replicas"
    description: "How many instances to run"
    default: 2

`inputs[].name`

string — required Unique identifier for this input parameter.

name: replicas

`inputs[].type`

string — required Type of the input parameter. Valid values: string, number, boolean, array, map

type: number

`inputs[].isSecret`

boolean — optional (default: false) Whether this input contains sensitive data.

isSecret: true

`inputs[].displayName`

string — optional Human-readable name displayed in the UI. If not provided, the name is used.

displayName: "Number of Replicas"

`inputs[].description`

string — optional Detailed description of what this input is for.

description: "How many instances to run"

`inputs[].default`

any — optional Default value for the input. If not provided, the input is required at install time.

default: 2

`inputs[].group`

string — optional Name of the input group this input belongs to. Inputs in the same group are displayed together.

group: scaling

`inputs[].condition`

string — optional Condition expression that determines whether this input should be displayed. Supports template syntax.

condition: '{{ eq (input "storage_type") "s3" }}'

`inputs[].hidden`

boolean — optional (default: false) Hides this input from the Dashboard installation form. Useful for internal configuration values like system defaults or automation-managed settings.

hidden: true

inputs:
  - name: internal_api_endpoint
    type: string
    hidden: true
    default: "https://internal.api.example.com"
    description: "Internal API endpoint for service communication"

Hidden inputs can still be set when installing a blueprint via the API or IaC (Resources as Code).

`inputs[].generated`

object — optional Configuration for auto-generating input values. Generated inputs are automatically populated when the blueprint is installed. Useful for credentials, API keys, or unique identifiers.

inputs:
  - name: api_token
    type: string
    isSecret: true
    generated:
      type: random-string
      length: 32

Available generation types:

random-string — Generate a random alphanumeric string
random-bytes — Generate random bytes (base64 encoded)
rsa-key — Generate an RSA key pair
ec-key — Generate an EC key pair

The length property is only applicable for random-string and random-bytes types.

Generated values are preserved across blueprint updates. Users can force regeneration from the Dashboard if needed.

`inputs[].defaultFrom`

object — optional Pull the default value from an environment-scoped variable group when the blueprint is installed and no explicit value is provided. Only valid for map type inputs with isSecret: true. Mutually exclusive with default and generated.

inputs:
  - name: db_credentials
    type: map
    isSecret: true
    displayName: "Database Credentials"
    defaultFrom:
      variableGroup: db-credentials

When a blueprint with defaultFrom is installed into an environment, the system looks up the named variable group in that environment and uses its key-value pairs as the input value. If no variable group with that name exists, the input remains unset and must be provided explicitly.

`inputs[].defaultFrom.variableGroup`

string — required Name of the variable group in the target environment. The group must exist when the blueprint is installed.

defaultFrom:
  variableGroup: db-credentials

`outputs`

array — optional List of outputs exposed by this blueprint. Outputs let blueprint consumers reference values produced by the blueprint’s underlying service installations (e.g., terraform outputs like database endpoints or connection strings). Non-secret outputs are available via template syntax: {{ (blueprintInstallation "name").outputs.<outputName> }}. All outputs (including secrets) can be consumed via valueFromOutput.

outputs:
  - name: endpoint
    type: string
    from: '{{ (serviceInstallation "postgres-rds").outputs.endpoint }}'
    description: "The database endpoint"
  - name: connection_string
    type: string
    isSecret: true
    from: '{{ (serviceInstallation "postgres-rds").outputs.connection_string }}'
    description: "Full connection string with credentials"

`outputs[].name`

string — required Unique identifier for this output within the blueprint.

name: endpoint

`outputs[].type`

string — required Type of the output value. Valid values: string, number, boolean.

type: string

`outputs[].from`

string — required Template expression that resolves the output value from installation outputs. Uses the serviceInstallation function to reference outputs: (serviceInstallation "name").outputs.<key>.

# Single value
from: '{{ (serviceInstallation "postgres-rds").outputs.endpoint }}'

# Composite value
from: '{{ (serviceInstallation "postgres-rds").outputs.endpoint }}:{{ (serviceInstallation "postgres-rds").outputs.port }}'

`outputs[].description`

string — optional Detailed description of what this output represents.

description: "The database endpoint for client connections"

`outputs[].displayName`

string — optional Human-readable name displayed in the UI.

displayName: "Database Endpoint"

`outputs[].isSecret`

boolean — optional (default: false) If true, this output contains sensitive data. Secret outputs are routed through the secrets system — they are encrypted at rest, masked in the UI, and never rendered into plaintext manifests or resource reports. Secret outputs are not available via template syntax. They must be consumed via valueFromOutput in env vars or secrets definitions.

isSecret: true

`outputs[].condition`

string — optional Condition expression that determines whether this output is available. Uses template syntax with blueprint functions.

condition: '{{ eq (input "enable_read_replica") "true" }}'

If the condition evaluates to false, the output is not produced and its status will show as skipped.

`inputGroups`

array — optional Groups for organizing inputs in the UI.

inputGroups:
  - name: scaling
    displayName: "Scaling Configuration"
    description: "Configure scaling behavior"

`inputGroups[].name`

string — required Unique identifier for this input group.

name: scaling

`inputGroups[].displayName`

string — required Display name shown in the UI.

displayName: "Scaling Configuration"

`inputGroups[].description`

string — optional Description for the group.

description: "Configure scaling behavior"

`inputGroups[].condition`

string — optional Condition expression that determines whether this group should be displayed. If false, all inputs in the group are hidden.

condition: '{{ eq (input "environment") "production" }}'

Blueprint installation inputs

When installing a blueprint, you provide values for the blueprint’s defined inputs. Each input value can be set using one of the following options:

`inputs[].value`

any — optional A literal value for the input.

inputs:
  - name: replicas
    value: 5

`inputs[].valueFromVariableGroup`

object — optional Reference an environment-scoped variable group by name. Only valid for map type inputs with isSecret: true.

inputs:
  - name: db_credentials
    valueFromVariableGroup:
      name: db-credentials
  - name: db_password
    valueFromVariableGroup:
      name: db-credentials
      key: password

This is useful when different environments have the same set of credentials stored in a variable group with a consistent name. The variable group must exist in the target environment.

valueFromVariableGroup is the explicit installation-time equivalent of defaultFrom on the blueprint input definition. Use defaultFrom when you want the variable group to be the fallback when no value is provided, and use valueFromVariableGroup when you want to explicitly bind the input to a variable group.

`inputs[].valueFromVariableGroup.name`

string — required Name of the variable group in the target environment.

`inputs[].valueFromVariableGroup.key`

string — optional The specific key to get from the variable group. If not specified, the entire variable group key-value map is used. When a key is specified, only that key’s value is used as the input value.

Examples

Basic blueprint

Package multiple services together:

kind: Blueprint
metadata:
  name: backend-stack
spec:
  description: "Complete backend infrastructure"
  installations:
    - service: api
    - service: worker
    - service: database

Blueprint with inputs

Allow configuration at install time:

kind: Blueprint
metadata:
  name: api-service
spec:
  description: "API service with configurable scaling"
  inputs:
    - name: replicas
      type: number
      displayName: "Replica Count"
      description: "Number of API replicas"
      default: 2
    - name: cpu_cores
      type: number
      displayName: "CPU Cores"
      default: 1
  installations:
    - service: api
      config: |
        replicas: '{{ input "replicas" }}'
        cpu_cores: '{{ input "cpu_cores" }}'

Blueprint with conditional inputs

Show inputs based on other input values:

kind: Blueprint
metadata:
  name: database-stack
spec:
  description: "Database with optional external provider"
  inputs:
    - name: database_type
      type: string
      displayName: "Database Type"
      default: "internal"
    - name: external_host
      type: string
      displayName: "External Host"
      description: "Database host address"
      condition: '{{ eq (input "database_type") "external" }}'
    - name: external_password
      type: string
      displayName: "External Password"
      isSecret: true
      condition: '{{ eq (input "database_type") "external" }}'
  installations:
    - service: postgres
      condition: '{{ eq (input "database_type") "internal" }}'
    - service: external-db-connector
      condition: '{{ eq (input "database_type") "external" }}'
      config: |
        host: '{{ input "external_host" }}'

Blueprint with generated inputs

Auto-generate credentials and tokens:

kind: Blueprint
metadata:
  name: api-with-auth
spec:
  description: "API service with auto-generated credentials"
  inputs:
    - name: api_token
      type: string
      isSecret: true
      generated:
        type: random-string
        length: 32
    - name: instance_id
      type: string
      generated:
        type: random-string
        length: 16
  installations:
    - service: api
      secrets:
        - name: api-credentials
          values:
            - key: token
              valueFromInput: api_token
      env:
        - key: INSTANCE_ID
          valueFromInput: instance_id

Blueprint with variable group defaults

Use environment-scoped variable groups as default values for secret map inputs. This allows each environment to provide its own credentials through a variable group with a consistent name:

kind: Blueprint
metadata:
  name: api-with-db
spec:
  description: "API service with database credentials from variable groups"
  inputs:
    - name: db_credentials
      type: map
      isSecret: true
      displayName: "Database Credentials"
      description: "Database connection credentials (host, port, username, password)"
      defaultFrom:
        variableGroup: db-credentials
  installations:
    - service: api
      secrets:
        - name: db-secret
          valueFromInput: db_credentials

When installed, the system looks up the db-credentials variable group in the target environment and uses its key-value pairs. You can override this at install time:

# Use the default from the variable group
kind: BlueprintInstallation
metadata:
  name: api-with-db-production
spec:
  blueprint: api-with-db
  environment: production
  # No inputs needed - defaultFrom pulls from the "db-credentials" variable group

---

# Or explicitly bind to a different variable group
kind: BlueprintInstallation
metadata:
  name: api-with-db-staging
spec:
  blueprint: api-with-db
  environment: staging
  inputs:
    - name: db_credentials
      valueFromVariableGroup:
        name: staging-db-credentials

Provider-specific configuration

Configure services differently based on cloud provider:

kind: Blueprint
metadata:
  name: load-balancer
spec:
  description: "Cloud provider-specific load balancer configuration"
  inputs:
    - name: use_internal_lb
      type: boolean
      displayName: "Use Internal Load Balancer"
      default: false
    - name: static_ip
      type: string
      displayName: "Static IP Address"
      description: "Static IP for the load balancer (optional)"
      condition: '{{ eq EnvironmentProviderType "gcp" }}'
  installations:
    - service: ingress-controller
      config: |
          service:
            type: LoadBalancer
            {{ if eq EnvironmentProviderType "aws" }}
            annotations:
              service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
              {{ if input "use_internal_lb" }}
              service.beta.kubernetes.io/aws-load-balancer-internal: "true"
              {{ end }}
            {{ else if eq EnvironmentProviderType "azure" }}
            annotations:
              {{ if input "use_internal_lb" }}
              service.beta.kubernetes.io/azure-load-balancer-internal: "true"
              {{ end }}
              service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: /healthz
            externalTrafficPolicy: Local
            {{ else if eq EnvironmentProviderType "gcp" }}
            annotations:
              {{ if input "use_internal_lb" }}
              cloud.google.com/load-balancer-type: "Internal"
              {{ end }}
              {{ if input "static_ip" }}
              loadBalancerIP: {{ input "static_ip" }}
              {{ end }}
            {{ end }}

Multi-tier application

Complex blueprint with multiple conditional features:

kind: Blueprint
metadata:
  name: application-stack
spec:
  description: "Full application stack with optional components"
  inputs:
    - name: environment_tier
      type: string
      displayName: "Environment Tier"
      description: "Deployment tier: dev, staging, or production"
      default: "dev"
    - name: enable_monitoring
      type: boolean
      displayName: "Enable Advanced Monitoring"
      default: false
    - name: enable_caching
      type: boolean
      displayName: "Enable Caching Layer"
      default: false
    - name: cache_size_gb
      type: number
      displayName: "Cache Size (GB)"
      default: 10
      condition: '{{ eq (input "enable_caching") true }}'
    - name: monitoring_retention_days
      type: number
      displayName: "Monitoring Retention (Days)"
      default: 30
      condition: '{{ eq (input "enable_monitoring") true }}'
  installations:
    # Core application - always installed
    - service: application
      config: |
          replicas: {{ if eq (input "environment_tier") "production" }}5{{ else if eq (input "environment_tier") "staging" }}3{{ else }}1{{ end }}
          resources:
            limits:
              cpu: {{ if eq (input "environment_tier") "production" }}"2000m"{{ else }}"1000m"{{ end }}
              memory: {{ if eq (input "environment_tier") "production" }}"4Gi"{{ else }}"2Gi"{{ end }}
          environment:
            TIER: {{ upper (input "environment_tier") }}
            CACHE_ENABLED: {{ if input "enable_caching" }}"true"{{ else }}"false"{{ end }}

    # Cache - conditional installation
    - service: redis-cache
      condition: '{{ eq (input "enable_caching") true }}'
      config: |
          storage:
            size: {{ input "cache_size_gb" }}Gi
          replicas: {{ if eq (input "environment_tier") "production" }}3{{ else }}1{{ end }}

    # Monitoring - conditional installation
    - service: prometheus
      condition: '{{ eq (input "enable_monitoring") true }}'
      config: |
          retention:
            time: {{ input "monitoring_retention_days" }}d
          storage:
            size: {{ if eq (input "environment_tier") "production" }}100Gi{{ else }}50Gi{{ end }}

    # High availability - only for production on AWS
    - service: ha-proxy
      condition: '{{ and (eq (input "environment_tier") "production") (eq EnvironmentProviderType "aws") }}'
      config: |
          replicas: 3
          antiAffinity: hard

Blueprint with outputs

Expose values from underlying installations for other services to consume:

kind: Blueprint
metadata:
  name: database-stack
spec:
  description: "Managed database with exposed connection details"
  inputs:
    - name: instance_size
      type: string
      displayName: "Instance Size"
      default: "db.t3.medium"
    - name: enable_read_replica
      type: boolean
      displayName: "Enable Read Replica"
      default: false
  outputs:
    - name: host
      type: string
      from: '{{ (serviceInstallation "postgres-rds").outputs.endpoint }}'
      displayName: "Database Host"
      description: "The database endpoint for client connections"
    - name: port
      type: number
      from: '{{ (serviceInstallation "postgres-rds").outputs.port }}'
      description: "The database port"
    - name: connection_string
      type: string
      isSecret: true
      from: '{{ (serviceInstallation "postgres-rds").outputs.connection_string }}'
      description: "Full connection string with credentials"
    - name: read_replica_host
      type: string
      from: '{{ (serviceInstallation "postgres-rds").outputs.read_replica_endpoint }}'
      condition: '{{ eq (input "enable_read_replica") "true" }}'
      description: "Read replica endpoint (only available when read replica is enabled)"
  installations:
    - service: postgres-rds
      config: |
        instance_class: '{{ input "instance_size" }}'
        enable_read_replica: {{ input "enable_read_replica" }}

Consuming services can reference blueprint outputs via valueFromOutput:

kind: Blueprint
metadata:
  name: api-service
spec:
  description: "API that consumes database outputs"
  installations:
    - service: api
      env:
        # Non-secret output
        - key: DATABASE_HOST
          valueFromOutput:
            blueprintInstallation: database-stack
            name: host
      secrets:
        # Secret output routed through the secrets system
        - name: db-connection
          values:
            - key: connection_string
              valueFromOutput:
                blueprintInstallation: database-stack
                name: connection_string

Or reference non-secret outputs in config templates:

config: |
  database:
    host: {{ (blueprintInstallation "database-stack").outputs.host }}
    port: {{ (blueprintInstallation "database-stack").outputs.port }}

Secret outputs (isSecret: true) are not available via template syntax. They must be consumed via valueFromOutput in env vars or secrets definitions to ensure they flow through the secrets system.

Storage configuration by provider

Demonstrate provider-specific storage configurations:

kind: Blueprint
metadata:
  name: data-platform
spec:
  description: "Data platform with provider-optimized storage"
  inputs:
    - name: storage_tier
      type: string
      displayName: "Storage Performance Tier"
      description: "Storage performance: standard, fast, or premium"
      default: "standard"
    - name: backup_enabled
      type: boolean
      displayName: "Enable Automated Backups"
      default: true
  installations:
    - service: database
      config: |
          storage:
            {{ if eq EnvironmentProviderType "aws" }}
            storageClass: {{ if eq (input "storage_tier") "premium" }}"gp3"{{ else if eq (input "storage_tier") "fast" }}"io2"{{ else }}"gp2"{{ end }}
            iops: {{ if eq (input "storage_tier") "premium" }}16000{{ else if eq (input "storage_tier") "fast" }}8000{{ else }}3000{{ end }}
            {{ else if eq EnvironmentProviderType "gcp" }}
            storageClass: {{ if eq (input "storage_tier") "premium" }}"pd-extreme"{{ else if eq (input "storage_tier") "fast" }}"pd-ssd"{{ else }}"pd-standard"{{ end }}
            {{ else if eq EnvironmentProviderType "azure" }}
            storageClass: {{ if eq (input "storage_tier") "premium" }}"managed-premium"{{ else if eq (input "storage_tier") "fast" }}"managed-premium"{{ else }}"managed"{{ end }}
            {{ end }}
            size: 100Gi
          backup:
            enabled: {{ input "backup_enabled" }}
            {{ if input "backup_enabled" }}
            schedule: "0 2 * * *"
            retention: 7d
            {{ end }}

Branch-based deployments

Maintain main and develop release lines side by side:

kind: Blueprint
metadata:
  name: backend-stack
spec:
  description: "Backend stack with branch-based release lines"
  branches:
    - name: main
    - name: develop
  installations:
    - service: api
    - service: worker

Pushes to main produce releases on the branch:main channel; pushes to develop produce releases on branch:develop. Each environment subscribes to whichever branch it should track.

⌘I

​Blueprint functions

​input

​Environment functions

​EnvironmentName

​EnvironmentProviderType

​EnvironmentOrgId

​EnvironmentNamespace

​EnvironmentReleaseChannel

​Conditionals

​Conditional installations

​Conditional configuration

​Conditional inputs

​Branch deployments

​Release versions

​Publishing from source versus importing a release

​Composing blueprints

​Passing inputs down

​Consuming child outputs

​Release selection

​Naming

​Lifecycle

​Properties

​name

​description

​displayName

​distribution

​version

​promotionPipeline

​branches

​branches[].name

​installations

​installations[].service

​installations[].blueprint

​installations[].releaseChannel

​installations[].branch

​installations[].inputs

​installations[].excludedInstallations

​installations[].name

​installations[].alias

​installations[].namespace

​installations[].condition

​installations[].config

​installations[].lifecycle

​installations[].dependencies

​installations[].secrets

​installations[].secrets[].name

​installations[].secrets[].generated

​installations[].secrets[].values

​installations[].secrets[].valueFromInput

​installations[].env

​installations[].env[].key

​installations[].env[].value

​installations[].env[].valueFromInput

​installations[].env[].valueFromOutput

​inputs

​inputs[].name

​inputs[].type

​inputs[].isSecret

​inputs[].displayName

​inputs[].description

​inputs[].default

​inputs[].group

​inputs[].condition

​inputs[].hidden

​inputs[].generated

​inputs[].defaultFrom

​inputs[].defaultFrom.variableGroup

​outputs

​outputs[].name

​outputs[].type

​outputs[].from

​outputs[].description

​outputs[].displayName

​outputs[].isSecret

​outputs[].condition

​inputGroups

​inputGroups[].name

​inputGroups[].displayName

​inputGroups[].description

​inputGroups[].condition

Blueprint functions

`input`

Environment functions

`EnvironmentName`

`EnvironmentProviderType`

`EnvironmentOrgId`

`EnvironmentNamespace`

`EnvironmentReleaseChannel`

Conditionals

Conditional installations

Conditional configuration

Conditional inputs

Branch deployments

Release versions

Publishing from source versus importing a release

Composing blueprints

Passing inputs down

Consuming child outputs

Release selection

Naming

Lifecycle

Properties

`name`

`description`

`displayName`

`distribution`

`version`

`promotionPipeline`

`branches`

`branches[].name`

`installations`

`installations[].service`

`installations[].blueprint`

`installations[].releaseChannel`

`installations[].branch`

`installations[].inputs`

`installations[].excludedInstallations`

`installations[].name`

`installations[].alias`

`installations[].namespace`

`installations[].condition`

`installations[].config`

`installations[].lifecycle`

`installations[].dependencies`

`installations[].secrets`

`installations[].secrets[].name`

`installations[].secrets[].generated`

`installations[].secrets[].values`

`installations[].secrets[].valueFromInput`

`installations[].env`

`installations[].env[].key`

`installations[].env[].value`

`installations[].env[].valueFromInput`

`installations[].env[].valueFromOutput`

`inputs`

`inputs[].name`

`inputs[].type`

`inputs[].isSecret`

`inputs[].displayName`

`inputs[].description`

`inputs[].default`

`inputs[].group`

`inputs[].condition`

`inputs[].hidden`

`inputs[].generated`

`inputs[].defaultFrom`

`inputs[].defaultFrom.variableGroup`

`outputs`

`outputs[].name`

`outputs[].type`

`outputs[].from`

`outputs[].description`

`outputs[].displayName`

`outputs[].isSecret`

`outputs[].condition`

`inputGroups`

`inputGroups[].name`

`inputGroups[].displayName`

`inputGroups[].description`

`inputGroups[].condition`