k8s

package
v0.8.0 Latest Latest
Warning

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

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

Documentation

Overview

Package k8s provides Kubernetes client helpers for Deployah resources.

It wraps label selectors, pod queries, and component discovery for projects deployed through Deployah.

Index

Constants

View Source 
const (
	ProjectLabel     = "deployah.dev/project"
	ComponentLabel   = "deployah.dev/component"
	EnvironmentLabel = "deployah.dev/environment"
)

Label constants for Deployah resources.

View Source 
const (
	MinStatefulMajor = 1
	MinStatefulMinor = 32
)

MinStatefulMajor and MinStatefulMinor are the Kubernetes version floor for kind: stateful with persistence (RWOP GA at 1.29, PVC retention policy GA at 1.32). Identity-only stateful components do not require it.

Variables

This section is empty.

Functions

func BuildComponentSelector 

func BuildComponentSelector(project, component string) (string, error)

BuildComponentSelector builds a selector for a specific project and component

func BuildLabelSelector 

func BuildLabelSelector(project, environment string) (labels.Selector, error)

BuildLabelSelector returns a labels.Selector for project and/or environment filters.

func BuildProjectSelector 

func BuildProjectSelector(project string) (string, error)

BuildProjectSelector builds a selector for a specific project

func BuildSelector 

func BuildSelector(project, component, environment string) (string, error)

BuildSelector builds a label selector from project, component, and environment.

func BuildTaskJob added in v0.8.0 

func BuildTaskJob(opts TaskJobOptions) (*batchv1.Job, error)

BuildTaskJob builds an Indexed batch/v1 Job for a CLI run. The name is left empty; GenerateName is set so concurrent runs do not collide. serviceAccountName is omitted so the pod uses the namespace default ServiceAccount.

func CheckAPIRequirements added in v0.3.0 

func CheckAPIRequirements(client kubernetes.Interface, reqs []APIRequirement) error

CheckAPIRequirements probes the cluster's available API groups and returns an error listing every requirement that is not satisfied. Returns nil when all requirements are met.

The check calls ServerGroups once and builds an in-memory set of available group/version strings, so it incurs a single network round-trip regardless of how many requirements are checked.

NOTE: client-go's ServerGroups does not accept a context (it uses context.TODO internally). Cancellation is not propagated to the underlying HTTP call. See https://github.com/kubernetes/kubernetes/issues/110810.

func CheckMinimumVersion added in v0.7.0 

func CheckMinimumVersion(client kubernetes.Interface, major, minor int, reason string) error

CheckMinimumVersion probes the cluster server version and returns an error when it is below major.minor. reason is included in the error.

func CreateTaskJob added in v0.8.0 

func CreateTaskJob(ctx context.Context, cs kubernetes.Interface, job *batchv1.Job) (*batchv1.Job, error)

CreateTaskJob creates the Job and returns the server copy (with Name).

func DeleteJobs added in v0.8.0 

func DeleteJobs(ctx context.Context, cs kubernetes.Interface, namespace, project, environment string) error

DeleteJobs deletes Jobs labeled with project and environment. A NotFound result is ignored (the Job is already gone). Other delete errors are collected with errors.Join so one failure does not skip the rest.

func EnsureSelfSignedCert added in v0.4.0 

func EnsureSelfSignedCert(ctx context.Context, client kubernetes.Interface, namespace, fqdn string) (certPEM, keyPEM []byte, err error)

EnsureSelfSignedCert returns a PEM cert/key pair for fqdn, reusing the existing `kubernetes.io/tls` Secret named `<fqdn>-tls` in namespace when present and not close to expiry. Otherwise it generates a new self-signed pair. Reuse (rather than regenerating on every call) is what keeps the rendered manifest identical across plan/apply/re-deploy: a fresh keypair every render would defeat both the apply-time verification and skip-on-no-change.

func GenerateSelfSignedCert added in v0.4.0 

