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

index

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: 7 Imported by: 0

Documentation

Index

Constants

View Source
const (
	MaxLabels        = maxLabels
	MaxSummaryFields = maxSummaryFields
	MaxOwners        = maxOwners
	MaxImages        = maxImages
	MaxImageBytes    = maxImageBytes
)

The per-record bounds every projection must respect. A projection that keeps more than these would hand the index a record it has to reject, so the projection reads these instead of guessing a larger size.

Variables

View Source
var (
	ErrInvalidRecord = errors.New("kubernetes index: invalid record")
	ErrRecordLimit   = errors.New("kubernetes index: record limit exceeded")
	ErrScopeLimit    = errors.New("kubernetes index: scope limit exceeded")
	// ErrKindNotServed reports that the cluster does not serve this kind, so a
	// caller never claims a listing that did not happen. The kind is still
	// recorded as known and empty; its first real listing later is a baseline,
	// not a wave of created changes.
	ErrKindNotServed = errors.New("kubernetes index: kind not served by the cluster")
)
View Source
var SyncSteps = []string{"connected", "listing", "building", "metrics"}

SyncSteps are the first-sync steps in execution order: connect to the cluster, list resources, build the projections that are published, and read CPU and memory usage (which runs after the first publication).

Functions

func RecordFits added in v1.4.32

func RecordFits(record Record) bool

RecordFits reports whether the index can hold this record, so a caller can check one record without ingesting it and without asking the index to reject a whole listing.

func RecordWithinBudget added in v1.4.32

func RecordWithinBudget(record Record) bool

RecordWithinBudget reports whether a record fits the per-record byte budget, including the allowance for container log metadata. A projection uses it to bound itself, because a record the index refuses costs the whole kind.

Types

type CaptureStatus added in v1.4.31

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

type CaptureVerificationStatus added in v1.4.31

type CaptureVerificationStatus struct {
	Stage      string `json:"stage"`
	HTTPStatus int    `json:"http_status,omitempty"`
}

type ContainerState added in v1.4.31

type ContainerState struct {
	Ready              bool      `json:"ready"`
	Running            bool      `json:"running"`
	StartedAt          time.Time `json:"started_at,omitempty,omitzero"`
	StateKnown         bool      `json:"state_known,omitempty"`
	Name               string    `json:"name"`
	Init               bool      `json:"init,omitempty"`
	CurrentTermination bool      `json:"current_termination,omitempty"`
	WaitingReason      string    `json:"waiting_reason,omitempty"`
	TerminatedReason   string    `json:"last_terminated_reason,omitempty"`
	ExitCode           int32     `json:"last_terminated_exit_code,omitempty"`
	Signal             int32     `json:"last_terminated_signal,omitempty"`
	TerminatedAt       time.Time `json:"last_terminated_at,omitempty,omitzero"`
	RestartCount       int32     `json:"restart_count"`
}

type Delta

type Delta struct {
	Kind   string  `json:"kind"`
	Op     string  `json:"op,omitempty"`
	Old    *Record `json:"old,omitempty"`
	New    *Record `json:"new,omitempty"`
	Resync bool    `json:"resync,omitempty"`
}

type Index

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

func New

func New(maxRecords int) *Index

func NewUnbounded added in v1.4.32

func NewUnbounded() *Index

NewUnbounded retains the per-record validation budget without limiting the number of safe projections in a complete background inventory.

func Restore added in v1.4.32

func Restore(snapshot Snapshot) (*Index, error)

Restore validates a persisted projected generation without turning a failed refresh into a successful observation or resetting owner evidence timestamps.

func (*Index) Ingest

func (index *Index) Ingest(kind string, records []Record, complete bool, observedAt time.Time) error

func (*Index) KindStatus

func (index *Index) KindStatus(kind string) (KindStatus, bool)

func (*Index) Refresh

func (index *Index) Refresh(ctx context.Context, kind string, interval time.Duration, now time.Time, load Loader) error

Refresh loads one kind at most once per interval. Concurrent readers wait for the same bounded load instead of issuing duplicate cluster requests.

func (*Index) RefreshGuarded added in v1.4.31

func (index *Index) RefreshGuarded(ctx context.Context, kind string, interval time.Duration, now time.Time, load Loader, guard func(func() error) error) error

func (*Index) Snapshot

func (index *Index) Snapshot() Snapshot

func (*Index) Status

func (index *Index) Status(now time.Time) Status

Status returns bounded freshness information for the current indexed view.

func (*Index) Subscribe

func (index *Index) Subscribe(buffer int) (<-chan Delta, func())

Subscribe returns a bounded stream of index deltas and an idempotent cancel function.

type KindStatus

