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

kubernetes

package
v1.4.33 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 61 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source
const (
	MaxLogStreamLineBytes  = 16 << 10
	MaxLogStreamBytes      = 16 << 20
	MaxLogStreamDuration   = 30 * time.Minute
	LogStreamHeartbeat     = 15 * time.Second
	LogStreamIdleTimeout   = 2 * time.Minute
	MaxPreviousLogDuration = 30 * time.Second
	MaxOrgLogStreams       = 4
	MaxProcessLogStreams   = 20
	MaxProcessLogReads     = 200

	// MaxStreamRequestQueryBytes bounds one log stream request's query. A resume
	// no longer has to carry a whole workload's state, so a request that needs
	// more is refused with an explicit answer instead of being left to an
	// intermediary's header limit.
	MaxStreamRequestQueryBytes = 2 << 10
)
View Source
const (
	MaxWorkloadLogPods    = 20
	MaxWorkloadLogSources = 40
)
View Source
const MaxLogClockSkew = 2 * time.Minute

MaxLogClockSkew bounds how far ahead of this server a log timestamp may be before it is refused. A container's clock runs a little ahead of the server's often enough that a resume a few seconds in the future is a clock difference, not a request for logs that cannot exist yet; anything further ahead is.

View Source
const MaxOrgIndexStreams = 8
View Source
const MaxProcessIndexStreams = 64

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")
	ErrGraphIncomplete       = errors.New("kubernetes: complete graph could not be verified")
	ErrCompleteGraphLimit    = errors.New("kubernetes: complete graph safety limit exceeded")
	ErrCredentialUnavailable = errors.New("kubernetes: credential unavailable")
)
View Source
var ErrClusterNotFound = errors.New("kubernetes: cluster not found")
View Source
var ErrClusterRequired = errors.New("kubernetes: cluster is required")
View Source
var ErrClusterUnavailable = errors.New("kubernetes: cluster unavailable")
View Source
var ErrConnectorCredentialUnresolved = errors.New("kubernetes: connector credential cannot be resolved")

ErrConnectorCredentialUnresolved reports a connector that is configured but whose credential cannot be resolved right now — the cluster is known, its published data is still on disk, and only the identity that reads it is gone. Its cause stays attached for classification and never renders: the message a caller sees names no identity, path, or endpoint.

View Source
var ErrConnectorNotConfigured = errors.New("kubernetes: connector not configured")

ErrConnectorNotConfigured reports that this deployment has no Kubernetes connector at all. It is one half of a pair: the other half is ErrConnectorCredentialUnresolved, and answering one with the other is how a surface renders a setup card over a cluster that published data yesterday.

View Source
var ErrIncompleteInventory = errors.New("kubernetes: incomplete inventory continuation")
View Source
var ErrIndexStreamBusy = errors.New("kubernetes: index stream concurrency limit reached")
View Source
var ErrInventoryNotReady = errors.New("kubernetes: inventory not ready")

ErrInventoryNotReady reports that a read needs an inventory kind that is not yet fresh and complete. It is a retryable state of Versus itself, not a permission problem: reporting it as cluster_permission_denied sends an operator to change RBAC that was never the cause.

View Source
var ErrLogStreamBusy = errors.New("kubernetes: log stream concurrency limit reached")
View Source
var ErrRequestTooLarge = errors.New("kubernetes: request too large")

ErrRequestTooLarge reports a request this server refuses to parse because it exceeds the surface's own bound. The answer is explicit and bounded, so an oversized request can never disappear into an intermediary's header limit.

View Source
var ErrTimelineContention = errors.New("kubernetes: timeline storage contention")

Functions

func ClusterHealth added in v1.4.31

func ClusterHealth(overview Overview) string

func DecodeCAData

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

DecodeCAData decodes bounded base64 PEM data for direct connector configuration.

func InventoryRetryAfter added in v1.4.32

func InventoryRetryAfter(err error) time.Duration

InventoryRetryAfter returns the bounded retry hint for a not-ready answer, falling back to the default when the error carries none.

func ParseQuantity

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

ParseQuantity converts a Kubernetes quantity to an exact rational value.

func WithLogStreamAuthorization added in v1.4.32

func WithLogStreamAuthorization(ctx context.Context, check func(context.Context) error) context.Context

WithLogStreamAuthorization installs a request-scoped access revalidator. The callback must honor cancellation and return only a safe authorization error. It is evaluated before admission and periodically even on idle reads.

Types

type AgentDetected added in v1.4.32

type AgentDetected struct {
	MetricsServer bool          `json:"metrics_server"`
	Traces        *TraceBackend `json:"traces"`
	Workloads     int           `json:"workloads"`
	Namespaces    int           `json:"namespaces"`
}

func DetectAgentBackends added in v1.4.32

func DetectAgentBackends(records []kubeindex.Record) AgentDetected

type AgentSettings added in v1.4.32

type AgentSettings struct {
	breaklogs.Settings
	Sources             []breaklogs.Source `json:"sources"`
	Detected            AgentDetected      `json:"detected"`
	LinkedSourceMissing bool               `json:"linked_source_missing"`
	CanWrite            bool               `json:"can_write"`
}

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 BreakLogContainer added in v1.4.32

type BreakLogContainer struct {
	Name string `json:"name"`
	Init bool   `json:"init,omitempty"`
	Main bool   `json:"main,omitempty"`
}

BreakLogContainer lists one container of the break's pods so a viewer can choose which container's logs to read.

type BreakLogCounts added in v1.4.32

type BreakLogCounts struct {
	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
	All      int `json:"all"`
}

type BreakLogLine added in v1.4.32

type BreakLogLine struct {
	Pod       string    `json:"pod,omitempty"`
	At        time.Time `json:"at"`
	PodUID    string    `json:"pod_uid"`
	Container string    `json:"container"`
	Init      bool      `json:"init"`
	Slot      string    `json:"slot"`
	Level     string    `json:"level"`
	Text      string    `json:"text"`
	Source    string    `json:"source"`
}

type BreakLogMarker added in v1.4.32

