podmin

command module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 18, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

README

Podmin - Minimal, Secure Container Platform

Podmin is a deliberately minimal container platform.

Goals:

  • Great developer experience with fast deployments.
  • Secure and reliable with zero infrastructure maintenance.
  • Low cost and minimal cloud services: VMs, object storage, secrets store.

Features

  • Set up a new cluster in your cloud provider with one command.
  • Divide a cluster into multiple NodeGroups to scale different sets of Pods on multiple VMs.
  • Build and push multi-arch container images to object storage, with no managed registry service.
  • Deploy pushed images using a Kubernetes-compatible DaemonSet manifest to run as Pods on each NodeGroup node.
  • Deploy a Kubernetes-compatible Service for stable DNS and readiness-aware load balancing to Pods.
  • Mount encrypted secrets from your cloud provider secrets store using host tmpfs.
  • Every Pod gets a short-lived SPIFFE-compatible client certificate
  • Pods associated with a Service also receive a certificate valid for their Service DNS name.
  • Use public IPv6 subnets without exposing inbound ports to the internet.
  • Mount ephemeral volumes from your VM.
  • Podmin only supports AWS for now, but has a deliberately cloud agnostic design.

How It Works

It only has two components, a CLI and a minimal agent process:

podmin CLI:

  • Deploys infrastructure to your cloud provider using OpenTofu/Terraform.
  • Lets you easily build, push, and deploy apps as Pods.

podmin-agent:

  • Runs on a VM alongside containerd, gVisor, kubelet, CoreDNS, and Zot.
  • Watches manifests, loads secrets, and updates kubelet static Pods.
  • Gives Pods direct-routed IPv6 addresses from each VM's delegated prefix using upstream ptp and host-local CNI plugins; there is no bridge, overlay, or Pod NAT.
  • Reuses kubelet readiness, coordinates ready Service endpoints over gRPC, and programs an eBPF VIP dataplane only when Services exist.
  • Keeps Service discovery opt-in: without inline Services, the eBPF dataplane remains inactive and no Service DNS or endpoint state is produced.
  • Issues workload certificates locally from a CA key held in the provider secret store and rotates public workload CA certificates through object storage.
  • Protects agent coordination with TLS 1.3 mutual authentication and renewable, in-memory node certificates issued under a separate cluster CA.

Podmin has the concept of NodeGroups:

  • Each NodeGroup can run multiple DaemonSet deployments.
  • One NodeGroup equates to one Auto Scaling Group.
  • Each DaemonSet runs one extracted static Pod on every VM in its NodeGroup.
  • Optional Services use Kubernetes-style <service>.<namespace>.svc.cluster.local names across the cluster.

When To Use

Use when you want:

  • Fast container deployments on a simple, reliable, no-maintenance platform.
  • The features of a Kubernetes Pod (e.g. init containers), without a Kubernetes API or control plane.
  • Horizontal scaling of Pods across a set of VMs, using cloud provider VM auto-scaling.
  • The ability to securely mount secrets from your cloud provider secrets store.
  • A low cost solution for running containers that only takes a few minutes to set up.

Do not use when you want:

  • Independent Pod scaling within the same NodeGroup
  • On-demand Pods
  • Persistent volumes
  • Kubernetes

When you need more from your container platform, check out Podplane Kubernetes PaaS.

Podmin aims to implement a subset of Podplane manifests and CLI commands, to ease migration to Podplane at a later date.

Scope & Roadmap

  • AWS-only: Google Cloud planned.
  • AWS Parameter Store and AWS Secrets Manager mounts; Google Secret Manager planned.
  • Auto-Scaling Group size fixed: automatic scaling based on metrics planned.
  • Ingress via the built-in Cloudflare Tunnel installer or user-deployed tunnel Pods; cloud provider NLB support is planned.
  • Observability planned: Fluent Bit shipping VM and Pod logs to S3 or an OpenTelemetry-compatible provider.

Documentation

Development

Run make setup, then make precommit lint test build. OpenTofu/Terraform validate infrastructure modules; ShellCheck and bash -n validate shell and rendered user-data. Releases use immutable semantic-version tags, GoReleaser, SHA-512 checksums, SBOMs, provenance, and keyless signing.

License

Podmin is licensed under the Apache License, Version 2.0. Copyright The Podmin Authors.

