Skip to main content
Version: Next 🚧

Providers

Kairos providers are plugin binaries used to extend node behavior through lifecycle events.

In practice, many users use providers for Kubernetes bootstrap, but providers are not limited to Kubernetes. A provider gives you a mechanism to react to lifecycle events and execute your own logic for system components.

Why providers exist​

Providers let Kairos keep a modular architecture:

  • Core images stay minimal and do not include Kubernetes providers.
  • Standard images include a Kubernetes provider and related integrations.
  • Additional behavior can be added without changing the core agent architecture.

Examples of what a provider can do:

  • Bootstrap a component during install/first boot.
  • Register custom lifecycle hooks.
  • Attach networking/coordination components.
  • Expose provider-specific CLI behavior.

How provider integration works​

Provider integration is event-driven.

  • kairos-agent initializes a provider bus and auto-loads provider binaries with the agent-provider prefix from standard provider directories.
  • Providers subscribe to known Kairos events and respond to them.
  • Communication is done through the same plugin framework used by Kairos components (go-pluggable).

Reference implementation points in source code:

Lifecycle semantics (important)​

Provider hooks map to specific lifecycle events.

  • A bootstrap event is tied to bootstrap/install flow.
  • If you bootstrap Kubernetes with provider-kairos, that bootstrap event is not the event you use for normal upgrade cycles.
  • For post-service orchestration patterns (for example running steps after k3s is up), use dedicated stages/services as shown in Run stages along with K3s.

For provider-related stage names, see Cloud-init architecture.

Official and community providers​

There are multiple providers in the ecosystem.

  • Officially maintained by Kairos: provider-kairos
  • Community-maintained: additional providers can be developed and maintained outside the core Kairos organization

The official provider-kairos currently includes:

  • Kubernetes support for k3s and k0s.
  • Edge networking capabilities through EdgeVPN for peer-to-peer coordination use cases.

Related docs:

Core vs standard, from a provider perspective​

  • Core: no Kubernetes provider selected.
  • Standard: a Kubernetes provider is included. In the official path, this means provider-kairos with either k3s or k0s.

For concrete build flags and examples, see:

Configuration and runtime hooks​

Provider behavior is configured through cloud-config provider sections and integrated with Kairos stages.