konfig

package
v0.7.9 Latest Latest
Warning

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

Go to latest
Published: Jul 3, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

README

pkg/konfig

konfig is the configuration root for the Orkestra runtime. It loads ENV variables at startup, normalises them into typed structs, and exposes them through a stable accessor API. The Katalog loader merges YAML-level values on top of what konfig provides, so konfig represents the ENV-layer defaults.

kfg, err := konfig.Init()  // reads ENV, validates, returns *Konfig

Precedence

Katalog YAML values
       ↓ merged on top of
ENV variables (konfig.Init)
       ↓ fallback to
hard-coded defaults

ENV variable reference

ENV Accessor Default Description
ORK_ENV kfg.Ork().Environment development Runtime environment (development, staging, production)
ORK_NAMESPACE kfg.Cluster().Namespace orkestra-system Namespace for Orkestra control-plane resources
ORK_GATEWAY_ENDPOINT kfg.GatewayEndpoint() "" Companion gateway URL advertised to control center
ORK_SERVICE_NAME kfg.Security().ServiceName orkestra-runtime Service name used by webhook configurations
KATALOG_PATH kfg.Katalog().Paths() [] Paths to Katalog YAML files
QUEUE_DEPTH kfg.Katalog().DefaultQueueDepth() 100 Default max items per CRD reconcile queue
FAILURE_THRESHOLD kfg.Katalog().DefaultFailureThreshold() 5 Consecutive failures before a CRD is marked degraded
DEFAULT_RESYNC kfg.Katalog().DefaultResync() 15s Default resync interval when not set on the CRD
DEFAULT_WORKERS kfg.Katalog().DefaultWorkers() 3 Default worker count per CRD
ORK_PORT kfg.Health().Port 8080 Health server port
LEASE_DURATION kfg.Konductor().LeaseDuration() 60s Leader election lease duration
RENEW_DEADLINE kfg.Konductor().RenewDeadline() 40s Leader election renew deadline
RETRY_PERIOD kfg.Konductor().RetryPeriod() 10s Leader election retry period
ENABLE_DELETION_PROTECTION kfg.Security().DeletionProtection.Enabled false Enable deletion-protection admission webhook
DELETION_PROTECTION_POLICY kfg.Security().DeletionProtection.FailurePolicy Fail Webhook failure policy
ENABLE_ADMISSION_WEBHOOK kfg.Security().Webhooks.Admission.Enabled false Enable admission mutation webhook
ENABLE_CONVERSION kfg.Security().Conversion.Enabled false Enable CRD version conversion webhook
ENABLE_NAMESPACE_PROTECTION kfg.Security().NamespaceProtection.Enabled false Enable namespace restriction webhook
TLS_CERT / TLS_KEY kfg.Security().Webhooks.TLSCert/TLSKey "" Override TLS paths (omit to let Orkestra generate its own)
SMTP_HOST / SMTP_PORT kfg.Notification().Email.* "" / 0 SMTP server for email notifications
SLACK_WEBHOOK_URL kfg.Notification().Slack.Webhook "" Slack incoming webhook URL
ENABLE_EMAIL_NOTIFIER kfg.Notification().Email.Enabled auto Defaults to true when SMTP vars are present
ENABLE_SLACK_NOTIFIER kfg.Notification().Slack.Enabled auto Defaults to true when SLACK_WEBHOOK_URL is present

Duration ENV vars are in whole seconds (DEFAULT_RESYNC=15 means 15s).

Developer documentation

I want to… Go to
Understand Init(), .env loading, and namespace resolution docs/01-init.md
Understand SecurityConfig and its ENV mappings docs/02-security.md
Understand NotificationConfig (capability vs intent) docs/03-notification.md

Documentation

Overview

pkg/konfig/ork.go

Index

Constants

View Source
const (
	// Ork
	Orkestra    = "OrKestra"
	Ork         = "ork"
	OrkOperator = "orkestra-operator"

	// Environment
	DevShort     = "dev"
	StagingShort = "uat"
	Live         = "live"
	ProdShort    = "prod"
	Development  = "development"
	Staging      = "staging"
	Production   = "production"

	// Modes
	DynamicMode = "dynamic"
	TypedMode   = "typed"
)