type BreakLogMarker struct {
	Type  string    `json:"type"`
	At    time.Time `json:"at"`
	Label string    `json:"label"`
}

type BreakLogPage added in v1.4.32

type BreakLogPage struct {
	Window   BreakLogWindow     `json:"window"`
	Pods     []BreakLogPod      `json:"pods"`
	Lines    []BreakLogLine     `json:"lines"`
	Markers  []BreakLogMarker   `json:"markers"`
	Counts   BreakLogCounts     `json:"counts"`
	Rate     []BreakLogRate     `json:"rate"`
	Patterns []BreakLogPattern  `json:"patterns"`
	Sources  []BreakLogSource   `json:"sources"`
	Coverage breaklogs.Coverage `json:"coverage"`
	Next     string             `json:"next,omitempty"`
	// Container is the applied filter: a container name, or "*" for all.
	Container     string              `json:"container"`
	MainContainer string              `json:"main_container,omitempty"`
	Containers    []BreakLogContainer `json:"containers"`
	PatternInput  []BreakLogLine      `json:"-"`
}

type BreakLogPattern added in v1.4.32

type BreakLogPattern struct {
	Template string `json:"template"`
	Level    string `json:"level"`
	Count    int    `json:"count"`
}

type BreakLogPod added in v1.4.32

type BreakLogPod struct {
	Name  string `json:"name"`
	UID   string `json:"uid"`
	State string `json:"state"`
	Short string `json:"short"`
}

type BreakLogRate added in v1.4.32

type BreakLogRate struct {
	Minute time.Time `json:"minute"`
	Total  int       `json:"total"`
	Errors int       `json:"errors"`
}

type BreakLogSource added in v1.4.32

type BreakLogSource struct {
	Kind string    `json:"kind"`
	Name string    `json:"name"`
	Type string    `json:"type,omitempty"`
	At   time.Time `json:"at"`
}

type BreakLogWindow added in v1.4.32

type BreakLogWindow struct {
	From time.Time `json:"from"`
	To   time.Time `json:"to"`
}

type BrokenTotals added in v1.4.31

type BrokenTotals struct {
	Total      int            `json:"total"`
	BySeverity map[string]int `json:"by_severity"`
}

type CaptureStatus added in v1.4.31

type CaptureStatus struct {
	EvidenceMode  string                       `json:"evidence_mode,omitempty"`
	EvidenceError string                       `json:"evidence_error,omitempty"`
	Mode          string                       `json:"mode"`
	Reason        string                       `json:"reason,omitempty"`
	LastCycleAt   *time.Time                   `json:"last_cycle_at,omitempty"`
	Behind        bool                         `json:"behind"`
	Verification  *projectedVerificationStatus `json:"verification,omitempty"`
}

type Change added in v1.4.29

type Change = kubechanges.Change

type ChangeFieldChange added in v1.4.29

type ChangeFieldChange = kubechanges.FieldChange

type ChangePage added in v1.4.29

type ChangePage struct {
	Items     []Change          `json:"items"`
	Next      string            `json:"next,omitempty"`
	Truncated bool              `json:"truncated"`
	Partial   []PartialFailure  `json:"partial_failures,omitempty"`
	Gaps      []kubechanges.Gap `json:"gaps"`
	Sync      SyncStatus        `json:"sync"`
}

type ChangeQuery added in v1.4.29

type ChangeQuery = kubechanges.Query

type ChangeType added in v1.4.29

type ChangeType = kubechanges.Type

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.

func (*Client) GetMetadataJSON added in v1.4.29

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

type ClusterEntry added in v1.4.31

type ClusterEntry struct {
	Info    ClusterInfo
	Service *Service
	Err     error
}

type ClusterInfo added in v1.4.31

type ClusterInfo struct {
	ID          string `json:"id"`
	DisplayName string `json:"display_name,omitempty"`
	Provider    string `json:"provider"`
}

type ClusterSummary added in v1.4.31

type ClusterSummary struct {
	ClusterInfo
	Version      string       `json:"version,omitempty"`
	Health       string       `json:"health"`
	Nodes        int          `json:"nodes"`
	ReadyNodes   int          `json:"ready_nodes"`
	Pods         int          `json:"pods"`
	RunningPods  int          `json:"running_pods"`
	Warnings     int          `json:"warnings"`
	Issues       *int         `json:"issues,omitempty"`
	Broken       *int         `json:"broken,omitempty"`
	LastChangeAt *time.Time   `json:"last_change_at,omitempty"`
	Sync         SyncStatus   `json:"sync"`
	ObservedAt   time.Time    `json:"observed_at"`
	Error        *ErrorDetail `json:"error,omitempty"`
}

type Condition

type Condition struct {
	Type         string    `json:"type"`
	Status       string    `json:"status"`
	Reason       string    `json:"reason,omitempty"`
	TransitionAt time.Time `json:"last_transition_at,omitempty,omitzero"`
}

type Config

type Config struct {
	Namespace            string
	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 CrashPage added in v1.4.31

type CrashPage struct {
	kubechanges.CrashPage
	Capture CaptureStatus `json:"capture"`
	Sync    SyncStatus    `json:"sync"`
}

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 DiagnoseOptions added in v1.4.29

type DiagnoseOptions struct {
	ResourceID   string
	Kind         string
	Namespace    string
	Name         string
	LogTail      int
	ChangeWindow time.Duration
}

type Diagnosis added in v1.4.29

type Diagnosis struct {
	Workload      WorkloadDetail      `json:"workload"`
	WarningEvents []ProjectedResource `json:"warning_events,omitempty"`
	WorstPodLogs  *PodLogs            `json:"worst_pod_logs,omitempty"`
	Changes       []Change            `json:"changes"`
	Neighborhood  kubegraph.Graph     `json:"neighborhood"`
	Partial       []PartialFailure    `json:"partial_failures,omitempty"`
	Omitted       []string            `json:"omitted_categories,omitempty"`
	Truncated     bool                `json:"truncated"`
	Sync          SyncStatus          `json:"sync"`
	Break         *Issue              `json:"break,omitempty"`
}

type Discovery

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

Discovery is a bounded cluster-driven API registry.

type ErrThrottled added in v1.4.31

type ErrThrottled struct{ RetryAfter time.Duration }

func (*ErrThrottled) Error added in v1.4.31

func (*ErrThrottled) Error() string

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 DiagnoseClusterError added in v1.4.31

func DiagnoseClusterError(err error, multiple bool, clusterID string) ErrorDetail

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
	Cursor    string
	Limit     int
}

