kubernetes

package
v1.4.25 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package kubernetes provides bounded, read-only access to Kubernetes APIs.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidEndpoint       = errors.New("kubernetes: invalid endpoint")
	ErrUnauthorized          = errors.New("kubernetes: unauthorized")
	ErrForbidden             = errors.New("kubernetes: forbidden")
	ErrNotFound              = errors.New("kubernetes: not found")
	ErrResponseTooLarge      = errors.New("kubernetes: response too large")
	ErrRedirect              = errors.New("kubernetes: redirect refused")
	ErrInvalidArguments      = errors.New("kubernetes: invalid arguments")
	ErrOperationBudget       = errors.New("kubernetes: operation budget exhausted")
	ErrCredentialUnavailable = errors.New("kubernetes: credential unavailable")
)

Functions

func DecodeCAData 

func DecodeCAData(value string) ([]byte, error)

DecodeCAData decodes bounded base64 PEM data for direct connector configuration.

func ParseQuantity 

func ParseQuantity(value string) (*big.Rat, error)

ParseQuantity converts a Kubernetes quantity to an exact rational value.

Types

type AuthOptions 

type AuthOptions struct {
	Mode, Endpoint, CAFile, CAData, ServerName, Token, TokenFile              string
	CertificateFile, KeyFile, CertificateData, KeyData                        string
	KubeconfigPath, KubeconfigContext                                         string
	EKSClusterName, EKSRegion, EKSRoleARN, EKSProfile                         string
	AKSCredentialMode, AKSServerID, AKSTenantID, AKSClientID, AKSClientSecret string
	AKSFederatedTokenFile, AKSEnvironment, GKECredentialsFile                 string
}

AuthOptions contains the supported, provider-neutral Kubernetes auth inputs.

type Client 

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

Client is a read-only, bounded Kubernetes API transport.

func NewClient 

func NewClient(config Config) (*Client, error)

NewClient validates transport policy and constructs a read-only API client.

func (*Client) GetJSON 

func (client *Client) GetJSON(ctx context.Context, apiPath string, output any) error

GetJSON performs one authenticated, bounded GET and decodes its JSON body.

type Condition 

type Condition struct {
	Type   string `json:"type"`
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

type Config 

type Config struct {
	Endpoint             string
	TokenFile            string
	CAFile               string
	CAData               []byte
	ServerName           string
	Credentials          CredentialSource
	Timeout              time.Duration
	MaxBodyBytes         int64
	AllowLoopbackHTTP    bool
	AllowLoopback        bool
	AllowPrivateNetworks bool
	EndpointCIDRs        []string
}

Config defines one Kubernetes API connection. Credentials are read from TokenFile for every request so projected service-account rotation is honored.

func ResolveAuthentication 

func ResolveAuthentication(options AuthOptions) (Config, error)

ResolveAuthentication resolves one explicit auth mode into the existing stdlib HTTP client configuration.

type CredentialSource 

type CredentialSource interface {
	Authorization(context.Context) (string, error)
	ClientCertificate(*tls.CertificateRequestInfo) (*tls.Certificate, error)
}

CredentialSource supplies request and TLS credentials without exposing them through connector configuration or status DTOs.

type Discovery 

type Discovery struct {
	ObservedAt time.Time            `json:"observed_at"`
	Resources  []ResourceDefinition `json:"resources"`
	Partial    []PartialFailure     `json:"partial_failures,omitempty"`
}

Discovery is a bounded cluster-driven API registry.

type ErrorDetail 

type ErrorDetail struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Action    string `json:"action"`
	Retryable bool   `json:"retryable"`
}

ErrorDetail is a bounded operator-facing explanation of a Kubernetes error. It never includes provider responses, credentials, endpoints, or raw causes.

func DiagnoseError 

func DiagnoseError(err error) ErrorDetail

DiagnoseError classifies connector failures without exposing their raw cause.

type EventOptions 

type EventOptions struct {
	Namespace string
	Type      string
	Kind      string
	Name      string
	UID       string
	Continue  string
	Limit     int
}

EventOptions is the server-owned object event filter contract.

type ListOptions 

type ListOptions struct {
	ResourceID string
	Namespace  string
	Labels     string
	Fields     string
	Continue   string
	Limit      int
}

type MetricsSourceStatus 

type MetricsSourceStatus struct {
	Availability string     `json:"availability"`
	Fresh        bool       `json:"fresh"`
	Total        int        `json:"total"`
	CPU          string     `json:"cpu,omitempty"`
	Memory       string     `json:"memory,omitempty"`
	ObservedAt   *time.Time `json:"observed_at,omitempty"`
}

