Azure - Ryvn

Environments define where your services are deployed. Ryvn provisions and manages infrastructure in target Azure subscriptions, including Kubernetes clusters, networking, 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: azure
    subscriptionId: 12345678-1234-1234-1234-123456789012
  config:
    region: eastus
    vnet_cidr: 10.1.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: eastus
    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:
  location: eastus
  vnet_cidr: "10.0.0.0/16"
  cluster_version: "1.31"

`config.location`

string — required Azure location where resources will be provisioned.

config:
  location: eastus

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

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

config:
  cluster_version: "1.30"

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

Property	Type	Description
`vm_size`	`string`	Azure VM size (e.g., `Standard_D4s_v3`)
`min_count`	`number`	Minimum node count for autoscaling
`max_count`	`number`	Maximum node count for autoscaling
`node_count`	`number`	Initial node count
`os_disk_size_gb`	`number`	OS disk size in GB
`labels`	`map(string)`	Kubernetes labels to apply to nodes
`taints`	`list(string)`	Kubernetes taints (non-system pools only)

Taints use the standard Kubernetes format: key=value:effect where effect is one of NoSchedule, PreferNoSchedule, or NoExecute.

config:
  aks_node_pools:
    application:
      vm_size: Standard_D4s_v3
      min_count: 2
      max_count: 10
      node_count: 3
      os_disk_size_gb: 100
      labels:
        team: platform
      taints:
        - dedicated=platform:NoSchedule

`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:
  existing_vnet_id: /subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/network/providers/Microsoft.Network/virtualNetworks/prod-us-vnet
  vnet_cidr: "10.0.0.0/19"

`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:
  vnet_cidr: "10.1.0.0/16"

`config.zones`

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

config:
  zones:
    - "1"
    - "3"

`setup`

string — optional Environment setup type. Controls who provisions the environment infrastructure. Available values:

customer-controlled - Ryvn Provisioner (VM in the customer’s Azure subscription) provisions the infrastructure
self - Ryvn Control Plane uses service principal credentials 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 Azure provider configuration.

provider:
  type: azure
  subscriptionId: 12345678-1234-1234-1234-123456789012

`provider.type`

string — required Must be azure.

provider:
  type: azure

`provider.subscriptionId`

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

provider:
  subscriptionId: 12345678-1234-1234-1234-123456789012

`provider.servicePrincipal`

object — optional Azure service principal credentials for authentication.

provider:
  servicePrincipal:
    appId: abcdef01-2345-6789-abcd-ef0123456789
    tenantId: fedcba98-7654-3210-fedc-ba9876543210
    clientSecret:
      valueFromOrgSecret:
        name: azure-credentials
        key: client_secret

`provider.servicePrincipal.appId`

string — required Azure application (client) ID.

servicePrincipal:
  appId: abcdef01-2345-6789-abcd-ef0123456789

`provider.servicePrincipal.tenantId`

string — required Azure tenant ID.

servicePrincipal:
  tenantId: fedcba98-7654-3210-fedc-ba9876543210

`provider.servicePrincipal.clientSecret`

object — required Service principal client secret configuration.

servicePrincipal:
  clientSecret:
    valueFromOrgSecret:
      name: azure-credentials
      key: client_secret

`provider.servicePrincipal.clientSecret.valueFromOrgSecret`

object — required Reference to an organization-level secret containing the client secret value.

clientSecret:
  valueFromOrgSecret:
    name: azure-credentials
    key: client_secret

`provider.servicePrincipal.clientSecret.valueFromOrgSecret.name`

string — required Name of the organization secret.

valueFromOrgSecret:
  name: azure-credentials
  key: client_secret

`provider.servicePrincipal.clientSecret.valueFromOrgSecret.key`

string — required Key within the organization secret to get the value from.