Variables

This section is empty.

Functions

func ApiVersions

func ApiVersions() []string

ApiVersions returns the list of supported apiVersions.

func DefaultInternalTLSName added in v0.3.7

func DefaultInternalTLSName() string

DefaultInternalTLSName returns the default name for Orkestra's internal TLS secret.

func DefaultWorkloadSecretName added in v0.3.7

func DefaultWorkloadSecretName() string

DefaultWorkloadSecretName returns the base name used for generated workload secrets. The caller appends the CR's name to form the final secret name.

func E2EKind added in v0.4.8

func E2EKind() string

E2EKind returns the kind string for an E2E document.

func GetBoolEnv

func GetBoolEnv(key string, def bool) bool

GetBoolEnv returns the boolean value of an env

func GetDurEnvSeconds

func GetDurEnvSeconds(key string, def int) time.Duration

GetDurEnvSeconds returns the time.duration value of an env

func GetIntEnv

func GetIntEnv(key string, def int) int

GetIntEnv returns the int value of an env

func GetStrEnv

func GetStrEnv(key, def string) string

GetStrEnv returns the string value of an env

func GetStrSliceEnv

func GetStrSliceEnv(key string, def []string) []string

GetStrSliceEnv returns the slice value of an env

func IsE2EKind added in v0.4.8

func IsE2EKind(kind string) bool

IsE2EKind returns true if the given kind is an E2E.

func IsKatalogKind

func IsKatalogKind(kind string) bool

IsKatalogKind returns true if the given kind is a Katalog.

func IsKomposerKind

func IsKomposerKind(kind string) bool

IsKomposerKind returns true if the given kind is a Komposer.

func IsKonduktorKind added in v0.3.9

func IsKonduktorKind(kind string) bool

IsKonduktorKind returns true if the given kind is a Konduktor.

func IsMotifKind added in v0.3.9

func IsMotifKind(kind string) bool

IsMotifKind returns true if the given kind is a Motif.

func IsSimulateKind added in v0.7.2

func IsSimulateKind(kind string) bool

IsSimulateKind returns true if the given kind is a Simulate.

func IsValidApiVersion

func IsValidApiVersion(apiVersion string) bool

IsValidApiVersion returns true if the given apiVersion is a supported version.

func IsValidPatternKind added in v0.7.6

func IsValidPatternKind(kind string) bool

IsValidPatternKind reports whether the given kind is one of the supported Orkestra pattern kinds.

func KatalogKind

func KatalogKind() string

KatalogKind returns the kind string for a Katalog document. Katalogs declare CRDs in spec.crds. No sources block.

func KomposerKind

func KomposerKind() string

KomposerKind returns the kind string for a Komposer document. Komposers compose Katalogs from sources (files, helm).

func KonduktorKind added in v0.3.9

func KonduktorKind() string

KonduktorKind returns the kind string for a Konduktor document.

func MotifKind added in v0.3.9

func MotifKind() string

MotifKind returns the kind string for a Motif document.

func SimulateKind added in v0.7.2

func SimulateKind() string

SimulateKind returns the kind string for a Simulate document.

func ValidKindsString added in v0.4.2

func ValidKindsString() string

ValidKindsString returns a comma‑separated list of all supported document kinds. Useful for error messages and CLI diagnostics.

func Validate

func Validate() *validator.Validate

-----------------------------------------------------------------------------

Types

type Instance added in v0.4.9

type Instance string

Instance identifiers used by Orkestra to distinguish between the internal runtime service and gateway service.

const (
	InstanceRuntime Instance = "runtime"
	InstanceGateway Instance = "gateway"
)

func Gateway added in v0.4.9

func Gateway() Instance

Gateway returns the instance identifier for the gateway service, Used by pkg/orkestra and other packages to determine what is running.

func Runtime added in v0.4.9

func Runtime() Instance

Runtime returns the instance identifier Used by pkg/orkestra and other packages to determine what is running.