MetricsSourceStatus summarizes one Metrics API source before display caps.

type ObjectRef 

type ObjectRef struct {
	APIVersion string `json:"api_version,omitempty"`
	Kind       string `json:"kind"`
	Namespace  string `json:"namespace,omitempty"`
	Name       string `json:"name"`
	UID        string `json:"uid,omitempty"`
}

type Overview 

type Overview struct {
	Connector         string           `json:"connector"`
	ClusterID         string           `json:"cluster_id"`
	ObservedAt        time.Time        `json:"observed_at"`
	Nodes             int              `json:"nodes"`
	ReadyNodes        int              `json:"ready_nodes"`
	Pods              int              `json:"pods"`
	RunningPods       int              `json:"running_pods"`
	Namespaces        int              `json:"namespaces"`
	ActiveNamespaces  int              `json:"active_namespaces"`
	Workloads         int              `json:"workloads"`
	Warnings          int              `json:"warnings"`
	RequestedCPU      string           `json:"requested_cpu,omitempty"`
	LimitedCPU        string           `json:"limited_cpu,omitempty"`
	AllocatableCPU    string           `json:"allocatable_cpu,omitempty"`
	RequestedMemory   string           `json:"requested_memory,omitempty"`
	LimitedMemory     string           `json:"limited_memory,omitempty"`
	AllocatableMemory string           `json:"allocatable_memory,omitempty"`
	UsageCPU          string           `json:"usage_cpu,omitempty"`
	UsageMemory       string           `json:"usage_memory,omitempty"`
	UsageSource       string           `json:"usage_source"`
	MetricsStatus     string           `json:"metrics_status"`
	MetricsObservedAt *time.Time       `json:"metrics_observed_at,omitempty"`
	MetricsFresh      bool             `json:"metrics_fresh"`
	Truncated         bool             `json:"truncated"`
	Omitted           []string         `json:"omitted_categories,omitempty"`
	Partial           []PartialFailure `json:"partial_failures,omitempty"`
}

type PartialFailure 

type PartialFailure struct {
	ResourceID   string `json:"resource_id,omitempty"`
	Scope        string `json:"scope,omitempty"`
	GroupVersion string `json:"group_version,omitempty"`
	Class        string `json:"class"`
}

PartialFailure is a bounded failure class with no raw Kubernetes Status text.

type PodLogs 

type PodLogs struct {
	ClusterID    string `json:"cluster_id"`
	Namespace    string `json:"namespace"`
	Pod          string `json:"pod"`
	Container    string `json:"container"`
	Previous     bool   `json:"previous"`
	SinceSeconds int    `json:"since_seconds"`
	TailLines    int    `json:"tail_lines"`
	Text         string `json:"text"`
	Truncated    bool   `json:"truncated"`
}

type ProjectedResource 

type ProjectedResource struct {
	ResourceID          string            `json:"resource_id"`
	APIVersion          string            `json:"api_version"`
	Kind                string            `json:"kind"`
	Namespace           string            `json:"namespace,omitempty"`
	Name                string            `json:"name"`
	UID                 string            `json:"uid,omitempty"`
	Labels              map[string]string `json:"labels,omitempty"`
	Owners              []ObjectRef       `json:"owners,omitempty"`
	Summary             map[string]any    `json:"summary,omitempty"`
	Conditions          []Condition       `json:"conditions,omitempty"`
	ProjectionTruncated []string          `json:"projection_truncated,omitempty"`
}

ProjectedResource is a bounded safe view, never an arbitrary raw object.

type ResourceDefinition 

type ResourceDefinition struct {
	ID         string   `json:"resource_id"`
	Group      string   `json:"group,omitempty"`
	Version    string   `json:"version"`
	Resource   string   `json:"resource"`
	Kind       string   `json:"kind"`
	Namespaced bool     `json:"namespaced"`
	Aliases    []string `json:"aliases,omitempty"`
	Verbs      []string `json:"verbs,omitempty"`
	Available  bool     `json:"available"`
	Reason     string   `json:"reason,omitempty"`
}

ResourceDefinition is a server-owned canonical mapping to one API resource.

type ResourceDescription 

type ResourceDescription struct {
	Resource    ProjectedResource   `json:"resource"`
	Related     []ObjectRef         `json:"related_resources,omitempty"`
	Events      []ProjectedResource `json:"events,omitempty"`
	Usage       *ResourceUsage      `json:"usage,omitempty"`
	UsageStatus string              `json:"usage_status"`
	Truncated   bool                `json:"truncated"`
	Omitted     []string            `json:"omitted_categories,omitempty"`
	Partial     []PartialFailure    `json:"partial_failures,omitempty"`
}

