health

package
v0.4.2 Latest Latest
Warning

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

 Go to latest Published: May 11, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

pkg/health

The health package owns the HTTP server that exposes Orkestra's lifecycle to Kubernetes. It has one responsibility: serve health and readiness probes so the cluster can gate traffic, restarts, and rolling updates correctly.

All webhook logic — admission, conversion, deletion protection, and namespace protection — lives in pkg/webhook.

Responsibilities

Concern Where
Startup probe (/startup) handler.go
Liveness probe (/health) handler.go
Readiness probe (/ready) handler.go
Prometheus metrics (/metrics) health.go (via promhttp.Handler)
Katalog API routes (/katalog/…) Registered externally by cmd/internal/konstructor.go
Conversion / admission stats types conversion_stats.go, admission_stats.go, etc.

Server lifecycle

NewHealthServer(konfig)
    ↓
hs.Register(path, handler)   ← called by konstructor.go for all /katalog routes
    ↓
hs.Start(ctx)
    • binds HTTP port  → /startup /health /ready /metrics + /katalog routes
    ↓
hs.Shutdown(ctx)
    • marks not-ready, drains HTTP server

Probe semantics

Endpoint Returns 200 when…
/startup SetStartupComplete() has been called
/health healthy atomic is true
/ready ready atomic is true — false during boot and after shutdown begins

SetStartupComplete() is called at the end of Start(). Degraded() and SetReady() are called by the dependency kordinator as informer caches sync and workers start.

Stats types

The stats types (ConversionStats, AdmissionStats, DeletionProtectionStats, NamespaceProtectionStats, WebhookStats) live in this package because the kordinator reads them when building the /katalog/{crd} API response. The webhook package writes to these instances; the health package only defines the types and exposes read snapshots.

→ Next: docs/01-probes.md

Documentation

Overview

health/admission_stats.go

pkg/health/conversion_stats.go

pkg/health/protection_stats.go

pkg/health/handlers.go

Package health implements Orkestra's HTTP health, readiness, and metrics surface.

Responsibility

The health package owns the HTTP server that Kubernetes uses to probe the operator's lifecycle. It serves three standard probe endpoints:

  • GET /startup — Kubernetes startupProbe. Returns 200 once the controller has fully initialised. Prevents liveness/readiness probes from running too early.
  • GET /health — Kubernetes livenessProbe. Returns 200 when the process is operational; 500 when a fatal condition is detected.
  • GET /ready — Kubernetes readinessProbe. Returns 200 when the controller is ready to process requests; 503 during startup, informer sync, and shutdown.

Additionally, the Prometheus metrics endpoint is served at GET /metrics. All Katalog API routes (/katalog/...) are registered externally via Register() by cmd/internal/konstructor.go before Start() is called.

What this package does NOT do

Webhook admission and conversion handling, TLS server lifecycle, and webhook configuration registration are handled by pkg/webhook. The two packages are intentionally separated: this package starts first to serve /ready during startup, and the webhook server starts after it, once the cluster-facing admission surface is needed.

Lifecycle

HealthServer implements domain.Komponent: 

New(konfig)
  → Register(path, handler)   — called before Start() to add Katalog routes
  → Start(ctx)                — bind port, start HTTP server
  → Shutdown(ctx)             — graceful drain, mark not-ready

pkg/health/namespace_protection_stats.go

NamespaceProtectionStats tracks counters for the /namespace-protection webhook. Distinct from DeletionProtectionStats (deletion protection) — different admission operations, different semantics. Deletion protection intercepts DELETE; namespace protection intercepts CREATE and UPDATE.

pkg/health/provider_stats.go

pkg/health/webhook_stats.go

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdmissionStats 

type AdmissionStats struct {

	// ── Validation counters ──────────────────────────────────────────────────
	ValidationTotal   int64 // total /validate calls
	ValidationAllowed int64 // allowed (no deny rules fired)
	ValidationDenied  int64 // denied (at least one deny rule fired)
	ValidationWarned  int64 // allowed with warnings (warn rules fired, no deny)

	// ── Mutation counters ────────────────────────────────────────────────────
	MutationTotal   int64 // total /mutate calls
	MutationApplied int64 // at least one rule produced a change
	MutationSkipped int64 // no rules produced changes — no-op
	// contains filtered or unexported fields
}

AdmissionStats tracks statistics for the /validate and /mutate endpoints. Thread-safe for concurrent updates from the admission handlers.

Follows the same pattern as ConversionStats — a rolling window ring buffer for percentile calculations alongside simple running totals.

