clusterconfig

package
v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 19, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package clusterconfig parses and resolves Podplane cluster configuration files.

Index

Constants

View Source
const DefaultACMEServer = "https://acme-v02.api.letsencrypt.org/directory"

DefaultACMEServer is the public ACME directory used when cluster.acme.server is omitted.

View Source
const DefaultSchemaRef = "./" + SchemaFileName

DefaultSchemaRef is the relative schema reference embedded in new cluster configs.

View Source
const SchemaFileName = "podplane.cluster.schema.json"

SchemaFileName is the local JSON Schema file written next to cluster configs.

Variables

View Source
var ClusterSchemaJSON = schemas.ClusterSchemaJSON

ClusterSchemaJSON is the JSON Schema for podplane.cluster.jsonc files.

Functions

func CleanRegistryMirrorPrefix added in v0.5.0

func CleanRegistryMirrorPrefix(prefix string) string

CleanRegistryMirrorPrefix cleans a registry mirror path prefix.

func Validate

func Validate(cfg *ClusterConfig) error

Validate validates the cluster config fields that are required for managed OpenTofu/Terraform generation.

func ValidateACME added in v0.8.0

func ValidateACME(acme *ACME, domains []Domain) error

ValidateACME validates the optional public certificate configuration.

func ValidateAWSAvailabilityZone added in v0.8.1

func ValidateAWSAvailabilityZone(region, zone string) error

ValidateAWSAvailabilityZone verifies that a standard or local AWS availability zone belongs to region.

func ValidateAWSRegion added in v0.8.1

func ValidateAWSRegion(region string) error

ValidateAWSRegion validates the syntax shared by standard and partition-specific AWS regions.

func ValidateClusterID

func ValidateClusterID(id string) error

ValidateClusterID validates a cluster ID using Netsy's identifier rules.

func ValidateComponents

func ValidateComponents(components Components) error

ValidateComponents validates the optional components configuration.

func ValidateDomainName added in v0.7.0

func ValidateDomainName(name string) error

ValidateDomainName validates a fully qualified DNS name without a trailing dot or wildcard label.

func ValidateSecrets added in v0.5.0

func ValidateSecrets(secrets Secrets) error

ValidateSecrets validates safe Podplane Secrets provider metadata.

func ValidateSeed

func ValidateSeed(seed Seed) error

ValidateSeed validates the optional seed configuration.

func Write

func Write(path string, cfg *ClusterConfig) error

Write writes a formatted cluster configuration file to disk.

func WriteSchema added in v0.2.0

func WriteSchema(dir string) error

WriteSchema writes the local JSON Schema file used by editors for offline validation, completion, and hover documentation.

Types

type ACME

type ACME struct {
	Server string `json:"server,omitempty"`
	Email  string `json:"email"`
}

ACME describes cluster-level ACME account configuration for ingress certs.

type Cluster

type Cluster struct {
	ID         string          `json:"id"`
	Name       string          `json:"name"`
	OIDC       OIDC            `json:"oidc"`
	ACME       *ACME           `json:"acme,omitempty"`
	Domains    []Domain        `json:"domains,omitempty"`
	Registry   Registry        `json:"registry,omitempty"`
	Pools      map[string]Pool `json:"pools,omitempty"`
	Providers  []Provider      `json:"providers,omitempty"`
	Secrets    Secrets         `json:"secrets,omitempty"`
	Kubernetes Kubernetes      `json:"kubernetes"`
	Seed       Seed            `json:"seed,omitempty"`
	Components Components      `json:"components,omitempty"`
}

Cluster groups everything under a top-level "cluster" object, to assist with differentiating from a Podplane OIDC configuration file (which typicaly has a .oidc.json suffix)

func (Cluster) RegistryMirrorHostname added in v0.5.0

func (c Cluster) RegistryMirrorHostname() string

RegistryMirrorHostname returns the mirror hostname, defaulting to cluster.registry.hostname.

