Components

The “Containers Layer” of the Podplane Architecture is designed as a set of “Components”, categorised into:

1. Core Components required for minimal cluster operation, so you can deploy and schedule Pods.

2. Addon Components for optional functionality to extend cluster capabilities - things like an ingress controller, CSI drivers, and more.

During cluster creation, users are given three initial state options to choose from:

1. Recommended - which includes all Core Components + a small selection of commonly used Addon Components such as Traefik ingress controller. The goal is that deployment templates such as “web” do not require any additional Addon Components to be installed.

2. Minimal - deploys just the Core Components. From there, users can manually install Components using podplane install as required.

3. None - does not install any Podplane Components, meaning you get a bare Kubernetes cluster and Nodes will be NotReady until a CNI is installed and they can become Ready and able to schedule Pods. For advanced users only.

Components are deployed with an opinionated, tested configuration - not the full surface area of each component’s underlying official Helm chart.

Core Components

• coredns for cluster DNS
• cilium for cluster CNI
  • cilium-crds for Cilium CNI
• fluxcd for automated Podplane container-layer upgrades
  • fluxcd-crds for Flux CD
• gateway-api-crds for any ingress controller using Gateway API, particularly Traefik
• platform-components for Podplane component management. This chart creates the Flux source, platform namespaces, and HelmReleases for enabled components.
• platform-rbac for default Podplane platform RBAC and admission policies

Addon Components

Recommended components which can also be installed via podplane install atop the Minimal set:

• agent-sandbox: Agent Sandbox controller for isolated, stateful singleton workloads such as AI agent runtimes
  • agent-sandbox-crds
• cluster-api for the Cluster API core controller
  • cluster-api-crds
• nstance for the Nstance Operator (requires cluster-api)
  • nstance-crds
• cert-manager: cert-manager and cert-manager-csi-driver
  • cert-manager-crds
• platform-certs for default self-signed and ACME certificate issuers, CA, certificates, etc. (requires cert-manager)
• trust-manager: trust-manager by the cert-manager project
  • trust-manager-crds
• platform-trust for default trust bundles (requires trust-manager)
• traefik: Traefik ingress controller

Addon components which can only be installed via podplane install:

• secrets-store-csi-driver: Secrets Store CSI Driver
  • secrets-store-csi-driver-crds
• snapshot: Snapshot controller
  • snapshot-crds
• Cloud Provider CSI Drivers:
  • csi-aws-ebs: AWS EBS CSI Drivers
• metrics-server: Kubernetes Metrics Server
• cluster-autoscaler: Kubernetes Cluster Autoscaler for automatic node scaling via Cluster API
• node-problem-detector: Node Problem Detector for surfacing node hardware/kernel/runtime issues

How It Works

Cluster State Initialization

Cluster state is initialised via the Podplane provider for OpenTofu/Terraform.

The provider uses Podplane seed files to create a Netsy bootstrap.netsy snapshot file, then uploads it to provider-specific object storage (S3 for AWS, GCS for Google Cloud). Before uploading, the provider checks that remote state does not already exist and performs a conditional put so it can never overwrite it by mistake. Netsy also has checks to ensure a bootstrap file is never loaded over existing cluster state.

The Recommended and Minimal options each have their own Podplane seed files. The None option skips cluster seeding entirely.

See Seeds for how seed files, the seeds manifest, the seedgen seed generator utility, and the Terraform provider fit together.

The Platform Component

A core component called platform is a Helm chart that holds all Podplane-related configuration - reserved namespaces, components management, default trust bundles (enabled when trust-manager is installed), etc.

It acts as the single control point for all component installations. The platform chart’s values file is the canonical list of enabled components and their configuration. Flux CD watches the platform chart and reconciles HelmRelease resources for each enabled component:

• podplane install <component> updates the platform chart values to enable a component; Flux CD then deploys it.
• podplane uninstall <component> disables a component in the platform chart values; Flux CD removes it.
• Core components cannot be uninstalled.

Component Dependencies

Component dependency metadata lives in the platform chart within the cluster itself - not hardcoded in the CLI. The CLI queries the Kubernetes API to read the platform chart’s metadata to determine what’s installed and what dependencies exist.

This means the CLI doesn’t need to bundle or fetch dependency information from the components repo at runtime. The components repo is where charts are authored, but the cluster is the runtime source of truth.

Dependency examples:

• Some addon components depend on other addon components (e.g. snapshot requires snapshot-crds).
• App templates (used by podplane deploy) also have component dependencies (e.g. the web template requires traefik).

When running podplane deploy or podplane install, the CLI checks dependencies and prompts the user to install missing ones.

Relationship to Cluster Config

podplane.cluster.jsonc is the user-facing projection of cluster configuration, including configuration values like cluster name/slug, and which components and features are enabled.

Conceptually, the cluster config file syncs its component/feature settings into the platform chart’s values.