Help us shape the future of Go! Take the 2026 Go Developer Survey

kubernetes

package
v4.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 22, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package kubernetes preserves the released path for the deliberately narrow Kubernetes integration.

New borrows a namespace-scoped apps/v1 Deployment client, with autoscaling/v1 scale access. The pinned Kubernetes SDK owns transport; providers must honor scope, pagination and context. This package creates no watch, cluster client, HPA/KEDA controller or shutdown loop. It preserves released type identities through the canonical adapter aliases.

Deprecated: use github.com/faustbrian/go-queue-control-plane/v4/adapters/kubernetes.

Index

Constants

View Source
const (
	// MaxPageSize bounds one Kubernetes Deployment request.
	MaxPageSize int64 = 500
	// MaxContinueTokenBytes bounds the opaque Kubernetes pagination token.
	MaxContinueTokenBytes = 4_096
)

Variables

View Source
var (
	// ErrInvalidConfiguration reports an unscoped Kubernetes adapter.
	ErrInvalidConfiguration = errors.New("kubernetes: invalid configuration")
	// ErrInvalidWorkload reports a malformed Kubernetes Deployment name.
	ErrInvalidWorkload = errors.New("kubernetes: invalid workload")
	// ErrInvalidPage reports an unbounded Deployment list request.
	ErrInvalidPage = errors.New("kubernetes: invalid page")
	// ErrInvalidResponse reports malformed or cross-namespace Kubernetes state.
	ErrInvalidResponse = errors.New("kubernetes: invalid response")
)
View Source
var (
	// ErrInvalidDispatcher reports a missing tenant-to-cluster resolver.
	ErrInvalidDispatcher = errors.New("kubernetes: invalid dispatcher")
	// ErrUnsupportedCommand reports a non-scaling command at this boundary.
	ErrUnsupportedCommand = errors.New("kubernetes: unsupported command")
)
View Source
var (
	// ErrInvalidResolver reports an empty or malformed tenant mapping.
	ErrInvalidResolver = errors.New("kubernetes: invalid tenant resolver")
	// ErrTenantNotConfigured reports a tenant without Kubernetes visibility.
	ErrTenantNotConfigured = errors.New("kubernetes: tenant not configured")
)
View Source
var ErrInvalidTenantDocument = errors.New("kubernetes: invalid tenant document")

ErrInvalidTenantDocument is a stable Kubernetes mapping error.

Functions

This section is empty.

Types

type Adapter

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

Adapter reports Deployment status from one configured namespace.

func New

func New(namespace string, client DeploymentClient) (*Adapter, error)

New creates an adapter scoped to namespace.

func (*Adapter) Get

func (adapter *Adapter) Get(ctx context.Context, name string) (Status, error)

Get returns the current status of one Deployment.

func (*Adapter) List

func (adapter *Adapter) List(ctx context.Context, limit int64, continueToken string) (Page, error)

List sends one bounded server-pagination request and projects its returned Deployments after namespace/name validation. It does not independently cap already materialized item counts or returned continuation metadata; custom clients must honor the requested bound and scope.

func (*Adapter) Scale

func (adapter *Adapter) Scale(ctx context.Context, name string, replicas uint32) (ScaleResult, error)

Scale updates only the Deployment scale subresource. Authorization and scale-to-zero confirmation are enforced by the control service before this adapter is called. The borrowed provider must honor workload/namespace identity; a successful API update is not proof of replica convergence.

type DeploymentClient

type DeploymentClient interface {
	// Get reads the named Deployment in the client's configured namespace
	// honoring ctx.
	Get(context.Context, string, metav1.GetOptions) (*appsv1.Deployment, error)
	// List must honor namespace and server pagination limits; Adapter does not
	// cap an already materialized response.
	List(context.Context, metav1.ListOptions) (*appsv1.DeploymentList, error)
	// GetScale reads the named autoscaling/v1 scale subresource honoring ctx.
	GetScale(context.Context, string, metav1.GetOptions) (*autoscalingv1.Scale, error)
	// UpdateScale updates only the borrowed scale subresource in the configured
	// namespace; failure may follow remote acceptance.
	UpdateScale(context.Context, string, *autoscalingv1.Scale, metav1.UpdateOptions) (*autoscalingv1.Scale, error)
}

DeploymentClient is the deliberately restricted part of a namespace-scoped Kubernetes Deployment client used by the control plane.

type DeploymentFactory

type DeploymentFactory func(namespace string) DeploymentClient

DeploymentFactory returns the restricted Deployment client for one namespace.

type Page