One AdmissionStats instance lives on the HealthServer and accumulates statistics across all CRDs. Per-CRD breakdown is available in Prometheus via the crd label on the metric series.

func NewAdmissionStats 

func NewAdmissionStats(windowSize int) *AdmissionStats

NewAdmissionStats creates a new stats tracker with a rolling window. windowSize determines how many requests are kept for percentile calculations. Use the same value as ConversionStats (controlled by CONVERSION_WINDOW env var).

func (*AdmissionStats) GetStats 

func (s *AdmissionStats) GetStats(webhooksEnabled bool) AdmissionStatsSnapshot

GetStats returns a point-in-time snapshot of the admission statistics.

func (*AdmissionStats) RecordMutationApplied 

func (s *AdmissionStats) RecordMutationApplied(duration time.Duration)

RecordMutationApplied records a /mutate call where at least one rule changed a field.

func (*AdmissionStats) RecordMutationSkipped 

func (s *AdmissionStats) RecordMutationSkipped(duration time.Duration)

RecordMutationSkipped records a /mutate call where no rules produced changes.

func (*AdmissionStats) RecordValidationAllowed 

func (s *AdmissionStats) RecordValidationAllowed(duration time.Duration)

RecordValidationAllowed records a /validate call that was allowed with no warnings.

func (*AdmissionStats) RecordValidationDenied 

func (s *AdmissionStats) RecordValidationDenied(duration time.Duration)

RecordValidationDenied records a /validate call that was denied.

func (*AdmissionStats) RecordValidationWarned 

func (s *AdmissionStats) RecordValidationWarned(duration time.Duration)

RecordValidationWarned records a /validate call that was allowed with warnings.

type AdmissionStatsSnapshot 

type AdmissionStatsSnapshot struct {
	// Validation
	ValidationTotal   int64   `json:"validationTotal"`
	ValidationAllowed int64   `json:"validationAllowed"`
	ValidationDenied  int64   `json:"validationDenied"`
	ValidationWarned  int64   `json:"validationWarned"`
	ValAvgLatencyMs   float64 `json:"valAvgLatencyMs"`
	ValP95LatencyMs   float64 `json:"valP95LatencyMs"`
	ValMaxLatencyMs   float64 `json:"valMaxLatencyMs"`

	// Mutation
	MutationTotal   int64   `json:"mutationTotal"`
	MutationApplied int64   `json:"mutationApplied"`
	MutationSkipped int64   `json:"mutationSkipped"`
	MutAvgLatencyMs float64 `json:"mutAvgLatencyMs"`
	MutP95LatencyMs float64 `json:"mutP95LatencyMs"`
	MutMaxLatencyMs float64 `json:"mutMaxLatencyMs"`

	// Whether admission webhooks are enabled
	WebhooksEnabled bool `json:"webhooksEnabled"`
}

AdmissionStatsSnapshot is a read-only point-in-time snapshot. Serialised into the /katalog/{crd} JSON response under the "admission" key.

type ConversionStats 

type ConversionStats struct {
	TotalRequests   int64
	SuccessRequests int64
	FailedRequests  int64
	// contains filtered or unexported fields
}

ConversionStats tracks statistics for the /convert endpoint. Thread‑safe for concurrent updates from the conversion handler.

func NewConversionStats 

func NewConversionStats(windowSize int) *ConversionStats

NewConversionStats creates a new stats tracker with a rolling window. windowSize determines how many requests are kept for percentile calculations.

func (*ConversionStats) GetStats 

func (s *ConversionStats) GetStats() ConversionStatsSnapshot

GetStats returns a snapshot of current statistics.

func (*ConversionStats) RecordFailure 

func (s *ConversionStats) RecordFailure()

RecordFailure records a failed conversion attempt.

func (*ConversionStats) RecordSuccess 

func (s *ConversionStats) RecordSuccess(duration time.Duration)

RecordSuccess records a successful conversion with its duration.

type ConversionStatsSnapshot 

type ConversionStatsSnapshot struct {
	TotalRequests   int64
	SuccessRequests int64
	FailedRequests  int64
	AvgLatency      time.Duration
	P95Latency      time.Duration
	MaxLatency      time.Duration
	MinLatency      time.Duration
}

ConversionStatsSnapshot is a read‑only snapshot of conversion statistics.

type DeletionProtectionStats added in v0.1.9 

type DeletionProtectionStats struct {
	TotalRequests int64 // total DELETE admission reviews received
	Blocked       int64 // DELETE requests denied (CRD or deployment protected)
	Allowed       int64 // DELETE requests allowed through
	// contains filtered or unexported fields
}

