Blueprint

Blueprint installations add all services defined in a blueprint as installations on an environment. Configure blueprint inputs to customize the installation for each environment.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: BlueprintInstallation
metadata:
  name: webapp-production
spec:
  blueprint: webapp
  environment: production
  inputs:
    - name: apiDomain
      value: "api.example.com"
    - name: dbPassword
      valueFromVariableGroup:
        name: db-credentials
        key: password

Secret inputs (isSecret: true) cannot take a raw value in YAML. Use valueFromVariableGroup, valueFromOutput, or set the value in the UI.

Properties

`blueprint`

string — required Name of the blueprint to install. All services defined in the blueprint will be added as installations on the environment.

blueprint: webapp

`environment`

string — required Target environment for this installation.

environment: production

`blueprintInstallationName`

string — optional Custom name for this blueprint installation. If not specified, uses the blueprint name.

blueprintInstallationName: webapp-prod

Installing the same blueprint more than once in a single environment (each with its own unique blueprintInstallationName) must be enabled for your organization by Ryvn. Until it is enabled, a second installation of the same blueprint in an environment is rejected even with a unique name. Reach out to Ryvn support to enable multi-install.

`releaseChannel`

string — optional Release channel this installation follows. If unset, uses the environment’s channel. Mutually exclusive with branch.

releaseChannel: stable

`branch`

string — optional Track a branch’s releases on a blueprint configured with branches. Mutually exclusive with releaseChannel. The referenced blueprint must declare this branch in its branches list.

branch: develop

`inputs`

array — optional Input parameters to pass to the blueprint. These inputs override any default values defined on the blueprint and are used by services within the blueprint.

inputs:
  - name: apiDomain
    value: "api.example.com"
  - name: dbPassword
    valueFromVariableGroup:
      name: db-credentials
      key: password

`inputs[].name`

string — required Name of the blueprint input parameter.

inputs:
  - name: dbPassword

`inputs[].value`

string — optional Value for the input parameter. Set exactly one of value, valueFromVariableGroup, or valueFromOutput. Secret inputs cannot use a raw value; use a variable group or a secret output instead, so secret values never live in git.

inputs:
  - name: apiDomain
    value: "api.example.com"

`inputs[].valueFromVariableGroup`

object — optional Reference an environment-scoped variable group to use as the input value. Only valid for inputs with isSecret: true: with a key, on a string input (that one key becomes the value); without a key, on a map input (the whole variable group becomes the value). Cannot be used with value or valueFromOutput.

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

The variable group must exist in the target environment. This is the explicit equivalent of defaultFrom on the blueprint input definition — use defaultFrom when you want a fallback when no value is provided, and 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.

`inputs[].valueFromOutput`

object — optional Source an input from an output of another installation in the same environment. Set exactly one of blueprintInstallation or serviceInstallation to the producer’s installation name, and set name to its output name. For a serviceInstallation target, name: connection.writer.endpoint selects the Terraform output connection, then its nested writer.endpoint value:

valueFromOutput:
  serviceInstallation: shared-rds
  name: connection.writer.endpoint

For a blueprintInstallation target, name matches a declared blueprint output exactly. Dots in a blueprint output name are part of the name, not a path into its value. To expose a nested value from a blueprint-owned service, declare an output on the blueprint:

outputs:
  - name: writer_endpoint
    type: string
    from: '{{ (serviceInstallation "db").outputs.connection.writer.endpoint }}'

Reference that output with name: writer_endpoint on the blueprintInstallation target. A blueprint output’s declared type must match the input’s type; a Terraform output must already have the input’s JSON type (for example, "8080" cannot feed a number input). Only a standalone service installation can be a serviceInstallation target. For a service owned by a blueprint installation, expose the value as an output of its owning blueprint and reference that blueprintInstallation.

kind: BlueprintInstallation
metadata:
  name: shared-postgres
spec:
  blueprint: aws-postgres
  environment: production
---
kind: BlueprintInstallation
metadata:
  name: temporal
spec:
  blueprint: aws-temporal-postgres
  environment: production
  inputs:
    - name: postgres_writer_endpoint
      valueFromOutput:
        blueprintInstallation: shared-postgres
        name: writer_endpoint
    - name: postgres_master_secret_arn
      valueFromOutput:
        blueprintInstallation: shared-postgres
        name: master_user_secret_arn

Ryvn resolves the output on every reconcile and updates the consumer when the producer’s output changes. If the producer or output is unavailable, the consumer holds its current services without changing them and reports the reason in its issues. View the issues in the UI banner, ryvn describe blueprint-installation, or ryvn plan. A secret output must feed a secret input (isSecret: true). Output references cannot be used on a platform installation or an immutable input, and cannot point to the installation itself or form a cycle between installations.

`inputs[].valueFromOutput.blueprintInstallation`

string — required when targeting a blueprint installation Name of another blueprint installation in the same environment.

