Configuration Schema Reference

Purpose: For platform engineers, provides field-by-field reference for cluster YAML configuration files, with paths matching the Go struct tags in the CLI codebase.

File Location

Configuration files live at:

~/.config/opencenter/clusters/<org>/<cluster>/.<cluster>-config.yaml

Example: ~/.config/opencenter/clusters/myorg/prod/.prod-config.yaml

The CLI generates v2 configuration only (schema_version: "2.0").

Top-Level Structure

The root configuration has six top-level keys. The opencenter and secrets sections are required.

schema_version: "2.0"
metadata: { ... }
opencenter:
  meta: { ... }
  cluster: { ... }
  infrastructure: { ... }
  services: { ... }
  managed_services: { ... }
  gitops: { ... }
deployment: { ... }
opentofu: { ... }
secrets: { ... }

Source: internal/config/v2/config.go → Config struct.

metadata

System-managed metadata. Not typically edited by users.

YAML Path	Type	Required	Description
metadata.created_at	string	no	Creation timestamp
metadata.updated_at	string	no	Last update timestamp
metadata.version	string	no	Config version
metadata.labels	map	no	Key-value labels
metadata.annotations	map	no	Key-value annotations

Source: internal/config/v2/config.go → ConfigMetadata.

opencenter.meta

Cluster identity and organizational context.

YAML Path	Type	Required	Description
opencenter.meta.name	string	yes	Cluster name (DNS-1123 compliant)
opencenter.meta.organization	string	yes	Organization identifier
opencenter.meta.env	string	yes	Environment: dev, staging, production
opencenter.meta.region	string	yes	Deployment region
opencenter.meta.status	string	no	Cluster status

Source: internal/config/v2/config.go → MetaConfig.

opencenter.cluster

Kubernetes cluster identity and configuration. Contains a nested kubernetes object for version, networking, security, and plugin settings.

YAML Path	Type	Required	Description
opencenter.cluster.cluster_name	string	yes	Cluster name (DNS-1123 compliant)
opencenter.cluster.base_domain	string	yes	Base domain (e.g., k8s.opencenter.cloud)
opencenter.cluster.cluster_fqdn	string	yes	Fully qualified domain name
opencenter.cluster.admin_email	string	yes	Administrator email for certificates and notifications
opencenter.cluster.kubernetes	object	yes	Kubernetes configuration (see below)

Source: internal/config/v2/cluster.go → ClusterConfig.

opencenter.cluster.kubernetes

Kubernetes version, networking, and security settings. This is where version (Kubernetes version), network plugin, and storage plugin are configured.

YAML Path	Type	Required	Description
opencenter.cluster.kubernetes.version	string	yes	Kubernetes version (semver, e.g., v1.29.0)
opencenter.cluster.kubernetes.api_port	integer	yes	API server port (1–65535)
opencenter.cluster.kubernetes.kube_vip_enabled	bool	no	Enable KubeVIP for control plane HA
opencenter.cluster.kubernetes.subnet_pods	string	yes	Pod network CIDR (e.g., 10.233.64.0/18)
opencenter.cluster.kubernetes.subnet_services	string	yes	Service network CIDR (e.g., 10.233.0.0/18)
opencenter.cluster.kubernetes.network_plugin	object	yes	CNI plugin configuration (see below)
opencenter.cluster.kubernetes.storage_plugin	object	no	CSI plugin configuration
opencenter.cluster.kubernetes.security	object	no	Kubernetes security settings
opencenter.cluster.kubernetes.oidc	object	no	OIDC authentication configuration

Source: internal/config/v2/cluster.go → KubernetesConfig.

CNI Plugin Configuration

The CNI plugin is configured under opencenter.cluster.kubernetes.network_plugin, not as a flat cni_plugin string. Enable exactly one of calico, cilium, or kube-ovn.

opencenter.cluster.kubernetes.network_plugin

Enable exactly one CNI plugin by setting its enabled field to true.

