Documentation
¶
Overview ¶
Package kubernetes implements a Kubernetes-based infrastructure provider for the ctrlplane. It maps ctrlplane instances to Kubernetes Deployments, Services, and ConfigMaps, providing full lifecycle management including provisioning, deployment, scaling, log streaming, and command execution.
Index ¶
- type Config
- type Option
- func WithConfig(cfg Config) Option
- func WithContext(ctx string) Option
- func WithImagePullSecrets(secrets ...string) Option
- func WithInCluster() Option
- func WithKubeconfig(path string) Option
- func WithLabels(labels map[string]string) Option
- func WithLocation(country, city string) Option
- func WithNamespace(ns string) Option
- func WithRegion(region string) Option
- type Provider
- func (p *Provider) ApplyManifests(ctx context.Context, req provider.ManifestApplyRequest) (*provider.ProvisionResult, error)
- func (p *Provider) ArgoApply(ctx context.Context, req provider.ArgoApplyRequest) (*provider.ProvisionResult, error)
- func (p *Provider) ArgoDelete(ctx context.Context, instanceID id.ID) error
- func (p *Provider) ArgoStatus(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
- func (p *Provider) Capabilities() []provider.Capability
- func (p *Provider) DeleteManifests(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Deploy(ctx context.Context, req provider.DeployRequest) (*provider.DeployResult, error)
- func (p *Provider) Deprovision(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Exec(_ context.Context, _ id.ID, _ provider.ExecRequest) (*provider.ExecResult, error)
- func (p *Provider) HealthCheck(ctx context.Context) (*provider.HealthStatus, error)
- func (p *Provider) HelmInstall(_ context.Context, req provider.HelmInstallRequest) (*provider.ProvisionResult, error)
- func (p *Provider) HelmStatus(_ context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
- func (p *Provider) HelmUninstall(_ context.Context, instanceID id.ID) error
- func (p *Provider) HelmUpgrade(_ context.Context, req provider.HelmUpgradeRequest) (*provider.DeployResult, error)
- func (p *Provider) Info() provider.ProviderInfo
- func (p *Provider) Logs(ctx context.Context, instanceID id.ID, opts provider.LogOptions) (io.ReadCloser, error)
- func (p *Provider) ManifestStatus(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
- func (p *Provider) Provision(ctx context.Context, req provider.ProvisionRequest) (*provider.ProvisionResult, error)
- func (p *Provider) Resources(ctx context.Context, instanceID id.ID) (*provider.ResourceUsage, error)
- func (p *Provider) Restart(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Rollback(_ context.Context, _ id.ID, _ id.ID) error
- func (p *Provider) Scale(ctx context.Context, instanceID id.ID, spec provider.ResourceSpec) error
- func (p *Provider) Start(ctx context.Context, instanceID id.ID) error
- func (p *Provider) Status(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
- func (p *Provider) Stop(ctx context.Context, instanceID id.ID) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Kubeconfig is the path to a kubeconfig file.
// When empty, the provider tries in-cluster config first, then falls back
// to the default kubeconfig loading rules (KUBECONFIG env, ~/.kube/config).
Kubeconfig string `env:"CP_K8S_KUBECONFIG" json:"kubeconfig,omitempty"`
// Context is the kubeconfig context to use.
// When empty, the current context is used.
Context string `env:"CP_K8S_CONTEXT" json:"context,omitempty"`
// Namespace is the Kubernetes namespace for all managed resources.
Namespace string `default:"default" env:"CP_K8S_NAMESPACE" json:"namespace"`
// Region is the region label reported in provider info.
Region string `default:"local" env:"CP_K8S_REGION" json:"region"`
// Country is reported as part of the provider's Location in
// ProviderInfo. Defaults to "Local" so dev environments without
// explicit configuration still surface a usable region in the
// studio catalog. Override for production clusters with the real
// country (e.g. "US").
Country string `default:"Local" env:"CP_K8S_COUNTRY" json:"country"`
// City is reported as part of the provider's Location. Defaults
// to "Localhost" for the same reason as Country. Override for
// production with the cluster's geographic city.
City string `default:"Localhost" env:"CP_K8S_CITY" json:"city"`
// InCluster forces in-cluster configuration only, skipping the local
// kubeconfig fallback. Use this in production to prevent accidentally
// picking up a developer's local kubeconfig.
InCluster bool `env:"CP_K8S_IN_CLUSTER" json:"in_cluster,omitempty"`
// Labels are additional labels applied to all managed resources.
Labels map[string]string `json:"labels,omitempty"`
// ImagePullSecrets is the list of Secret names in the same namespace
// that contain credentials to pull private container images.
// Corresponds to the Kubernetes podSpec.imagePullSecrets field.
// Use CP_K8S_IMAGE_PULL_SECRETS (comma-separated) to configure via env.
ImagePullSecrets []string `env:"CP_K8S_IMAGE_PULL_SECRETS" json:"image_pull_secrets,omitempty"`
// ArgoNamespace is the namespace where ctrlplane creates Argo CD
// Application CRs (where Argo CD itself runs). Defaults to "argocd".
ArgoNamespace string `default:"argocd" env:"CP_K8S_ARGO_NAMESPACE" json:"argo_namespace,omitempty"`
}
Config holds configuration for the Kubernetes provider.
type Option ¶
Option configures a Kubernetes provider.
func WithConfig ¶
WithConfig applies all non-zero fields from a Config struct. This is useful when loading configuration from files or environment variables.
func WithContext ¶
WithContext sets the kubeconfig context to use.
func WithImagePullSecrets ¶ added in v1.5.2
WithImagePullSecrets sets the list of Kubernetes Secret names that contain credentials for pulling private container images. Each name is added to the pod spec's imagePullSecrets field verbatim.
func WithInCluster ¶
func WithInCluster() Option
WithInCluster forces in-cluster configuration only, skipping the local kubeconfig fallback. Use this in production to prevent accidentally picking up a developer's local kubeconfig.
func WithKubeconfig ¶
WithKubeconfig sets the path to a kubeconfig file. When empty, in-cluster configuration is used.
func WithLabels ¶
WithLabels sets additional labels applied to all managed resources.
func WithLocation ¶ added in v1.5.1
WithLocation sets the country/city pair reported in provider info. Surfaced through the catalog/regions endpoint so the studio UI can show where each region physically lives. Empty values fall back to the config defaults ("Local"/"Localhost") so dev still shows a non-empty location.
func WithNamespace ¶
WithNamespace sets the Kubernetes namespace for all managed resources.
func WithRegion ¶
WithRegion sets the region label reported in provider info.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is a Kubernetes-based infrastructure provider.
helmConfig and loadChart are injectable seams: production wiring builds a cluster-backed action.Configuration and a repo/OCI chart loader, while tests inject an in-memory storage driver and an in-memory chart.
func New ¶
New creates a new Kubernetes provider with the given options. Without any options, sane defaults are used (namespace: "default", region: "local"). Configuration is resolved in order: explicit kubeconfig path, in-cluster config, then default kubeconfig loading rules (KUBECONFIG env, ~/.kube/config).
func (*Provider) ApplyManifests ¶ added in v1.5.2
func (p *Provider) ApplyManifests(ctx context.Context, req provider.ManifestApplyRequest) (*provider.ProvisionResult, error)
ApplyManifests applies every rendered document for an instance, labels each object, and records the applied refs in a per-instance tracking ConfigMap so they can later be deleted or inspected.
func (*Provider) ArgoApply ¶ added in v1.5.2
func (p *Provider) ArgoApply(ctx context.Context, req provider.ArgoApplyRequest) (*provider.ProvisionResult, error)
ArgoApply creates or updates the instance's Argo CD Application CR.
func (*Provider) ArgoDelete ¶ added in v1.5.2
ArgoDelete removes the instance's Application CR. A missing Application is treated as success.
func (*Provider) ArgoStatus ¶ added in v1.5.2
func (p *Provider) ArgoStatus(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
ArgoStatus reads the Application's sync and health status and maps them to an InstanceState.
func (*Provider) Capabilities ¶
func (p *Provider) Capabilities() []provider.Capability
Capabilities returns the set of features this provider supports.
func (*Provider) DeleteManifests ¶ added in v1.5.2
DeleteManifests removes every object previously applied for an instance, then the tracking ConfigMap itself. A missing tracking object means there is nothing to delete.
func (*Provider) Deploy ¶
func (p *Provider) Deploy(ctx context.Context, req provider.DeployRequest) (*provider.DeployResult, error)
Deploy pushes a new release by updating each targeted service's container image and ConfigMap. Services not listed in req.Services are left at their current image — Kubernetes performs a rolling update only on the changed containers.
func (*Provider) Deprovision ¶
Deprovision tears down all resources for an instance.
func (*Provider) Exec ¶
func (p *Provider) Exec(_ context.Context, _ id.ID, _ provider.ExecRequest) (*provider.ExecResult, error)
Exec runs a command inside the instance (stub).
func (*Provider) HealthCheck ¶
HealthCheck tests connectivity to the Kubernetes API server.
Uses the discovery REST client directly (instead of Discovery().ServerVersion(), which doesn't accept a context) so the caller's ctx deadline is honored — without this, an unreachable cluster blocked the providerhealth cache sweep indefinitely and stalled the studio process at startup.
func (*Provider) HelmInstall ¶ added in v1.5.2
func (p *Provider) HelmInstall(_ context.Context, req provider.HelmInstallRequest) (*provider.ProvisionResult, error)
HelmInstall installs the rendered chart as a new release for the instance.
func (*Provider) HelmStatus ¶ added in v1.5.2
func (p *Provider) HelmStatus(_ context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
HelmStatus reports the instance release's state.
func (*Provider) HelmUninstall ¶ added in v1.5.2
HelmUninstall removes the instance's release.
func (*Provider) HelmUpgrade ¶ added in v1.5.2
func (p *Provider) HelmUpgrade(_ context.Context, req provider.HelmUpgradeRequest) (*provider.DeployResult, error)
HelmUpgrade upgrades the instance's existing release.
func (*Provider) Info ¶
func (p *Provider) Info() provider.ProviderInfo
Info returns metadata about this provider, including a default location so studio's catalog endpoints surface a usable region in dev environments without explicit per-cluster geographic config.
func (*Provider) Logs ¶
func (p *Provider) Logs(ctx context.Context, instanceID id.ID, opts provider.LogOptions) (io.ReadCloser, error)
Logs streams logs for the instance.
func (*Provider) ManifestStatus ¶ added in v1.5.2
func (p *Provider) ManifestStatus(ctx context.Context, instanceID id.ID) (*provider.InstanceStatus, error)
ManifestStatus reports the aggregate state of an instance's applied objects. It is existence-based: all tracked objects present yields Running; any missing yields Provisioning. Deep readiness of arbitrary resources is out of scope for this iteration.
func (*Provider) Provision ¶
func (p *Provider) Provision(ctx context.Context, req provider.ProvisionRequest) (*provider.ProvisionResult, error)
Provision creates a Kubernetes workload for an instance.
For req.Kind=KindDeployment (default): emits a Deployment + Service + per-service ConfigMaps. Pod has Main + Sidecars in containers[] and Inits in initContainers[].
For req.Kind=KindStatefulSet: emits a StatefulSet + headless Service (ClusterIP=None) + volumeClaimTemplates per persistent volume + per- service ConfigMaps. Each replica gets its own PVC by name.
func (*Provider) Resources ¶
func (p *Provider) Resources(ctx context.Context, instanceID id.ID) (*provider.ResourceUsage, error)
Resources returns a one-shot point-in-time sample of the instance's pod resource usage via the metrics.k8s.io API.
Sums per-container CPU + memory across every pod that matches the instance's label selector (replica fan-out is handled by ctrlplane's metrics package — this returns the raw aggregate for one Instance, which on k8s typically means one pod-set owned by a Deployment).
Network bytes are zero — metrics-server doesn't expose them. Operators who need per-pod network counters can wire a Prometheus scraper at the metrics.Service layer; the dashboard renders gracefully when those fields are zero.
When metrics-server isn't installed, the underlying API returns 404 and Resources reports a zero-valued usage rather than an error — the metrics poller treats that as a missing sample, so the dashboard shows "—" rather than perpetual errors.
func (*Provider) Restart ¶
Restart performs a rollout restart by updating a pod template annotation.
func (*Provider) Rollback ¶
Rollback reverts to a previous release (no-op: ctrlplane handles release state).
func (*Provider) Scale ¶
Scale adjusts the instance's resource allocation. A ScaleRequest may carry CPU/memory changes, a replica change, or both: resource changes patch the pod template's container resources (rolling the pods), replica changes patch the scale subresource.
Source Files