EventOptions is the server-owned object event filter contract.

type EventPage added in v1.4.29

type EventPage struct {
	Items            []ProjectedResource `json:"items"`
	Next             string              `json:"next,omitempty"`
	Truncated        bool                `json:"truncated"`
	Partial          []PartialFailure    `json:"partial_failures,omitempty"`
	EncodedTruncated bool                `json:"-"`
	Omitted          []string            `json:"-"`
}

type GitOpsApp added in v1.4.29

type GitOpsApp struct {
	Tool       string    `json:"tool"`
	Kind       string    `json:"kind"`
	Namespace  string    `json:"namespace"`
	Name       string    `json:"name"`
	Sync       string    `json:"sync"`
	Health     string    `json:"health"`
	Revision   string    `json:"revision,omitempty"`
	LastSyncAt time.Time `json:"last_sync_at,omitempty"`
	Message    string    `json:"message,omitempty"`
	Source     string    `json:"source,omitempty"`
	Suspended  bool      `json:"suspended"`
}

type GitOpsAppOptions added in v1.4.29

type GitOpsAppOptions struct {
	Namespace string
	Tool      string
	Status    string
	Limit     int
	Cursor    string
}

type GitOpsAppPage added in v1.4.29

type GitOpsAppPage struct {
	Items     []GitOpsApp      `json:"items"`
	Available bool             `json:"available"`
	Reason    string           `json:"reason,omitempty"`
	Next      string           `json:"next,omitempty"`
	Partial   []PartialFailure `json:"partial_failures,omitempty"`
	Truncated bool             `json:"truncated"`
}

type GraphQuery added in v1.4.29

type GraphQuery struct {
	Namespace     string
	GroupBy       string
	MaxNodes      int
	ConnectedOnly bool
	Complete      bool
	Limit         int
	Cursor        string
	// contains filtered or unexported fields
}

type HelmRelease added in v1.4.29

type HelmRelease struct {
	Namespace string         `json:"namespace"`
	Name      string         `json:"name"`
	Current   HelmRevision   `json:"current"`
	History   []HelmRevision `json:"history"`
	Health    string         `json:"health"`
}

type HelmReleaseOptions added in v1.4.29

type HelmReleaseOptions struct {
	Namespace string
	Status    string
	Limit     int
	Cursor    string
}

type HelmReleasePage added in v1.4.29

type HelmReleasePage struct {
	Items     []HelmRelease    `json:"items"`
	Next      string           `json:"next,omitempty"`
	Truncated bool             `json:"truncated"`
	Partial   []PartialFailure `json:"partial_failures,omitempty"`
}

type HelmRevision added in v1.4.29

type HelmRevision struct {
	Revision int       `json:"revision"`
	Status   string    `json:"status"`
	Created  time.Time `json:"created,omitempty"`
}

type Issue added in v1.4.29

type Issue struct {
	OccurrenceID  string                    `json:"occurrence_id,omitempty"`
	State         string                    `json:"state,omitempty"`
	ClosedAt      *time.Time                `json:"closed_at,omitempty"`
	Root          ObjectRef                 `json:"root"`
	Rule          string                    `json:"rule"`
	Severity      string                    `json:"severity"`
	Count         int                       `json:"count"`
	Examples      []ObjectRef               `json:"examples,omitempty"`
	FirstSeen     time.Time                 `json:"first_seen,omitempty"`
	LastSeen      time.Time                 `json:"last_seen,omitempty"`
	Broken        bool                      `json:"broken,omitempty"`
	Of            int                       `json:"of,omitempty"`
	BrokeAt       *time.Time                `json:"broke_at,omitempty"`
	BrokeAtSource string                    `json:"broke_at_source,omitempty"`
	Evidence      *kubebreaks.Evidence      `json:"evidence,omitempty"`
	Changes       []kubebreaks.LinkedChange `json:"changes,omitempty"`
	MoreChanges   int                       `json:"more_changes,omitempty"`
	History       string                    `json:"history,omitempty"`
	Gaps          []kubechanges.Gap         `json:"gaps,omitempty"`
	Rebuilt       []string                  `json:"rebuilt,omitempty"`
	Untracked     []string                  `json:"untracked,omitempty"`
	Partial       bool                      `json:"partial,omitempty"`
	// Pending lists resource IDs whose evidence is still loading; History
	// and Changes may fill in once they are listed.
	Pending []string `json:"pending,omitempty"`
}

type IssueAlert added in v1.4.32

type IssueAlert struct {
	OrgID                                                           string
	Cluster, Namespace, WorkloadKind, Workload, RootUID, ResourceID string
	Rule, RuleLabel, Severity                                       string
	Count, Of                                                       int
	BrokeAt                                                         time.Time
	Evidence, Changes                                               []string
	HistoryIncomplete                                               bool
	RollupCount                                                     int
}

IssueAlert contains only notification-safe facts, never raw object or log payloads.

type IssueAlertSettings added in v1.4.32

type IssueAlertSettings struct {
	Enabled         bool      `json:"enabled"`
	Level           string    `json:"level"`
	EnabledAt       time.Time `json:"enabled_at"`
	CanWrite        bool      `json:"can_write"`
	Available       bool      `json:"available"`
	Reason          string    `json:"reason"`
	LinksReady      bool      `json:"links_ready"`
	ChannelsEnabled bool      `json:"channels_enabled"`
}

type IssueOptions added in v1.4.29

type IssueOptions struct {
	Since, Until   time.Time
	Namespace      string
	Severity       string
	Kind           string
	Limit          int
	Cursor         string
	Broken         bool
	IncludeChanges bool
	RootUID        string
	Context        string
	// contains filtered or unexported fields
}

type IssuePage added in v1.4.29

