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.

Environments define where your services are deployed. Ryvn provisions and manages infrastructure in target Google Cloud projects, including Kubernetes clusters, networking, load balancers, and DNS. 
# yaml-language-server: $schema=https://api.ryvn.app/v1/schemas/resources.json
kind: Environment
metadata:
  name: prod-us
spec:
  releaseChannel: production
  provider:
    type: gcp
    projectId: my-project-123
  config:
    region: us-east1
    subnet_cidr: 10.0.0.0/17
  installations:
    - service: api
    - service: frontend

​
Properties

​
name

string — required Environment identifier. Must be lowercase, alphanumeric with hyphens only. 
name: production

​
labels

object — optional Key-value labels for grouping and filtering environments. Use labels to organize environments by team, region, customer, or any other dimension. Constraints:
  • Maximum 50 labels per environment
  • Keys must start with an alphanumeric character and contain only alphanumerics, dots, hyphens, and underscores
  • Keys and values are each limited to 63 characters
metadata:
  name: prod-us
  labels:
    team: platform
    region: us-central
    customer: acme

​
releaseChannel

string — optional Default release channel for installations in this environment. When installations don’t specify a release channel, they use the environment’s channel. 
releaseChannel: stable

​
maintenanceWindow

string — optional Maintenance window for this environment. Automated deployments will only occur during specified intervals. 
maintenanceWindow: business-hours

​
config

object — optional Configuration passed to the Ryvn environment provisioner. 
config:
  region: us-central1
  subnet_cidr: "10.0.0.0/17"
  pod_cidr: "192.168.0.0/18"
  service_cidr: "192.168.64.0/18"

​
config.region

string — required GCP region where resources will be provisioned. 
config:
  region: us-central1

​
config.zones

array — optional List of zones for the GKE cluster. If not specified, uses default zones for the region. 
config:
  zones:
    - us-central1-a
    - us-central1-b
    - us-central1-c

​
config.internal_root_domain

string — optional Internal root domain for services using internal networking. If not specified, Ryvn generates a default domain in the format {environment}.{org-slug}.ryvn.internal. 
config:
  internal_root_domain: internal.example.com

​
config.public_root_domain

string — optional Public root domain for services using public networking. If not specified, Ryvn generates a default domain in the format {environment}.{org-slug}.ryvn.run. 
config:
  public_root_domain: example.com

​
config.subnet_cidr

string — optional CIDR block for the subnet. Defaults to 10.0.0.0/17. 
config:
  subnet_cidr: "10.1.0.0/17"

​
config.pod_cidr

string — optional CIDR block for pods. Defaults to 192.168.0.0/18. 
config:
  pod_cidr: "192.168.0.0/18"

​
config.service_cidr

string — optional CIDR block for services. Defaults to 192.168.64.0/18. 
config:
  service_cidr: "192.168.64.0/18"

​
config.node_pools

object — optional Map of node pool definitions to create. 
config:
  node_pools:
    default:
      machine_type: n2-standard-4
      total_min_count: 2
      total_max_count: 10
      initial_node_count: 3
      disk_size_gb: 100
      disk_type: pd-standard
      labels:
        environment: production

​
config.node_pools_labels

object — optional Map of node pool labels to apply to each node pool. 
config:
  node_pools_labels:
    default:
      team: infrastructure
      cost-center: engineering

​
config.flow_logs

object — optional Configuration for VPC flow logs. 
config:
  flow_logs:
    enable: "true"
    interval: INTERVAL_5_SEC
    sampling: "0.5"
    metadata: INCLUDE_ALL_METADATA
    filter: "true"

​
config.external_dns_namespace

string — optional Kubernetes namespace where external-dns is deployed. Defaults to external-dns. 
config:
  external_dns_namespace: external-dns

​
config.skip_dns_provisioning

boolean — optional If true, skips provisioning DNS managed zones. Defaults to false. 
config:
  skip_dns_provisioning: true

​
config.cluster_bootstrap_perms

boolean — optional If true, grants cluster admin permissions to the Ryvn Agent for initial setup. Should be disabled after bootstrap. Defaults to false. 
config:
  cluster_bootstrap_perms: true

​
config.terraform_executor_policies

object — optional Additional IAM policies to be added to the Ryvn Agent role. Can specify either predefined roles or custom permissions. Cannot specify both. 
config:
  terraform_executor_policies:
    roles:
      - roles/storage.admin
      - roles/compute.viewer

​
config.terraform_executor_policies.roles

array — optional List of predefined GCP roles to attach. Cannot be used with permissions. 
terraform_executor_policies:
  roles:
    - roles/storage.admin
    - roles/compute.viewer

​
config.terraform_executor_policies.permissions

array — optional List of custom permissions to add. If specified, these will override the default permissions. Cannot be used with roles. 
terraform_executor_policies:
  permissions:
    - storage.buckets.create
    - storage.buckets.delete

​
setup

string — optional Environment setup type. Controls who provisions the environment infrastructure. Available values:
  • customer-controlled - Ryvn Provisioner (Compute instance in the customer’s GCP project) provisions the infrastructure
  • self - Ryvn Control Plane uses workload identity to provision the infrastructure (default)