DeletionProtectionStats tracks counters for the /deletion-protection webhook endpoint. Thread-safe for concurrent updates from the deletion protection handler.

Follows the same pattern as ConversionStats, AdmissionStats, and NamespaceProtectionStats. No latency tracking — deletion protection decisions are fast in-memory lookups and the blocking count is the meaningful signal.

func NewDeletionProtectionStats added in v0.1.9 

func NewDeletionProtectionStats() *DeletionProtectionStats

NewDeletionProtectionStats creates a new DeletionProtectionStats instance.

func (*DeletionProtectionStats) GetStats added in v0.1.9 

func (s *DeletionProtectionStats) GetStats() DeletionProtectionStatsSnapshot

GetStats returns a point-in-time snapshot of deletion protection statistics.

func (*DeletionProtectionStats) RecordAllowed added in v0.1.9 

func (s *DeletionProtectionStats) RecordAllowed()

RecordAllowed records a DELETE that was allowed through the webhook.

func (*DeletionProtectionStats) RecordBlocked added in v0.1.9 

func (s *DeletionProtectionStats) RecordBlocked()

RecordBlocked records a DELETE that was denied by the webhook.

type DeletionProtectionStatsSnapshot added in v0.1.9 

type DeletionProtectionStatsSnapshot struct {
	TotalRequests int64 `json:"total"`
	Blocked       int64 `json:"blocked"`
	Allowed       int64 `json:"allowed"`
}

DeletionProtectionStatsSnapshot is a read-only point-in-time snapshot. Serialised into the /katalog/{crd} JSON response under the "protection" key.

type HealthServer 

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

HealthServer serves Orkestra's HTTP health, readiness, and metrics endpoints. It is intentionally minimal — all webhook and admission logic lives in pkg/webhook.

Routes are registered before Start() via Register(). Start() binds the HTTP port and begins serving. Shutdown() drains and stops the server.

func NewHealthServer 

func NewHealthServer(kfg *konfig.Konfig) *HealthServer

NewHealthServer constructs a HealthServer. No I/O is performed. Routes must be registered via Register() before calling Start().

func (*HealthServer) Degraded 

func (h *HealthServer) Degraded()

Degraded transitions the server out of ready state without marking it unhealthy.

func (*HealthServer) Healthy 

func (h *HealthServer) Healthy() bool

Healthy reports whether the server is healthy.

func (*HealthServer) Name 

func (h *HealthServer) Name() string

Name returns the component name.

func (*HealthServer) Ready 

func (h *HealthServer) Ready() bool

Ready reports whether the server is ready for health checks.

func (*HealthServer) Register 

func (hs *HealthServer) Register(path string, handler http.HandlerFunc)

Register adds a route to the health server mux. Must be called before Start() — routes registered after Start() are not guaranteed to be visible.

func (*HealthServer) SetReady 

func (h *HealthServer) SetReady()

SetReady marks the server as ready to serve traffic.

func (*HealthServer) SetStarted 

func (h *HealthServer) SetStarted()

SetStarted marks the server as having begun serving.

func (*HealthServer) SetStartupComplete 

func (h *HealthServer) SetStartupComplete()

SetStartupComplete marks the startup sequence as finished.

func (*HealthServer) Shutdown 

func (h *HealthServer) Shutdown(ctx context.Context)

Shutdown gracefully stops the HTTP server and marks the server as not ready.

func (*HealthServer) Start 

func (h *HealthServer) Start(ctx context.Context) error

Start binds the HTTP port, registers the standard probe endpoints, and begins serving. After this call, /startup, /health, /ready, and /metrics are live.

func (*HealthServer) Started 

func (h *HealthServer) Started() bool

Started reports whether the HTTP server has begun serving.

func (*HealthServer) StartupComplete 

func (h *HealthServer) StartupComplete() bool

StartupComplete reports whether the startup sequence has finished.

func (*HealthServer) Unhealthy 

func (h *HealthServer) Unhealthy()

Unhealthy marks the server as unhealthy, signaling a fatal condition.

func (*HealthServer) Uptime 

func (h *HealthServer) Uptime() string

Uptime returns human-readable uptime since the server started.

type NamespaceProtectionStats added in v0.1.9 

type NamespaceProtectionStats struct {
	TotalRequests int64 // total CREATE/UPDATE admission reviews received
	Blocked       int64 // requests denied — namespace not in allowed set / in restricted set
	Allowed       int64 // requests allowed through
	// contains filtered or unexported fields
}

NamespaceProtectionStats tracks counters for the /namespace-protection webhook endpoint. Thread-safe for concurrent updates from the namespace protection handler.

