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 characterslabels(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:
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).