Skip to content

How To Use Productive K3S Infra

productive-k3s-infra is organized around complete use cases under use-cases/, not around isolated snippets.

Choose the matching use case

  • multipass: local three-node cluster on top of Multipass VMs
  • onprem-basic: bootstrap existing hosts over SSH
  • aws-single-node: provision one EC2 instance with OpenTofu and bootstrap it remotely

Understand the execution contract

Each use case is responsible for the infrastructure around the cluster, while productive-k3s remains responsible for the cluster bootstrap itself.

In practice that means productive-k3s-infra handles:

  • host creation or host targeting
  • generated inventories and cluster metadata
  • bundle copy from a local checkout or a remote release
  • orchestration of server, agent, and stack phases when the use case needs them
  • use-case-specific validation

Choose the Productive K3S source mode

Most public use cases support two source modes:

  • PRODUCTIVE_K3S_SOURCE=local: package a sibling local checkout of productive-k3s
  • PRODUCTIVE_K3S_SOURCE=remote: download a published GitHub Release bundle

If remote is used, PRODUCTIVE_K3S_VERSION can pin a specific release. If it is omitted, the use case resolves the latest release from PRODUCTIVE_K3S_RELEASE_REPO.

Use the Makefile entry points

The public operator interface is make.

Typical patterns:

  • infrastructure only: infra-up
  • preflight only: preflight
  • full bootstrap: up
  • validation only: validate
  • inspect generated state: status
  • cleanup or teardown: clean or down

See Make targets for the detailed matrix.

Notes

Note

These public use cases are intentionally pragmatic. They are meant to be evaluable, reusable, and explainable. They are not presented as fully hardened production blueprints.

Note

Generated artifacts under each use case are part of the public workflow. They make infrastructure decisions, bootstrap inputs, and validation state easier to inspect.