YAML Path	Type	Required	Description
opencenter.cluster.kubernetes.network_plugin.calico	object	no	Calico CNI configuration
opencenter.cluster.kubernetes.network_plugin.cilium	object	no	Cilium CNI configuration
opencenter.cluster.kubernetes.network_plugin.kube-ovn	object	no	Kube-OVN CNI configuration

Each plugin object supports enabled (bool) and version (string). Calico additionally supports ipip_mode, vxlan_mode, and network_policy.

Example:

opencenter:
  cluster:
    kubernetes:
      version: "v1.29.0"
      network_plugin:
        calico:
          enabled: true
          network_policy: true

opencenter.cluster.kubernetes.security

YAML Path	Type	Required	Description
opencenter.cluster.kubernetes.security.pod_security_policy	bool	no	Enable Pod Security Policy
opencenter.cluster.kubernetes.security.pod_security_standards	string	no	PSA level: privileged, baseline, restricted
opencenter.cluster.kubernetes.security.audit_logging	bool	no	Enable API server audit logging
opencenter.cluster.kubernetes.security.encryption_at_rest	bool	no	Enable etcd encryption at rest
opencenter.cluster.kubernetes.security.admission_controllers	list	no	Additional admission controllers

Source: internal/config/v2/cluster.go → KubernetesSecurityConfig.

opencenter.infrastructure

Provider-agnostic infrastructure configuration with provider-specific extensions under cloud.

YAML Path	Type	Required	Description
opencenter.infrastructure.provider	string	yes	Provider type: openstack, vmware, kind, baremetal, with compatibility values including vsphere, aws, gcp, and azure
opencenter.infrastructure.ssh	object	yes	SSH configuration
opencenter.infrastructure.os_version	string	yes	Operating system version
opencenter.infrastructure.server_group_affinity	list	no	Server group affinity policies
opencenter.infrastructure.k8s_api_ip	string	no	Kubernetes API IP (IPv4)
opencenter.infrastructure.node_naming	object	no	Node naming prefix/suffix
opencenter.infrastructure.bastion	object	no	Bastion host configuration
opencenter.infrastructure.networking	object	yes	Network topology and DNS
opencenter.infrastructure.compute	object	yes	Compute resources (flavors, node counts)
opencenter.infrastructure.storage	object	yes	Storage configuration (volumes, block devices)
opencenter.infrastructure.cloud	object	yes	Provider-specific configuration

Source: internal/config/v2/infrastructure.go → InfrastructureConfig.

Planned Providers

aws, gcp, and azure are planned compatibility values and not part of the documented GA provider set. Currently documented GA providers: openstack, vmware, kind, baremetal.

opencenter.infrastructure.ssh

YAML Path	Type	Required	Description
opencenter.infrastructure.ssh.authorized_keys	list	yes	SSH public keys (minimum 1)
opencenter.infrastructure.ssh.username	string	no	SSH username

opencenter.infrastructure.networking

YAML Path	Type	Required	Description
opencenter.infrastructure.networking.subnet_nodes	string	yes	Node subnet CIDR (IPv4)
opencenter.infrastructure.networking.allocation_pool_start	string	yes	DHCP pool start IP
opencenter.infrastructure.networking.allocation_pool_end	string	yes	DHCP pool end IP
opencenter.infrastructure.networking.gateway	string	no	Gateway IP
opencenter.infrastructure.networking.vrrp_ip	string	conditional	VRRP virtual IP (required when vrrp_enabled: true)
opencenter.infrastructure.networking.vrrp_enabled	bool	no	Enable VRRP for HA
opencenter.infrastructure.networking.loadbalancer_provider	string	yes	LB provider: ovn, octavia, metallb, cloud-native
opencenter.infrastructure.networking.use_designate	bool	no	Use OpenStack Designate DNS
opencenter.infrastructure.networking.dns_zone_name	string	yes	DNS zone name (FQDN)
opencenter.infrastructure.networking.dns_nameservers	list	yes	DNS nameserver IPs (minimum 1)
opencenter.infrastructure.networking.ntp_servers	list	yes	NTP server addresses (minimum 1)