When using customer-controlled, combine with customerEmail to automatically generate customer invite codes. 
setup: customer-controlled

​
customerEmail

string — optional Email address of the customer admin for this environment. Only used with setup: customer-controlled. When specified, Ryvn automatically:
  1. Creates a customer organization and user account
  2. Sends an invite code to the customer to provision the environment
customerEmail: admin@customer.com

​
requireApproval

boolean — optional (default: false) When true, deployments require approval before executing. See Deployment Approvals. 
requireApproval: true

​
provider

object — required GCP provider configuration. 
provider:
  type: gcp
  projectId: my-project-123

​
provider.type

string — required Must be gcp. 
provider:
  type: gcp

​
provider.projectId

string — optional GCP project ID where resources will be provisioned. 
provider:
  projectId: my-project-123

​
provider.credentialConfig

string — optional Credential configuration JSON generated from the workload identity application. This is a JSON string that contains the credential configuration. 
provider:
  credentialConfig: |
    {
      "type": "external_account",
      "audience": "//iam.googleapis.com/projects/123/locations/global/...",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "token_url": "https://sts.googleapis.com/v1/token"
    }

​
installations

array — optional List of service installations to deploy in this environment. See Server, Job, Helm Chart, Terraform, and Blueprint installation documentation for details. 
installations:
  - service: api
  - blueprint: observability-stack

​
Platform blueprint configuration

The GCP platform blueprint (ryvn.app/gcp-platform) accepts the following configuration inputs when installed in an environment:

​
Observability configuration

InputTypeDefaultDescription
logRedactionbooleanfalseEnable log redaction to remove sensitive information from logs
redactionPatternsarray-Regex patterns for log redaction (available when logRedaction is enabled)
metricsbooleantrueEnable metrics collection and forwarding
installations:
  - blueprint: ryvn.app/gcp-platform
    inputs:
      - name: logRedaction
        value: true
      - name: redactionPatterns
        value:
          - "password=\\S+"
          - "api[_-]?key=\\S+"
      - name: metrics
        value: true

​
Outputs

Environment outputs are available in service installation configs using template syntax. Reference these values to configure services with infrastructure details provisioned by Ryvn.

​
.ryvn.env.name

The name of the environment. 
environment: '{{ .ryvn.env.name }}'

​
.ryvn.env.orgId

The organization ID. 
org_id: '{{ .ryvn.env.orgId }}'

​
.ryvn.env.defaultNamespace

The default Kubernetes namespace for the environment (typically same as environment name). 
namespace: '{{ .ryvn.env.defaultNamespace }}'

​
.ryvn.env.releaseChannel

The release channel for this environment. 
channel: '{{ .ryvn.env.releaseChannel }}'

​
.ryvn.env.provider.type

The provider type (e.g., aws, gcp, azure, k3s). 
provider_type: '{{ .ryvn.env.provider.type }}'

​
.ryvn.env.provider.gcp.projectId

The GCP project ID where resources are provisioned. 
project_id: '{{ .ryvn.env.provider.gcp.projectId }}'

​
.ryvn.env.config

Environment configuration as a key-value map. Access custom config values you define in your environment using dot notation. 
# Example: Access custom operational settings
debug_mode: '{{ .ryvn.env.config.enable_debug_mode }}'

# Example: Access external service configuration
datadog_site: '{{ .ryvn.env.config.datadog_region }}'

​
.ryvn.env.state.cluster_name

The name of the GKE cluster. 
cluster_name: '{{ .ryvn.env.state.cluster_name }}'

​
.ryvn.env.state.cluster_endpoint

Endpoint for the Kubernetes API server. 
endpoint: '{{ .ryvn.env.state.cluster_endpoint }}'

​
.ryvn.env.state.cluster_region

GCP region where the GKE cluster is deployed. 
region: '{{ .ryvn.env.state.cluster_region }}'

​
.ryvn.env.state.ryvn_agent_service_account.email

Email address of the service account for the Ryvn Agent. 
service_account_email: '{{ .ryvn.env.state.ryvn_agent_service_account.email }}'

​
.ryvn.env.state.ryvn_agent_service_account.id

ID of the service account for the Ryvn Agent. 
service_account_id: '{{ .ryvn.env.state.ryvn_agent_service_account.id }}'

​
.ryvn.env.state.ryvn_agent_service_account.unique_id

Unique ID of the service account for the Ryvn Agent. 
service_account_unique_id: '{{ .ryvn.env.state.ryvn_agent_service_account.unique_id }}'

​
.ryvn.env.state.cert_manager_identity.email

Email address of the service account for cert-manager. 
cert_manager_service_account_email: '{{ .ryvn.env.state.cert_manager_identity.email }}'

​
.ryvn.env.state.cert_manager_identity.id

ID of the service account for cert-manager. 
cert_manager_service_account_id: '{{ .ryvn.env.state.cert_manager_identity.id }}'

​
.ryvn.env.state.cert_manager_identity.unique_id

Unique ID of the service account for cert-manager. 
cert_manager_service_account_unique_id: '{{ .ryvn.env.state.cert_manager_identity.unique_id }}'

