Properties
name
string — required
Environment identifier. Must be lowercase, alphanumeric with hyphens only.
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
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.
maintenanceWindow
string — optional
Maintenance window for this environment. Automated deployments will only occur during specified intervals.
config
object — optional
Configuration passed to the Ryvn environment provisioner.
config.region
string — optional
AWS region where resources will be provisioned. Defaults to us-east-1.
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.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.vpc_cidr
string — optional
CIDR block for the VPC. Defaults to 10.0.0.0/16.
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.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.
Use
NO_SCHEDULE, PREFER_NO_SCHEDULE, or NO_EXECUTE for each taint’s effect. See Node group with taints for the map format and an example.
config.create_cloudwatch_log_group
boolean — optional
If true, creates a new CloudWatch log group for EKS cluster logging. Defaults
to false.
config.terraform_executor_policies
array — optional
IAM policy statements for the Ryvn Agent role. When set, they replace the
default policy (a broad allow with explicit denies on data access) outright, so
the list must cover everything the agent needs for the services you install.
Each statement includes effect, actions, and resources, and optionally a
condition to scope permissions using IAM condition operators.
config.cluster_endpoint_public_access_cidrs
array — optional
Additional CIDR blocks which can access the Amazon EKS public API server
endpoint. Ryvn Hub IPs are always allowed so the control plane can provision and
manage the cluster; if this is not specified, no other source can reach the
endpoint.
config.enable_flow_log
boolean — optional
If true, enables VPC Flow Logs. Defaults to false.
config.skip_dns_provisioning
boolean — optional
If true, skips provisioning DNS managed zones. Defaults to false.
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:
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.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.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.
setup
string — optional
Environment setup type. Controls who provisions the environment infrastructure.
Available values:
self- Ryvn Control Plane uses cross-account permissions to provision the infrastructure (default)pre-provisioned- Use existing or externally managed infrastructure
requireApproval
boolean — optional (default: false)
When true, deployments require approval before executing. See Deployment Approvals.
provider
object — required
AWS provider configuration.
provider.type
string — required
Must be aws.
provider.accountId
string — optional
AWS account ID where resources will be provisioned.
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 characterslabels(optional): labels to apply to the namespace
installations
array — optional
List of service installations to deploy in this environment. See
Server, Job,
Helm Chart,
Terraform, and
Blueprint installation documentation for details.
Platform blueprint configuration
The AWS platform blueprint (ryvn.app/aws-platform) accepts the following configuration inputs when installed in an environment:
Node configuration
The first three inputs tune the default
application Karpenter NodePool and its ryvn-ec2-node-class EC2NodeClass. customNodePools and customNodeClasses are YAML maps keyed by name, merged into the defaults the way Helm merges values: new keys are added alongside application, a key named application overrides only the fields you list, lists (cpuSizes, budgets, blockDeviceMappings) are replaced wholesale, and application: null removes the default pool. Setting customNodePools stops instanceCategories/cpuSizes from being applied to application; setting customNodeClasses stops diskSize from being applied.
Every node is labeled ryvn.app/node-group-name: <pool>, so a Server or Job can target a pool with nodeSelector; pools with NoSchedule taints also need matching tolerations. All pools are on-demand linux; spot is not available.
karpenter.sh/do-not-disrupt: "true" pod annotation. For GPU pools and the NVIDIA device plugin, see the GPU workloads guide.
Observability configuration
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.
.ryvn.env.orgId
The organization ID.
.ryvn.env.defaultNamespace
The default Kubernetes namespace for the environment (typically same as environment name).
.ryvn.env.releaseChannel
The release channel for this environment.
.ryvn.env.provider.type
The provider type (e.g., aws, gcp, azure).
.ryvn.env.provider.aws.accountId
The AWS account ID where resources are provisioned.
.ryvn.env.config
Environment configuration as a key-value map. Access custom config values you define in your environment using dot notation.
.ryvn.env.state.cluster_name
The name of the EKS cluster.
.ryvn.env.state.cluster_endpoint
Endpoint for the Kubernetes API server.
.ryvn.env.state.cluster_region
AWS region where the EKS cluster is deployed.
.ryvn.env.state.cluster_oidc_issuer_url
URL for the OpenID Connect identity provider on the EKS cluster.
.ryvn.env.state.ryvn_agent_role_arn
ARN of the IAM role for the Ryvn Agent.
.ryvn.env.state.aws_load_balancer_controller_role_arn
ARN of the IAM role for AWS Load Balancer Controller.
.ryvn.env.state.addons
Per-addon outputs keyed by EKS addon name. Each entry exposes role_arn, the IAM role the addon’s service account runs as (IRSA), reflecting any service_account_role_arn override in config.cluster_addons. Use it to attach additional IAM policies from your own IaC, for example to let the EFS CSI driver mount file systems you create outside Ryvn. Policies you attach are preserved across environment updates.
Available entries: aws-ebs-csi-driver, and aws-efs-csi-driver on environments using the Karpenter provisioner. Because the keys contain hyphens, use index to reference them in templates.
.ryvn.env.state.cluster_node_security_group_id
Security group ID attached to the EKS cluster nodes.
.ryvn.env.state.cluster_security_group_id
Security group ID attached to the EKS cluster.
.ryvn.env.state.control_plane_logging.log_group_name
Name of the CloudWatch log group receiving EKS control-plane logs.
.ryvn.env.state.control_plane_logging.log_group_arn
ARN of the CloudWatch log group receiving EKS control-plane logs.
.ryvn.env.state.control_plane_logging.enabled_log_types
List of EKS control-plane log types currently emitted: api, audit,
authenticator, controllerManager, scheduler.