type IssuePage struct {
	RootContext *PersistedRootContext `json:"root_context,omitempty"`
	Items       []Issue               `json:"items"`
	Totals      map[string]int        `json:"totals"`
	Truncated   bool                  `json:"truncated"`
	Next        string                `json:"next,omitempty"`
	Partial     []PartialFailure      `json:"partial_failures,omitempty"`
	Sync        SyncStatus            `json:"sync"`
	Broken      BrokenTotals          `json:"broken"`
}

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"`
	Complete     bool       `json:"complete"`
	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 NamespacePage added in v1.4.32

type NamespacePage struct {
	Items   []string         `json:"items"`
	Sync    SyncStatus       `json:"sync"`
	Partial []PartialFailure `json:"partial_failures,omitempty"`
}

type NeighborhoodQuery added in v1.4.29

type NeighborhoodQuery struct {
	ResourceID string
	Kind       string
	Namespace  string
	Name       string
	Hops       int
	MaxNodes   int
}

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"`
	// contains filtered or unexported fields
}

type Outcome added in v1.4.32

type Outcome struct {
	IncidentID          string
	NotificationOutcome string
}

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"`
	Sync              SyncStatus       `json:"sync"`
}

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 PersistedRootContext added in v1.4.33

type PersistedRootContext struct {
	Root       ObjectRef `json:"root"`
	Occurrence Issue     `json:"occurrence"`
	Retained   bool      `json:"retained"`
}

PersistedRootContext describes captured identity, not a live graph lookup.

type PodLogSession added in v1.4.32

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

PodLogSession reserves viewer and upstream capacity before SSE headers are committed. Close cancels an active reader; capacity is released after it exits.

func (*PodLogSession) Close added in v1.4.32

func (session *PodLogSession) Close()

func (*PodLogSession) Stream added in v1.4.32

func (session *PodLogSession) Stream(emit func(PodLogStreamEvent) error) error

type PodLogStreamEvent added in v1.4.30

type PodLogStreamEvent struct {
	Event           string `json:"-"`
	Text            string `json:"text"`
	Container       string `json:"container"`
	Timestamp       string `json:"timestamp,omitempty"`
	Sequence        uint64 `json:"sequence,omitempty"`
	Ordinal         uint64 `json:"ordinal,omitempty"`
	Cursor          string `json:"cursor,omitempty"`
	Reason          string `json:"reason,omitempty"`
	Code            string `json:"code,omitempty"`
	Message         string `json:"message,omitempty"`
	Action          string `json:"action,omitempty"`
	Retryable       bool   `json:"retryable,omitempty"`
	ReplayUncertain bool   `json:"replay_uncertain,omitempty"`
	// CursorLagging marks a terminal limit event whose cursor never caught up
	// with the newest line this stream sent: rotating from that cursor alone
	// replays the same bytes and stops at the same limit. NewestTimestamp is the
	// newest emitted line's timestamp, bounded and free of line text, so a viewer
	// resumes from the line instead of guessing. Both are absent when the cursor
	// is current.
	CursorLagging   bool   `json:"cursor_lagging,omitempty"`
	NewestTimestamp string `json:"newest_timestamp,omitempty"`
}

type PodLogStreamOptions added in v1.4.30

type PodLogStreamOptions struct {
	Namespace    string
	Pod          string
	Container    string
	SinceSeconds int
	TailLines    int
	// SinceTime resumes from a timestamp instead of a cursor, the way kubectl
	// logs -f does. It is the resume a client keeps when the line-level cursor
	// would not fit in the request budget.
	SinceTime  time.Time
	Timestamps bool
	Previous   bool
	Cursor     string
	// contains filtered or unexported fields
}

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"`
	CreatedAt           time.Time         `json:"created_at,omitempty,omitzero"`
	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"`
	// contains filtered or unexported fields
}

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 {
	Sync             SyncStatus          `json:"sync"`
	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 Rollout added in v1.4.29

type Rollout struct {
	Namespace  string `json:"namespace"`
	Name       string `json:"name"`
	Phase      string `json:"phase"`
	Strategy   string `json:"strategy,omitempty"`
	Step       int    `json:"step"`
	TotalSteps int    `json:"total_steps"`
	StableRS   string `json:"stable_rs,omitempty"`
	CanaryRS   string `json:"canary_rs,omitempty"`
	Weight     int    `json:"weight,omitempty"`
	Message    string `json:"message,omitempty"`
}

type RolloutListOptions added in v1.4.29

type RolloutListOptions struct {
	Namespace string
	Limit     int
	Cursor    string
}

type RolloutPage added in v1.4.29

type RolloutPage struct {
	Items     []Rollout        `json:"items"`
	Available bool             `json:"available"`
	Reason    string           `json:"reason,omitempty"`
	Next      string           `json:"next,omitempty"`
	Truncated bool             `json:"truncated"`
	Partial   []PartialFailure `json:"partial_failures,omitempty"`
}

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) ActiveScope added in v1.4.31

func (service *Service) ActiveScope() Scope

func (*Service) AgentSettings added in v1.4.32

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

func (*Service) BreakLogs added in v1.4.32

func (service *Service) BreakLogs(ctx context.Context, query breaklogs.Query) (BreakLogPage, error)

func (*Service) CachedIndexSnapshot added in v1.4.32

func (service *Service) CachedIndexSnapshot(ctx context.Context, kinds ...string) (kubeindex.Snapshot, kubeindex.Status, error)

CachedIndexSnapshot reads a generation only. Collection is never charged to, or awaited by, the UI request.

func (*Service) CachedNamespaceSnapshot added in v1.4.32

func (service *Service) CachedNamespaceSnapshot(ctx context.Context, namespace string, kinds ...string) (kubeindex.Snapshot, kubeindex.Status, error)

func (*Service) CachedResources added in v1.4.32

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

CachedResources serves display pages over the complete projected inventory.

func (*Service) CaptureStatus added in v1.4.31

func (service *Service) CaptureStatus() CaptureStatus

func (*Service) Changes added in v1.4.29

func (service *Service) Changes(ctx context.Context, query ChangeQuery) (ChangePage, error)

