Skip to main content
Environments define where your services are deployed. Ryvn provisions and manages infrastructure in target AWS accounts, including VPCs, Kubernetes clusters, 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: aws
    accountId: "123456789012"
  config:
    region: us-east-1
    vpc_cidr: 10.0.0.0/16
  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-west-2
  vpc_cidr: "10.0.0.0/16"
  cluster_version: "1.33"

​
config.region

string — optional AWS region where resources will be provisioned. Defaults to us-east-1. 
config:
  region: us-west-2

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

string — optional CIDR block for the VPC. Defaults to 10.0.0.0/16. 
config:
  vpc_cidr: "10.1.0.0/16"

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

object — optional Map of EKS managed node group definitions to create. Each key is a node group name, and its value is an object with the following fields. Values will be merged with defaults if not specified.
FieldTypeDescription
instance_typeslist(string)EC2 instance types for the node group (e.g., ["t3.large", "t3.xlarge"])
min_sizenumberMinimum number of nodes
max_sizenumberMaximum number of nodes
desired_sizenumberInitial desired number of nodes
ami_typestringAMI type (e.g., AL2_x86_64, AL2_ARM_64, BOTTLEROCKET_x86_64)
labelsmap(string)Kubernetes labels applied to nodes
subnet_idslist(string)Specific subnet IDs for node placement
block_device_mappingsmap(object)EBS volume configuration (see example below)
config:
  eks_managed_node_groups:
    default:
      instance_types: ["t3.large"]
      min_size: 2
      max_size: 10
      desired_size: 3
    gpu:
      instance_types: ["g5.xlarge"]
      min_size: 0
      max_size: 4
      desired_size: 0
      ami_type: AL2_x86_64_GPU
      labels:
        workload-type: gpu
      block_device_mappings:
        xvda:
          device_name: /dev/xvda
          ebs:
            volume_size: 100
            volume_type: gp3
            encrypted: true
            delete_on_termination: true

​
config.create_cloudwatch_log_group

boolean — optional If true, creates a new CloudWatch log group for EKS cluster logging. Defaults to false. 
config:
  create_cloudwatch_log_group: true

​
config.terraform_executor_policies