type Page struct {
	// Items is a newly projected status slice; the client must honor the
	// requested page bound.
	Items []Status `json:"items"`
	// Continue is provider-supplied opaque pagination state, not authorization.
	Continue string `json:"continue,omitempty"`
	// Remaining is provider-reported remaining item count; zero also represents
	// absent metadata.
	Remaining int64 `json:"remaining"`
}

Page is one bounded page of Deployment status.

type ScaleDispatcher

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

ScaleDispatcher sends validated scaling commands to a tenant-scoped Kubernetes adapter.

func NewScaleDispatcher

func NewScaleDispatcher(resolver TenantResolver) (*ScaleDispatcher, error)

NewScaleDispatcher creates a scale-only Kubernetes command dispatcher.

func (*ScaleDispatcher) Dispatch

func (dispatcher *ScaleDispatcher) Dispatch(ctx context.Context, command controlplane.Command) error

Dispatch resolves the tenant and updates only the workload scale subresource.

type ScaleResult

type ScaleResult struct {
	// Namespace is configured namespace attribution; the provider must honor
	// that scope.
	Namespace string `json:"namespace"`
	// Name is the requested workload attribution.
	Name string `json:"name"`
	// DesiredReplicas is the update response's desired replica count, not
	// observed convergence.
	DesiredReplicas int32 `json:"desired_replicas"`
	// CurrentReplicas is the update response's observed replica count.
	CurrentReplicas int32 `json:"current_replicas"`
	// ResourceVersion is the update response's opaque resource version.
	ResourceVersion string `json:"resource_version"`
}

ScaleResult is the Kubernetes acknowledgement of an authorized replica update.

type Scaler

type Scaler interface {
	// Scale updates the named workload replicas honoring ctx;
	// authorization/confirmation must happen before this borrowed provider
	// call.
	Scale(context.Context, string, uint32) (ScaleResult, error)
}

Scaler is the scale-only workload mutation exposed to the dispatcher.

type StaticTenantResolver

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

StaticTenantResolver stores an immutable tenant-to-namespace mapping.

func LoadTenantResolver

func LoadTenantResolver(
	reader io.Reader,
	maxBytes int64,
	factory DeploymentFactory,
) (*StaticTenantResolver, error)

LoadTenantResolver builds immutable namespace-scoped adapters from one strict, bounded tenant document.

func NewStaticTenantResolver

func NewStaticTenantResolver(configured map[string]TenantAdapter) (*StaticTenantResolver, error)

NewStaticTenantResolver copies a fixed tenant adapter mapping.

func (*StaticTenantResolver) ListTenantWorkloads

func (resolver *StaticTenantResolver) ListTenantWorkloads(
	ctx context.Context,
	tenant string,
	limit int64,
	continueToken string,
) (Page, error)

ListTenantWorkloads returns a bounded page through the preconfigured tenant boundary.

func (*StaticTenantResolver) ResolveTenant

func (resolver *StaticTenantResolver) ResolveTenant(_ context.Context, tenant string) (Scaler, error)

ResolveTenant returns the preconfigured scale-only tenant boundary.

type Status

type Status struct {
	// Namespace is the validated configured namespace of the reported
	// Deployment.
	Namespace string `json:"namespace"`
	// Name is the validated DNS-compatible Deployment name.
	Name string `json:"name"`
	// Generation is the API object's desired configuration generation.
	Generation int64 `json:"generation"`
	// ObservedGeneration is the controller's last observed generation, not
	// necessarily Generation.
	ObservedGeneration int64 `json:"observed_generation"`
	// DesiredReplicas is the reported spec replica count; absent Spec.Replicas
	// projects to zero.
	DesiredReplicas int32 `json:"desired_replicas"`
	// UpdatedReplicas is the reported updated replica count.
	UpdatedReplicas int32 `json:"updated_replicas"`
	// ReadyReplicas is the reported ready replica count.
	ReadyReplicas int32 `json:"ready_replicas"`
	// AvailableReplicas is the reported available replica count.
	AvailableReplicas int32 `json:"available_replicas"`
	// UnavailableReplicas is the reported unavailable replica count.
	UnavailableReplicas int32 `json:"unavailable_replicas"`
}

Status is the bounded Deployment state presented by the control plane.

type TenantAdapter

type TenantAdapter interface {
	Scaler
	// List returns a page honoring requested namespace, limit and cursor; the
	// resolver borrows the adapter and does not close it.
	List(context.Context, int64, string) (Page, error)
}

TenantAdapter is the complete bounded Kubernetes surface for one tenant.

type TenantResolver

type TenantResolver interface {
	// ResolveTenant returns the borrowed namespace-scoped scaler for a tenant;
	// errors refuse dispatch.
	ResolveTenant(context.Context, string) (Scaler, error)
}

TenantResolver maps a tenant to its namespace-scoped Kubernetes adapter.

Jump to

Keyboard shortcuts

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