Changes returns the bounded timeline for the service's org/cluster scope.

func (*Service) Crashes added in v1.4.31

func (service *Service) Crashes(ctx context.Context, query kubechanges.CrashQuery) (CrashPage, error)

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) DiagnoseWorkload added in v1.4.29

func (service *Service) DiagnoseWorkload(ctx context.Context, options DiagnoseOptions) (Diagnosis, error)

DiagnoseWorkload combines bounded workload, warning-event and scrubbed log evidence.

func (*Service) Discover

func (service *Service) Discover(ctx context.Context) (result Discovery, resultErr 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 and safely projects one discovered Kubernetes resource.

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) GitOpsApps added in v1.4.29

func (service *Service) GitOpsApps(ctx context.Context, options GitOpsAppOptions) (GitOpsAppPage, error)

GitOpsApps lists only discovered GitOps APIs and safely projected status.

func (*Service) Graph added in v1.4.29

func (service *Service) Graph(ctx context.Context, query GraphQuery) (kubegraph.Graph, error)

Graph builds a bounded topology graph from the shared projected index.

func (*Service) IndexSnapshot added in v1.4.29

func (service *Service) IndexSnapshot(ctx context.Context, kinds ...string) (kubeindex.Snapshot, kubeindex.Status, error)

IndexSnapshot polls requested kinds within the normal operation budget and returns the shared last-good view plus its per-kind freshness state.

func (*Service) InvalidateDiscovery

func (service *Service) InvalidateDiscovery()

InvalidateDiscovery expires only this service's scoped discovery generation.

func (*Service) IssueAlertSettings added in v1.4.32

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

func (*Service) Issues added in v1.4.29

func (service *Service) Issues(ctx context.Context, options IssueOptions) (IssuePage, error)

Issues returns bounded findings from projected cluster resources.

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) (EventPage, 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) Namespaces added in v1.4.32

func (service *Service) Namespaces(ctx context.Context, hints ...string) (NamespacePage, error)

func (*Service) Neighborhood added in v1.4.29

func (service *Service) Neighborhood(ctx context.Context, query NeighborhoodQuery) (kubegraph.Graph, error)

Neighborhood returns a capped BFS slice from the same shared graph view.

func (*Service) OpenPodLogStream added in v1.4.32

func (service *Service) OpenPodLogStream(ctx context.Context, options PodLogStreamOptions) (*PodLogSession, error)

func (*Service) OpenWorkloadLogStream added in v1.4.32

func (service *Service) OpenWorkloadLogStream(ctx context.Context, options WorkloadLogStreamOptions) (*WorkloadLogSession, error)

func (*Service) Overview

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

func (*Service) OverviewGraph added in v1.4.29

func (service *Service) OverviewGraph(ctx context.Context) (kubegraph.Graph, error)

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) Related added in v1.4.32

func (service *Service) Related(ctx context.Context, query NeighborhoodQuery) (kubegraph.Graph, error)

Related follows ownership from the selected root, not from every node it discovers. Config, identity, and placement are terminal leaves; walking back through them would incorrectly include unrelated users of shared resources.

func (*Service) Release added in v1.4.29

func (service *Service) Release(ctx context.Context, namespace, name string) (HelmRelease, error)

Release returns one label-only Helm release and its bounded revision history.

func (*Service) Releases added in v1.4.29

func (service *Service) Releases(ctx context.Context, options HelmReleaseOptions) (HelmReleasePage, error)

Releases reads Helm revision labels from PartialObjectMetadata only.

func (*Service) Rollout added in v1.4.29

func (service *Service) Rollout(ctx context.Context, namespace, name string) (Rollout, error)

Rollout returns one safely projected Argo Rollouts status record.

func (*Service) Rollouts added in v1.4.29

func (service *Service) Rollouts(ctx context.Context, options RolloutListOptions) (RolloutPage, error)

Rollouts lists discovered Argo Rollouts using the same projection as Rollout.

func (*Service) SaveAgentSettings added in v1.4.32

func (service *Service) SaveAgentSettings(ctx context.Context, settings breaklogs.Settings) error

func (*Service) SaveIssueAlertSettings added in v1.4.32

func (service *Service) SaveIssueAlertSettings(ctx context.Context, enabled bool, level, actor string) error

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) SetBreakLogSources added in v1.4.32

func (service *Service) SetBreakLogSources(resolve func(string) []breaklogs.Source)

func (*Service) SetCaptureMode added in v1.4.31

func (service *Service) SetCaptureMode(mode string) error

func (*Service) SetChangeStorage added in v1.4.29

func (service *Service) SetChangeStorage(provider storage.Provider)

SetChangeStorage installs the shared persistence provider for scoped timelines.

func (*Service) SetIssueAlertSink added in v1.4.32

func (service *Service) SetIssueAlertSink(sink func(context.Context, IssueAlert) (Outcome, error))

func (*Service) SetLogStreamContext added in v1.4.30

func (service *Service) SetLogStreamContext(ctx context.Context)

func (*Service) SetScrubber

func (service *Service) SetScrubber(scrubber Scrubber)

SetScrubber installs the shared model/API text redactor.

func (*Service) SetTrafficContributor added in v1.4.29

func (service *Service) SetTrafficContributor(provider TrafficContributor)

SetTrafficContributor installs an optional traffic reader without coupling the OSS Kubernetes service to any particular telemetry implementation.

func (*Service) StartCapture added in v1.4.31

func (service *Service) StartCapture(parent context.Context)

func (*Service) StopCapture added in v1.4.31

func (service *Service) StopCapture()

func (*Service) StreamPodLogs added in v1.4.30

func (service *Service) StreamPodLogs(ctx context.Context, options PodLogStreamOptions, emit func(PodLogStreamEvent) error) error

func (*Service) StreamWorkloadLogs added in v1.4.32

func (service *Service) StreamWorkloadLogs(ctx context.Context, options WorkloadLogStreamOptions, emit func(WorkloadLogStreamEvent) error) error

func (*Service) SubscribeIndex added in v1.4.29

func (service *Service) SubscribeIndex(ctx context.Context, buffer int, kinds ...string) (<-chan kubeindex.Delta, func(), kubeindex.Status, error)

