Skip to main content
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

​
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.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.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