func GenerateSelfSignedCert(fqdn string) (certPEM, keyPEM []byte, err error)

GenerateSelfSignedCert generates a fresh self-signed PEM cert/key pair for fqdn without any cluster access. Used for the plan --offline render, where there is no cluster to fetch a reusable secret from.

func HasSelfSignedComponents added in v0.4.0 

func HasSelfSignedComponents(resolved *spec.ResolvedSpec) bool

HasSelfSignedComponents reports whether resolved has at least one exposed component whose TLSMode is selfSigned, meaning a caller must have a working Kubernetes clientset (or explicitly accept offline generation) before rendering.

func ListJobs added in v0.8.0 

func ListJobs(ctx context.Context, cs kubernetes.Interface, namespace, project, environment string) ([]batchv1.Job, error)

ListJobs returns Jobs labeled with project and environment.

func MaterializeSelfSignedTLS added in v0.4.0 

func MaterializeSelfSignedTLS(ctx context.Context, client kubernetes.Interface, namespace string, resolved *spec.ResolvedSpec) error

MaterializeSelfSignedTLS fills TLSCertPEM/TLSKeyPEM on every resolved component whose TLSMode is selfSigned. Call it once per CLI invocation, before any chart render, so the plan render, apply-time verification render, and real apply all see identical certificate bytes. Pass a nil client to force offline generation (no cluster access), as plan --offline does.

func WaitForJob added in v0.8.0 

func WaitForJob(ctx context.Context, cs kubernetes.Interface, namespace, name string) error

WaitForJob waits until the Job succeeds or fails. ctx should already carry the session timeout. Get errors that are not a permanent API status (Forbidden, Unauthorized, Invalid, BadRequest) are retried until ctx is done. Consecutive NotFound results are retried a few times, then treated as a permanent miss (the Job was deleted or never became visible). Every failure is wrapped as "wait for job <name>".

func WatchDeployEvents added in v0.3.0 

func WatchDeployEvents(
	ctx context.Context,
	client kubernetes.Interface,
	namespace, releasePrefix string,
) (<-chan DeployEvent, error)

WatchDeployEvents watches Kubernetes events in namespace and returns a channel of DeployEvent values filtered to resources whose name starts with releasePrefix. The channel is closed when ctx is canceled.

It lists existing events to obtain the initial resourceVersion, then uses a RetryWatcher for automatic reconnection on transient API failures. The background goroutine stops when ctx is canceled; the returned channel is closed once the goroutine exits.

Types

type APIRequirement added in v0.3.0 

type APIRequirement struct {
	// GroupVersions holds the acceptable group/version strings (e.g.
	// ["autoscaling/v2", "autoscaling/v2beta2"]). Any single match satisfies
	// the requirement.
	GroupVersions []string
	// Reason is a human-readable explanation shown when the requirement is
	// not met, e.g. `required by component "web" (autoscaling enabled)`.
	Reason string
}

APIRequirement describes a cluster API group/version that a spec feature needs. At least one of the GroupVersions must be present on the cluster.

func RequiredAPIs added in v0.7.0 

func RequiredAPIs(manifest *spec.Spec, environment string, resolved *spec.ResolvedSpec) []APIRequirement

RequiredAPIs derives the Kubernetes API group/version requirements for components deployed in the target environment, including cert-manager (TLS mode) via the resolved spec and prometheus-operator when metrics are enabled.

type Client 

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

Client wraps Kubernetes operations for Deployah resources.

func NewClient 

func NewClient(k8sClient kubernetes.Interface, namespace string) *Client

NewClient creates a new Kubernetes client for Deployah operations.

func (*Client) GetAvailableComponents 

func (c *Client) GetAvailableComponents(ctx context.Context, projectName string) ([]string, error)

GetAvailableComponents lists component names from running pods for a project.

func (*Client) GetAvailableEnvironments 

