GCP - Ryvn

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. See the full GCP permission reference for the roles and permissions Ryvn needs to provision your environment.

# 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
  platform:
    blueprint: ryvn.app/gcp-platform
    inputs:
      - name: logs
        value: true
---
kind: ServiceInstallation
metadata:
  name: api-prod-us
spec:
  service: api
  environment: prod-us

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 up to three zones in 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 an internal domain for the environment, separate from its public domain.

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
      location_policy: ANY
      labels:
        environment: production

location_policy controls which zone the cluster autoscaler scales a regional pool into. BALANCED (the GKE default) spreads nodes evenly across zones; ANY prefers zones with unused reservations and available capacity, which helps pools that scale from zero onto zonal reservations.

`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 — managed by Ryvn Grants the provisioning identity cluster admin permissions so Ryvn can install the agent and its access RBAC after the cluster is created. Ryvn always sets this to true; a value in config is ignored.

`config.terraform_executor_policies`

object — optional IAM grants for the Ryvn Agent, the in-cluster identity that runs Terraform for your installations. Leave it unset to keep the default custom role, which is shaped as management-without-data-access (see default_permissions in the platform module). Anything you supply replaces the default grants outright, the same way terraform_executor_policies on AWS replaces the default policy. Only the grants you list are bound, so include everything the agent needs for the services you install. roles, permissions, and bindings can be combined.

config:
  terraform_executor_policies:
    roles:
      - roles/storage.admin
      - roles/compute.viewer

`config.terraform_executor_policies.roles`

array — optional Predefined GCP roles to bind to the agent at the project level.

terraform_executor_policies:
  roles:
    - roles/storage.admin
    - roles/compute.viewer

`config.terraform_executor_policies.permissions`

array — optional Permissions for the agent’s custom role (ryvn_agent_role_ENVIRONMENT), in place of the defaults.

terraform_executor_policies:
  permissions:
    - storage.buckets.create
    - storage.buckets.delete

`config.terraform_executor_policies.bindings`

array — optional Role bindings for the agent, each optionally scoped by an IAM condition. Use this to grant a role only on the resources you intend the agent to manage.

Field	Type	Description
`name`	`string`	Stable key for the binding, 1–12 lowercase alphanumerics or hyphens. Also names the custom role when `permissions` is used
`role`	`string`	Predefined or existing custom role to bind. Exactly one of `role` or `permissions`
`permissions`	`list(string)`	Permissions for a custom role created for this binding (`ryvn_agent_ENVIRONMENT_NAME`)
`condition`	`object`	Optional IAM condition: `title`, `expression`, and optional `description`, as accepted by `gcloud --condition`

terraform_executor_policies:
  bindings:
    - name: kms
      role: roles/cloudkms.admin
      condition:
        title: Ryvn key rings only
        expression: resource.name.startsWith("projects/my-project/locations/us-central1/keyRings/my-env-")

GCP authorizes create permissions on the parent resource (the location for key rings, the project for most resources), so a resource.name condition scopes operations on existing resources but not their creation. Grant the sensitive operations (setIamPolicy, update, destroy) under a condition and leave creation unconditional.

With the default grants, the agent’s destructive Cloud SQL permissions (creating and dropping databases and users, updating or deleting instances, managing backups) are granted through a separate role whose binding is conditioned on a ryvn-managed-ENVIRONMENT tag that the agent attaches to the Cloud SQL instances it provisions — so it cannot touch Cloud SQL instances it did not create. Instances created before this behavior existed carry no tag; re-running the postgres installation attaches it. Supplying any terraform_executor_policies replaces the defaults and drops this scoping. The tag is still attached, so you can restate it with a bindings entry whose condition is resource.matchTag('PROJECT_ID/ryvn-managed-ENVIRONMENT', 'true').

`setup`

string — optional Environment setup type. Controls who provisions the environment infrastructure. Available values:

self - Ryvn Control Plane uses workload identity to provision the infrastructure (default)
pre-provisioned - Use existing or externally managed infrastructure

setup: self

`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"
    }

`namespaces`

array — optional Kubernetes namespaces to create in this environment, with optional labels. Ryvn creates each one, adds its own labels, and reapplies yours on every sync. The default namespace (same name as the environment) exists either way; list it only to label it. Removing an entry does not delete the namespace. See Namespaces.

