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"
    services:
      - service: my-service
        # ... service configuration
environments:
  - name: production
    installations:
      - fromBlueprint:
          name: my-blueprint
          # ... installation configuration
previews:
  - name: feature-preview
    environment: staging
    fromBlueprint:
      name: 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.
`services`	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.
`installationName`	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.
`envVars`	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.
`valueFrom`	object	No	Reference to a git sync secret. Only valid for secret environment variables.

Environment Variable Examples

envVars:
  - key: DATABASE_URL
    isSecret: true
    valueFrom:
      gitSyncSecret:
        name: database-credentials
  - key: LOG_LEVEL
    isSecret: false
    value: "info"
  - key: API_KEY
    isSecret: true
    # Value will be required when blueprint is installed

Secrets

Secrets can be generated automatically or referenced from git sync secrets.

Property	Type	Required	Description
`name`	string	Yes	Name of the secret.
`fromGitSyncSecret`	object	No	Reference to a git sync secret.
`generated`	object	No	Configuration for automatically generated secrets.
`keys`	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 git sync secret
  - name: database_password
    fromGitSyncSecret:
      name: db-credentials
  # User-defined secret with keys
  - name: api_credentials
    keys: ["username", "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
`fromBlueprint`	object	Yes	Blueprint installation configuration.

From Blueprint Installation

Property	Type	Required	Description
`name`	string	Yes	Name of the blueprint to install.
`blueprintInstallationName`	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:
      - fromBlueprint:
          name: my-app-blueprint
          blueprintInstallationName: prod-web-app
          inputs:
            - name: replica_count
              value: 5
      - fromBlueprint:
          name: database-blueprint
          inputs:
            - name: db_password
              value: "secure-production-password"
  
  - name: staging
    installations:
      - fromBlueprint:
          name: web-app-blueprint
          inputs:
            - name: replica_count
              value: 2

previews:
  - name: feature-auth
    environment: staging
    fromBlueprint:
      name: 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.
`fromBlueprint`	object	Yes	Blueprint configuration for the preview.

Preview Examples

previews:
  - name: feature-auth
    environment: staging
    fromBlueprint:
      name: my-app-blueprint
      inputs:
        - name: feature_flags
          value: ["new_auth_system"]

  - name: performance-test
    environment: testing
    fromBlueprint:
      name: 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"
    services:
      - service: web-app
        installationName: frontend
        envVars:
          - key: DATABASE_URL
            isSecret: true
            valueFrom:
              gitSyncSecret:
                name: 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"
    services:
      - service: postgres-db
        config: |
          postgresql:
            auth:
              postgresPassword: "{{ .ryvn.blueprint.inputs.db_password }}"
            primary:
              persistence:
                size: 10Gi

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

previews:
  - name: feature-auth
    environment: staging
    fromBlueprint:
      name: 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 service
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 or fromGitSyncSecret reference

Cross-References

Referenced services must exist in the organization
Referenced git sync 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

From Blueprint Installation

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

​From Blueprint Installation

​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

From Blueprint Installation

Previews

Preview Properties

Complete Example

Validation Rules

Naming Conventions

Required Fields

Cross-References

Input Validation