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.

Is a provider the right mechanism?

A provider keeps reacting for the life of the node, and its binary ships in the image. If you only need to act once, or only need extra files, see Choosing how to extend Kairos for a comparison with Dockerfiles, system extensions and bundles.

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.