name (required): a DNS-1123 label, lowercase alphanumerics and hyphens, up to 63 characters
labels (optional): labels to apply to the namespace

namespaces:
  - name: prod-us
    labels:
      pod-security.kubernetes.io/enforce: baseline
  - name: inngest

`platform`

object — optional Platform blueprint used to provision the environment and its inputs. Self-provisioned environments default to the Ryvn-managed platform blueprint for the cloud (ryvn.app/gcp-platform); pre-provisioned environments (setup: pre-provisioned) default to ryvn.app/base-platform. See Platform blueprint configuration for the available inputs.

platform:
  blueprint: ryvn.app/gcp-platform
  inputs:
    - name: logs
      value: true
    - name: metrics
      value: false

`installations`

array — read-only Present in the API representation of an environment only. Git export emits each deployed installation as a standalone resource, and git sync does not read this field. To deploy into an environment, declare standalone ServiceInstallation or BlueprintInstallation resources whose spec.environment references the environment:

kind: ServiceInstallation
metadata:
  name: api-prod-us
spec:
  service: api
  environment: prod-us
---
kind: BlueprintInstallation
metadata:
  name: observability-stack-prod-us
spec:
  blueprint: observability-stack
  environment: prod-us

Installations listed inline under an Environment’s spec.installations are ignored by git sync. Declare them as separate resources.

See Server, Job, Helm Chart, Terraform, and Blueprint installation documentation for details.

Platform blueprint configuration

The GCP platform blueprint (ryvn.app/gcp-platform) accepts the following inputs via the environment’s platform field:

Observability configuration

Apart from workload logs, which the Ryvn collector handles, GKE writes system and control-plane logs to Cloud Logging and system metrics to Cloud Monitoring in your project.

Input	Type	Default	Description
`logs`	`boolean`	`true`	Collect and forward workload logs.
`logRedaction`	`boolean`	`false`	Enable log redaction to remove sensitive information from logs
`redactionPatterns`	`array`	-	Regex patterns for log redaction (available when logRedaction is enabled)
`metrics`	`boolean`	`true`	Enable metrics collection and forwarding

platform:
  blueprint: ryvn.app/gcp-platform
  inputs:
    - name: logs
      value: false
    - 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).

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`

Private IP endpoint of the Kubernetes API server, reachable only from inside the VPC.

endpoint: '{{ .ryvn.env.state.cluster_endpoint }}'

`.ryvn.env.state.cluster_endpoint_dns`

DNS-based endpoint of the Kubernetes API server, gated by IAM.

endpoint: '{{ .ryvn.env.state.cluster_endpoint_dns }}'

`.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 }}'

`.ryvn.env.state.vpc.self_link`

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"
---
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"
---
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"
---
kind: ServiceInstallation
metadata:
  name: api-staging
spec:
  service: api
  environment: staging
---
kind: ServiceInstallation
metadata:
  name: frontend-staging
spec:
  service: frontend
  environment: staging

Installations for the other environments follow the same pattern. 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
---
kind: ServiceInstallation
metadata:
  name: api-production
spec:
  service: api
  environment: production

Pre-provisioned environment:

kind: Environment
metadata:
  name: customer-prod
spec:
  releaseChannel: stable
  setup: pre-provisioned
  provider:
    type: gcp
    projectId: customer-project-123
---
kind: ServiceInstallation
metadata:
  name: api-customer-prod
spec:
  service: api
  environment: customer-prod

⌘I

​Properties

​name

​labels

​releaseChannel

​maintenanceWindow

​config

​config.region

​config.zones

​config.internal_root_domain

​config.public_root_domain

​config.subnet_cidr

​config.pod_cidr

​config.service_cidr

​config.node_pools

​config.node_pools_labels

​config.flow_logs

​config.external_dns_namespace

​config.skip_dns_provisioning

​config.cluster_bootstrap_perms

​config.terraform_executor_policies

​config.terraform_executor_policies.roles

​config.terraform_executor_policies.permissions

​config.terraform_executor_policies.bindings

​setup

​requireApproval

​provider

