Ryvn YAML Specification

The ryvn.yaml file is the primary configuration file for defining your Ryvn resources. It must be placed in the root directory of your repository and defines blueprints, environments, and previews that will be managed by Ryvn.

Only one ryvn.yaml file is allowed per repository, and it must be in the root directory.

File Structure

apiVersion: v1
blueprints:
  - name: my-blueprint
    description: "Description of the blueprint"
    installations:
      - service: my-service
        # ... service configuration
environments:
  - name: production
    installations:
      - blueprint: my-blueprint
        # ... installation configuration
previews:
  - name: feature-preview
    environment: staging
    blueprint: my-blueprint
    # ... preview configuration

Top-Level Properties

Property	Type	Required	Description
`apiVersion`	string	Yes	API version of the Ryvn YAML specification. Currently only `v1` is supported.
`blueprints`	array	No	List of blueprints to be managed by Ryvn.
`environments`	array	No	List of environments to be managed by Ryvn.
`previews`	array	No	List of previews to be managed by Ryvn.

Blueprints

Blueprints define reusable application templates that can be installed across multiple environments. They encapsulate service configurations, environment variables, secrets, and input parameters.

Blueprint Properties

Property	Type	Required	Description
`name`	string	Yes	Name of the blueprint. Must be lowercase alphanumeric with hyphens, max 63 characters.
`description`	string	Yes	Description of the blueprint.
`displayName`	string	No	Human-readable name for the blueprint.
`inputs`	array	No	List of input parameters required by the blueprint.
`installations`	array	Yes	List of service installations associated with this blueprint.

Blueprint Inputs

Inputs define parameters that can be customized when installing a blueprint into an environment.

Property	Type	Required	Description
`name`	string	Yes	Name of the input parameter.
`description`	string	No	Detailed description of what the input is for.
`displayName`	string	No	Human-readable name for the input.
`type`	string	Yes	Type of the input. Valid values: `string`, `number`, `boolean`, `array`, `object`.
`default`	any	No	Default value for the input. If not provided, the input will be required.

Input Type Examples

inputs:
  - name: database_url
    type: string
    description: "Database connection string"
    default: "postgresql://localhost:5432/mydb"
  - name: replica_count
    type: number
    description: "Number of service replicas"
    default: 3
  - name: enable_debug
    type: boolean
    description: "Enable debug logging"
    default: false
  - name: allowed_origins
    type: array
    description: "CORS allowed origins"
    default: ["https://example.com"]
  - name: config
    type: object
    description: "Application configuration"
    default:
      timeout: 30
      retries: 3

Blueprint Service Installations

Service installations define how services are configured when installed from a blueprint.

Property	Type	Required	Description
`service`	string	Yes	Name of the service to install.
`name`	string	No	Custom name for the installation. If not provided, uses the service name.
`namespace`	string	No	Kubernetes namespace for the installation. If not provided, uses the environment’s default namespace.
`env`	array	No	Environment variables for the service. Only valid for web-server services.
`config`	string	No	YAML configuration string for the service. Supports template variables like `{{ .ryvn.blueprint.inputs.cpu }}`.
`secrets`	array	No	Secrets belonging to the service. Only valid for helm-chart and terraform service types.

Environment Variables

Environment variables can be configured for web-server services.

Property	Type	Required	Description
`key`	string	Yes	The key (name) of the environment variable.
`isSecret`	boolean	Yes	Whether the environment variable is a secret.
`value`	string	No	The value of the environment variable. Omit for secrets.
`orgSecret`	string	No	Reference to an organization secret. Only valid for secret environment variables.

Environment Variable Examples

env:
  - key: LOG_LEVEL
    value: "info"
  - key: API_URL
    value: "https://example.com"

  # referencing an organization secret will create env variables from all the keys
  # defined in the secret. For example, if the database-credentials secret has keys
  # like DB_USERNAME = "postgres" and DB_PASSWORD = "secret", it will create following
  # on the installation:
  # - key: DB_USERNAME
  #   value: "postgres"
  # - key: DB_PASSWORD
  #   value: "secret"
  - orgSecret: database-credentials

Secrets

Secrets can be generated automatically, referenced from organization secrets, or defined with user values.

Property	Type	Required	Description
`name`	string	Yes	Name of the secret.
`orgSecret`	string	No	Reference to an organization secret.
`generated`	object	No	Configuration for automatically generated secrets.
`values`	array	No	Keys for user-defined secrets. Cannot be specified for generated secrets.

Generated Secret Configuration

Property	Type	Required	Description
`type`	string	Yes	Type of secret to generate. Valid values: `random-string`, `random-bytes`, `rsa-key`, `ec-key`.
`length`	integer	No	Length for random-string or random-bytes. Uses default if not specified.

Secret Examples

secrets:
  # Generated random string
  - name: jwt_secret
    generated:
      type: random-string
      length: 32
  # Generated RSA key
  - name: ssh_key
    generated:
      type: rsa-key
  # Reference organization secret
  - name: database_password
    orgSecret: db-credentials
  # User-defined secret with keys
  - name: api_credentials
    values:
      - key: username
      - key: password

Configuration Templates

The config property supports template variables that reference blueprint inputs.

Configuration Template Examples

# Helm chart values.yaml
config: |
  replicaCount: {{ .ryvn.blueprint.inputs.replica_count }}
  image:
    repository: my-app
    tag: latest
  resources:
    requests:
      cpu: {{ .ryvn.blueprint.inputs.cpu }}
      memory: {{ .ryvn.blueprint.inputs.memory }}

# Terraform variables
config: |
  {
    "instance_type": "{{ .ryvn.blueprint.inputs.instance_type }}",
    "environment": "{{ .ryvn.blueprint.inputs.environment }}"
  }

