Documentation
¶
Overview ¶
Package kube talks to the apiserver and projects what it finds into model.Snapshot.
Everything here is read-only. That is not a convention: TestNoMutatingVerbs walks this package's AST and fails on any call to a mutating client verb. v0.1 runs under a developer kubeconfig with full cluster-admin, so RBAC will not hold that line for us — the binary has to.
Index ¶
- func RenderLogs(b *model.LogBundle) string
- type AmbiguousError
- type Client
- func (c *Client) Calls() int64
- func (c *Client) Gather(ctx context.Context, ref Ref) (*model.Snapshot, error)
- func (c *Client) Logs(ctx context.Context, ref Ref, opts LogOptions) (*model.LogBundle, error)
- func (c *Client) Pending(ctx context.Context, ref Ref) ([]*model.PendingReport, error)
- func (c *Client) Resolve(ctx context.Context, query, namespace string) (Ref, error)
- func (c *Client) Trace(ctx context.Context, service, namespace string) (*model.TraceReport, error)
- func (c *Client) Triage(ctx context.Context, namespace string) ([]*model.Snapshot, []string, []string, error)
- func (c *Client) WithTimeout(ctx context.Context) (context.Context, context.CancelFunc)
- type LogOptions
- type Options
- type Ref
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RenderLogs ¶ added in v0.1.2
RenderLogs formats a bundle for a human or a model to read.
Types ¶
type AmbiguousError ¶
type AmbiguousError struct {
Query string
Candidates []Ref
// Noun names what was being resolved. Empty means workloads, which is the common case and
// the wording USAGE documents; trace_service_path resolves Services through the same tiers
// and would otherwise report them as workloads.
Noun string
}
AmbiguousError lists the candidates when a fuzzy name matches more than one workload. Returning the choices beats picking one: during an incident, silently diagnosing the wrong workload costs more than one extra round-trip.
func (*AmbiguousError) Error ¶
func (e *AmbiguousError) Error() string
type Client ¶
type Client struct {
Typed kubernetes.Interface
Metrics metricsv.Interface
Dynamic dynamic.Interface
Context string // resolved context name, for audit logging
// contains filtered or unexported fields
}
Client bundles the three typed clients a gather needs, plus the call budget they share.
func (*Client) Gather ¶
Gather collects everything needed to diagnose one workload and projects it into a Snapshot.
Failures are recorded in Snapshot.Degraded rather than returned. During an incident a partial diagnosis beats no diagnosis — but detectors must consult Snapshot.Missing and dock their confidence, so "we could not see the metrics API" never masquerades as "memory looks fine".
func (*Client) Logs ¶ added in v0.1.2
Logs fetches container output for a workload, choosing the pod, container and instance itself.
The choices are the product. Anyone can call GetLogs; knowing that a crashlooping container's CURRENT instance has produced nothing and the interesting output is in the PREVIOUS one is the part that saves an incident's worth of thrash.
func (*Client) Pending ¶ added in v0.1.16
Pending explains why a workload's pods will not schedule.
Needs data no other path gathers: every node's capacity, and the sum of requests already committed on each one. That second number is why this cannot reuse the workload gather — it requires every pod in the cluster, not just this workload's.
Cost is four list calls regardless of cluster size.
func (*Client) Resolve ¶
Resolve turns a fuzzy query into exactly one Ref.
Accepts "checkout", "checkout-api", "deploy/checkout-api", or "deployment/checkout-api". Matching is tiered — exact name first, then prefix, then substring — and stops at the first tier that produces hits, so an exact name is never made ambiguous by an unrelated substring match.
func (*Client) Trace ¶ added in v0.1.19
Trace follows the request path for one Service and reports where it gives out.
Four list calls regardless of cluster size: Services (which also resolves the name), Ingresses, EndpointSlices, and the pods in the namespace.
The pods are listed unfiltered rather than by the Service's own selector, which costs one list of one namespace and buys the near-miss analysis: a selector that matches nothing is only actionable once you know whether the pods are absent or merely mislabelled, and a selector-filtered list cannot tell those apart because it returns empty either way.
func (*Client) Triage ¶ added in v0.1.10
func (c *Client) Triage(ctx context.Context, namespace string) ([]*model.Snapshot, []string, []string, error)
Triage answers "what is broken right now" across a whole cluster.
It deliberately does NOT loop Gather. A per-workload gather costs ~13 apiserver calls, and a real cluster has hundreds of workloads — 165 on the cluster this was built against, which would be roughly 2,100 calls against a budget of 60, issued precisely when the control plane is already under stress during an incident.
So the data flow is inverted: a fixed handful of cluster-wide list calls, then pods are grouped by owner locally and one synthetic Snapshot is assembled per owner. Cost is constant in the number of workloads. The detectors are reused unchanged, which is the whole reason they were written as pure functions over a Snapshot.
func (*Client) WithTimeout ¶
WithTimeout derives the per-invocation deadline. Callers must use the returned context for every apiserver call so a slow cluster degrades the snapshot instead of hanging the MCP session.
type LogOptions ¶ added in v0.1.2
type LogOptions struct {
Container string // empty means auto-select
Previous *bool // nil means decide from the container's state
TailLines int64 // 0 means a sensible default
SinceSecs int64 // 0 means no lower bound
Budget int // token budget; 0 means the default
}
LogOptions controls log selection. Every field is optional; the zero value means "decide for me", which is the intended path.
type Options ¶
type Options struct {
Kubeconfig string // path; empty means the standard loading rules, then in-cluster
Context string // kubeconfig context name; empty means current-context
Timeout time.Duration // per-invocation deadline for the whole gather
MaxCalls int64 // hard cap on apiserver requests per invocation
}
Options configures cluster access and the blast-radius limits on a single tool invocation.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions are deliberately conservative. A diagnostic tool that DoSes the control plane during an incident is a career-limiting artifact.
Source Files