ResourceDescription adds deterministic diagnostic evidence to one resource.

type ResourcePage 

type ResourcePage struct {
	Items            []ProjectedResource `json:"items"`
	Continue         string              `json:"continue,omitempty"`
	Truncated        bool                `json:"truncated"`
	EncodedTruncated bool                `json:"encoded_truncated"`
	Omitted          []string            `json:"omitted_categories,omitempty"`
	Partial          []PartialFailure    `json:"partial_failures,omitempty"`
}

type ResourceUsage 

type ResourceUsage struct {
	Kind      string    `json:"kind"`
	Namespace string    `json:"namespace,omitempty"`
	Name      string    `json:"name"`
	Timestamp time.Time `json:"timestamp,omitempty"`
	Window    string    `json:"window,omitempty"`
	CPU       string    `json:"cpu,omitempty"`
	Memory    string    `json:"memory,omitempty"`
}

ResourceUsage is one bounded exact pod or node Metrics API sample.

type Scope 

type Scope struct {
	OrgID        string `json:"org_id,omitempty"`
	ClusterID    string `json:"cluster_id"`
	CredentialID string `json:"-"`
}

Scope isolates cached discovery and reads by organization, cluster, and credential.

type Scrubber 

type Scrubber interface{ Scrub(string) string }

Scrubber removes sensitive substrings before text leaves the service.

type SearchOptions 

type SearchOptions struct {
	Query        string
	Namespace    string
	Category     string
	Labels       string
	Fields       string
	PerKindLimit int
	TotalLimit   int
}

SearchOptions bounds a true cross-kind name search.

type SearchResult 

type SearchResult struct {
	Items         []ProjectedResource `json:"items"`
	Continuations map[string]string   `json:"continuations,omitempty"`
	Requests      int                 `json:"requests"`
	RequestBudget int                 `json:"request_budget"`
	Truncated     bool                `json:"truncated"`
	Omitted       []string            `json:"omitted_categories,omitempty"`
	Partial       []PartialFailure    `json:"partial_failures,omitempty"`
}

SearchResult contains ranked projected matches and explicit incomplete evidence.

type Service 

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

Service owns all Kubernetes path construction, decoding, projection, and relationships.

func NewService 

func NewService(client *Client, scope Scope, discoveryTTL time.Duration) *Service

NewService constructs a scoped read-only Kubernetes application service.

func (*Service) Describe 

func (service *Service) Describe(ctx context.Context, resourceID, namespace, name string) (ResourceDescription, error)

Describe returns one resource with deterministic owners and object-scoped events.

func (*Service) Discover 

func (service *Service) Discover(ctx context.Context) (Discovery, error)

Discover builds a preferred-version resource registry with partial failures.

func (*Service) Get 

func (service *Service) Get(ctx context.Context, resourceID, namespace, name string) (ProjectedResource, error)

Get reads one discovered resource by canonical ID and name.

func (*Service) GetWorkload 

func (service *Service) GetWorkload(ctx context.Context, namespace, kind, name string) (WorkloadDetail, error)

GetWorkload returns bounded workload state plus deterministic related resources.

func (*Service) InvalidateDiscovery 

func (service *Service) InvalidateDiscovery()

InvalidateDiscovery expires only this service's scoped discovery generation.

func (*Service) List 

func (service *Service) List(ctx context.Context, options ListOptions) (ResourcePage, error)

List reads one discovered resource page and safely projects every item.

func (*Service) ListEvents 

func (service *Service) ListEvents(ctx context.Context, options EventOptions) (ResourcePage, error)

ListEvents lists events using server-authored field selectors only.

func (*Service) ListWorkloads 

func (service *Service) ListWorkloads(ctx context.Context, namespace, kind string, limit int) (WorkloadPage, error)

ListWorkloads aggregates every supported workload kind or one validated kind.

func (*Service) Overview 

func (service *Service) Overview(ctx context.Context) (Overview, error)

Overview returns bounded health counts and explicit partial failures.

func (*Service) PodLogs 

func (service *Service) PodLogs(ctx context.Context, namespace, pod, container string, previous bool, sinceSeconds, tailLines int) (PodLogs, error)

PodLogs reads one bounded pod log stream, optionally selecting a container.

func (*Service) Scope 

func (service *Service) Scope() Scope

Scope returns the immutable cache and request identity of this service.

func (*Service) Scoped 

func (service *Service) Scoped(scope Scope) *Service

Scoped returns a service for another org/cluster/credential that shares the transport and keyed discovery cache with the original service.

func (*Service) Search 

func (service *Service) Search(ctx context.Context, options SearchOptions) (SearchResult, error)