func (Cluster) RegistryMirrorPrefix added in v0.5.0

func (c Cluster) RegistryMirrorPrefix() string

RegistryMirrorPrefix returns the cleaned mirror prefix, defaulting to mirror.

type ClusterConfig

type ClusterConfig struct {
	Schema  string  `json:"$schema,omitempty"`
	Cluster Cluster `json:"cluster"`
}

ClusterConfig represents a cluster configuration file Typically files are named podplane.cluster.jsonc or have a .cluster.jsonc suffix.

func Load

func Load(path string) (*ClusterConfig, error)

Load reads a .cluster.jsonc file from disk, strips comments, and unmarshals it into a ClusterConfig.

func NewDraftConfig

func NewDraftConfig(providerKind string) *ClusterConfig

NewDraftConfig returns a mutable draft cluster config for the requested provider.

func (*ClusterConfig) DefaultDomain added in v0.7.0

func (c *ClusterConfig) DefaultDomain() *Domain

DefaultDomain returns the first configured domain, or nil when the cluster has no domains.

func (*ClusterConfig) ResolvedClientID

func (c *ClusterConfig) ResolvedClientID() string

ResolvedClientID returns the configured OIDC client_id, defaulting to the cluster ID.

func (*ClusterConfig) ResolvedGroupsClaim added in v0.5.0

func (c *ClusterConfig) ResolvedGroupsClaim() string

ResolvedGroupsClaim returns the configured groups_claim, defaulting to "groups".

func (*ClusterConfig) ResolvedKubernetesAPIURL

func (c *ClusterConfig) ResolvedKubernetesAPIURL() string

ResolvedKubernetesAPIURL builds the https URL for the cluster's API server. Defaults to port 6443 if api_port is unset. Returns "" if api_hostname is not set.

func (*ClusterConfig) ResolvedRegistryHostname added in v0.7.0

func (c *ClusterConfig) ResolvedRegistryHostname() string

ResolvedRegistryHostname returns the configured registry hostname or the stable domainless hostname.

func (*ClusterConfig) ResolvedUsernameClaim

func (c *ClusterConfig) ResolvedUsernameClaim() string

ResolvedUsernameClaim returns the configured username_claim, defaulting to "sub".

type Components

type Components struct {
	Source   *ComponentsSource   `json:"source,omitempty"`
	Registry *ComponentsRegistry `json:"registry,omitempty"`
}

Components describes optional platform-components configuration.

type ComponentsRegistry added in v0.2.0

type ComponentsRegistry struct {
	Mirror ComponentsRegistryMirror `json:"mirror,omitempty"`
}

ComponentsRegistry describes the registry settings platform-components should use when rendering component image references.

type ComponentsRegistryMirror added in v0.2.0

type ComponentsRegistryMirror struct {
	Enabled  bool   `json:"enabled,omitempty"`
	Hostname string `json:"hostname,omitempty"`
	Prefix   string `json:"prefix,omitempty"`
}

ComponentsRegistryMirror enables explicit mirrored component image references such as <hostname>/<prefix>/<original-registry>/<repository>:<tag>.

type ComponentsSource

type ComponentsSource struct {
	URL       string                     `json:"url"`
	Ref       ComponentsSourceRef        `json:"ref,omitempty"`
	SecretRef *ComponentsSourceSecretRef `json:"secretRef,omitempty"`
}

ComponentsSource overrides the Git repository used by platform-components.

type ComponentsSourceRef

type ComponentsSourceRef struct {
	Branch string `json:"branch,omitempty"`
	Tag    string `json:"tag,omitempty"`
	Semver string `json:"semver,omitempty"`
	Commit string `json:"commit,omitempty"`
}

ComponentsSourceRef selects a Git ref for the components source. At most one field should be set.

type ComponentsSourceSecretRef added in v0.5.0

type ComponentsSourceSecretRef struct {
	Name string `json:"name"`
}