func (Instance) String added in v0.4.9

func (i Instance) String() string

String returns the string representation of the Instance, suitable for logging, printing, and serialization.

type Konfig

type Konfig struct {
	// contains filtered or unexported fields
}

func Init

func Init(filenames ...string) (*Konfig, error)

func NewDefaultKonfig

func NewDefaultKonfig() *Konfig

NewDefaultKonfig returns a Konfig populated from environment variables with sensible defaults. Used by CLI commands that do not go through the full Init() path (e.g. ork validate, ork template, ork simulate). All fields follow the same GetStrEnv/GetIntEnv/GetDurEnvSeconds pattern as Init().

func (*Konfig) AdmissionEnabled

func (k *Konfig) AdmissionEnabled() bool

AdmissionEnabled reports whether admission webhooks are enabled. Reads from SecurityConfig (populated from ENV at Init).

func (*Konfig) Cluster

func (k *Konfig) Cluster() *clusterKonfig

Cluster returns cluster Konfigurations

func (*Konfig) ConversionEnabled

func (k *Konfig) ConversionEnabled() bool

ConversionEnabled reports whether the conversion webhook is enabled. Reads from SecurityConfig (populated from ENV at Init).

func (*Konfig) Finalizers

func (k *Konfig) Finalizers() []string

Finalizers return a list of default finalizers

func (*Konfig) GatewayEndpoint added in v0.4.9

func (k *Konfig) GatewayEndpoint() string

GatewayEndpoint returns the companion gateway URL advertised to the control center. Empty string when no gateway is configured (e.g. runtime-only deployment).

func (*Konfig) GatewayServiceName added in v0.4.9

func (k *Konfig) GatewayServiceName() string

Gateway service name

func (*Konfig) HTTPSPort

func (k *Konfig) HTTPSPort() string

HTTPSPort returns the HTTPS port string (e.g. ":8443") used by the webhook server.

func (*Konfig) HTTPSPortInt32

func (k *Konfig) HTTPSPortInt32() int32

HTTPSPortInt32 returns the HTTPS port as int32 (8443) used in webhook client configs.

func (*Konfig) Health

func (k *Konfig) Health() *healthServer

Health returns health konfigurations

func (*Konfig) IsDev

func (k *Konfig) IsDev() bool

IsDev returns true for development environment

func (*Konfig) IsGatewayInstance added in v0.4.9

func (k *Konfig) IsGatewayInstance() bool

IsGatewayInstance reports whether the active instance is the external Orkestra gateway service.

func (*Konfig) IsProduction

func (c *Konfig) IsProduction() bool

IsDev returns true for production environment

func (*Konfig) IsRuntimeInstance added in v0.4.9

func (k *Konfig) IsRuntimeInstance() bool

IsRuntimeInstance reports whether the active instance is the internal Orkestra runtime service.

func (*Konfig) IsStaging

func (k *Konfig) IsStaging() bool

IsDev returns true for staging environment

func (*Konfig) Katalog

func (k *Konfig) Katalog() *katalogKonfig

Katalog returns katalog Konfigurations

func (*Konfig) Konductor

func (c *Konfig) Konductor() *konductorElection

Konductor returns konductor Konfigurations

func (*Konfig) Notification

func (k *Konfig) Notification() *NotificationConfig

Notification returns the unified notification configuration. This is the primary accessor for all notification-related settings.

func (*Konfig) Ork

func (k *Konfig) Ork() *orkKonfig

Ork returns Ork Konfigurations

func (*Konfig) RegistryConfig

func (k *Konfig) RegistryConfig() *registryConfig

RegistryConfig returns registry configuration.

func (*Konfig) RunningInstance added in v0.4.9

func (k *Konfig) RunningInstance() string

Running instance returns the current running orkestra instance

func (*Konfig) RuntimeServiceName added in v0.4.9

func (k *Konfig) RuntimeServiceName() string

Runtime service name

func (*Konfig) Security

func (k *Konfig) Security() *SecurityConfig

Security returns the unified security configuration. This is the primary accessor for all security-related settings.