func (c *Client) GetAvailableEnvironments(ctx context.Context, projectName, componentName string) ([]string, error)

GetAvailableEnvironments lists environment names from running pods for a project and component.

func (*Client) GetKubernetesClient 

func (c *Client) GetKubernetesClient() kubernetes.Interface

GetKubernetesClient returns the underlying Kubernetes client.

func (*Client) GetNamespace 

func (c *Client) GetNamespace() string

GetNamespace returns the namespace this client operates in.

func (*Client) GetPodInfo 

func (c *Client) GetPodInfo(ctx context.Context, podName string) (*PodInfo, error)

GetPodInfo retrieves detailed information about a specific pod

func (*Client) GetPodStatus 

func (c *Client) GetPodStatus(ctx context.Context, releaseName string) (int, int, string, error)

GetPodStatus retrieves pod status information for a release.

func (*Client) GetRunningPods 

func (c *Client) GetRunningPods(ctx context.Context, project, component, environment string) ([]PodInfo, error)

GetRunningPods lists running pods for a project, component, and environment.

func (*Client) ValidateComponentExists 

func (c *Client) ValidateComponentExists(ctx context.Context, projectName, componentName string) error

ValidateComponentExists reports whether a component has running pods.

func (*Client) ValidatePodExists 

func (c *Client) ValidatePodExists(ctx context.Context, podName string) error

ValidatePodExists checks if a pod with the given name exists

type DeployEvent added in v0.3.0 

type DeployEvent struct {
	// UID is the Kubernetes object UID of the source event.
	UID types.UID
	// Type is the event severity, either "Normal" or "Warning".
	Type string
	// Reason is the short CamelCase reason string
	// (Scheduled, Pulled, BackOff, etc.).
	Reason string
	// Message is the human-readable event description.
	Message string
	// Object is the formatted involvedObject reference,
	// for example "pod/api-7d9abc" or "replicaset/api-5f123".
	Object string
	// Count is the number of times this event has occurred.
	Count int32
	// Timestamp is the last time the event was observed.
	Timestamp time.Time
}

DeployEvent carries a single Kubernetes event relevant to a deploy. It is a thin translation of a Kubernetes Event object with only the fields the deploy watcher needs for rendering and deduplication.

type PodInfo 

type PodInfo struct {
	// Name is the pod name in the cluster.
	Name string
	// Namespace is the pod namespace.
	Namespace string
	// Containers lists container names in the pod.
	Containers []string
	// Status is the pod phase or ready summary string.
	Status string
}

PodInfo summarizes a pod returned by Client.GetRunningPods and related queries.

type SelectorBuilder 

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

SelectorBuilder helps build Kubernetes label selectors for Deployah resources

func NewSelectorBuilder 

func NewSelectorBuilder() *SelectorBuilder

NewSelectorBuilder constructs an empty SelectorBuilder.

func (*SelectorBuilder) Build 

func (sb *SelectorBuilder) Build() string

Build returns the final label selector string.

func (*SelectorBuilder) WithComponent 

func (sb *SelectorBuilder) WithComponent(component string) (*SelectorBuilder, error)

WithComponent adds a component label requirement to the selector

func (*SelectorBuilder) WithEnvironment 

func (sb *SelectorBuilder) WithEnvironment(environment string) (*SelectorBuilder, error)

WithEnvironment adds an environment label requirement to the selector. The name is normalized to its label-safe form so wildcard environments (review/pr-42) match what deploy wrote.

func (*SelectorBuilder) WithProject 

func (sb *SelectorBuilder) WithProject(project string) (*SelectorBuilder, error)

WithProject adds a project label requirement to the selector

type TaskJobOptions added in v0.8.0 

type TaskJobOptions struct {
	Project     string
	Environment string
	Namespace   string
	TaskName    string
	Task        spec.Task
	Count       int
	Parallelism int
	Profile     *spec.PlatformProfile
}

TaskJobOptions controls a CLI-created Job.

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.