ComponentsSourceSecretRef references Flux-native Git credentials in the GitRepository namespace.

type Domain

type Domain struct {
	Zone         string          `json:"zone"`
	Provider     *DomainProvider `json:"provider,omitempty"`
	LoadBalancer string          `json:"load_balancer,omitempty"`
}

Domain is one entry in cluster.domains.

func (Domain) ResolvedDomainLoadBalancer added in v0.7.0

func (d Domain) ResolvedDomainLoadBalancer() string

ResolvedDomainLoadBalancer returns the domain's selected load balancer.

type DomainProvider

type DomainProvider struct {
	Kind                    string `json:"kind"`
	Account                 string `json:"account,omitempty"`
	Profile                 string `json:"profile,omitempty"`
	Region                  string `json:"region,omitempty"`
	HostedZoneID            string `json:"hosted_zone_id,omitempty"`
	RoleARN                 string `json:"role_arn,omitempty"`
	SecretProviderClassName string `json:"secret_provider_class_name,omitempty"`
	SecretName              string `json:"secret_name,omitempty"`
	SecretKey               string `json:"secret_key,omitempty"`
	Project                 string `json:"project,omitempty"`
	HostedZoneName          string `json:"hosted_zone_name,omitempty"`
}

DomainProvider is the DNS provider for a Domain.

func (*DomainProvider) SupportsACME added in v0.8.0

func (p *DomainProvider) SupportsACME() bool

SupportsACME reports whether Podplane currently supports automated ACME DNS-01 challenges for this domain provider.

type Kubernetes

type Kubernetes struct {
	APIHostname     string   `json:"api_hostname"`
	APIPort         int      `json:"api_port,omitempty"`
	APILoadBalancer string   `json:"api_load_balancer,omitempty"`
	ClusterCIDR     []string `json:"cluster_cidr,omitempty"`
	ServiceCIDR     []string `json:"service_cidr,omitempty"`
}

Kubernetes describes how the API server is reached and configured.

type Listener

type Listener struct {
	Port       int    `json:"port"`
	TargetPort int    `json:"target_port,omitempty"`
	Pool       string `json:"pool"`
}

Listener describes one load-balancer listener and its target pool.

type LoadBalancer

type LoadBalancer struct {
	Public    bool       `json:"public"`
	Subnets   string     `json:"subnets"`
	Listeners []Listener `json:"listeners"`
}

LoadBalancer describes one provider load balancer.

type OIDC

type OIDC struct {
	IssuerURL     string   `json:"issuer_url"`
	ClientID      string   `json:"client_id,omitempty"`
	UsernameClaim string   `json:"username_claim,omitempty"`
	GroupsClaim   string   `json:"groups_claim,omitempty"`
	SigningAlgs   []string `json:"signing_algs,omitempty"`
	// CACert may be: an inline PEM (string starts with "-----BEGIN"), an
	// http(s):// URL, or a path on disk.
	CACert string `json:"ca_cert,omitempty"`
}

OIDC describes the issuer the cluster's API server trusts.

type Pool

type Pool struct {
	Arch         string `json:"arch"`
	InstanceType string `json:"instance_type"`
	Size         int    `json:"size"`
	DiskSize     int    `json:"disk_size,omitempty"`
}

Pool is one entry in cluster.pools.<name>.

type Provider

type Provider struct {
	Kind          string                  `json:"kind"`
	Region        string                  `json:"region,omitempty"`
	Account       string                  `json:"account,omitempty"`
	Profile       string                  `json:"profile,omitempty"`
	Project       string                  `json:"project,omitempty"`
	Tags          map[string]string       `json:"tags,omitempty"`
	VPC           VPC                     `json:"vpc"`
	Zones         map[string][]Subnet     `json:"zones,omitempty"`
	LoadBalancers map[string]LoadBalancer `json:"load_balancers,omitempty"`
	Buckets       []string                `json:"buckets,omitempty"`
	Roles         map[string]Role         `json:"roles,omitempty"`
}

