Blueprints

Blueprints are reusable templates that allow you to configure everything needed to automate installations of your services. They define a collection of service installations, and inputs which can be customized across environments. When you install a blueprint on an environment, it creates installations for all the services defined in the blueprint and keeps them in sync with the blueprint.

Blueprints help you standardize installations and reduce configuration duplication across environments.

When to use blueprints?

Blueprints are most powerful when you have multiple environments and find yourself repeating the same configuration patterns across them. They allow you to avoid configuration drift and ensure consistency for your services. On the other hand, if you only have a single environment, it may be premature to use blueprints and it would be easier to just manage the configuration directly at the installation level.

Start with blueprints when you have at least two environments or when you find yourself copying configurations between deployments.

Using blueprints

Blueprints are configured via Git Sync using the resource-based YAML format. See infrastructure as code to set up Git Sync before using blueprints. Here is an example of a blueprint of a simple application consisting of a frontend and backend web-server.

# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Blueprint
metadata:
  name: application-blueprint
spec:
  description: Blueprint for my application
  displayName: My Application Blueprint
  inputs:
    - name: "public_domain"
      type: "string"
      description: "The public domain of the application"
    - name: "backend_replicas"
      type: "number"
      default: 2
  installations:
    - service: frontend
      env:
        - key: "BACKEND_URL"
          value: "backend.{{ input \"public_domain\" }}"
      config: |
        replicas: 3
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"

    - service: backend
      variableGroups:
        - name: "openai-key"
      config: |
        replicas: {{ input "backend_replicas" }}
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"

Install the blueprint on environments:

kind: BlueprintInstallation
metadata:
  name: application-blueprint-production
spec:
  blueprint: "application-blueprint"
  environment: production
  inputs:
    - name: "public_domain"
      value: "mango.app"
---
kind: BlueprintInstallation
metadata:
  name: application-blueprint-staging
spec:
  blueprint: "application-blueprint"
  environment: staging
  inputs:
    - name: "public_domain"
      value: "staging.mango.app"
    - name: "backend_replicas"
      value: 1

See Blueprint Reference for detailed information about all the blueprint fields.

Blueprint syncing

When you make changes to blueprints, these changes will result in changes to all blueprint installations automatically, if they are valid and do not require intervention.

Changes to environment variable or configuration made to installations directly will be overwritten if the same key is also defined on the blueprint and the effective value is different.

If you add an environment variable or a secret directly on the installation but this environment variable or secret does not appear in the blueprint definition, then it will be ignored and not managed by the blueprint. This also means if you remove an environment variable or secret from the blueprint definition, it will not be automatically removed from the installation.

Release versions

Each sync that changes a blueprint’s definition publishes a new release. Ryvn numbers releases automatically unless the blueprint sets spec.version to an exact SemVer version such as 1.4.0. With an exact version, identical content reuses the existing release, different content under an existing version is refused as a conflict, and a retired version is refused; Ryvn never falls back to an automatic number. Pull request previews keep their generated -preview.* identity and do not consume the stable version. Maintenance versions such as 1.4.3 after 2.0.0 are allowed and do not become channel head over a higher version. Run ryvn plan -f <blueprint.yaml> to see the requested version listed as a BlueprintRelease entry under the blueprint (create, unchanged, or blocked with the reason) before syncing; ryvn get blueprint <name> -o yaml shows spec.version when the blueprint uses an exact version, while ryvn describe blueprint <name> and the blueprint definition page show the resolved release version. Pull sync converges on the current commit and may skip intermediate commits. A release can also be imported without a source repository from a document exported with ryvn get blueprint-release:

ryvn create blueprint-release -f redis-1.4.0.json

Blueprints whose releases are imported or edited this way must stay outside the paths git sync manages. See Release versions for the version grammar, prerequisites and the document format.

Blueprint inputs

Inputs allow you to customize blueprint behavior when installing it on an environment. They support various data types:

Type	Description	Example
`string`	Text values	Application names, URLs
`number`	Numeric values	CPU cores, memory limits
`boolean`	True/false values	Feature flags, enable/disable options
`array`	Lists of values	Port lists, environment names
`object`	Complex data structures	Configuration objects

Input properties

Each input can have these properties:

Property	Description	Required
`name`	Unique identifier for the input	Yes
`type`	Data type (string, number, boolean, array, object)	Yes
`description`	Detailed explanation of the input’s purpose	No
`displayName`	Human-readable name for the UI	No
`default`	Default value if not specified	No

Inputs without default values are automatically converted to blueprint inputs and are required to be assigned a value when installing the blueprint.

Service configuration

Each service installation in a blueprint can be configured with:

Environment variables

For web-server services, you can define environment variables:

variableGroups:
  - name: "api-credentials"
env:
  - key: "LOG_LEVEL"
    value: "info"

Service configuration

The config field contains service-specific configuration as a YAML string. This is the same configuration that you would provide to the service when installing it manually. For helm charts, this is the same as the override values.yaml file and for terraform, this is the same as the variables yaml file.

config: |
  replicas: 3
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"
  env:
    - name: "NODE_ENV"
      value: "production"

Dependencies