array — optional Additional IAM policy statements to be added to the Ryvn Agent role. Each policy statement should include effect, actions, and resources. 
config:
  terraform_executor_policies:
    - effect: Allow
      actions:
        - s3:GetObject
        - s3:PutObject
      resources:
        - arn:aws:s3:::my-bucket/*

​
config.cluster_endpoint_public_access_cidrs

array — optional List of CIDR blocks which can access the Amazon EKS public API server endpoint. If not specified, defaults to Ryvn Hub IPs. 
config:
  cluster_endpoint_public_access_cidrs:
    - "203.0.113.0/24"
    - "198.51.100.0/24"

​
config.enable_flow_log

boolean — optional If true, enables VPC Flow Logs. Defaults to false. 
config:
  enable_flow_log: true

​
config.skip_dns_provisioning

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

​
config.cluster_addons

object — optional Map of cluster addon configurations. Each key is an addon name (e.g., vpc-cni, coredns, kube-proxy, aws-ebs-csi-driver), and its value is passed to the terraform-aws-modules/eks module’s cluster_addons input. Will be merged with Ryvn’s default addon configurations. Default addons include coredns, eks-pod-identity-agent, kube-proxy, vpc-cni, and aws-ebs-csi-driver. Common fields per addon:
FieldTypeDescription
configuration_valuesstringJSON or YAML string of addon-specific configuration
resolve_conflicts_on_createstringConflict resolution on create: OVERWRITE or NONE
resolve_conflicts_on_updatestringConflict resolution on update: OVERWRITE, PRESERVE, or NONE
before_computebooleanInstall addon before compute resources are created
config:
  cluster_addons:
    vpc-cni:
      configuration_values: |
        enableNetworkPolicy: "true"
    coredns:
      configuration_values: |
        corefile: |
          .:53 {
            errors
          }

​
config.enable_transit_gateway_subnets

boolean — optional If true, enables creation of Transit Gateway subnets. When enabled, creates /28 subnets (14 usable IPs each) following AWS best practices. Defaults to false. 
config:
  enable_transit_gateway_subnets: true

​
config.transit_gateway_subnets

array — optional Custom CIDR blocks for transit gateway subnets. If empty, will auto-calculate /28 subnets when enable_transit_gateway_subnets is true. AWS recommends /28 subnets to minimize IP usage. 
config:
  transit_gateway_subnets:
    - "10.0.255.0/28"
    - "10.0.255.16/28"
    - "10.0.255.32/28"

​
config.pod_identity_associations

object — optional Map of additional EKS Pod Identity associations to create. Assumes IAM roles already exist. Cannot create associations in system-managed namespaces. 
config:
  pod_identity_associations:
    my_app:
      namespace: default
      service_account: my-app-sa
      role_arn: arn:aws:iam::123456789012:role/MyAppRole

​
setup

string — optional Environment setup type. Controls who provisions the environment infrastructure. Available values:
  • customer-controlled - Ryvn Provisioner (EC2 instance in the customer’s AWS account) provisions the infrastructure
  • self - Ryvn Control Plane uses cross-account permissions 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 AWS provider configuration. 
provider:
  type: aws
  accountId: "123456789012"

​
provider.type

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

​
provider.accountId

string — optional AWS account ID where resources will be provisioned. 
provider:
  accountId: "123456789012"

​
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 AWS platform blueprint (ryvn.app/aws-platform) accepts the following configuration inputs when installed in an environment:

​
Node Configuration

InputTypeDefaultDescription
instanceCategoriesarray["m", "r"]Types of EC2 instances to use. Options include general purpose (m), memory optimized (r), compute optimized (c), and burstable performance (t).
cpuSizesarray["4", "8", "16", "32"]The number of vCPUs allowed for each instance.
diskSizestring"128Gi"Amount of ephemeral disk space allocated to each node for storing container images, logs, and application data. Data does not persist if the node is replaced.
customNodePoolsstring""Advanced configuration for defining custom node pools with specific requirements, taints, or labels. Provide as YAML.
customNodeClassesstring""Advanced configuration for defining custom node classes with specific AMIs, block devices, or instance store policies. Provide as YAML.

​
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/aws-platform
    inputs:
      - name: instanceCategories
        value: ["m", "c"]
      - name: cpuSizes
        value: ["8", "16"]
      - name: diskSize
        value: "256Gi"
      - 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.aws.accountId

The AWS account ID where resources are provisioned. 
account_id: '{{ .ryvn.env.provider.aws.accountId }}'

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

AWS region where the EKS cluster is deployed. 
region: '{{ .ryvn.env.state.cluster_region }}'

​
.ryvn.env.state.cluster_oidc_issuer_url

URL for the OpenID Connect identity provider on the EKS cluster. 
oidc_issuer: '{{ .ryvn.env.state.cluster_oidc_issuer_url }}'

​
.ryvn.env.state.ryvn_agent_role_arn

ARN of the IAM role for the Ryvn Agent. 
role_arn: '{{ .ryvn.env.state.ryvn_agent_role_arn }}'

​
.ryvn.env.state.aws_load_balancer_controller_role_arn

ARN of the IAM role for AWS Load Balancer Controller. 
alb_controller_role: '{{ .ryvn.env.state.aws_load_balancer_controller_role_arn }}'

​
.ryvn.env.state.cluster_node_security_group_id

Security group ID attached to the EKS cluster nodes. 
node_sg: '{{ .ryvn.env.state.cluster_node_security_group_id }}'

​
.ryvn.env.state.cluster_security_group_id

Security group ID attached to the EKS cluster. 
cluster_sg: '{{ .ryvn.env.state.cluster_security_group_id }}'

​
.ryvn.env.state.vpc.id

VPC ID where the cluster is deployed. 
vpc_id: '{{ .ryvn.env.state.vpc.id }}'

​
.ryvn.env.state.vpc.name

VPC name. 
vpc_name: '{{ .ryvn.env.state.vpc.name }}'

​
.ryvn.env.state.vpc.cidr

VPC CIDR block. 
vpc_cidr: '{{ .ryvn.env.state.vpc.cidr }}'

​
.ryvn.env.state.vpc.azs

List of availability zones used by the VPC. 
availability_zones: '{{ .ryvn.env.state.vpc.azs | toJson }}'

​
.ryvn.env.state.vpc.private_subnet_ids

List of private subnet IDs. 
private_subnets: '{{ .ryvn.env.state.vpc.private_subnet_ids | toJson }}'

​
.ryvn.env.state.vpc.private_subnet_cidr_blocks

List of CIDR blocks for private subnets. 
private_cidrs: '{{ .ryvn.env.state.vpc.private_subnet_cidr_blocks | toJson }}'

​
.ryvn.env.state.vpc.public_subnet_ids

List of public subnet IDs. 
public_subnets: '{{ .ryvn.env.state.vpc.public_subnet_ids | toJson }}'

​
.ryvn.env.state.vpc.public_subnet_cidr_blocks

List of CIDR blocks for public subnets. 
public_cidrs: '{{ .ryvn.env.state.vpc.public_subnet_cidr_blocks | toJson }}'

​
.ryvn.env.state.vpc.default_security_group_id

Default security group ID for the VPC. 
default_sg: '{{ .ryvn.env.state.vpc.default_security_group_id }}'

​
.ryvn.env.state.vpc.nat_public_ips

List of public IPs for NAT Gateways. 
nat_ips: '{{ .ryvn.env.state.vpc.nat_public_ips | toJson }}'

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

Route53 hosted 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.id

Route53 hosted zone ID for the internal domain. 
internal_zone_id: '{{ .ryvn.env.state.internal_domain.id }}'

​
.ryvn.env.state.karpenter.queue_name

SQS queue name for Karpenter interruption handling. 
queue_name: '{{ .ryvn.env.state.karpenter.queue_name }}'

​
.ryvn.env.state.karpenter.namespace

Kubernetes namespace where Karpenter is deployed. 
namespace: '{{ .ryvn.env.state.karpenter.namespace }}'

​
Examples

Multi-environment setup: 
kind: Environment
metadata:
  name: staging
spec:
  releaseChannel: staging
  provider:
    type: aws
    accountId: "123456789012"
  config:
    region: us-west-2
    vpc_cidr: "10.1.0.0/16"
  installations:
    - service: api
    - service: frontend
---
kind: Environment
metadata:
  name: prod-us
spec:
  releaseChannel: production
  provider:
    type: aws
    accountId: "987654321098"
  config:
    region: us-east-1
    vpc_cidr: "10.0.0.0/16"
    enable_flow_log: true
  installations:
    - service: api
    - service: frontend
    - service: database
---
kind: Environment
metadata:
  name: prod-eu
spec:
  releaseChannel: production
  provider:
    type: aws
    accountId: "987654321098"
  config:
    region: eu-west-1
    vpc_cidr: "10.2.0.0/16"
    enable_flow_log: true
  installations:
    - service: api
    - service: frontend
    - service: database
With custom domains: 
kind: Environment
metadata:
  name: production
spec:
  releaseChannel: production
  provider:
    type: aws
    accountId: "123456789012"
  config:
    region: us-east-1
    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: aws
    accountId: "111122223333"
  installations:
    - service: api