SubscribeIndex primes the shared index, then subscribes to its bounded deltas.

func (*Service) SyncHealth added in v1.4.32

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

SyncHealth reports every known kind's inventory state from the published generation. It never lists the cluster and never waits for a cycle, so a caller can gate on it on every render.

A cluster that cannot be read is still answered. The failure comes back typed and carries a report whose state is error, so a surface keeps the one fact that has to outlive the credential — whether the cluster was ever ready — instead of losing it to an error status. Callers that only care whether the read succeeded keep using err.

func (service *Service) TestLogLink(ctx context.Context, request TestLinkRequest) (TestLinkResult, error)

func (*Service) Timeline added in v1.4.32

func (service *Service) Timeline(ctx context.Context, query TimelineQuery) (TimelinePage, error)

func (*Service) Top added in v1.4.29

func (service *Service) Top(ctx context.Context, options TopOptions) (TopPage, error)

Top returns the highest-usage pods or nodes from the Metrics API.

func (*Service) Traffic added in v1.4.29

func (service *Service) Traffic(ctx context.Context, query TrafficQuery) (Traffic, error)

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.

func (*Service) UsageHistory added in v1.4.32

func (service *Service) UsageHistory(ctx context.Context, namespace, pod string) (UsageHistory, error)

UsageHistory records drawer interest, but never starts a sampler per viewer.

func (*Service) UsagePage added in v1.4.32

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

UsagePage applies display paging without changing complete cached totals.

func (*Service) ValidatePodLogStream added in v1.4.30

func (service *Service) ValidatePodLogStream(options PodLogStreamOptions) error

func (*Service) ValidateWorkloadLogStream added in v1.4.32

func (service *Service) ValidateWorkloadLogStream(ctx context.Context, options WorkloadLogStreamOptions) error

func (*Service) WorkloadLogs added in v1.4.29

func (service *Service) WorkloadLogs(ctx context.Context, options WorkloadLogOptions) (WorkloadLogs, error)

func (*Service) Workloads added in v1.4.29

func (service *Service) Workloads(ctx context.Context, options WorkloadListOptions) (WorkloadPage, error)

Workloads lists one stable page of supported workload projections.

type ServiceRegistry

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

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

func NewClusterRegistry added in v1.4.31

func NewClusterRegistry(multiple bool, entries []ClusterEntry) *ServiceRegistry

func NewClusterRegistryWithScope added in v1.4.31

func NewClusterRegistryWithScope(multiple bool, entries []ClusterEntry, scope tenancy.OrgScope) *ServiceRegistry

func NewServiceRegistry

func NewServiceRegistry(base *Service) *ServiceRegistry

func (*ServiceRegistry) Close added in v1.4.31

func (registry *ServiceRegistry) Close()

func (*ServiceRegistry) CloseContext added in v1.4.31

func (registry *ServiceRegistry) CloseContext(ctx context.Context) error

func (*ServiceRegistry) Clusters added in v1.4.31

func (registry *ServiceRegistry) Clusters() []ClusterInfo

func (*ServiceRegistry) DeregisterCluster added in v1.4.31

func (registry *ServiceRegistry) DeregisterCluster(clusterID string)

func (*ServiceRegistry) Each added in v1.4.31

func (registry *ServiceRegistry) Each(visit func(*Service))

func (*ServiceRegistry) LocalReportService added in v1.4.32

func (registry *ServiceRegistry) LocalReportService(orgID, clusterID string) (*Service, error)

LocalReportService resolves only local report scope, without validating a credential or starting capture. Read orgs use the same trusted deployment policy as normal resolution; this does not authorize inventory reads.

func (*ServiceRegistry) Multiple added in v1.4.31

func (registry *ServiceRegistry) Multiple() bool

func (*ServiceRegistry) Resolve

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

func (*ServiceRegistry) ResolveCluster added in v1.4.31

func (registry *ServiceRegistry) ResolveCluster(orgID, clusterID string) (*Service, error)

func (*ServiceRegistry) ResolveOrg

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

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

func (*ServiceRegistry) StartCapture added in v1.4.31

func (registry *ServiceRegistry) StartCapture(ctx context.Context)

func (*ServiceRegistry) Summaries added in v1.4.31

func (registry *ServiceRegistry) Summaries(ctx context.Context, orgID string, allow func(string) bool) []ClusterSummary

type SyncHealth added in v1.4.32

type SyncHealth struct {
	Progress *SyncProgress `json:"progress,omitempty"`
	State    string        `json:"state"`
	Partial  bool          `json:"partial"`
	// FirstReadyAt is when this cluster first recorded a ready generation. It is
	// recorded once, kept with the cluster's inventory metadata, and carried
	// forward from then on, so a credential fault, a restart, a re-index, or any
	// later syncing, partial, stale, or error report still says the cluster has
	// been ready before. It is a property of the cluster, not of the process, and
	// the moment it keeps is always the first one. A cluster that has never been
	// ready omits it.
	FirstReadyAt time.Time `json:"first_ready_at,omitzero"`
	// Class names why the whole read failed, drawn from the same closed
	// vocabulary a kind's own failure class uses, so a surface gets one word it
	// already knows. It is set only on an error report and stays empty otherwise.
	Class string `json:"class,omitempty"`
	// AgeSeconds is how old the snapshot this report describes is, in seconds:
	// the oldest observation it stands behind. It is absent when no snapshot has
	// ever been published, because zero seconds would claim the empty screen is
	// current data.
	AgeSeconds *float64 `json:"age_s,omitempty"`
	// Kinds carries one entry per known kind. A kind the cluster does not serve is
	// present with Absent set, so it is never confused with a missing kind.
	Kinds map[string]kubeindex.KindStatus `json:"kinds"`
	// Failing lists the kinds whose latest listing did not finish cleanly, ready
	// for a surface to render: name, class, counts, and since when. It carries the
	// blocking faults only.
	Failing []SyncKindProblem `json:"failing"`
	// Unreadable lists the kinds this connector identity is not allowed to read.
	// A capability gap is not a sync fault: these kinds are excluded from Failing
	// and from the aggregate state, so a least-privilege install still reaches
	// ready and can show everything it is allowed to see.
	Unreadable []SyncKindProblem `json:"unreadable"`
	// TotalKinds counts every kind before the payload bound is applied.
	TotalKinds      int  `json:"total_kinds"`
	ReadyKinds      int  `json:"ready_kinds"`
	FailingKinds    int  `json:"failing_kinds"`
	UnreadableKinds int  `json:"unreadable_kinds"`
	PendingKinds    int  `json:"pending_kinds"`
	Truncated       bool `json:"truncated"`
	// OmittedKinds names the kinds the bound dropped, bounded itself.
	OmittedKinds []string `json:"omitted_kinds,omitempty"`
}

