Configuration Reference¶

All configuration lives in group_vars/all.yml. Role defaults provide sensible starting points; see each role's defaults/main.yml for the full list of available variables.

Versions are not listed on this page. They are pinned in the defaults/main.yml of each role and kept up to date by Renovate.

Global¶

Tool Versions¶

The kubectl_install, helm_install, and clusterctl_install roles provide the CLI tools. With yake_install_method: docker they run as the container images ghcr.io/yakecloud/<tool>; with binary the matching static binaries are downloaded to .local/.

Each role also exposes <role>_container_registry (default ghcr.io) and <role>_container_image (yakecloud/kubectl, yakecloud/helm, yakecloud/clusterctl) to pull the images from a different registry.

clusterapi_install_capi_version (v1.14.4, core, kubeadm bootstrap and control plane) and clusterapi_install_capo_version (v0.15.1, OpenStack) pin the Cluster API providers for clusterctl init and clusterctl upgrade apply. CAPO must match the vendored ORC manifest. The two pins are used independently by clusterctl init: an empty pin lets only that provider float to the latest version. With both pins set, clusterctl upgrade apply only runs if an installed provider differs from its pin. If either pin is empty, it runs on every playbook run and upgrades all providers to the latest versions of clusterapi_install_contract (default v1beta2).

With the binary method the downloads of kubectl, Helm and kind are verified against the published sha256 files. clusterctl, gardenctl and gardenlogin publish none and are not verified. Binaries are kept per version (.local/<tool>-<version>), so a version change takes effect.

The optional gardenctl_install role (tag gardenctl) is disabled by default. Set gardenctl_install_enabled: true to install gardenctl. The container image ghcr.io/yakecloud/gardenctl contains gardenctl, gardenlogin, and kubectl; with binary gardenctl and gardenlogin are downloaded to .local/.

The default gardenctl-v2.yaml is only written if it does not exist yet, so manual changes are kept.

Management Cluster¶

Configured via the management_cluster role.

The kubeconfig is written to management_cluster_kubeconfig, by default /var/lib/yake/kubeconfig.<management_cluster_name>.

Garden Cluster¶

The garden cluster is provisioned by the clusterapi_cluster role on OpenStack.

OpenStack Credentials¶

Machines¶

Control plane and worker nodes are placed in OpenStack server groups with a soft-anti-affinity policy. This is controlled by clusterapi_cluster_control_plane_server_group_enabled, clusterapi_cluster_worker_server_group_enabled and the matching ..._server_group_policy variables.

Control plane machine health checks are enabled by default (clusterapi_cluster_control_plane_machine_health_check_enabled). Unhealthy nodes are remediated after 300s, with up to 3 retries (clusterapi_cluster_control_plane_remediation_max_retry).

Worker machine health checks are enabled by default as well, one per machine deployment (clusterapi_cluster_worker_machine_health_check_enabled). A worker is replaced after 300s with Ready Unknown or False, or when its Node has not registered after 20m (clusterapi_cluster_worker_machine_health_check_node_startup_timeout); remediation pauses while more than 40% of a deployment's workers are unhealthy (clusterapi_cluster_worker_machine_health_check_max_unhealthy). Deleting a worker spends at most 600s draining its Node and 600s waiting for its volumes to detach (clusterapi_cluster_worker_node_drain_timeout_seconds, clusterapi_cluster_worker_node_volume_detach_timeout_seconds), so a remediation of an unreachable worker cannot hang.

Worker machine deployments support multiple pools and failure domains:

clusterapi_cluster_worker_machine_deployments:
  - name: md-0
    replicas: 3
    failure_domain: nova
    image_id: "{{ clusterapi_cluster_openstack_image_id }}"

To specify different failure domains for machines and their volumes use:

clusterapi_cluster_worker_machine_deployments:
  - name: md-0
    replicas: 3
    failure_domain: nova
    root_volume_failure_domain: cinder
    image_id: "{{ clusterapi_cluster_openstack_image_id }}"

Make sure to also specify clusterapi_cluster_openstack_ignore_volume_az: true (default: false), so that the cinder-csi does not expose it on the PV, causing an AZ mismatch.

