kubernetes

package
v4.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 13, 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