Environments

Environments define where blueprints are installed and how they are configured.

Environment Properties

Property	Type	Required	Description
`name`	string	Yes	Name of the environment.
`installations`	array	No	List of installations associated with this environment.

Installations

Installations define how blueprints are installed into environments.

Property	Type	Required	Description
`blueprint`	string	Yes	Name of the blueprint to install.

Blueprint Installation Properties

Property	Type	Required	Description
`name`	string	No	Custom name for the blueprint installation. If not provided, uses the blueprint name.
`inputs`	array	No	Input values to override blueprint defaults.

Environment Installation Examples

environments:
  - name: production
    installations:
      - blueprint: my-app-blueprint
        name: prod-web-app
        inputs:
          - name: replica_count
            value: 5
      - blueprint: database-blueprint
        inputs:
          - name: db_password
            value: "secure-production-password"
  - name: staging
    installations:
      - blueprint: web-app-blueprint
        inputs:
          - name: replica_count
            value: 2

previews:
  - name: feature-auth
    environment: staging
    blueprint: web-app-blueprint
    inputs:
      - name: replica_count
        value: 1

Previews

Previews enable automatic deployment of feature branches or pull requests for testing and review.

Preview Properties

Property	Type	Required	Description
`name`	string	Yes	Name of the preview. Must be lowercase alphanumeric with hyphens, max 63 characters.
`environment`	string	Yes	Name of the environment where previews will be installed.
`blueprint`	string	Yes	Name of the blueprint to install.

Preview Examples

previews:
  - name: feature-auth
    environment: staging
    blueprint: my-app-blueprint
    inputs:
      - name: feature_flags
        value: ["new_auth_system"]
  - name: performance-test
    environment: testing
    blueprint: my-app-blueprint
    inputs:
      - name: load_testing
        value: true

Complete Example

Full ryvn.yaml Example

apiVersion: v1

blueprints:
  - name: web-app-blueprint
    description: "A complete web application with database"
    displayName: "Web Application"
    inputs:
      - name: replica_count
        type: number
        description: "Number of application replicas"
        default: 3
      - name: database_url
        type: string
        description: "Database connection string"
    installations:
      - service: web-app
        name: frontend
        env:
          - key: DATABASE_URL
            isSecret: true
            orgSecret: database-credentials
          - key: LOG_LEVEL
            isSecret: false
            value: "info"
        config: |
          replicaCount: {{ .ryvn.blueprint.inputs.replica_count }}
          image:
            repository: my-web-app
            tag: latest
        secrets:
          - name: jwt_secret
            generated:
              type: random-string
              length: 32
  
  - name: database-blueprint
    description: "PostgreSQL database with backup configuration"
    installations:
      - service: postgres-db
        config: |
          postgresql:
            auth:
              postgresPassword: "{{ .ryvn.blueprint.inputs.db_password }}"
            primary:
              persistence:
                size: 10Gi

environments:
  - name: production
    installations:
      - blueprint: web-app-blueprint
        name: prod-web-app
        inputs:
          - name: replica_count
            value: 5
      - blueprint: database-blueprint
        inputs:
          - name: db_password
            value: "secure-production-password"
  
  - name: staging
    installations:
      - blueprint: web-app-blueprint
        inputs:
          - name: replica_count
            value: 2

previews:
  - name: feature-auth
    environment: staging
    blueprint: web-app-blueprint
    inputs:
      - name: replica_count
        value: 1

Validation Rules

Ryvn performs comprehensive validation of your ryvn.yaml file:

Naming Conventions

All names must be lowercase alphanumeric with hyphens only
Names must be less than 63 characters
Names must match the pattern: ^[a-z0-9]+(-[a-z0-9]+)*$

Required Fields

Blueprints must have at least one installation
Service installations must specify a service name
Environment variables must have a key and isSecret value
Secrets must have a name and either generated config, orgSecret reference, or values array

Cross-References

Referenced organization secrets must exist
Referenced blueprints must exist when installing into environments
Referenced environments must exist for previews

Input Validation

Required inputs must be provided when installing blueprints
Input values must match their declared types
Secret inputs cannot have default values

Validation errors will prevent the sync from completing. Check the validation output in your Ryvn dashboard for detailed error messages.

Get Started

Provision

Deploy

Concepts

Configure

Observability

Networking

Support

Ryvn YAML Specification

File Structure

Top-Level Properties

Blueprints

Blueprint Properties

Blueprint Inputs

Blueprint Service Installations

Environment Variables

Secrets

Generated Secret Configuration

Configuration Templates

Environments

Environment Properties

Installations

Blueprint Installation Properties

Previews

Preview Properties

Complete Example

Validation Rules

Naming Conventions

Required Fields

Cross-References

Input Validation

Get Started

Provision

Deploy

Concepts

Configure

Observability

Networking

Support

​File Structure

​Top-Level Properties

​Blueprints

​Blueprint Properties

​Blueprint Inputs

​Blueprint Service Installations

​Environment Variables

​Secrets

Generated Secret Configuration

​Configuration Templates

​Environments

​Environment Properties

​Installations

​Blueprint Installation Properties

​Previews

​Preview Properties

​Complete Example

​Validation Rules

​Naming Conventions

​Required Fields

​Cross-References

​Input Validation

File Structure

Top-Level Properties

Blueprints

Blueprint Properties

Blueprint Inputs

Blueprint Service Installations

Environment Variables

Secrets

Configuration Templates

Environments

Environment Properties

Installations

Blueprint Installation Properties

Previews

Preview Properties

Complete Example

Validation Rules

Naming Conventions

Required Fields

Cross-References

Input Validation