Search searches names across discovered readable kinds with per-kind and total budgets.

func (*Service) SetScrubber 

func (service *Service) SetScrubber(scrubber Scrubber)

SetScrubber installs the shared model/API text redactor.

func (*Service) Usage 

func (service *Service) Usage(ctx context.Context, namespace string, limit int) (Usage, error)

Usage returns bounded pod and node Metrics API samples with freshness metadata.

type ServiceRegistry 

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

ServiceRegistry resolves one shared service instance per org, cluster, and credential.

func NewServiceRegistry 

func NewServiceRegistry(base *Service) *ServiceRegistry

func (*ServiceRegistry) Resolve 

func (registry *ServiceRegistry) Resolve(scope Scope) *Service

func (*ServiceRegistry) ResolveOrg 

func (registry *ServiceRegistry) ResolveOrg(orgID string) *Service

ResolveOrg inherits the configured cluster and credential while changing org scope.

type Usage 

type Usage struct {
	ObservedAt   time.Time           `json:"observed_at"`
	Availability string              `json:"availability"`
	Fresh        bool                `json:"fresh"`
	PodMetrics   MetricsSourceStatus `json:"pod_metrics"`
	NodeMetrics  MetricsSourceStatus `json:"node_metrics"`
	Pods         []ResourceUsage     `json:"pods,omitempty"`
	Nodes        []ResourceUsage     `json:"nodes,omitempty"`
	Truncated    bool                `json:"truncated"`
	Omitted      []string            `json:"omitted_categories,omitempty"`
	Partial      []PartialFailure    `json:"partial_failures,omitempty"`
}

Usage reports Metrics API availability separately from an empty metric set.

type WorkloadContainer 

type WorkloadContainer struct {
	Name     string            `json:"name"`
	Image    string            `json:"image,omitempty"`
	Probes   []string          `json:"probes,omitempty"`
	Requests map[string]string `json:"requests,omitempty"`
	Limits   map[string]string `json:"limits,omitempty"`
}

WorkloadContainer is the bounded operational view of one workload container.

type WorkloadDetail 

type WorkloadDetail struct {
	ResourceID         string              `json:"resource_id"`
	Kind               string              `json:"kind"`
	Namespace          string              `json:"namespace,omitempty"`
	Name               string              `json:"name"`
	Desired            *int64              `json:"desired,omitempty"`
	Current            *int64              `json:"current,omitempty"`
	Ready              *int64              `json:"ready,omitempty"`
	Available          *int64              `json:"available,omitempty"`
	Unavailable        *int64              `json:"unavailable,omitempty"`
	Succeeded          *int64              `json:"succeeded,omitempty"`
	Failed             *int64              `json:"failed,omitempty"`
	Active             *int64              `json:"active,omitempty"`
	Generation         *int64              `json:"generation,omitempty"`
	ObservedGeneration *int64              `json:"observed_generation,omitempty"`
	UpdateStrategy     string              `json:"update_strategy,omitempty"`
	Conditions         []Condition         `json:"conditions,omitempty"`
	Containers         []WorkloadContainer `json:"containers,omitempty"`
	Pods               []WorkloadPod       `json:"pods,omitempty"`
	Nodes              []string            `json:"nodes,omitempty"`
	NodeSelector       map[string]string   `json:"node_selector,omitempty"`
	Affinity           []string            `json:"affinity,omitempty"`
	TopologySpread     []string            `json:"topology_spread,omitempty"`
	TerminationGrace   *int64              `json:"termination_grace_seconds,omitempty"`
	HPAs               []ObjectRef         `json:"hpas,omitempty"`
	PDBs               []ObjectRef         `json:"pdbs,omitempty"`
	Usage              []ResourceUsage     `json:"usage,omitempty"`
	Truncated          bool                `json:"truncated"`
	Omitted            []string            `json:"omitted_categories,omitempty"`
	Partial            []PartialFailure    `json:"partial_failures,omitempty"`
}

WorkloadDetail is a dedicated bounded SRE view, not a generic resource projection.

type WorkloadPage 

type WorkloadPage struct {
	Items     []ProjectedResource `json:"items"`
	Truncated bool                `json:"truncated"`
	Omitted   []string            `json:"omitted_categories,omitempty"`
	Partial   []PartialFailure    `json:"partial_failures,omitempty"`
}

WorkloadPage aggregates the supported workload kinds.

type WorkloadPod 

type WorkloadPod struct {
	Name         string `json:"name"`
	Phase        string `json:"phase,omitempty"`
	Node         string `json:"node,omitempty"`
	RestartCount int64  `json:"restart_count"`
}

WorkloadPod captures status and placement for one related pod.

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.