`inputs[].valueFromOutput.serviceInstallation`

string — required when targeting a standalone service installation Name of the standalone service installation in the same environment.

`inputs[].valueFromOutput.name`

string — required For a standalone service installation, the first segment names the Terraform output; remaining dot-separated segments select nested values. For a blueprint installation, use the exact declared output name.

`excludedInstallations`

array — optional List of service installations within this blueprint that should be excluded from automatic updates. These installations will not receive automatic updates when the blueprint is updated, allowing you to pin specific services to their current versions.

excludedInstallations:
  - name: redis-cache
  - name: postgres-db

Examples

Marketplace blueprint

Install a marketplace blueprint using the ryvn.app/ prefix:

kind: BlueprintInstallation
metadata:
  name: my-database
spec:
  blueprint: ryvn.app/postgres
  environment: production
  inputs:
    - name: size
      value: medium
    - name: highAvailability
      value: "true"
    - name: backupRetentionDays
      value: "14"

With variable groups

kind: BlueprintInstallation
metadata:
  name: webapp-production
spec:
  blueprint: webapp
  environment: production
  inputs:
    - name: dbPassword
      valueFromVariableGroup:
        name: db-credentials
        key: password
    - name: apiKey
      valueFromVariableGroup:
        name: api-keys
        key: stripe_key

Multiple blueprints:

kind: BlueprintInstallation
metadata:
  name: webapp-production
spec:
  blueprint: webapp
  environment: production
  inputs:
    - name: environment
      value: "production"
    - name: dbPassword
      valueFromVariableGroup:
        name: credentials
        key: db_password
---
kind: BlueprintInstallation
metadata:
  name: monitoring-production
spec:
  blueprint: monitoring
  environment: production
  inputs:
    - name: slackWebhook
      valueFromVariableGroup:
        name: webhooks
        key: slack_url

Mixed inputs:

kind: BlueprintInstallation
metadata:
  name: platform-production
spec:
  blueprint: platform
  environment: production
  inputs:
    - name: region
      value: "us-east-1"
    - name: instanceType
      value: "t3.large"
    - name: awsAccessKey
      valueFromVariableGroup:
        name: aws-credentials
        key: access_key
    - name: awsSecretKey
      valueFromVariableGroup:
        name: aws-credentials
        key: secret_key
    - name: encryptionEnabled
      value: "true"

Whole variable group as a map input:

kind: BlueprintInstallation
metadata:
  name: api-with-db-production
spec:
  blueprint: api-with-db
  environment: production
  inputs:
    - name: db_credentials
      valueFromVariableGroup:
        name: db-credentials

Excluding installations from updates:

kind: BlueprintInstallation
metadata:
  name: webapp-production
spec:
  blueprint: webapp
  environment: production
  excludedInstallations:
    - name: postgres-db
    - name: redis-cache
  inputs:
    - name: environment
      value: "production"

Tracking a specific branch:

kind: BlueprintInstallation
metadata:
  name: webapp-preview
spec:
  blueprint: webapp
  environment: preview
  branch: develop

Services

Environments

Installations

Blueprints

Releases

Properties

`blueprint`

`environment`

`blueprintInstallationName`

`releaseChannel`

`branch`

`inputs`

`inputs[].name`

`inputs[].value`

`inputs[].valueFromVariableGroup`

`inputs[].valueFromVariableGroup.name`

`inputs[].valueFromVariableGroup.key`

`inputs[].valueFromOutput`

`inputs[].valueFromOutput.blueprintInstallation`

`inputs[].valueFromOutput.serviceInstallation`

`inputs[].valueFromOutput.name`

`excludedInstallations`

Examples

Marketplace blueprint

With variable groups

​Properties

​blueprint

​environment

​blueprintInstallationName

​releaseChannel

​branch

​inputs

​inputs[].name

​inputs[].value

​inputs[].valueFromVariableGroup

​inputs[].valueFromVariableGroup.name

​inputs[].valueFromVariableGroup.key

​inputs[].valueFromOutput

​inputs[].valueFromOutput.blueprintInstallation

​inputs[].valueFromOutput.serviceInstallation

​inputs[].valueFromOutput.name

​excludedInstallations

​Examples

​Marketplace blueprint

​With variable groups

Properties

`blueprint`

`environment`

`blueprintInstallationName`

`releaseChannel`

`branch`

`inputs`

`inputs[].name`

`inputs[].value`

`inputs[].valueFromVariableGroup`

`inputs[].valueFromVariableGroup.name`

`inputs[].valueFromVariableGroup.key`

`inputs[].valueFromOutput`

`inputs[].valueFromOutput.blueprintInstallation`

`inputs[].valueFromOutput.serviceInstallation`

`inputs[].valueFromOutput.name`

`excludedInstallations`

Examples

Marketplace blueprint

With variable groups