AWS - Ryvn

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

`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-east
    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-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.

Field	Type	Description
`instance_types`	`list(string)`	EC2 instance types for the node group (e.g., `["t3.large", "t3.xlarge"]`)
`min_size`	`number`	Minimum number of nodes
`max_size`	`number`	Maximum number of nodes
`desired_size`	`number`	Initial desired number of nodes
`ami_type`	`string`	AMI type (e.g., `AL2_x86_64`, `AL2_ARM_64`, `BOTTLEROCKET_x86_64`)
`labels`	`map(string)`	Kubernetes labels applied to nodes
`subnet_ids`	`list(string)`	Specific subnet IDs for node placement
`block_device_mappings`	`map(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. You can optionally add a condition field to scope permissions using IAM condition operators.

Field	Type	Description
`effect`	`string`	IAM effect (`Allow` or `Deny`)
`actions`	`list(string)`	List of IAM actions
`resources`	`list(string)`	List of resource ARNs
`resource`	`string`	Single resource ARN (alternative to `resources`)
`condition`	`object`	Optional IAM condition block

config:
  terraform_executor_policies:
    - effect: Allow
      actions:
        - s3:GetObject
        - s3:PutObject
      resources:
        - arn:aws:s3:::my-bucket/*

To add IAM conditions for fine-grained access control:

config:
  terraform_executor_policies:
    - effect: Allow
      actions:
        - kms:Decrypt
        - kms:Encrypt
      resources:
        - arn:aws:kms:us-east-1:123456789012:key/*
      condition:
        StringEquals:
          kms:ViaService: secretsmanager.us-east-1.amazonaws.com

`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, aws-efs-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. Environments using the Karpenter provisioner also include aws-efs-csi-driver by default. Some default addons (such as aws-ebs-csi-driver and aws-efs-csi-driver) are pre-configured with service_account_role_arn for IRSA. Common fields per addon:

Field	Type	Description
`configuration_values`	`string`	JSON or YAML string of addon-specific configuration
`service_account_role_arn`	`string`	IAM role ARN for the addon’s service account (IRSA). Set automatically for default addons — avoid overriding unless you are providing your own role.
`resolve_conflicts_on_create`	`string`	Conflict resolution on create: `OVERWRITE` or `NONE`
`resolve_conflicts_on_update`	`string`	Conflict resolution on update: `OVERWRITE`, `PRESERVE`, or `NONE`
`before_compute`	`boolean`	Install 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:

Creates a customer organization and user account
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

Input	Type	Default	Description
`instanceCategories`	`array`	`["m", "r"]`	Types of EC2 instances to use. Options include general purpose (m), memory optimized (r), compute optimized (c), and burstable performance (t).
`cpuSizes`	`array`	`["4", "8", "16", "32"]`	The number of vCPUs allowed for each instance.
`diskSize`	`string`	`"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.
`customNodePools`	`string`	`""`	Advanced configuration for defining custom node pools with specific requirements, taints, or labels. Provide as YAML.
`customNodeClasses`	`string`	`""`	Advanced configuration for defining custom node classes with specific AMIs, block devices, or instance store policies. Provide as YAML.

Observability configuration

Input	Type	Default	Description
`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

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.control_plane_logging.log_group_name`

Name of the CloudWatch log group receiving EKS control-plane logs.

log_group: '{{ .ryvn.env.state.control_plane_logging.log_group_name }}'

`.ryvn.env.state.control_plane_logging.log_group_arn`

ARN of the CloudWatch log group receiving EKS control-plane logs.

log_group_arn: '{{ .ryvn.env.state.control_plane_logging.log_group_arn }}'

`.ryvn.env.state.control_plane_logging.enabled_log_types`

List of EKS control-plane log types currently emitted: api, audit, authenticator, controllerManager, scheduler.

log_types: '{{ .ryvn.env.state.control_plane_logging.enabled_log_types | toJson }}'

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

Services

Environments

Installations

Blueprints

Releases

Documentation Index

​Properties

​name

​labels

​releaseChannel

​maintenanceWindow

​config

​config.region

​config.internal_root_domain

​config.public_root_domain

​config.vpc_cidr

​config.cluster_bootstrap_perms

​config.eks_managed_node_groups

​config.create_cloudwatch_log_group

​config.terraform_executor_policies

​config.cluster_endpoint_public_access_cidrs

​config.enable_flow_log

​config.skip_dns_provisioning

​config.cluster_addons

​config.enable_transit_gateway_subnets

​config.transit_gateway_subnets

​config.pod_identity_associations

​setup

​customerEmail

​requireApproval

​provider

​provider.type

​provider.accountId

​installations

​Platform blueprint configuration

​Node configuration

​Observability configuration

​Outputs

​.ryvn.env.name

​.ryvn.env.orgId

​.ryvn.env.defaultNamespace

​.ryvn.env.releaseChannel

​.ryvn.env.provider.type

​.ryvn.env.provider.aws.accountId

​.ryvn.env.config

​.ryvn.env.state.cluster_name

​.ryvn.env.state.cluster_endpoint

​.ryvn.env.state.cluster_region

​.ryvn.env.state.cluster_oidc_issuer_url

​.ryvn.env.state.ryvn_agent_role_arn

​.ryvn.env.state.aws_load_balancer_controller_role_arn

​.ryvn.env.state.cluster_node_security_group_id

​.ryvn.env.state.cluster_security_group_id

​.ryvn.env.state.control_plane_logging.log_group_name

​.ryvn.env.state.control_plane_logging.log_group_arn

​.ryvn.env.state.control_plane_logging.enabled_log_types

​.ryvn.env.state.vpc.id

​.ryvn.env.state.vpc.name

​.ryvn.env.state.vpc.cidr

​.ryvn.env.state.vpc.azs

​.ryvn.env.state.vpc.private_subnet_ids

​.ryvn.env.state.vpc.private_subnet_cidr_blocks

​.ryvn.env.state.vpc.public_subnet_ids

​.ryvn.env.state.vpc.public_subnet_cidr_blocks

​.ryvn.env.state.vpc.default_security_group_id

​.ryvn.env.state.vpc.nat_public_ips

​.ryvn.env.state.outbound_ips

​.ryvn.env.state.public_domain.name

​.ryvn.env.state.public_domain.id

​.ryvn.env.state.public_domain.nameservers

​.ryvn.env.state.internal_domain.name

​.ryvn.env.state.internal_domain.id

​.ryvn.env.state.karpenter.queue_name

​.ryvn.env.state.karpenter.namespace

​Examples