type KindStatus struct {
	State string `json:"state"`
	// A time that was never observed is omitted rather than serialized as
	// 0001-01-01T00:00:00Z, so no client can render it as a date.
	ObservedAt time.Time `json:"observed_at,omitzero"`
	// CompletedAt bounds when records from the latest successful (possibly
	// partial) load became visible. ObservedAt is the LIST start, not its end.
	CompletedAt   time.Time `json:"completed_at,omitzero"`
	LastAttemptAt time.Time `json:"last_attempt_at,omitzero"`
	Records       int       `json:"records"`
	Partial       bool      `json:"partial"`
	Error         string    `json:"error,omitempty"`
	// FailingSince is when this failure began. It is set on the transition into
	// a failing state or class and kept until the kind recovers, so a surface can
	// say how long a kind has been failing instead of how long ago it retried.
	FailingSince time.Time `json:"failing_since,omitzero"`
	// Skipped counts records the latest listing could not keep. It is never
	// zero for an incomplete report: a dropped record is always counted, so a
	// kind that lost data says so instead of looking complete.
	Skipped int `json:"skipped,omitempty"`
	// Absent marks a kind the cluster does not serve: it was never listed, so
	// the first listing that comes back later is a baseline rather than a wave
	// of created changes.
	Absent bool `json:"absent,omitempty"`
	// CycleFailure marks a state that came from the failure of a whole inventory
	// cycle rather than from this kind's own listing. A cycle that cannot run
	// says the connector could not read anything at all, so it stays a fault even
	// when its class is a permission class: a per-kind capability gap and a dead
	// credential are different problems with different remedies.
	CycleFailure bool `json:"cycle_failure,omitempty"`
	// contains filtered or unexported fields
}

type Loader

type Loader func(context.Context) ([]Record, bool, error)

type OwnerRef

type OwnerRef struct {
	APIVersion      string
	Controller      bool
	ControllerKnown bool
	Kind            string
	Namespace       string
	Name            string
	UID             string
}

type Record

type Record struct {
	APIVersion      string
	UID             string
	Kind            string
	Namespace       string
	Name            string
	ResourceVersion string
	Generation      int64
	Labels          map[string]string
	Selector        map[string]string
	References      map[string][]string
	Owners          []OwnerRef
	// OwnerObservedAt is the first load completion for these owner references.
	// Re-lists preserve it; a new UID or changed owner references reset it.
	OwnerObservedAt         time.Time
	Target                  *OwnerRef
	CreatedAt               time.Time
	Phase                   string
	EventType               string
	NodeName                string
	NodeReady               bool
	Images                  []string
	Summary                 map[string]string
	Replicas                int32
	Ready                   int32
	Available               int32
	ObservedGeneration      int64
	RequestedCPUMilli       int64
	RequestedMemoryByte     int64
	AllocatableCPUMilli     int64
	AllocatableMemory       int64
	Health                  string
	Containers              []ContainerState
	LogContainers           []ContainerState
	MainContainer           string
	LogContainersPartial    bool
	ReadyStatus             string
	ReadyTransitionAt       time.Time
	ProgressingStatus       string
	ProgressingReason       string
	ProgressingTransitionAt time.Time
	AvailableStatus         string
	AvailableTransitionAt   time.Time
	UpdateRevision          string
	CurrentRevision         string
	Revision                string
	Updated                 int32
	EventFirstAt            time.Time
	EventLastAt             time.Time
	EventCount              int32
}

type Registry

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

func NewRegistry

func NewRegistry(maxScopes, maxRecords int) *Registry

func NewUnboundedRegistry added in v1.4.32

func NewUnboundedRegistry(maxScopes int) *Registry

NewUnboundedRegistry scopes inventories without limiting their record count.

func (*Registry) ForScope

func (registry *Registry) ForScope(scope Scope) (*Index, error)

type Scope

type Scope struct {
	OrgID        string
	ClusterID    string
	CredentialID string
}

type Snapshot

type Snapshot struct {
	Records []Record
	Kinds   map[string]KindStatus
}

type Status

type Status struct {
	State      string                `json:"state"`
	AgeSeconds float64               `json:"age_s"`
	Partial    bool                  `json:"partial"`
	Kinds      map[string]KindStatus `json:"kinds"`
	Capture    *CaptureStatus        `json:"capture,omitempty"`
	Progress   *SyncProgress         `json:"progress,omitempty"`
	// Pending lists requested resource IDs not listed yet; PendingKinds counts
	// every resource type the cluster's published inventory still lacks.
	Pending      []string `json:"pending,omitempty"`
	PendingKinds int      `json:"pending_kinds,omitempty"`
}

type SyncProgress added in v1.4.32

type SyncProgress struct {
	// Step is the step in progress, one of SyncSteps.
	Step      string   `json:"step"`
	StepIndex int      `json:"step_index"`
	StepTotal int      `json:"step_total"`
	StepsDone []string `json:"steps_done"`
	// Counts holds records listed so far per Kubernetes kind. A kind appears
	// once its list completes.
	Counts map[string]int `json:"counts"`
	// KindsDone counts resolved checks, including absent APIs and unreadable kinds;
	// Counts contains only successfully listed records.
	KindsDone      int                `json:"kinds_done"`
	KindsTotal     int                `json:"kinds_total"`
	ClusterVersion string             `json:"cluster_version,omitempty"`
	NodeCount      *int               `json:"node_count,omitempty"`
	StartedAt      time.Time          `json:"started_at"`
	UpdatedAt      time.Time          `json:"updated_at"`
	RemainingKinds []string           `json:"remaining_kinds,omitempty"`
	KindStatus     map[string]string  `json:"kind_status,omitempty"`
	PhaseStatus    map[string]string  `json:"phase_status,omitempty"`
	PhaseSeconds   map[string]float64 `json:"phase_seconds,omitempty"`
}

SyncProgress describes a cluster's first inventory sync until the first ready generation has been published. It only reports what the background sync has already observed; it never claims the data is complete.

Jump to

Keyboard shortcuts

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