Networking¶

By default, CAPO creates a new network and subnet for the garden cluster. The subnet CIDR is set via clusterapi_cluster_openstack_managed_subnets (default: 172.28.0.0/24 with DNS nameserver 1.1.1.1):

clusterapi_cluster_openstack_managed_subnets:
  - cidr: "192.168.0.0/24"
    dns_nameservers:
      - "1.1.1.1"

The pod network is set via clusterapi_cluster_pod_cidr_blocks (default: [10.244.0.0/16]).

To use an existing subnet instead (for example, one allocated from an OpenStack subnet pool), set clusterapi_cluster_openstack_subnets. This is mutually exclusive with managed_subnets. DNS nameservers are configured on the subnet in OpenStack directly, not here.

clusterapi_cluster_openstack_subnets:
  - id: "existing-subnet-uuid"

CNI¶

Registry Caches and Host Entries¶

The nodes pull images through the registry caches at https://registry.osism.cloud/v2/<name>. The registry provides caches for dockerhub, pkg, gcr, ghcr, quay and k8s. The mirrors need a valid TLS certificate (no skip_verify). An empty URL disables a mirror. The URLs are set per upstream registry through clusterapi_cluster_container_registry_cache_dockerhub, ..._pkg, ..._gcr, ..._ghcr, ..._quay and ..._k8s.

To make additional hostnames resolvable on the nodes (for example for a private registry or Keystone), use clusterapi_cluster_hosts_entries:

clusterapi_cluster_hosts_entries:
  - ip: "12.34.56.54"
    hostname: "harbor.example.com"

Secrets Encryption¶

clusterapi_cluster_secrets_encryption_enabled (default false, enabled in group_vars/all.yml.example) encrypts Secrets at rest in the etcd of the garden cluster with secretbox. Without it, all Gardener credentials (OpenStack, DNS, CA key, kubeconfigs) are stored in plain text in etcd and in its backups or snapshots. It is recommended, but opt-in, because it cannot simply be disabled again.

The key is generated once and kept in the Secret <name>-encryption-config in the management cluster (moved along on kind upgrades) and in /var/lib/yake/encryption-key.<name> (mode 0600). An existing key is never replaced, rotation is a manual task. Once a cluster stores its Secrets encrypted, the role refuses to run with the variable set to false, because the API server could no longer read them. To turn encryption off on purpose, decrypt the stored Secrets first (see "Decrypt all data" in the Kubernetes documentation) and delete the config Secret.

On an existing cluster, enabling it rolls the control plane machines once. After the rollout, the role rewrites all Secrets one time so that they are stored encrypted, and records this with the annotation yake.cloud/secrets-encrypted on the config Secret.

Gardener Operator¶

The gardener_operator role deploys the Gardener Operator and configures the entire Gardener control plane.

Core Settings¶

Dex and Kyverno¶

Dex provides OIDC login for the dashboard. It is configured through gardener_operator_dex:

gardener_operator_dex:
  dashboard_secret: "..."
  theme: dark              # optional, "light" or "dark"; empty keeps the Dex default (light)
  static_passwords:
    - email: "admin@example.com"
      username: "admin"
      hash: "$2a$10$..."   # bcrypt hash
  connectors: []           # see https://dexidp.io/docs/connectors/

Projects¶

Additional Gardener projects are created from gardener_operator_projects (default: []). The project seeds that hosts the managed seeds is configured with gardener_operator_managed_seeds_project; its members default to the admin email above.

OpenStack Credentials¶

Used for the Gardener control plane, DNS, and backup integration.

DNS Provider¶

Gardener manages DNS records for shoots and internal domains. The provider is selected by gardener_operator_dns_provider_type.

Provider Extensions¶

Extension versions are managed by Renovate and follow their respective upstream releases.

The storage class that the OpenStack provider extension creates for shoot control planes is set with gardener_operator_provider_openstack_storageclass_name (default: default), ..._storageclass_type and ..._storageclass_zone (default: nova). Raw Helm values for the extension can be passed with gardener_operator_provider_openstack_helm_values.

OS types to deploy are controlled by gardener_operator_os_types (default: [gardenlinux]). Add ubuntu to also support Ubuntu-based worker nodes.

Certificate Issuance¶

The shoot certificate service supports ACME (Let's Encrypt or your own ACME endpoint) and a CA. With a CA, no ACME endpoint or DNS challenge is needed (for example in air-gapped setups).

# ACME (default)
gardener_operator_shoot_cert_service_issuer_type: acme
gardener_operator_shoot_cert_service_acme_email: "certs@example.com"
gardener_operator_shoot_cert_service_acme_server: "https://acme-v02.api.letsencrypt.org/directory"
# Staging: https://acme-staging-v02.api.letsencrypt.org/directory

# Custom CA
gardener_operator_shoot_cert_service_issuer_type: ca
gardener_operator_shoot_cert_service_ca_certificate: |
  -----BEGIN CERTIFICATE-----
  ...
gardener_operator_shoot_cert_service_ca_key: |
  -----BEGIN RSA PRIVATE KEY-----
  ...

# Generated CA: issuer_type ca without certificate and key
gardener_operator_shoot_cert_service_issuer_type: ca

If issuer_type is ca and neither certificate nor key is set, the role generates a self-signed root CA once in gardener_operator_generated_ca_dir (default /var/lib/yake/ca) and reuses it. Its subject and validity are set with gardener_operator_generated_ca_common_name (default Gardener CA) and gardener_operator_generated_ca_days (default 3650). The validity must exceed the lifetime of the certificates it signs (Gardener requests about 180 days) and is not changed for an existing CA: delete the directory to apply a new value. Import ca.crt into your clients. The CA key is stored unencrypted on the Ansible host and in the cluster, so use your own (intermediate) CA for production. See the role README for details.

The nameservers used for the DNS precheck of the ACME challenge are set with gardener_operator_shoot_cert_service_precheck_nameservers (default: 1.1.1.1,1.0.0.1). They and gardener_operator_shoot_cert_service_ca_certificates only apply to ACME.

Monitoring¶

Shoot Prometheus metrics of all seeds can be forwarded to a central endpoint via remote write. It is enabled when remote_write.url is non-empty:

gardener_operator_monitoring:
  remote_write:
    url: "https://prometheus.example.com/api/v1/write"
    keep: []          # metric names to forward; empty forwards all
  basic_auth:
    username: ""
    password: ""

Cloud Profiles¶

Cloud profiles define the infrastructure options available to shoot clusters. Multiple profiles can be configured for different OpenStack environments.

gardener_operator_cloudprofiles:
  - name: openstack-a
    storageclasses:
      - name: ssd
        default: "true"
        type: ssd
        availability: nova
    floating_pools:
      - name: public
    loadbalancer_providers:
      - name: ovn
    keystone_urls:
      - region: region-a
        url: "https://keystone.example.com:5000"
    machine_images:
      - name: gardenlinux
        versions:
          - version: 2150.15.0
            image: "Garden Linux 2150.15"
            regions:
              - name: region-a
                id: "6ed7d8aa-e770-4061-a8d7-461a83e41c31"
    kubernetes_versions:
      - version: 1.37.2
        classification: supported
    machinetypes:
      - name: SCS-4V-8
        cpu: "4"
        gpu: "0"
        memory: 8Gi
    # Optional: flavor/image for `gardenctl ssh` bastions (must exist in this profile)
    bastion:
      machine_type: SCS-4V-8
      machine_image: gardenlinux
      machine_image_version: 2150.15.0  # optional
    regions:
      - name: region-a
        zones:
          - nova

Different compute and volume availability zones¶

If the Nova and Cinder availability zones are named differently (e.g. compute in AZ1, volumes in nova), set both fields on the cloud profile. Then shoots and managed seeds can run with compute and volumes in different zones. This also works with root disks of the OpenStack default volume type __DEFAULT__:

gardener_operator_cloudprofiles:
  - name: openstack-a
    ignore_volume_az: true               # PVs (e.g. etcd) via cinder-csi
    root_disk_availability_zone: nova    # root volumes of workers

root_disk_availability_zone requires provider-openstack 1.59.0 or later. See the role README for details.

Managed Seeds¶

Each entry in gardener_operator_managed_seeds creates a shoot cluster and registers it as a Gardener seed.

Subnet pool allocation:

When a subnet pool is configured, the OpenStack provider allocates the CIDR automatically. This is mutually exclusive with workers_cidr.

subnet_pool:
  id: "subnet-pool-uuid"
  prefix_length: 24  # optional, controls the allocated subnet size

OpenStack credentials per seed:

openstack:
  auth_url: "https://keystone.example.com:5000"
  project_name: "seed-project"
  domain_name: "my-domain"
  region_name: "region-a"
  application_credential_id: "..."
  application_credential_name: "yake-seed-a"
  application_credential_secret: "..."
  # cacert: |  # optional, for custom CA
  #   -----BEGIN CERTIFICATE-----

Worker pool configuration:

workers:
  - name: worker-4v16
    machinetype: SCS-4V-16
    image_name: gardenlinux
    image_version: 2150.15.0
    minimum: 3
    maximum: 15
    volume_type: ssd       # optional
    volume_size: 50Gi
    zones:
      - nova

Seed settings:

settings:
  excess_capacity_reservation: true  # reserve capacity for shoot control planes
  backup:                             # optional, enables etcd backups for shoots on this seed
    provider: openstack
    region: region-a
    credentials:
      authURL: "..."
      tenantName: "..."
      domainName: "..."
      regionName: "..."
      applicationCredentialID: "..."
      applicationCredentialName: "..."
      applicationCredentialSecret: "..."

Backups¶

Garden etcd backup (enabled when gardener_operator_garden_backup_credentials is non-empty):

gardener_operator_garden_backup_provider: openstack
gardener_operator_garden_backup_region: "region-a"
gardener_operator_garden_backup_bucket_name: gardener-etcd
gardener_operator_garden_backup_credentials: |
  authURL: "..."
  tenantName: "..."
  ...

Internal seed etcd backup (enabled when gardener_operator_internal_seed_backup_credentials is non-empty):

gardener_operator_internal_seed_backup_provider: openstack
gardener_operator_internal_seed_backup_region: "region-a"
gardener_operator_internal_seed_backup_credentials: |
  authURL: "..."
  ...

An empty gardener_operator_garden_backup_bucket_name lets gardener-operator create and own the bucket garden-<Garden UID> and delete it with the Garden; the name cannot be changed once the Garden has a backup. A seed's bucket is always named after the seed's UID, so seeds take no bucket name.

A Garden that is rebuilt after its runtime cluster was lost gets a new UID and therefore a new, empty bucket. To restore the virtual garden from the old snapshots instead, set gardener_operator_garden_backup_bucket_name to the old name garden-<old Garden UID> before the new Garden is created; the snapshots keep the same prefix, so its etcd restores from them. Record the generated name while the landscape runs, for example with kubectl get backupbuckets.extensions.gardener.cloud in the runtime cluster. The bucket only survives when the Garden is not deleted, because gardener-operator deletes the bucket it owns together with the Garden.

The internal seed's excess_capacity_reservation is controlled by gardener_operator_internal_seed_excess_capacity_reservation (default: "false"). Only enable it on hosts with more than 16Gi of RAM.

S3-compatible storage is also supported by setting the provider to S3 and configuring the corresponding credentials.

Registry Mirrors¶

Registry caches (gardener_operator_managed_seeds_registry_caches, default []) run a pull-through cache inside the seed for each listed upstream, with an optional volume_size. To proxy container image pulls through a private registry instead, configure gardener_operator_managed_seeds_registry_mirrors. The registry cache extension is deployed automatically when this list is non-empty.

gardener_operator_managed_seeds_registry_mirrors:
  - upstream: docker.io
    host: "https://harbor.example.com/docker.io"
  - upstream: registry.k8s.io
    host: "https://harbor.example.com/registry.k8s.io"
  - upstream: europe-docker.pkg.dev
    host: "https://harbor.example.com/europe-docker.pkg.dev"
    ca: true  # set to true if the mirror uses a custom CA certificate

When ca: true is set for any mirror, provide the CA bundle:

gardener_operator_managed_seeds_registry_mirrors_ca: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----