func (*Konfig) SetInstance added in v0.4.9

func (k *Konfig) SetInstance(instance Instance)

SetInstance sets the active Orkestra instance name (runtime or gateway) on the Konfig. This controls which service name is used when resolving endpoints and wiring.

type NotificationConfig

type NotificationConfig struct {
	Email struct {
		Enabled  bool // true when SMTP_* env vars are present
		SMTPHost string
		SMTPPort int
		SMTPUser string
		SMTPPass string
		From     string // optional override for From: header
	}

	Slack struct {
		Enabled bool   // true when SLACK_WEBHOOK_URL is present
		Webhook string // default webhook URL
	}

	// DefaultInterval is the fallback notification interval when neither the
	// team nor the Katalog YAML defines one.
	DefaultInterval time.Duration
}

NotificationConfig is the unified notification configuration populated from ENV vars at Init() time. Katalog YAML values are merged on top via the Katalog loader, so this represents the ENV-level defaults.

Precedence: Katalog YAML > NotificationConfig (ENV) > hard default.

This struct defines *capability* — whether Orkestra is able to send email or Slack notifications at all. Teams and conditions define *intent*.

type SecurityConfig

type SecurityConfig struct {
	ServiceName struct {
		Runtime string
		Gateway string
	}

	DeletionProtection struct {
		Enabled           bool
		CleanupOnShutdown bool
		ServiceName       string
		FailurePolicy     string
	}
	Webhooks struct {
		Admission struct {
			Enabled bool
		}
		CleanupOnShutdown bool
		FailurePolicy     string
		ServiceName       string
		// TLS paths — shared with deletion protection, admission, and conversion.
		// Set by ensureSecurity() after cert generation/loading.
		TLSCert string
		TLSKey  string

		Housekeeper struct {
			Enabled      bool
			SyncInterval time.Duration
		}
	}
	// Conversion is separate from admission webhooks — conversion has its own
	// /convert endpoint, window stats, and CRD patch logic.
	Conversion struct {
		Enabled bool
		// ConversionWindow is the rolling window size for latency/throughput stats.
		ConversionWindow  int
		CleanupOnShutdown bool // TODO
	}

	// NamespaceProtection controls the optional validating webhook that prevents
	// Orkestra-managed CRs from being created or updated in forbidden namespaces.
	//
	// This is an admission-time safeguard only. If disabled, namespace rules are
	// not enforced at apply time. If enabled, the webhook blocks CRs whose target
	// namespace violates the CRD’s declared allowedNamespaces or restrictedNamespaces.
	//
	// The webhook is managed by the housekeeper and will be recreated if
	// deleted, ensuring continuous enforcement when enabled.
	//
	// Precedence: Katalog YAML > SecurityConfig (ENV) > hard default.
	NamespaceProtection struct {
		Enabled           bool
		FailurePolicy     string
		ServiceName       string
		CleanupOnShutdown bool
	}

	// CertManager controls the lifecycle of Orkestra’s auto-generated TLS certificate.
	// Only applies when certificates are auto-generated (TLS_CERT/TLS_KEY not set).
	//
	// Precedence: Katalog YAML > SecurityConfig (ENV) > hard default.
	CertManager struct {
		// AutoRotate enables pre-emptive certificate rotation before expiry.
		// Default: true. Set TLS_AUTO_ROTATE=false to opt out.
		AutoRotate bool
		// RotationThreshold is how far before expiry Orkestra rotates.
		// Parsed from TLS_ROTATION_THRESHOLD env (e.g. "30d"). Default: "30d".
		RotationThreshold string
		// ValidFor is the default certificate validity duration.
		// Parsed from TLS_ROTATE_AFTER env (e.g. "30d"). Default: "1y".
		ValidFor string
	}
}

SecurityConfig is the unified security configuration populated from ENV vars at Init() time. Katalog YAML values are merged on top via the Katalog loader, so this represents the ENV-level defaults.

Precedence: Katalog YAML > SecurityConfig (ENV) > hard default.

Jump to

Keyboard shortcuts

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