​
.ryvn.env.state.vpc.id

ID of the VPC network. 
vpc_id: '{{ .ryvn.env.state.vpc.id }}'

​
.ryvn.env.state.vpc.name

Name of the VPC network. 
vpc_name: '{{ .ryvn.env.state.vpc.name }}'
Self link of the VPC network (required for many GCP resources). 
vpc_self_link: '{{ .ryvn.env.state.vpc.self_link }}'

​
.ryvn.env.state.vpc.subnet_ids

List of subnet IDs. 
subnet_ids: '{{ .ryvn.env.state.vpc.subnet_ids | toJson }}'

​
.ryvn.env.state.vpc.subnet_cidrs

List of subnet CIDR blocks. 
subnet_cidrs: '{{ .ryvn.env.state.vpc.subnet_cidrs | toJson }}'

​
.ryvn.env.state.outbound_ips

List of public IPs used for outbound internet traffic from workloads in this environment. 
outbound_ips: '{{ .ryvn.env.state.outbound_ips | toJson }}'

​
.ryvn.env.state.vpc.nat_public_ips

List of public IPs assigned to Cloud NAT. 
nat_ips: '{{ .ryvn.env.state.vpc.nat_public_ips | toJson }}'

​
.ryvn.env.state.vpc.secondary_ranges.pods.name

Name of the secondary range for pods. 
pods_range_name: '{{ .ryvn.env.state.vpc.secondary_ranges.pods.name }}'

​
.ryvn.env.state.vpc.secondary_ranges.pods.cidr

CIDR block for the pods secondary range. 
pods_cidr: '{{ .ryvn.env.state.vpc.secondary_ranges.pods.cidr }}'

​
.ryvn.env.state.vpc.secondary_ranges.services.name

Name of the secondary range for services. 
services_range_name: '{{ .ryvn.env.state.vpc.secondary_ranges.services.name }}'

​
.ryvn.env.state.vpc.secondary_ranges.services.cidr

CIDR block for the services secondary range. 
services_cidr: '{{ .ryvn.env.state.vpc.secondary_ranges.services.cidr }}'

​
.ryvn.env.state.public_domain.name

Public root domain name for the environment. 
domain: '{{ .ryvn.env.state.public_domain.name }}'

​
.ryvn.env.state.public_domain.fqdn

Fully qualified domain name for the public domain (includes trailing dot). 
domain_fqdn: '{{ .ryvn.env.state.public_domain.fqdn }}'

​
.ryvn.env.state.public_domain.id

Cloud DNS managed zone ID for the public domain. 
zone_id: '{{ .ryvn.env.state.public_domain.id }}'

​
.ryvn.env.state.public_domain.nameservers

List of nameservers for the public domain. 
nameservers: '{{ .ryvn.env.state.public_domain.nameservers | toJson }}'

​
.ryvn.env.state.internal_domain.name

Internal domain name for the environment. 
internal_domain: '{{ .ryvn.env.state.internal_domain.name }}'

​
.ryvn.env.state.internal_domain.fqdn

Fully qualified domain name for the internal domain (includes trailing dot). 
internal_domain_fqdn: '{{ .ryvn.env.state.internal_domain.fqdn }}'

​
.ryvn.env.state.internal_domain.id

Cloud DNS managed zone ID for the internal domain. 
internal_zone_id: '{{ .ryvn.env.state.internal_domain.id }}'

​
Examples

Multi-environment setup: 
kind: Environment
metadata:
  name: staging
spec:
  releaseChannel: staging
  provider:
    type: gcp
    projectId: my-staging-project
  config:
    region: us-west1
    subnet_cidr: "10.1.0.0/17"
  installations:
    - service: api
    - service: frontend
---
kind: Environment
metadata:
  name: prod-us
spec:
  releaseChannel: production
  provider:
    type: gcp
    projectId: my-production-project
  config:
    region: us-central1
    subnet_cidr: "10.0.0.0/17"
    node_pools:
      default:
        machine_type: n2-standard-4
        total_min_count: 3
        total_max_count: 10
    flow_logs:
      enable: "true"
  installations:
    - service: api
    - service: frontend
    - service: database
---
kind: Environment
metadata:
  name: prod-eu
spec:
  releaseChannel: production
  provider:
    type: gcp
    projectId: my-production-project
  config:
    region: europe-west1
    subnet_cidr: "10.2.0.0/17"
    node_pools:
      default:
        machine_type: n2-standard-4
        total_min_count: 3
        total_max_count: 10
    flow_logs:
      enable: "true"
  installations:
    - service: api
    - service: frontend
    - service: database
With custom domains: 
kind: Environment
metadata:
  name: production
spec:
  releaseChannel: production
  provider:
    type: gcp
    projectId: my-production-project
  config:
    region: us-central1
    internal_root_domain: internal.example.com
    public_root_domain: example.com
  installations:
    - service: api
Customer-provisioned environment: 
kind: Environment
metadata:
  name: customer-prod
spec:
  releaseChannel: stable
  setup: customer-controlled
  customerEmail: admin@customer.com
  provider:
    type: gcp
    projectId: customer-project-123
  installations:
    - service: api