Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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: Environment
metadata:
  name: production
spec:
  installations:
    - blueprint: "application-blueprint"
      inputs:
        - name: "public_domain"
          value: "mango.app"
---
kind: Environment
metadata:
  name: staging
spec:
  installations:
    - blueprint: "application-blueprint"
      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.

​
Blueprint inputs

Inputs allow you to customize blueprint behavior when installing it on an environment. They support various data types:
TypeDescriptionExample
stringText valuesApplication names, URLs
numberNumeric valuesCPU cores, memory limits
booleanTrue/false valuesFeature flags, enable/disable options
arrayLists of valuesPort lists, environment names
objectComplex data structuresConfiguration objects

​
Input properties

Each input can have these properties:
PropertyDescriptionRequired
nameUnique identifier for the inputYes
typeData type (string, number, boolean, array, object)Yes
descriptionDetailed explanation of the input’s purposeNo
displayNameHuman-readable name for the UINo
defaultDefault value if not specifiedNo
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"

​
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

TypeDescriptionUse Case
random-stringRandom alphanumeric stringAPI keys, tokens
random-bytesRandom binary dataEncryption keys
rsa-keyRSA key pairSSL certificates, SSH keys
ec-keyElliptic curve key pairModern 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

PropertyDescriptionRequired
nameUnique identifier for the outputYes
typeData type (string, number, boolean)Yes
fromTemplate expression resolving the value from installation outputsYes
descriptionDescription of what this output representsNo
displayNameHuman-readable name for the UINo
isSecretWhether this output contains sensitive dataNo
conditionCondition expression controlling whether the output is producedNo
See Blueprint Reference for the full property reference.

​
Installing blueprints

To install a blueprint on an environment, add it to your environment configuration: 
kind: Environment
metadata:
  name: production
spec:
  installations:
    - blueprint: "full-stack-app"
      name: "prod-app"
      inputs:
        - name: "app_name"
          value: "my-production-app"
        - name: "database_size"
          value: 50

​
Installation options

OptionDescriptionRequired
blueprintName of the blueprint to installYes
nameCustom name for this installationNo
inputsValues for blueprint inputsNo
If you install the same blueprint multiple times on an environment, you must provide a unique name for each installation.