See the LICENSE file for details.

Documentation

The Go Gopher

There is no documentation for this package.

Source Files

View all Source files

Directories

Path Synopsis
cmd
podmin command
podmin-agent command
internal
agent
Package agent composes and runs the Podmin node daemon.
 Package agent composes and runs the Podmin node daemon.
agent/api
Package api implements protobuf gRPC coordination and loopback HTTP health.
 Package api implements protobuf gRPC coordination and loopback HTTP health.
agent/coordinator
Package coordinator elects the service leader and distributes service snapshots.
 Package coordinator elects the service leader and distributes service snapshots.
agent/dataplane
Package dataplane models Podmin's IPv6 service dataplane.
 Package dataplane models Podmin's IPv6 service dataplane.
agent/identity
Package identity creates and validates Podmin agent certificates.
 Package identity creates and validates Podmin agent certificates.
agent/pods
Package pods watches kubelet's local PodsAPI and publishes fail-closed snapshots.
 Package pods watches kubelet's local PodsAPI and publishes fail-closed snapshots.
agent/service
Package service provides authoritative service DNS and readiness-selected endpoint control.
 Package service provides authoritative service DNS and readiness-selected endpoint control.
agent/staticpod
Package staticpod reconciles complete candidate sets into Podmin's owned kubelet manifest directory.
 Package staticpod reconciles complete candidate sets into Podmin's owned kubelet manifest directory.
agent/workload
Package workload issues short-lived workload identities from the workload CA.
 Package workload issues short-lived workload identities from the workload CA.
buildvars
Package buildvars exposes build info injected by build-time linker flags.
 Package buildvars exposes build info injected by build-time linker flags.
cli
Package cli implements the Podmin command line.
 Package cli implements the Podmin command line.
cli/cmd
Package cmd defines the Podmin CLI commands.
 Package cmd defines the Podmin CLI commands.
cli/config
Package config stores local configuration used by the Podmin CLI.
 Package config stores local configuration used by the Podmin CLI.
cli/dependencies
Package dependencies defines and resolves runtime dependencies for the Podmin CLI.
 Package dependencies defines and resolves runtime dependencies for the Podmin CLI.
cli/deploy
Package deploy publishes immutable workloads and commits desired state.
 Package deploy publishes immutable workloads and commits desired state.
cli/images
Package images transfers CLI-managed OCI images between registries, local storage, and object storage.
 Package images transfers CLI-managed OCI images between registries, local storage, and object storage.
cli/infra
Package infra executes the Podmin CLI's embedded infrastructure modules.
 Package infra executes the Podmin CLI's embedded infrastructure modules.
cli/infra/aws
Package aws contains the Podmin CLI's embedded AWS infrastructure module.
 Package aws contains the Podmin CLI's embedded AWS infrastructure module.
cli/install
Package install publishes opinionated Podmin-managed workloads.
 Package install publishes opinionated Podmin-managed workloads.
cli/setup
Package setup creates or updates a Podmin cluster.
 Package setup creates or updates a Podmin cluster.
cli/transfer
Package transfer provides byte progress and concurrency for network transfers.
 Package transfer provides byte progress and concurrency for network transfers.
cli/tui
Package tui renders interactive and text progress for CLI operations.
 Package tui renders interactive and text progress for CLI operations.
cli/userdata
Package userdata renders cloud-init user-data scripts for the Podmin CLI.
 Package userdata renders cloud-init user-data scripts for the Podmin CLI.
cloud
Package cloud defines provider-neutral capabilities shared by Podmin consumers.
 Package cloud defines provider-neutral capabilities shared by Podmin consumers.
cloud/aws
Package aws provides AWS adapters shared by Podmin's CLI and agent.
 Package aws provides AWS adapters shared by Podmin's CLI and agent.
manifest
Package manifest builds, transforms, and validates Podmin's typed Kubernetes manifest subset.
 Package manifest builds, transforms, and validates Podmin's typed Kubernetes manifest subset.
registry
Package registry owns Podmin cluster image reference conventions.
 Package registry owns Podmin cluster image reference conventions.
secrets
Package secrets defines provider-neutral secret naming and management.
 Package secrets defines provider-neutral secret naming and management.
scripts
sitegen command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.