SyncHealth is the complete inventory health of one cluster: every kind the index knows, not only the kinds one view asked for. View payloads stay narrow on purpose; this is what a caller gates on, because a kind outside a view's own request would otherwise fail without anyone noticing.

func SyncHealthReport added in v1.4.32

func SyncHealthReport(err error) (SyncHealth, bool)

SyncHealthReport returns the report a failed health read can still answer, and false when the failure carries none. A caller that gets false keeps its usual error answer, so no other failure changes shape.

type SyncKindProblem added in v1.4.32

type SyncKindProblem struct {
	Kind    string `json:"kind"`
	State   string `json:"state"`
	Class   string `json:"class,omitempty"`
	Skipped int    `json:"skipped,omitempty"`
	Records int    `json:"records"`
	// Since is when this failure began, kept until the kind recovers. A zero time
	// is omitted rather than rendered as a date.
	Since time.Time `json:"since,omitzero"`
	// ObservedAt is the last successful listing start, omitted when there is none.
	ObservedAt time.Time `json:"observed_at,omitzero"`
}

SyncKindProblem is one failing kind in plain terms. Since is when the failing attempt started, so a surface can say how long the kind has been failing.

type SyncProgress added in v1.4.32

type SyncProgress = kubeindex.SyncProgress

SyncProgress is the first-sync progress attached to a view's sync status.

type SyncStatus added in v1.4.29

type SyncStatus struct {
	State      string  `json:"state"`
	AgeSeconds float64 `json:"age_s"`
	Partial    bool    `json:"partial"`
	// Progress is present only during a cluster's first sync.
	Progress *SyncProgress `json:"progress,omitempty"`
	// Pending lists resource IDs this view needs that are still loading after
	// the core generation; PendingKinds counts all resource types still loading.
	Pending      []string `json:"pending,omitempty"`
	PendingKinds int      `json:"pending_kinds,omitempty"`
}

type TestLinkRequest added in v1.4.32

type TestLinkRequest struct {
	Source string           `json:"source"`
	Fields breaklogs.Fields `json:"fields"`
}

type TestLinkResult added in v1.4.32

type TestLinkResult struct {
	Lines      int    `json:"lines"`
	Namespace  string `json:"namespace"`
	Workload   string `json:"workload"`
	DurationMS int64  `json:"duration_ms"`
	Preview    string `json:"preview"`
	Truncated  bool   `json:"truncated"`
}

type TimelineItem added in v1.4.32

type TimelineItem struct {
	Type   string                  `json:"type"`
	ID     string                  `json:"id"`
	At     time.Time               `json:"at"`
	Change *Change                 `json:"change,omitempty"`
	Crash  *kubechanges.CrashEvent `json:"crash,omitempty"`
	Issue  *Issue                  `json:"issue,omitempty"`
}

type TimelinePage added in v1.4.32

type TimelinePage struct {
	Items      []TimelineItem    `json:"items"`
	Next       string            `json:"next,omitempty"`
	Sync       SyncStatus        `json:"sync"`
	Partial    []PartialFailure  `json:"partial_failures,omitempty"`
	Gaps       []kubechanges.Gap `json:"gaps"`
	CrashCount int               `json:"crash_count"`
	Total      int               `json:"total"`
	Counts     map[string]int    `json:"counts"`
	Since      time.Time         `json:"since"`
	Until      time.Time         `json:"until"`
	BreaksOnly bool              `json:"breaks_only,omitempty"`
}

type TimelineQuery added in v1.4.32

type TimelineQuery struct {
	Since, Until                                  time.Time
	Namespace, Kind, RootUID, PodUID, ResourceUID string
	Limit                                         int
	Cursor                                        string
	// BreaksOnly keeps only break items, so paging, totals and counts cover
	// breaks alone. Cursors are bound to it.
	BreaksOnly bool
}

type TopItem added in v1.4.29

type TopItem struct {
	ResourceUsage
	RequestCPU    string     `json:"request_cpu,omitempty"`
	RequestMemory string     `json:"request_memory,omitempty"`
	Owner         *ObjectRef `json:"owner,omitempty"`
}

type TopOptions added in v1.4.29

type TopOptions struct {
	Kind      string
	Namespace string
	Sort      string
	Limit     int
}

type TopPage added in v1.4.29

type TopPage struct {
	Items        []TopItem        `json:"items"`
	Total        int              `json:"total"`
	Truncated    bool             `json:"truncated"`
	Availability string           `json:"availability"`
	Fresh        bool             `json:"fresh"`
	Partial      []PartialFailure `json:"partial_failures,omitempty"`
	Sync         SyncStatus       `json:"sync"`
}

type TraceBackend added in v1.4.32

type TraceBackend struct {
	Kind      string `json:"kind"`
	Namespace string `json:"namespace"`
}

type Traffic added in v1.4.29

type Traffic struct {
	Available  bool          `json:"available"`
	Reason     string        `json:"reason,omitempty"`
	Source     string        `json:"source,omitempty"`
	Window     string        `json:"window"`
	ObservedAt time.Time     `json:"observed_at,omitempty"`
	Edges      []TrafficEdge `json:"edges,omitempty"`
	Unmapped   int           `json:"unmapped"`
	External   []string      `json:"external,omitempty"`
	Truncated  bool          `json:"truncated"`
}

type TrafficContributor added in v1.4.29