valueFromOrgSecret:
  name: azure-credentials
  key: client_secret

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

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/azure-platform
    inputs:
      - 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.azure.subscriptionId`

The Azure subscription ID where resources are provisioned.

subscription_id: '{{ .ryvn.env.provider.azure.subscriptionId }}'

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

cluster_name: '{{ .ryvn.env.state.cluster.name }}'

`.ryvn.env.state.cluster.id`

Azure resource ID of the AKS cluster.

cluster_id: '{{ .ryvn.env.state.cluster.id }}'

`.ryvn.env.state.cluster.cluster_fqdn`

Fully qualified domain name of the AKS cluster.

cluster_fqdn: '{{ .ryvn.env.state.cluster.cluster_fqdn }}'

`.ryvn.env.state.cluster.location`

Azure location where the AKS cluster is deployed.

location: '{{ .ryvn.env.state.cluster.location }}'

`.ryvn.env.state.cluster.oidc_issuer_url`

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

oidc_issuer: '{{ .ryvn.env.state.cluster.oidc_issuer_url }}'

`.ryvn.env.state.ryvn_agent_role.client_id`

Client ID of the managed identity for the Ryvn Agent.

client_id: '{{ .ryvn.env.state.ryvn_agent_role.client_id }}'

`.ryvn.env.state.ryvn_agent_role.tenant_id`

Tenant ID of the managed identity for the Ryvn Agent.

tenant_id: '{{ .ryvn.env.state.ryvn_agent_role.tenant_id }}'

`.ryvn.env.state.ryvn_agent_role.principal_id`

Principal ID of the managed identity for the Ryvn Agent.

principal_id: '{{ .ryvn.env.state.ryvn_agent_role.principal_id }}'

`.ryvn.env.state.ryvn_agent_role.id`

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

identity_id: '{{ .ryvn.env.state.ryvn_agent_role.id }}'

`.ryvn.env.state.subscription.subscription_id`

Azure subscription ID where resources are deployed.

subscription_id: '{{ .ryvn.env.state.subscription.subscription_id }}'

`.ryvn.env.state.subscription.client_id`

Client ID for the subscription.

sub_client_id: '{{ .ryvn.env.state.subscription.client_id }}'

`.ryvn.env.state.resource_group.name`

Name of the Azure resource group.

resource_group: '{{ .ryvn.env.state.resource_group.name }}'

`.ryvn.env.state.resource_group.location`

Location of the Azure resource group.

rg_location: '{{ .ryvn.env.state.resource_group.location }}'

`.ryvn.env.state.vnet.id`

Azure resource ID of the virtual network.

vnet_id: '{{ .ryvn.env.state.vnet.id }}'

`.ryvn.env.state.vnet.name`

Name of the virtual network.

vnet_name: '{{ .ryvn.env.state.vnet.name }}'

`.ryvn.env.state.vnet.location`

Location of the virtual network.

vnet_location: '{{ .ryvn.env.state.vnet.location }}'

`.ryvn.env.state.vnet.cidr`

CIDR block of the virtual network.

vnet_cidr: '{{ .ryvn.env.state.vnet.cidr }}'

`.ryvn.env.state.vnet.address_spaces`

List of address spaces for the virtual network.

address_spaces: '{{ .ryvn.env.state.vnet.address_spaces | toJson }}'

`.ryvn.env.state.vnet.subnet_ids`

List of subnet resource IDs.

subnet_ids: '{{ .ryvn.env.state.vnet.subnet_ids | toJson }}'

`.ryvn.env.state.vnet.subnet_names`

List of subnet names.

subnet_names: '{{ .ryvn.env.state.vnet.subnet_names | toJson }}'

`.ryvn.env.state.vnet.network_plugin_mode`

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

plugin_mode: '{{ .ryvn.env.state.vnet.network_plugin_mode }}'

`.ryvn.env.state.vnet.service_cidr`

Service CIDR for Kubernetes services.

service_cidr: '{{ .ryvn.env.state.vnet.service_cidr }}'

`.ryvn.env.state.vnet.dns_service_ip`

DNS service IP for the cluster.

dns_ip: '{{ .ryvn.env.state.vnet.dns_service_ip }}'

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

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

outbound_ips: '{{ .ryvn.env.state.vnet.outbound_load_balancer_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`

Azure DNS zone resource 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`

Azure Private DNS zone resource ID for the internal domain.

internal_zone_id: '{{ .ryvn.env.state.internal_domain.id }}'

`.ryvn.env.state.external_dns_identity.client_id`

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

external_dns_client_id: '{{ .ryvn.env.state.external_dns_identity.client_id }}'

`.ryvn.env.state.external_dns_private_identity.client_id`

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

external_dns_private_client_id: '{{ .ryvn.env.state.external_dns_private_identity.client_id }}'

`.ryvn.env.state.cert_manager_identity.client_id`

Client ID of the managed identity for cert-manager.

cert_manager_client_id: '{{ .ryvn.env.state.cert_manager_identity.client_id }}'

Examples

Multi-environment setup:

kind: Environment
metadata:
  name: staging
spec:
  releaseChannel: staging
  provider:
    type: azure
    subscriptionId: 87654321-4321-4321-4321-210987654321
    servicePrincipal:
      appId: 12345678-abcd-efab-cdef-123456789012
      tenantId: fedcba98-7654-3210-fedc-ba9876543210
      clientSecret:
        valueFromOrgSecret:
          name: staging-azure-credentials
          key: client_secret
  config:
    location: westus
    vnet_cidr: "10.1.0.0/16"
  installations:
    - service: api
    - service: frontend
---
kind: Environment
metadata:
  name: prod-us
spec:
  releaseChannel: production
  provider:
    type: azure
    subscriptionId: 12345678-1234-1234-1234-123456789012
    servicePrincipal:
      appId: abcdef01-2345-6789-abcd-ef0123456789
      tenantId: fedcba98-7654-3210-fedc-ba9876543210
      clientSecret:
        valueFromOrgSecret:
          name: prod-azure-credentials
          key: client_secret
  config:
    location: eastus
    vnet_cidr: "10.0.0.0/16"
    aks_node_pools:
      application:
        vm_size: Standard_D4s_v3
        min_count: 3
        max_count: 10
  installations:
    - service: api
    - service: frontend
    - service: database
---
kind: Environment
metadata:
  name: prod-eu
spec:
  releaseChannel: production
  provider:
    type: azure
    subscriptionId: 12345678-1234-1234-1234-123456789012
    servicePrincipal:
      appId: abcdef01-2345-6789-abcd-ef0123456789
      tenantId: fedcba98-7654-3210-fedc-ba9876543210
      clientSecret:
        valueFromOrgSecret:
          name: prod-azure-credentials
          key: client_secret
  config:
    location: northeurope
    vnet_cidr: "10.2.0.0/16"
    aks_node_pools:
      application:
        vm_size: Standard_D4s_v3
        min_count: 3
        max_count: 10
  installations:
    - service: api
    - service: frontend
    - service: database

With custom domains:

kind: Environment
metadata:
  name: production
spec:
  releaseChannel: production
  provider:
    type: azure
    subscriptionId: 12345678-1234-1234-1234-123456789012
    servicePrincipal:
      appId: abcdef01-2345-6789-abcd-ef0123456789
      tenantId: fedcba98-7654-3210-fedc-ba9876543210
      clientSecret:
        valueFromOrgSecret:
          name: prod-azure-credentials
          key: client_secret
  config:
    location: eastus
    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: azure
    subscriptionId: aaaabbbb-cccc-dddd-eeee-ffffgggghhh
    servicePrincipal:
      appId: 11111111-2222-3333-4444-555555555555
      tenantId: 66666666-7777-8888-9999-000000000000
      clientSecret:
        valueFromOrgSecret:
          name: customer-azure-creds
          key: secret
  installations:
    - service: api

Services

Environments

Installations

Blueprints

Releases

Documentation Index

​Properties

​name

​labels

​releaseChannel

​maintenanceWindow

​config

​config.location

​config.internal_root_domain

​config.public_root_domain

​config.cluster_version

​config.cluster_bootstrap_perms

​config.aks_node_pools

​config.existing_vnet_id

​config.vnet_cidr

​config.zones

​setup

​customerEmail

​requireApproval

​provider

​provider.type

​provider.subscriptionId

​provider.servicePrincipal

​provider.servicePrincipal.appId

​provider.servicePrincipal.tenantId

​provider.servicePrincipal.clientSecret

​provider.servicePrincipal.clientSecret.valueFromOrgSecret

​provider.servicePrincipal.clientSecret.valueFromOrgSecret.name

​provider.servicePrincipal.clientSecret.valueFromOrgSecret.key

​installations

​Platform blueprint configuration

​Observability configuration

​Outputs

​.ryvn.env.name

​.ryvn.env.orgId

​.ryvn.env.defaultNamespace

​.ryvn.env.releaseChannel

​.ryvn.env.provider.type

​.ryvn.env.provider.azure.subscriptionId

​.ryvn.env.config

​.ryvn.env.state.cluster.name

​.ryvn.env.state.cluster.id

​.ryvn.env.state.cluster.cluster_fqdn

​.ryvn.env.state.cluster.location

​.ryvn.env.state.cluster.oidc_issuer_url

​.ryvn.env.state.ryvn_agent_role.client_id

​.ryvn.env.state.ryvn_agent_role.tenant_id

​.ryvn.env.state.ryvn_agent_role.principal_id

​.ryvn.env.state.ryvn_agent_role.id

​.ryvn.env.state.subscription.subscription_id

​.ryvn.env.state.subscription.client_id

​.ryvn.env.state.resource_group.name

​.ryvn.env.state.resource_group.location

​.ryvn.env.state.vnet.id

​.ryvn.env.state.vnet.name

​.ryvn.env.state.vnet.location

​.ryvn.env.state.vnet.cidr

​.ryvn.env.state.vnet.address_spaces

​.ryvn.env.state.vnet.subnet_ids

​.ryvn.env.state.vnet.subnet_names

​.ryvn.env.state.vnet.network_plugin_mode

​.ryvn.env.state.vnet.service_cidr

​.ryvn.env.state.vnet.dns_service_ip

​.ryvn.env.state.outbound_ips

​.ryvn.env.state.vnet.outbound_load_balancer_public_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.external_dns_identity.client_id

​.ryvn.env.state.external_dns_private_identity.client_id

​.ryvn.env.state.cert_manager_identity.client_id

​Examples