A service can declare which siblings must be ready before it installs for the first time, by alias or name. Ryvn resolves them to the installations it creates, so the order holds in every environment the blueprint is installed in. See Installation Dependencies.

dependencies:
  - serviceInstallation: db

Template variables

Configuration can reference blueprint inputs using template syntax.

config: |
  replicas: {{ input "replicas" }}
  cpu: '{{ input "cpu" }}'
  app_name: '{{ input "app_name" }}'

Secrets management

Blueprints can define secrets that are automatically generated or referenced from variable groups:

Generated secrets

secrets:
  - name: "api-key"
    generated:
      type: "random-string"
      length: 32
  - name: "ssl-cert"
    generated:
      type: "rsa-key"

Secret types

Type	Description	Use Case
`random-string`	Random alphanumeric string	API keys, tokens
`random-bytes`	Random binary data	Encryption keys
`rsa-key`	RSA key pair	SSL certificates, SSH keys
`ec-key`	Elliptic curve key pair	Modern cryptography

Variable Groups

For secrets managed via variable groups (recommended):

variableGroups:
  - name: "database-credentials"

User-defined secrets

For secrets that need to be provided by users:

secrets:
  - name: "database-password"
    values:
      - key: "database-password"
        valueFromInput:
          name: "database_password"

Blueprint outputs

Outputs allow a blueprint to expose values produced by its underlying service installations — such as database endpoints, connection strings, or resource IDs — so that other services can consume them.

Defining outputs

Declare outputs in the blueprint spec. Each output uses a from template to resolve its value from an installation’s outputs (e.g., terraform outputs):

kind: Blueprint
metadata:
  name: database-stack
spec:
  description: "Managed database infrastructure"
  outputs:
    - name: host
      type: string
      from: '{{ (serviceInstallation "postgres-rds").outputs.endpoint }}'
      description: "Database endpoint"
    - name: connection_string
      type: string
      isSecret: true
      from: '{{ (serviceInstallation "postgres-rds").outputs.connection_string }}'
      description: "Full connection string with credentials"
  installations:
    - service: postgres-rds

Consuming outputs

Other services can reference blueprint outputs in two ways: Template syntax (non-secret outputs only):

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

Structured references (all outputs, including secrets):

env:
  - key: DATABASE_HOST
    valueFromOutput:
      blueprintInstallation: database-stack
      name: host
secrets:
  - name: db-connection
    values:
      - key: connection_string
        valueFromOutput:
          blueprintInstallation: database-stack
          name: connection_string

Secret outputs (isSecret: true) are not available via template syntax. Use valueFromOutput to consume them — this ensures secrets are routed through the secrets system and never rendered into plaintext manifests.

Output properties

Property	Description	Required
`name`	Unique identifier for the output	Yes
`type`	Data type (`string`, `number`, `boolean`)	Yes
`from`	Template expression resolving the value from installation outputs	Yes
`description`	Description of what this output represents	No
`displayName`	Human-readable name for the UI	No
`isSecret`	Whether this output contains sensitive data	No
`condition`	Condition expression controlling whether the output is produced	No

See Blueprint Reference for the full property reference.

Installing blueprints

To install a blueprint on an environment, declare a standalone BlueprintInstallation resource:

kind: BlueprintInstallation
metadata:
  name: prod-app
spec:
  blueprint: "full-stack-app"
  environment: production
  inputs:
    - name: "app_name"
      value: "my-production-app"
    - name: "database_size"
      value: 50

Installation options

Option	Description	Required
`metadata.name`	Name of this installation	Yes
`spec.blueprint`	Name of the blueprint to install	Yes
`spec.environment`	Environment to install into	Yes
`spec.inputs`	Values for blueprint inputs	No

Installing the same blueprint multiple times on an environment must be enabled for your organization by Ryvn. Once enabled, you must provide a unique metadata.name for each installation. Until it is enabled, a second installation of the same blueprint in an environment is rejected even with a unique metadata.name.

Get started

Agents

Provision

Deploy

Concepts

Configure

Connections

Release

Templating

Observability

Networking

Support

When to use blueprints?

Using blueprints

Blueprint syncing

Release versions

Blueprint inputs

Input properties

Service configuration

Environment variables

Service configuration

Dependencies

Template variables

Secrets management

Generated secrets

Secret types

Variable Groups

User-defined secrets

Blueprint outputs

Defining outputs

Consuming outputs

Output properties

Installing blueprints

Installation options

​When to use blueprints?

​Using blueprints

​Blueprint syncing

​Release versions

​Blueprint inputs

​Input properties

​Service configuration

​Environment variables

​Service configuration

​Dependencies

​Template variables

​Secrets management

​Generated secrets

​Secret types

​Variable Groups

​User-defined secrets

​Blueprint outputs

​Defining outputs

​Consuming outputs

​Output properties

​Installing blueprints

​Installation options

When to use blueprints?

Using blueprints

Blueprint syncing

Release versions

Blueprint inputs

Input properties

Service configuration

Environment variables

Service configuration

Dependencies

Template variables

Secrets management

Generated secrets

Secret types

Variable Groups

User-defined secrets

Blueprint outputs

Defining outputs

Consuming outputs

Output properties

Installing blueprints

Installation options