Provider is one entry in cluster.providers[].

type Registry added in v0.5.0

type Registry struct {
	Hostname string          `json:"hostname,omitempty"`
	Ingress  RegistryIngress `json:"ingress,omitempty"`
}

Registry describes the cluster-level OCI registry endpoint used by node-local zot, podplane push, and optional registry ingress.

type RegistryIngress added in v0.5.0

type RegistryIngress struct {
	Enabled bool `json:"enabled,omitempty"`
}

RegistryIngress configures optional Docker-compatible public registry ingress.

type Role

type Role struct {
	Buckets     []string `json:"buckets"`
	Permissions string   `json:"permissions,omitempty"`
}

Role is one entry in cluster.providers[].roles.<name>.

type Secrets added in v0.5.0

type Secrets struct {
	DefaultProvider string                     `json:"default_provider,omitempty"`
	Providers       map[string]SecretsProvider `json:"providers,omitempty"`
}

Secrets describes Podplane Secrets provider selection. Only safe provider metadata belongs here; backend credentials are configured on the operator.

type SecretsProvider added in v0.5.0

type SecretsProvider struct {
	Kind string `json:"kind"`

	// KeyPrefix partitions backend keys for this provider. Defaults to the
	// cluster ID when omitted.
	KeyPrefix string `json:"key_prefix,omitempty"`

	// AWS ObjectType is the Secrets Store CSI AWS objectType value, such as
	// "secretsmanager" or "ssmparameter".
	ObjectType string `json:"object_type,omitempty"`
	Region     string `json:"region,omitempty"`

	// GCP fields.
	ProjectID string `json:"project_id,omitempty"`
	Location  string `json:"location,omitempty"`

	// Vault/OpenBao fields for operator/runtime configuration. These
	// fields are not persisted in cached cluster summaries.
	Address      string `json:"address,omitempty"`
	MountPath    string `json:"mount_path,omitempty"`
	CACert       string `json:"ca_cert,omitempty"`
	AuthPath     string `json:"auth_path,omitempty"`
	OperatorRole string `json:"operator_role,omitempty"`
}

SecretsProvider is one named Podplane Secrets backend exposed to templates and CLI commands. Kind matches the upstream Secrets Store CSI provider slug.

type Seed

type Seed struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
	Digest  string `json:"digest,omitempty"`
}

Seed describes the Podplane seed file used to create the initial Netsy snapshot.

type ServiceNetwork added in v0.7.0

type ServiceNetwork struct {
	CIDRs   []string
	API     []netip.Addr
	CoreDNS []netip.Addr
}

ServiceNetwork contains canonical service networks and reserved addresses.

func ServiceNetworkFromCIDRs added in v0.7.0

func ServiceNetworkFromCIDRs(cidrs []string) (ServiceNetwork, error)

ServiceNetworkFromCIDRs validates Kubernetes service CIDRs and returns their reserved addresses.

type Subnet

type Subnet struct {
	Pool     string   `json:"pool,omitempty"`
	Services []string `json:"services,omitempty"`
	Public   bool     `json:"public,omitempty"`
	ID       string   `json:"id,omitempty"`
	V4CIDR   string   `json:"v4cidr,omitempty"`
	V6CIDR   string   `json:"v6cidr,omitempty"`
}

Subnet is one entry in cluster.providers[].zones.<zone>[].

func (Subnet) ResolvedRole added in v0.7.0

func (s Subnet) ResolvedRole() string

ResolvedRole returns the subnet role used by the Nstance network module.

type VPC

type VPC struct {
	ID     string `json:"id,omitempty"`
	V4CIDR string `json:"v4cidr,omitempty"`
	V6CIDR string `json:"v6cidr,omitempty"`
}

VPC describes the cluster's VPC. Either ID (existing) or V4CIDR/V6CIDR (create new) is set, not both.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL