Skip to main content
Environments define where your services are deployed. Ryvn provisions and manages infrastructure in target Azure subscriptions, including Kubernetes clusters, networking, load balancers, and DNS.

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. This window governs Ryvn deployments only. AKS node image and Kubernetes patch upgrades follow config.maintenance_window_node_os and config.maintenance_window_auto_upgrade.

config

object — optional Configuration passed to the Ryvn environment provisioner.

config.location

string — required Azure location where resources will be provisioned.

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

string — optional Kubernetes version to use for the AKS cluster. Defaults to 1.31.

config.node_os_channel_upgrade

string — optional How AKS keeps the node OS image up to date: NodeImage, SecurityPatch, Unmanaged or None. Defaults to NodeImage. NodeImage and SecurityPatch upgrades only run during config.maintenance_window_node_os.

config.maintenance_window_node_os

object — optional AKS planned maintenance schedule for node OS image upgrades. Defaults to Sundays 00:00–08:00 UTC. Set to null to let AKS upgrade node images at any time.
Azure can still apply urgent security fixes outside the window.

config.maintenance_window_auto_upgrade

object — optional AKS planned maintenance schedule for Kubernetes patch version upgrades. Takes the same fields as config.maintenance_window_node_os, except that frequency must be Weekly, AbsoluteMonthly or RelativeMonthly. Defaults to Sundays 00:00–08:00 UTC. Set to null to let AKS upgrade at any time.

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

object — optional Map of AKS node pool definitions to create. Values will be merged with defaults if not specified. Default node pools are application and system. Each node pool supports the following properties: Taints use the standard Kubernetes format: key=value:effect where effect is one of NoSchedule, PreferNoSchedule, or NoExecute.

config.existing_vnet_id

string — optional Azure resource ID of a pre-existing virtual network. When set, Ryvn provisions its subnets inside the existing VNet instead of creating a new one. Must be in the same Azure region as the environment.

config.vnet_cidr

string — optional CIDR block for the virtual network. Defaults to 10.0.0.0/16. When config.existing_vnet_id is set, this is the CIDR range within the existing VNet reserved for Ryvn’s subnets.

config.zones

array — optional List of availability zones for AKS node pools. If not specified, uses all zones available in the region.

config.control_plane_log_retention_days

number — optional Retention for AKS control-plane and full audit logs in Log Analytics. Accepts whole days from 30 to 730 and defaults to 30.

setup

string — optional Environment setup type. Controls who provisions the environment infrastructure. Available values:
  • self - Ryvn Control Plane uses service principal credentials 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 Azure provider configuration.

provider.type

string — required Must be azure.

provider.subscriptionId

string — optional Azure subscription ID where resources will be provisioned.

provider.servicePrincipal

object — optional Azure service principal credentials for authentication. Enter the client secret in the Ryvn dashboard during cloud provider setup, or through the API’s clientSecret field. In YAML, declare only appId and tenantId: the client secret stored for that service principal is kept. Keep servicePrincipal in the YAML once it is configured; the service principal cannot be removed after provisioning has started.

provider.servicePrincipal.appId

string — required Azure application (client) ID.

provider.servicePrincipal.tenantId

string — required Azure tenant ID.

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

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/azure-platform); pre-provisioned environments (setup: pre-provisioned) default to ryvn.app/base-platform. See Platform blueprint configuration for the available inputs.

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:
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 Azure platform blueprint (ryvn.app/azure-platform) accepts the following inputs via the environment’s platform field:

Observability configuration

The Azure provisioner automatically collects AKS API server, controller manager, scheduler, autoscaler, guard, and full kube-audit logs into a Log Analytics workspace in the environment’s resource group. The resource-specific AKSControlPlane and AKSAudit tables keep 30 days by default; configure control_plane_log_retention_days to change retention. Full audit includes read requests, subject to Azure’s managed audit policy. Ingestion and retention incur Azure charges. Query access requires Entra permissions on the workspace. This collection is independent of the workload logs option below and does not install Container Insights or enable additional metrics. The workspace follows the environment’s lifecycle; configure a separate archive for logs that must outlive the environment. After deployment, open the AKS resource’s Diagnostic settings and check ryvn-control-plane-logs. Generate a permitted Kubernetes read and a harmless write, then verify matching records in AKSAudit and control-plane records in AKSControlPlane. Collection starts after attachment and does not backfill prior operations. See AKS control-plane logs.

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.azure.subscriptionId

The Azure subscription 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 AKS cluster.

.ryvn.env.state.cluster.id

Azure resource ID of the AKS cluster.

.ryvn.env.state.cluster.cluster_fqdn

Fully qualified domain name of the AKS cluster.

.ryvn.env.state.cluster.location

Azure location where the AKS cluster is deployed.

.ryvn.env.state.cluster.oidc_issuer_url

URL for the OpenID Connect identity provider on the AKS cluster.

.ryvn.env.state.ryvn_agent_role.client_id

Client ID of the managed identity for the Ryvn Agent.

.ryvn.env.state.ryvn_agent_role.tenant_id

Tenant ID of the managed identity for the Ryvn Agent.

.ryvn.env.state.ryvn_agent_role.principal_id

Principal ID of the managed identity for the Ryvn Agent.

.ryvn.env.state.ryvn_agent_role.id

Azure resource ID of the managed identity for the Ryvn Agent.

.ryvn.env.state.subscription.subscription_id

Azure subscription ID where resources are deployed.

.ryvn.env.state.subscription.client_id

Client ID for the subscription.

.ryvn.env.state.resource_group.name

Name of the Azure resource group.

.ryvn.env.state.resource_group.location

Location of the Azure resource group.

.ryvn.env.state.vnet.id

Azure resource ID of the virtual network.

.ryvn.env.state.vnet.name

Name of the virtual network.

.ryvn.env.state.vnet.location

Location of the virtual network.

.ryvn.env.state.vnet.cidr

CIDR block of the virtual network.

.ryvn.env.state.vnet.address_spaces

List of address spaces for the virtual network.

.ryvn.env.state.vnet.subnet_ids

List of subnet resource IDs.

.ryvn.env.state.vnet.subnet_names

List of subnet names.

.ryvn.env.state.vnet.network_plugin_mode

Network plugin mode for the AKS cluster (e.g., “overlay”).

.ryvn.env.state.vnet.service_cidr

Service CIDR for Kubernetes services.

.ryvn.env.state.vnet.dns_service_ip

DNS service IP for the cluster.

.ryvn.env.state.outbound_ips

List of public IPs used for outbound internet traffic from workloads in this environment.

.ryvn.env.state.vnet.outbound_load_balancer_public_ips

List of public IPs assigned to the AKS outbound load balancer.

.ryvn.env.state.public_domain.name

Public root domain name for the environment.

.ryvn.env.state.public_domain.id

Azure DNS zone resource ID for the public domain.

.ryvn.env.state.public_domain.nameservers

List of nameservers for the public domain.

.ryvn.env.state.internal_domain.name

Internal domain name for the environment.

.ryvn.env.state.internal_domain.id

Azure Private DNS zone resource ID for the internal domain.

.ryvn.env.state.external_dns_identity.client_id

Client ID of the managed identity for ExternalDNS (public zones).

.ryvn.env.state.external_dns_private_identity.client_id

Client ID of the managed identity for ExternalDNS (private zones).

.ryvn.env.state.cert_manager_identity.client_id

Client ID of the managed identity for cert-manager.

Examples

Multi-environment setup:
Installations for the other environments follow the same pattern. With custom domains:
Pre-provisioned environment: