k8s

README

k8s

Kubernetes clusters as Pulumi components, behind one provider-neutral contract.

Provisions the cluster and the things a cluster needs around it — the network, the peering, a registry pull-through cache, a backup store — as Pulumi ComponentResources with documented child names and names the caller supplies. EKS Auto Mode is the first provider; self-hosted Talos is the second. Whichever provider made it, the consumer of a cluster sees the same thing: a name, an endpoint, a CA, an OIDC issuer and a set of capabilities.

What	Where
Go module github.com/truvity/k8s	go get github.com/truvity/k8s@v0.1.0
pkg/cluster — the provider-neutral contract: outputs and capabilities, with a validator	Go package, no cloud dependency
pkg/aws/pullthroughcache — ECR pull-through cache rules and their credential secrets, truvity:k8s/aws:PullThroughCache	Pulumi component, unreleased
pkg/aws/backupbucket — DEPRECATED, moved to truvity/cnpg pkg/aws/backupstore; a versioned, KMS-encrypted cross-account backup bucket with version deletion denied, optional Object Lock and cross-region replica, truvity:k8s/aws:BackupBucket	Pulumi component, unreleased
pkg/aws/vpcpeering — a cross-account, cross-region VPC peering with its routes, DNS-resolution options and private-zone associations, truvity:k8s/aws:VpcPeering	Pulumi component, unreleased
pkg/aws/vpc — a VPC with its subnets, route tables, gateways, NAT, IPv6, hardened defaults, gateway endpoints and flow logs, truvity:k8s/aws:Vpc	Pulumi component, unreleased
pkg/aws/podidentity — an EKS Pod Identity role with its trust policy, permissions and one association per service account, truvity:k8s/aws:PodIdentity	Pulumi component, unreleased
pkg/aws/ekscluster — an EKS Auto Mode cluster with its secrets key, cluster and node roles and control-plane log group, truvity:k8s/aws:EksCluster	Pulumi component, unreleased
pkg/aws/eksoidc — the external OIDC issuer association of an EKS cluster, truvity:k8s/aws:EksOidc	Pulumi component, unreleased
pkg/aws/ackfactory — the AWS identity of the ACK controllers: the IAM and EKS controller roles, the service controllers' roles (adopting what is live) and the per-project capability roles; plain functions, names are API	Go package, unreleased
charts/cluster-baseline — Pod Security Admission labels per namespace (default level, reasoned exemptions, warn-first rollout), a guard, and opt-in default-deny, quota and limit range	Helm chart, oci://ghcr.io/truvity/charts/cluster-baseline, unreleased
charts/cluster-foundation — Namespaces with their Pod Security labels and deletion protection, ClusterRoleBindings, StorageClasses and the EKS Auto Mode NetworkPolicy switch, every name a value	Helm chart, oci://ghcr.io/truvity/charts/cluster-foundation, unreleased
charts/cluster-network-policies — a cluster's own NetworkPolicies as data: selector, policy types and rules per entry, each with a required reason, sync wave and optional deletion protection	Helm chart, oci://ghcr.io/truvity/charts/cluster-network-policies, unreleased
charts/eks-auto-node-pools — Karpenter NodePools and NodeClasses for EKS Auto Mode, one disruption budget per pool, subnet tags and roles as values	Helm chart, oci://ghcr.io/truvity/charts/eks-auto-node-pools, unreleased
charts/guardrails-projects — the guardrails of every project namespace from a list of project rows: Namespace with labels and Pod Security, baseline NetworkPolicy (shared rules filtered by the row's kind), quota and LimitRange by profile, Roles and RoleBindings, an ACK IAMRoleSelector for the row's ceiling role; data-bearing objects carry Prune=false,Delete=false	Helm chart, oci://ghcr.io/truvity/charts/guardrails-projects
charts/tenancy — DEPRECATED (window): per-tenant NetworkPolicy, quota, RBAC, NATS account and Pod Identity and the Namespace itself with its Pod Security labels, one profile per tier, every name a value	Helm chart, oci://ghcr.io/truvity/charts/tenancy, unreleased
charts/volume-snapshot-crds — the CSI external-snapshotter CustomResourceDefinitions, mirrored verbatim at the upstream version pinned in crdctl.yaml	Helm chart, oci://ghcr.io/truvity/charts/volume-snapshot-crds
charts/cilium-crds — the Cilium CustomResourceDefinitions, mirrored verbatim at the upstream version pinned in crdctl.yaml	Helm chart, oci://ghcr.io/truvity/charts/cilium-crds

The two CRD charts carry the UPSTREAM version they mirror, not this repository's: a release publishes each only if that version is not in the registry yet. Their CRDs are generated by just crds (which also sets the chart version) and committed; just crds-check proves they still equal the upstream.

The provider packages (EKS first) are not in v0.1.0; they arrive one reviewed extraction at a time and are listed in the CHANGELOG. The extracted components so far, the pull-through cache, the backup bucket, the VPC peering, the VPC and the Pod Identity role, are unreleased.

Who it is for

A team that runs its own clusters from a Pulumi program in Go and wants the cluster, its network and its supporting pieces as reusable components, rather than as a copy of another team's infrastructure repository. It assumes you already have a Pulumi backend, cloud credentials and a naming scheme; it chooses none of them.

It deliberately does not pick your names, your address ranges, your permission boundaries or your accounts, does not install workloads into the cluster. The charts render cluster objects and never workloads: cluster-baseline labels namespaces someone else owns, cluster-foundation renders the foundation objects (namespaces, role bindings, storage classes), eks-auto-node-pools the Karpenter pools and tenancy what each tenant namespace needs around it; see the reference.

The model

Three ideas.

A component is a Pulumi ComponentResource with a documented set of child resources. The child names are part of the API: a caller that adopts a component over existing infrastructure relies on them to keep its resources' URNs, through aliases the component declares.

A contract is what every provider component reports, in pkg/cluster.Outputs: name, endpoint, certificate authority, OIDC issuer and the capabilities the cluster offers (node pools, storage, network policy, workload identity, load balancing, API access). A consumer asks for a capability; it does not branch on the provider.

A caller-supplied name is any name, tag, range or boundary a component would otherwise have to choose. Components take them as inputs; none has a default that belongs to one estate.

Install and a worked example

go get github.com/truvity/k8s@v0.1.0

The contract is what a consumer of any provider writes against:

out := cluster.Outputs{
	Provider:                cluster.ProviderEKS,
	Name:                    "example",
	Endpoint:                "https://api.example.test",
	CertificateAuthorityPEM: caPEM,
	OIDCIssuer:              "https://oidc.example.test/id/abc",
	Capabilities:            cluster.NewCapabilities(cluster.NodePools, cluster.WorkloadIdentity),
}
if err := out.Validate(); err != nil {
	return err // the provider reported something a consumer cannot use
}
if out.Capabilities.Has(cluster.WorkloadIdentity) {
	// wire pod identities against out.OIDCIssuer
}

Consumers

The estate this is being extracted from will adopt it cluster by cluster, each adoption proven by an empty Pulumi preview (see docs/decisions/0002-urn-stability.md). No consumer is recorded at v0; a repository that adopts it adds a line here.

Neighbours

• pulumi-pipeline — runs many Pulumi stacks as one pipeline with refusal gates; the natural driver for programs that use these components.
• policy — the contracts this repository is held to (docs/contracts/component.md).
• ci-workflows — the shared CI and release workflows this repository calls.

Documentation

• docs/adoption.md — using a component, adopting one over existing infrastructure, and every breaking upgrade.
• docs/reference.md — the Go types and the capability set.
• docs/safety.md — what is refused and what must never be done to a cluster's resources.
• docs/doctrine.md — why it is shaped this way.
• docs/decisions/ — the decisions, one page each.
• SECURITY.md and CONTRIBUTING.md.

The rule that makes this repository public

Mechanism only. A cluster's name, its address ranges, its account, its permission boundaries and every tag pattern are the caller's: an input, a hook the caller supplies, or a file the caller commits. Nothing here defaults to one estate's value, and the tests never reach a real cloud — providers run against Pulumi mocks and cluster behaviour against kind. hack/leak-canary.sh enforces the mechanical half over tracked files and runs in the gate.

Status

v0: the API may still move in a minor release, and every move is a Breaking: bullet in the CHANGELOG. Today the module holds the contract only; providers are added by extraction from a running estate, each with its URN-stability proof.

Development

devbox shell        # pins every tool
just check          # build, test, lint, leak-canary
just vuln           # reachable Go advisories (its own workflow in CI, not in check)

Releasing

Releases are a v* tag, which the shared release workflow turns into the Go module version and a GitHub Release. Automatic patch releases are not armed; the first release and every minor and major are hand-cut tags.

Licence

MIT. See LICENSE.