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"
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
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.
| 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 |
| 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"
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 }}
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 |
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
| Option | Description | Required |
|---|
blueprint | Name of the blueprint to install | Yes |
name | Custom name for this installation | No |
inputs | Values for blueprint inputs | No |
If you install the same blueprint multiple times on an environment, you must provide a unique
name for each installation.