opencenter.infrastructure.compute

YAML Path	Type	Required	Description
opencenter.infrastructure.compute.flavor_bastion	string	no	Bastion VM flavor
opencenter.infrastructure.compute.flavor_master	string	no	Control plane VM flavor
opencenter.infrastructure.compute.flavor_worker	string	no	Worker VM flavor
opencenter.infrastructure.compute.flavor_worker_windows	string	no	Windows worker VM flavor
opencenter.infrastructure.compute.master_count	integer	no	Number of control plane nodes
opencenter.infrastructure.compute.worker_count	integer	no	Number of worker nodes
opencenter.infrastructure.compute.worker_count_windows	integer	no	Number of Windows worker nodes
opencenter.infrastructure.compute.additional_server_pools_worker	list	no	Additional worker pools

opencenter.infrastructure.cloud

Provider-specific configuration. Populate the sub-object matching your provider value.

YAML Path	Type	Description
opencenter.infrastructure.cloud.openstack	object	OpenStack-specific settings (auth_url, region, project_id, image_id, network_id, etc.)
opencenter.infrastructure.cloud.vmware	object	VMware-specific settings (vcenter_server, datacenter, datastore, network, template)
opencenter.infrastructure.cloud.kind	object	Local Kind runtime settings where applicable
opencenter.infrastructure.cloud.aws	object	AWS-specific settings (region, vpc_id, subnet_ids, ami_id)
opencenter.infrastructure.cloud.gcp	object	GCP-specific settings (project, region, network, subnetwork)
opencenter.infrastructure.cloud.azure	object	Azure-specific settings (subscription_id, resource_group, location)

Source: internal/config/v2/infrastructure.go → CloudConfig.

opencenter.services

A polymorphic map of platform service configurations. Each key is a service name, and the value is decoded using the service registry.

Common fields shared by all services (via BaseServiceConfig):

Field	Type	Required	Description
enabled	bool	no	Whether the service is deployed
namespace	string	no	Target namespace
hostname	string	no	Service hostname
image_repository	string	no	Override image repository
image_tag	string	no	Override image tag
release	string	no	Helm release name

Example:

opencenter:
  services:
    cert-manager:
      enabled: true
      namespace: cert-manager
    kyverno:
      enabled: true
    harbor:
      enabled: false

Source: internal/config/v2/services.go → ServiceMap, BaseServiceConfig.

opencenter.gitops

GitOps repository configuration for FluxCD.

YAML Path	Type	Required	Description
opencenter.gitops.git_url	string	yes	Git repository URL
opencenter.gitops.git_branch	string	no	Git branch
opencenter.gitops.git_path	string	no	Path within the repository
opencenter.gitops.base_repo_url	string	no	openCenter-gitops-base repository URL
opencenter.gitops.base_repo_release	string	no	Base repository release tag
opencenter.gitops.flux_interval	string	no	FluxCD reconciliation interval
opencenter.gitops.flux_prune	bool	no	Enable FluxCD pruning

Source: internal/config/v2/config.go → GitOpsConfig.

secrets

Top-level secrets configuration. In v2, this is a peer of opencenter, not nested inside it.

YAML Path	Type	Required	Description
secrets.global	object	no	Infrastructure-wide credentials (AWS keys, OpenStack credentials)
secrets.service_secrets	map	no	Per-service secret values
secrets.sops	object	no	SOPS encryption configuration

Source: internal/config/v2/config.go → SecretsConfig.

Secrets Backend (v1 path)

In v1 configurations, the secrets backend is configured at opencenter.secrets.backend (values: sops, barbican, file). In v2, SOPS configuration moved to secrets.sops at the top level. If you see references to secrets.backend in older documentation, the correct v2 path is secrets.sops.enabled and related fields.