type TrafficContributor interface {
	ReadTraffic(context.Context, TrafficQuery) (Traffic, error)
}

type TrafficEdge added in v1.4.29

type TrafficEdge struct {
	From        TrafficWorkload `json:"from"`
	To          TrafficWorkload `json:"to"`
	RatePerSec  *float64        `json:"rate_per_sec"`
	ErrorRate   *float64        `json:"error_rate"`
	P95Ms       *float64        `json:"p95_ms"`
	BytesPerSec *float64        `json:"bytes_per_sec"`
}

TrafficEdge leaves unavailable measurements nil so they serialize as null.

type TrafficQuery added in v1.4.29

type TrafficQuery struct {
	Namespace string
	Source    string
	Window    string
}

type TrafficWorkload added in v1.4.29

type TrafficWorkload struct {
	Namespace string `json:"namespace"`
	Kind      string `json:"kind"`
	Name      string `json:"name"`
}

type Usage

type Usage struct {
	Next         string              `json:"next,omitempty"`
	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 UsageHistory added in v1.4.32

type UsageHistory struct {
	ObservedAt       time.Time     `json:"observed_at"`
	Source           string        `json:"source"`
	Availability     string        `json:"availability"`
	LiveSince        time.Time     `json:"live_since"`
	Samples          []UsageSample `json:"samples"`
	RetentionSeconds int           `json:"retention_seconds"`
}

type UsageSample added in v1.4.32

type UsageSample struct {
	Timestamp   time.Time `json:"timestamp"`
	CPUMilli    float64   `json:"cpu_milli"`
	MemoryBytes float64   `json:"memory_bytes"`
}

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 {
	UID                string              `json:"uid,omitempty"`
	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 WorkloadListOptions added in v1.4.29

type WorkloadListOptions struct {
	Namespace string
	Kind      string
	Query     string
	Limit     int
	Cursor    string
}

type WorkloadLogLine added in v1.4.29

type WorkloadLogLine struct {
	Pod       string    `json:"pod"`
	Container string    `json:"container,omitempty"`
	At        time.Time `json:"at,omitempty"`
	Text      string    `json:"text"`
}

type WorkloadLogOptions added in v1.4.29

type WorkloadLogOptions struct {
	Namespace    string
	Kind         string
	Name         string
	Pod          string
	Container    string
	Previous     bool
	SinceSeconds int
	TailLines    int
	Grep         string
	MaxPods      int
}

type WorkloadLogPod added in v1.4.32

type WorkloadLogPod struct {
	UID             string   `json:"uid"`
	Name            string   `json:"name"`
	Containers      []string `json:"containers"`
	InitContainers  []string `json:"init_containers"`
	MainContainer   string   `json:"main_container,omitempty"`
	Admitted        bool     `json:"admitted"`
	Truncated       bool     `json:"truncated,omitempty"`
	Reason          string   `json:"reason,omitempty"`
	AllPodsAdmitted bool     `json:"all_pods_admitted"`
	AllPodsReason   string   `json:"all_pods_reason,omitempty"`
}

type WorkloadLogSession added in v1.4.32

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

WorkloadLogSession owns one viewer admission and every source reservation. Close is idempotent; Stream must have a single caller.

func (*WorkloadLogSession) Close added in v1.4.32

func (session *WorkloadLogSession) Close()

func (*WorkloadLogSession) Stream added in v1.4.32

func (session *WorkloadLogSession) Stream(emit func(WorkloadLogStreamEvent) error) (result error)

type WorkloadLogSource added in v1.4.32

type WorkloadLogSource struct {
	SourceID    string `json:"source_id"`
	PodUID      string `json:"pod_uid"`
	Pod         string `json:"pod"`
	Namespace   string `json:"namespace"`
	Container   string `json:"container"`
	Incarnation string `json:"incarnation"`
	Admitted    bool   `json:"admitted"`
	Reason      string `json:"reason,omitempty"`
}

type WorkloadLogStreamEvent added in v1.4.32

type WorkloadLogStreamEvent struct {
	PodLogStreamEvent
	WorkloadUID string              `json:"workload_uid"`
	PodUID      string              `json:"pod_uid,omitempty"`
	Pod         string              `json:"pod,omitempty"`
	Namespace   string              `json:"namespace,omitempty"`
	Incarnation string              `json:"incarnation,omitempty"`
	SourceID    string              `json:"source_id,omitempty"`
	Sources     []WorkloadLogSource `json:"sources,omitempty"`
	Pods        []WorkloadLogPod    `json:"pods,omitempty"`
	Truncated   bool                `json:"truncated,omitempty"`
}

type WorkloadLogStreamOptions added in v1.4.32

type WorkloadLogStreamOptions struct {
	Kind, Name, Namespace, UID string
	PodUIDs                    []string
	Container                  string
	SinceSeconds, TailLines    int
	// SinceTime resumes every source from a caller's timestamp, the way
	// kubectl logs -f does. It replaces the resume cursor: a reconnect carries a
	// timestamp, so a request stays small no matter how many sources a workload
	// has.
	SinceTime            time.Time
	Previous, Timestamps bool
}

type WorkloadLogs added in v1.4.29

type WorkloadLogs struct {
	Pods        []string          `json:"pods"`
	Lines       []WorkloadLogLine `json:"lines"`
	Truncated   bool              `json:"truncated"`
	OmittedPods []string          `json:"omitted_pods"`
	Partial     []PartialFailure  `json:"partial_failures,omitempty"`
}

type WorkloadPage

type WorkloadPage struct {
	Sync      SyncStatus          `json:"sync"`
	Items     []ProjectedResource `json:"items"`
	Counts    map[string]int      `json:"counts,omitempty"`
	Next      string              `json:"next,omitempty"`
	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"`
	UID          string    `json:"uid,omitempty"`
	StartedAt    time.Time `json:"started_at,omitempty,omitzero"`
	Phase        string    `json:"phase,omitempty"`
	Node         string    `json:"node,omitempty"`
	RestartCount int64     `json:"restart_count"`
	CreatedAt    time.Time `json:"created_at,omitempty,omitzero"`
}

WorkloadPod captures status and placement for one related pod.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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