func NewNamespaceProtectionStats added in v0.1.9 

func NewNamespaceProtectionStats() *NamespaceProtectionStats

NewNamespaceProtectionStats creates a new NamespaceProtectionStats instance.

func (*NamespaceProtectionStats) GetStats added in v0.1.9 

func (s *NamespaceProtectionStats) GetStats() NamespaceProtectionStatsSnapshot

GetStats returns a point-in-time snapshot of namespace protection statistics.

func (*NamespaceProtectionStats) RecordAllowed added in v0.1.9 

func (s *NamespaceProtectionStats) RecordAllowed()

RecordAllowed records a CREATE/UPDATE that passed the namespace rule.

func (*NamespaceProtectionStats) RecordBlocked added in v0.1.9 

func (s *NamespaceProtectionStats) RecordBlocked()

RecordBlocked records a CREATE/UPDATE that was denied by the namespace rule.

type NamespaceProtectionStatsSnapshot added in v0.1.9 

type NamespaceProtectionStatsSnapshot struct {
	TotalRequests int64 `json:"total"`
	Blocked       int64 `json:"blocked"`
	Allowed       int64 `json:"allowed"`
}

NamespaceProtectionStatsSnapshot is a read-only point-in-time snapshot. Serialised into the /katalog/{crd} JSON response under the "namespaceProtection" key.

type ProviderStatEntry 

type ProviderStatEntry struct {
	Provider  string
	Total     int64
	Errors    int64
	ErrorRate float64
}

ProviderStatEntry is one provider's snapshot — provider name, totals, error rate.

type ProviderStats 

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

ProviderStats tracks per-provider reconcile and delete call totals and errors. Thread-safe for concurrent updates from the template reconciler.

One ProviderStats instance is created per CRD at startup and shared between:

  • GenericReconciler, which writes to it after each provider.Reconcile / provider.Delete call
  • BuildCRDInfoHandler, which reads it to surface error rates in the CRD detail response

Detailed per-kind breakdowns are available in Prometheus via RecordProviderReconcile. This struct exists for fast in-memory error rate checks without querying Prometheus.

func NewProviderStats 

func NewProviderStats() *ProviderStats

NewProviderStats creates a new ProviderStats instance.

func (*ProviderStats) GetSnapshot 

func (s *ProviderStats) GetSnapshot() []ProviderStatEntry

GetSnapshot returns a point-in-time snapshot for all providers that have been called. Only providers that have been called at least once are included.

func (*ProviderStats) RecordDeleteFailure 

func (s *ProviderStats) RecordDeleteFailure(provider string)

RecordDeleteFailure records a failed provider.Delete call.

func (*ProviderStats) RecordDeleteSuccess 

func (s *ProviderStats) RecordDeleteSuccess(provider string)

RecordDeleteSuccess records a successful provider.Delete call.

func (*ProviderStats) RecordFailure 

func (s *ProviderStats) RecordFailure(provider string)

RecordFailure records a failed provider.Reconcile call for the named provider.

func (*ProviderStats) RecordSuccess 

func (s *ProviderStats) RecordSuccess(provider string)

RecordSuccess records a successful provider.Reconcile call for the named provider.

type WebhookStats 

type WebhookStats struct {
	Reconciled int64 // total successful reconciliation cycles
	Failed     int64 // reconciliation attempts that encountered errors
	// contains filtered or unexported fields
}

WebhookStats tracks reconciliation counters for the webhook controller. Thread-safe for concurrent updates from the reconciliation loop.

Mirrors the pattern used by ConversionStats, AdmissionStats, and ProtectionStats. No latency tracking — reconciliation is periodic and the meaningful signals are successful cycles and failures.

func NewWebhookStats 

func NewWebhookStats() *WebhookStats

NewWebhookStats creates a new WebhookStats instance.

func (*WebhookStats) GetStats 

func (s *WebhookStats) GetStats() WebhookStatsSnapshot

GetStats returns a point-in-time snapshot of webhook reconciliation statistics. Serialized into the /katalog/{crd} JSON response under the "webhooks" key.

func (*WebhookStats) RecordFailure 

func (s *WebhookStats) RecordFailure()

RecordFailure increments the reconciliation failure counter.

func (*WebhookStats) RecordReconciled 

func (s *WebhookStats) RecordReconciled()

RecordReconciled increments the successful reconciliation counter.

type WebhookStatsSnapshot 

type WebhookStatsSnapshot struct {
	Reconciled int64 `json:"reconciled"`
	Failed     int64 `json:"failed"`
}

WebhookStatsSnapshot is a read-only point-in-time snapshot.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.