​provider.type

​provider.projectId

​provider.credentialConfig

​namespaces

​platform

​installations

​Platform blueprint configuration

​Observability configuration

​Outputs

​.ryvn.env.name

​.ryvn.env.orgId

​.ryvn.env.defaultNamespace

​.ryvn.env.releaseChannel

​.ryvn.env.provider.type

​.ryvn.env.provider.gcp.projectId

​.ryvn.env.config

​.ryvn.env.state.cluster_name

​.ryvn.env.state.cluster_endpoint

​.ryvn.env.state.cluster_endpoint_dns

​.ryvn.env.state.cluster_region

​.ryvn.env.state.ryvn_agent_service_account.email

​.ryvn.env.state.ryvn_agent_service_account.id

​.ryvn.env.state.ryvn_agent_service_account.unique_id

​.ryvn.env.state.cert_manager_identity.email

​.ryvn.env.state.cert_manager_identity.id

​.ryvn.env.state.cert_manager_identity.unique_id

​.ryvn.env.state.vpc.id

​.ryvn.env.state.vpc.name

​.ryvn.env.state.vpc.self_link

​.ryvn.env.state.vpc.subnet_ids

​.ryvn.env.state.vpc.subnet_cidrs

​.ryvn.env.state.outbound_ips

​.ryvn.env.state.vpc.nat_public_ips

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

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

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

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

​.ryvn.env.state.public_domain.name

​.ryvn.env.state.public_domain.fqdn

​.ryvn.env.state.public_domain.id

​.ryvn.env.state.public_domain.nameservers

​.ryvn.env.state.internal_domain.name

​.ryvn.env.state.internal_domain.fqdn

​.ryvn.env.state.internal_domain.id

​Examples

Properties

`name`

`labels`

`releaseChannel`

`maintenanceWindow`

`config`

`config.region`

`config.zones`

`config.internal_root_domain`

`config.public_root_domain`

`config.subnet_cidr`

`config.pod_cidr`

`config.service_cidr`

`config.node_pools`

`config.node_pools_labels`

`config.flow_logs`

`config.external_dns_namespace`

`config.skip_dns_provisioning`

`config.cluster_bootstrap_perms`

`config.terraform_executor_policies`

`config.terraform_executor_policies.roles`

`config.terraform_executor_policies.permissions`

`config.terraform_executor_policies.bindings`

`setup`

`requireApproval`

`provider`

`provider.type`

`provider.projectId`

`provider.credentialConfig`

`namespaces`

`platform`

`installations`

Platform blueprint configuration

Observability configuration

Outputs

`.ryvn.env.name`

`.ryvn.env.orgId`

`.ryvn.env.defaultNamespace`

`.ryvn.env.releaseChannel`

`.ryvn.env.provider.type`

`.ryvn.env.provider.gcp.projectId`

`.ryvn.env.config`

`.ryvn.env.state.cluster_name`

`.ryvn.env.state.cluster_endpoint`

`.ryvn.env.state.cluster_endpoint_dns`

`.ryvn.env.state.cluster_region`

`.ryvn.env.state.ryvn_agent_service_account.email`

`.ryvn.env.state.ryvn_agent_service_account.id`

`.ryvn.env.state.ryvn_agent_service_account.unique_id`

`.ryvn.env.state.cert_manager_identity.email`

`.ryvn.env.state.cert_manager_identity.id`

`.ryvn.env.state.cert_manager_identity.unique_id`

`.ryvn.env.state.vpc.id`

`.ryvn.env.state.vpc.name`

`.ryvn.env.state.vpc.self_link`

`.ryvn.env.state.vpc.subnet_ids`

`.ryvn.env.state.vpc.subnet_cidrs`

`.ryvn.env.state.outbound_ips`

`.ryvn.env.state.vpc.nat_public_ips`

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

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

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

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

`.ryvn.env.state.public_domain.name`

`.ryvn.env.state.public_domain.fqdn`

`.ryvn.env.state.public_domain.id`

`.ryvn.env.state.public_domain.nameservers`

`.ryvn.env.state.internal_domain.name`

`.ryvn.env.state.internal_domain.fqdn`

`.ryvn.env.state.internal_domain.id`

Examples