feat(kubernetes): add the autoscaler, policy, networking and Karpenter kinds (#91)

Author: liamcervante

pkg/tree/kubernetes/autoscaling/autoscaling.go

@@ -0,0 +1,74 @@
+// Package autoscaling models the Kubernetes autoscalers as a service in the
+// tree. Unlike the apps, batch and core groups, its members provision nothing
+// and cost nothing directly — they are held because they decide whether a
+// change to a workload's manifest has any effect.
+//
+// A rightsizing recommendation edits the requests and limits declared on a
+// workload. An autoscaler attached to that workload can overwrite those values
+// at admission (VerticalPodAutoscaler) or make the declared replica count dead
+// config (HorizontalPodAutoscaler). Either way a pull request that edits the
+// manifest changes a number the cluster ignores, and the finding never
+// resolves. That is a correctness problem rather than a coverage one, which is
+// why these are in the tree despite carrying no cost of their own.
+//
+// The two kinds are separate Kubernetes API groups — HorizontalPodAutoscaler is
+// autoscaling/v2, built in; VerticalPodAutoscaler is autoscaling.k8s.io/v1, a
+// CRD installed with the VPA controller. They share this package because they
+// are the same concern from the tree's point of view: something other than the
+// manifest is deciding a workload's resources.
+//
+// Each slice is tagged with the kind, which becomes the resource Type on the
+// wire — mirroring the apps, batch and core groups.
+package autoscaling
+
+import (
+	"github.com/infracost/go-proto/pkg/tree/value"
+)
+
+// Autoscaling is the group holding the Kubernetes autoscaler kinds.
+type Autoscaling struct {
+	VerticalPodAutoscalers   []VerticalPodAutoscaler   `tree:"verticalpodautoscaler"`
+	HorizontalPodAutoscalers []HorizontalPodAutoscaler `tree:"horizontalpodautoscaler"`
+}
+
+// TargetRef identifies the workload an autoscaler acts on — spec.targetRef on a
+// VerticalPodAutoscaler, spec.scaleTargetRef on a HorizontalPodAutoscaler.
+//
+// This is the join back to the workload, and it is a pointer rather than an
+// identity: the autoscaler names the workload, so finding the autoscaler that
+// governs a given Deployment means searching by these fields rather than by the
+// autoscaler's own name, which is arbitrary and frequently unrelated.
+//
+// Kind and Name are namespace-scoped — an autoscaler can only target a workload
+// in its own namespace — so the namespace on the embedding kind's ObjectMeta
+// completes the reference.
+type TargetRef struct {
+	// APIVersion is the target's apiVersion, e.g. "apps/v1". Optional in both
+	// CRDs and frequently omitted, so an empty value means unspecified rather
+	// than absent.
+	APIVersion value.String `tree:"api_version"`
+
+	// Kind is the target's kind, e.g. "Deployment" or "StatefulSet". Recorded
+	// verbatim from the manifest, so it keeps the CamelCase the Kubernetes API
+	// uses rather than the lower-cased form the tree's addresses carry.
+	Kind value.String `tree:"kind"`
+
+	// Name is the target workload's metadata.name.
+	Name value.String `tree:"name"`
+}
+
+// ResourceAmounts is a CPU/memory pair as an autoscaler or a LimitRange states
+// it, in the same base units the workload containers use — CPU in millicores,
+// memory in bytes — so a bound can be compared against a container's request
+// without converting first.
+//
+// Both are optional in every position they appear: a policy may bound only CPU,
+// or only memory. Note that absence is not representable on its own — an unset
+// value serializes as a zero — and a zero bound reads as "pinned to nothing"
+// rather than "unbounded". Where the distinction matters the parser marks the
+// value it filled in with flag.Synthetic, which does survive, the same way
+// meta.ObjectMeta.Namespace records an assumed namespace.
+type ResourceAmounts struct {
+	CPUMillicores value.Int `tree:"cpu_millicores"`
+	MemoryBytes   value.Int `tree:"memory_bytes"`
+}

pkg/tree/kubernetes/autoscaling/horizontal_pod_autoscaler.go

@@ -0,0 +1,158 @@
+package autoscaling
+
+import (
+	"github.com/infracost/go-proto/pkg/tree/kubernetes/meta"
+	"github.com/infracost/go-proto/pkg/tree/resource"
+	"github.com/infracost/go-proto/pkg/tree/value"
+)
+
+// MetricSourceType values for a HorizontalPodAutoscaler's spec.metrics[].type.
+// The distinction that matters is whether the metric is a share of what the
+// container requests: only Resource and ContainerResource are, and only those
+// couple the replica count to the numbers a rightsizing recommendation edits.
+const (
+	// MetricSourceTypeResource scales on a resource the pod requests — cpu or
+	// memory — summed across the pod's containers.
+	MetricSourceTypeResource = "Resource"
+
+	// MetricSourceTypeContainerResource is the same, narrowed to one named
+	// container rather than the pod total. On a multi-container pod this says
+	// which container's request the replica count actually keys off.
+	MetricSourceTypeContainerResource = "ContainerResource"
+
+	// MetricSourceTypePods scales on a custom per-pod metric averaged over the
+	// pods. Not a share of anything requested, so it does not couple to the
+	// container's resources.
+	MetricSourceTypePods = "Pods"
+
+	// MetricSourceTypeObject scales on a metric describing some other
+	// Kubernetes object. The described object is not modelled.
+	MetricSourceTypeObject = "Object"
+
+	// MetricSourceTypeExternal scales on a metric from outside the cluster — a
+	// queue depth, a request rate. The replica count is then driven by
+	// something no manifest describes.
+	MetricSourceTypeExternal = "External"
+)
+
+// MetricTargetType values for a metric's target.type — which of the target's
+// value fields the manifest set.
+const (
+	// MetricTargetTypeUtilization targets a percentage of the requested
+	// resource. This is the setpoint that makes observed headroom expected
+	// rather than wasted, and it is only valid on Resource and
+	// ContainerResource metrics.
+	MetricTargetTypeUtilization = "Utilization"
+
+	// MetricTargetTypeValue targets a raw metric value.
+	MetricTargetTypeValue = "Value"
+
+	// MetricTargetTypeAverageValue targets a raw metric value averaged over the
+	// pods.
+	MetricTargetTypeAverageValue = "AverageValue"
+)
+
+// HorizontalPodAutoscaler is an autoscaling/v2 HorizontalPodAutoscaler.
+//
+// It provisions nothing and costs nothing, and unlike a VerticalPodAutoscaler
+// it does not touch container requests — so it does not invalidate a rightsizing
+// recommendation. What it invalidates is the workload's declared replica count:
+// once an HPA governs a Deployment, spec.replicas in the manifest is read at
+// creation and then never again, and a recommendation that proposes editing it
+// is proposing a change with no effect.
+//
+// It also changes how a per-pod saving becomes a real one. Shrinking a request
+// on an HPA-governed workload does not reduce the pod count, it makes each pod
+// cheaper to schedule and lets the same node fit more of them — so the saving
+// only banks if the node count follows, which is the node-coupling question
+// rather than the pod one.
+//
+// MinReplicas and MaxReplicas are held for that reason: they bound how much of
+// the estate the workload can occupy, which is what a saving is computed
+// against.
+//
+// Metrics are held for a sharper one. A utilization target is a setpoint rather
+// than an observation: an HPA holding a Deployment at 50% CPU produces a
+// workload sitting at 50% of its request by design, and a rightsizing pass that
+// reads that as half wasted will propose halving the request. Halving it puts
+// utilization back at the target, the HPA scales out, and the same spend
+// returns as more smaller pods. The observed utilization is something the
+// metrics pipeline reports and reports better; the target it is being held at
+// exists only in the manifest, the same way a VerticalPodAutoscaler's
+// updateMode does.
+//
+// The kind, address ([namespace, kind, name]) and source range live on the
+// embedded resource.Resource; the HPA's own name and namespace on the embedded
+// meta.ObjectMeta; and its Kubernetes labels are stored as the base resource's
+// Tags.
+type HorizontalPodAutoscaler struct {
+	resource.Resource `tree:"-"`
+	meta.ObjectMeta   `tree:"-"`
+
+	// ScaleTargetRef is spec.scaleTargetRef — the workload this HPA scales.
+	// Required by the API, so an empty value means a malformed manifest.
+	ScaleTargetRef TargetRef `tree:"scale_target_ref"`
+
+	// MinReplicas is spec.minReplicas. Optional, defaulting to 1 when omitted —
+	// so unset is not zero, and reading it as zero would suggest the workload
+	// can scale to nothing, which it cannot without a separate feature gate.
+	MinReplicas value.Int `tree:"min_replicas"`
+
+	// MaxReplicas is spec.maxReplicas, required by the API. This is the ceiling
+	// a worst-case cost is computed against.
+	MaxReplicas value.Int `tree:"max_replicas"`
+
+	// Metrics are spec.metrics — what the controller scales on, and the value
+	// it holds that signal at. Empty when the manifest states none, in which
+	// case the controller falls back to a default CPU utilization target that
+	// is cluster configuration rather than repository state.
+	Metrics []Metric `tree:"metrics"`
+
+	// Annotations are the HPA's Kubernetes annotations, surfaced verbatim.
+	Annotations []resource.Tag `tree:"annotations"`
+}
+
+// Metric is one entry of a HorizontalPodAutoscaler's spec.metrics.
+//
+// The API models this as a five-way union — one nested block per source type,
+// each with a target of its own. It is flattened here the way an Ingress path
+// flattens its backend: Type says which block the manifest wrote, and the
+// fields below carry whichever parts of it mean anything. The described object
+// on an Object metric is not modelled; such a metric is recorded so a reader
+// knows the replica count is driven from somewhere outside the workload, not so
+// that it can be resolved.
+type Metric struct {
+	// Type is the metric source: one of the MetricSourceType constants above.
+	Type value.String `tree:"type"`
+
+	// Name is what the metric is called, which is a different thing per Type.
+	// On Resource and ContainerResource it is the resource name — "cpu" or
+	// "memory", matching the keys a container's own requests use. On Pods,
+	// Object and External it is the custom metric's name, which is arbitrary.
+	Name value.String `tree:"name"`
+
+	// ContainerName is the container a ContainerResource metric measures, and
+	// empty on every other type. This is the container whose request the
+	// replica count keys off, which on a multi-container pod need not be the
+	// one a rightsizing recommendation would otherwise pick.
+	ContainerName value.String `tree:"container_name"`
+
+	// TargetType is which kind of target the metric states: one of the
+	// MetricTargetType constants above.
+	TargetType value.String `tree:"target_type"`
+
+	// TargetUtilization is target.averageUtilization as a percentage, so 50
+	// means 50%. Set only where TargetType is Utilization, which is the case
+	// that decides whether observed headroom is waste or the configuration
+	// working as intended.
+	//
+	// Unset serializes as a zero, and zero is not a target anything states, so
+	// read TargetType rather than testing this for absence.
+	TargetUtilization value.Int `tree:"target_utilization"`
+
+	// TargetValue is target.value or target.averageValue, whichever TargetType
+	// names, kept as the quantity string the manifest wrote. Custom and
+	// external metrics carry arbitrary units that nothing here can normalise,
+	// so this is not converted to a number the way CPU and memory are.
+	TargetValue value.String `tree:"target_value"`
+}

pkg/tree/kubernetes/autoscaling/vertical_pod_autoscaler.go

@@ -0,0 +1,154 @@
+package autoscaling
+
+import (
+	"github.com/infracost/go-proto/pkg/tree/kubernetes/meta"
+	"github.com/infracost/go-proto/pkg/tree/resource"
+	"github.com/infracost/go-proto/pkg/tree/value"
+)
+
+// UpdateMode values for a VerticalPodAutoscaler's spec.updatePolicy.updateMode.
+// The distinction that matters is whether the controller writes requests back
+// onto pods: only Off leaves the manifest's values in force.
+const (
+	// UpdateModeOff computes recommendations and does nothing with them. The
+	// manifest's requests are what the pods run with, so editing the manifest
+	// works normally — a VPA in this mode is an observation, not an obstacle.
+	UpdateModeOff = "Off"
+
+	// UpdateModeInitial applies recommendations at pod creation only. Existing
+	// pods keep their current requests; the next rollout takes the
+	// controller's numbers rather than the manifest's.
+	UpdateModeInitial = "Initial"
+
+	// UpdateModeRecreate applies recommendations at pod creation and evicts
+	// running pods whose requests drift far enough from them.
+	UpdateModeRecreate = "Recreate"
+
+	// UpdateModeAuto is the default when updatePolicy is omitted entirely, and
+	// currently behaves as Recreate. Note the consequence for parsing: a VPA
+	// with no updatePolicy block is not "unset" but "Auto", so treating an
+	// absent mode as harmless gets the common case backwards.
+	UpdateModeAuto = "Auto"
+)
+
+// ContainerPolicyMode values for a container policy's mode field.
+const (
+	// ContainerPolicyModeAuto applies the VPA's recommendations to this
+	// container. The default when a container policy omits mode.
+	ContainerPolicyModeAuto = "Auto"
+
+	// ContainerPolicyModeOff exempts this container, so its manifest requests
+	// stand even when the VPA as a whole is in an applying mode. A workload can
+	// therefore be partly governed: a sidecar left to the VPA and the app
+	// container opted out, or the reverse.
+	ContainerPolicyModeOff = "Off"
+)
+
+// ControlledValues values for a container policy's controlledValues field — how
+// far the controller's writes reach into the container's resources.
+const (
+	// ControlledValuesRequestsAndLimits lets the controller write both requests
+	// and limits, scaling the limit to preserve the ratio the manifest
+	// declared. This is the default when the field is omitted, so an absent
+	// controlledValues means the manifest's limits are overwritten too.
+	ControlledValuesRequestsAndLimits = "RequestsAndLimits"
+
+	// ControlledValuesRequestsOnly leaves limits alone. An edit to a
+	// container's limits then survives, though an edit to its requests still
+	// does not.
+	ControlledValuesRequestsOnly = "RequestsOnly"
+)
+
+// VerticalPodAutoscaler is an autoscaling.k8s.io VerticalPodAutoscaler — a CRD
+// installed alongside the VPA controller, not a built-in kind.
+//
+// It provisions nothing and costs nothing. It is in the tree because in every
+// mode but Off it sets container requests at admission, which means a
+// recommendation that edits the workload's manifest changes a value the cluster
+// then overwrites. The pull request merges, the pods keep their old sizes, and
+// the finding never resolves. Nothing in the metrics reports that a VPA exists,
+// so the manifest is the only place this is visible.
+//
+// Reading it in the other direction is the useful one: given a workload, is
+// there a VPA whose TargetRef names it, and if so does anything exempt the
+// container and resource being recommended on — UpdateMode Off for the VPA as a
+// whole, or a container policy narrower than that. It decides whether the
+// workload is fixable by editing code at all, or whether the recommendation
+// belongs in the VPA's own resource policy instead.
+//
+// The kind, address ([namespace, kind, name]) and source range live on the
+// embedded resource.Resource; the VPA's own name and namespace on the embedded
+// meta.ObjectMeta; and its Kubernetes labels are stored as the base resource's
+// Tags.
+type VerticalPodAutoscaler struct {
+	resource.Resource `tree:"-"`
+	meta.ObjectMeta   `tree:"-"`
+
+	// TargetRef is spec.targetRef — the workload this VPA governs. Required by
+	// the CRD, so an empty value means the manifest is malformed rather than
+	// that the VPA applies broadly.
+	TargetRef TargetRef `tree:"target_ref"`
+
+	// UpdateMode is spec.updatePolicy.updateMode: one of the UpdateMode
+	// constants above.
+	//
+	// An absent updatePolicy means Auto, not "no mode" — the emptiest possible
+	// VPA manifest is one of the applying ones. Whether the parser records that
+	// default explicitly or leaves the value unset for the consumer to
+	// interpret is the parser's decision; either way an empty value must not be
+	// read as Off.
+	UpdateMode value.String `tree:"update_mode"`
+
+	// ContainerPolicies is spec.resourcePolicy.containerPolicies, empty when the
+	// VPA states no per-container policy. Each entry can exempt a container or
+	// bound what the controller is allowed to set for it.
+	ContainerPolicies []ContainerPolicy `tree:"container_policies"`
+
+	// Annotations are the VPA's Kubernetes annotations, surfaced verbatim.
+	Annotations []resource.Tag `tree:"annotations"`
+}
+
+// ContainerPolicy is one entry of a VerticalPodAutoscaler's
+// spec.resourcePolicy.containerPolicies — the per-container overrides on what
+// the controller may do.
+//
+// These matter to a recommendation three times over. Mode decides whether a
+// given container is governed at all. ControlledResources and ControlledValues
+// narrow that to which of its numbers are governed, so a container can be
+// governed for memory and left alone for CPU. And the Min/Max bounds are the
+// range the controller will keep it inside — a recommendation outside those
+// bounds cannot take effect even where the VPA is applying.
+type ContainerPolicy struct {
+	// ContainerName is the container this policy applies to. The wildcard "*"
+	// matches every container in the pod, and is how a whole workload is
+	// exempted with a single entry — so this is not always a real container
+	// name.
+	ContainerName value.String `tree:"container_name"`
+
+	// Mode is the policy's mode: one of the ContainerPolicyMode constants
+	// above. Empty means Auto, the CRD's default.
+	Mode value.String `tree:"mode"`
+
+	// ControlledResources is the policy's controlledResources — which of the
+	// container's resources the controller sets, by resource name ("cpu",
+	// "memory").
+	//
+	// This is Mode narrowed to a single resource: a policy listing only
+	// "memory" leaves CPU requests alone, so a CPU rightsizing recommendation
+	// on that container is actionable while a memory one is not. Nil means the
+	// field was omitted, which defaults to both — so absence is the governing
+	// case, and must not be read as controlling nothing.
+	ControlledResources *value.List[string] `tree:"controlled_resources"`
+
+	// ControlledValues is the policy's controlledValues: one of the
+	// ControlledValues constants above. Empty means RequestsAndLimits, the
+	// CRD's default — so as with UpdateMode an absent value is the wider of the
+	// two, and reading empty as requests-only gets it backwards.
+	ControlledValues value.String `tree:"controlled_values"`
+
+	// MinAllowed and MaxAllowed bound what the controller may set. Either side
+	// of either pair may be unset, meaning unbounded in that direction — which
+	// is why these are not plain numbers; see ResourceAmounts.
+	MinAllowed ResourceAmounts `tree:"min_allowed"`
+	MaxAllowed ResourceAmounts `tree:"max_allowed"`
+}