secrets.sops

YAML Path	Type	Required	Description
secrets.sops.enabled	bool	no	Enable SOPS encryption
secrets.sops.age_key_file	string	conditional	Path to Age key file (required when enabled: true)
secrets.sops.encrypted_regex	string	no	Regex pattern for fields to encrypt

secrets.global

YAML Path	Type	Required	Description
secrets.global.aws_access_key	string	no	AWS access key ID
secrets.global.aws_secret_key	string	no	AWS secret access key
secrets.global.openstack_auth_url	string	no	OpenStack auth URL
secrets.global.openstack_username	string	no	OpenStack username
secrets.global.openstack_password	string	no	OpenStack password
secrets.global.openstack_project_id	string	no	OpenStack project ID

opentofu

OpenTofu/Terraform backend configuration.

YAML Path	Type	Required	Description
opentofu.backend.type	string	yes	Backend type: s3, local, remote
opentofu.backend.local.path	string	conditional	Local state file path (required for local type)
opentofu.backend.s3.bucket	string	conditional	S3 bucket name (required for s3 type)
opentofu.backend.s3.key	string	conditional	S3 state key (required for s3 type)
opentofu.backend.s3.region	string	conditional	S3 region (required for s3 type)

Source: internal/config/v2/config.go → OpenTofuConfig.

deployment

Deployment behavior configuration.

YAML Path	Type	Required	Description
deployment	object	no	Deployment settings (auto-deploy, etc.)

Source: internal/config/v2/deployment.go.

Complete Example

schema_version: "2.0"
metadata:
  labels:
    team: platform
opencenter:
  meta:
    name: prod-cluster
    organization: my-org
    env: production
    region: us-east-1
  cluster:
    cluster_name: prod-cluster
    base_domain: k8s.example.com
    cluster_fqdn: prod.k8s.example.com
    admin_email: admin@example.com
    kubernetes:
      version: "v1.29.0"
      api_port: 6443
      subnet_pods: "10.233.64.0/18"
      subnet_services: "10.233.0.0/18"
      network_plugin:
        calico:
          enabled: true
          network_policy: true
      security:
        audit_logging: true
        encryption_at_rest: true
        pod_security_standards: baseline
  infrastructure:
    provider: openstack
    os_version: "22.04"
    ssh:
      authorized_keys:
        - "ssh-ed25519 AAAA..."
    networking:
      subnet_nodes: "192.168.1.0/24"
      allocation_pool_start: "192.168.1.100"
      allocation_pool_end: "192.168.1.200"
      dns_zone_name: k8s.example.com
      dns_nameservers:
        - "8.8.8.8"
      ntp_servers:
        - "pool.ntp.org"
      loadbalancer_provider: octavia
    compute:
      master_count: 3
      worker_count: 3
      flavor_master: m1.large
      flavor_worker: m1.xlarge
    storage:
      default_storage_class: csi-cinder-sc-delete
      worker_volume_size: 100
      worker_volume_destination_type: volume
      worker_volume_source_type: image
      worker_volume_type: HA-Standard
    cloud:
      openstack:
        auth_url: "https://identity.example.com/v3"
        region: us-east-1
        project_id: "abc123"
        image_id: "img-456"
        network_id: "net-789"
  services:
    cert-manager:
      enabled: true
    kyverno:
      enabled: true
    harbor:
      enabled: false
  gitops:
    git_url: "ssh://git@github.com/my-org/my-cluster.git"
    git_branch: main
secrets:
  sops:
    enabled: true
    age_key_file: "/path/to/age.key"
  global:
    openstack_auth_url: "https://identity.example.com/v3"
    openstack_project_id: "abc123"

Schema Validation

Run opencenter cluster validate to check a configuration against the schema. The --json flag outputs machine-readable results for CI/CD pipelines.

opencenter cluster validate my-cluster
opencenter cluster validate my-cluster --json