flightctl

Declarative management of fleets of edge devices and their workloads.

User Documentation • Developer Documentation • Contributing

Overview

Flight Control aims to provide simple, scalable, and secure management of edge devices and applications. Users declare the operating system version, host configuration, and set of applications they want to run on an individual device or a whole fleet of devices, and Flight Control rolls out the target configuration to devices. A device agent running on each device automatically applies changes and reports progress and health status back.

Flight Control is designed for modern, container-centric toolchains and operational best practices. It works best on image-based Linux operating systems running bootc or ostree, with container workloads running on Podman/Docker or Kubernetes (MicroShift). APIs are Kubernetes-like, so they instantly feel familiar to Kubernetes users and allow reuse of existing tools and toolchains.

Demo

Architecture

The Flight Control Service exposes two API endpoints — a user-facing HTTPS endpoint (authenticated via JWT from an external OIDC provider) and an agent-facing mTLS endpoint (authenticated via device certificates bootstrapped from hardware root-of-trust). The Flight Control Agent runs on each managed device, calls home, polls for target configuration, applies updates autonomously, and reports status back.

Key Features

• Declarative / GitOps API — Kubernetes-like API lets you store fleet and device configuration in Git; ResourceSync polls repositories or receives webhooks.
• Fleet management — Define a device template and rollout policy once; it automatically applies to all current and future member devices. Supports disruption budgets and staged rollouts.
• Secure device lifecycle — Friction-free enrollment, automatic certificate rotation, TPM-backed attestation, and decommissioning.
• OS image updates — OTA updates via bootc or rpm-ostree with transactional rollback (Greenboot integration). The agent downloads assets before applying, so updates survive network interruptions.
• Container and VM workloads — Podman containers (docker-compose, Quadlets), MicroShift/Kubernetes workloads (Helm, kustomize).
• OS image building — ImageBuild produces bootc container images with the embedded agent; ImageExport exports to qcow2, vmdk, or iso.
• Remote console — Live console sessions to managed devices directly from the CLI or UI.
• Pluggable auth and RBAC — Keycloak, generic OIDC, OpenShift OAuth, AAP, PAM; SpiceDB or Kubernetes RBAC for authorization.
• Observability — Prometheus metrics, Alertmanager integration, OpenTelemetry telemetry gateway, and a CVE view at device and fleet level.
• Web UI — Browser-based dashboard for device inventory, fleet management, and ClickOps workflows.

Quick Start

The fastest path to a running local environment uses kind (Kubernetes in Docker):

# 1. Build all binaries
make build

# 2. Deploy to a local kind cluster (builds containers, installs Helm chart)
make deploy

# 3. Authenticate with the CLI
# The server URL is written to ~/.flightctl/client.yaml by make deploy
bin/flightctl login $(cat ~/.flightctl/client.yaml | grep server | awk '{print $2}') --web --certificate-authority ~/.flightctl/certs/ca.crt

# 4. Apply an example fleet and verify
bin/flightctl apply -f examples/fleet.yaml
bin/flightctl get fleets
bin/flightctl get devices

For a Linux-native setup using systemd + Podman (no Kubernetes required):

make deploy-quadlets

Certificates and client configuration are written to ~/.flightctl/.

Prerequisites

For agent development, enable the Podman socket:

systemctl --user enable --now podman.socket

Build & Test

Install test tooling:

go install gotest.tools/gotestsum@latest
go install go.uber.org/mock/mockgen@v0.4.0

Integration tests accept these environment variables: INTEGRATION_PROCS=N for parallelism, TEST_DIR=./test/integration/store for a specific suite, INTEGRATION_GINKGO_FOCUS="pattern" for individual tests.

Deployment Options

Pre-built container images are published to quay.io/flightctl/ for each release. Helm charts are published to oci://quay.io/flightctl/charts/flightctl.

CLI Reference

The flightctl CLI communicates with the Flight Control Service to manage resources.

Output formats: table (default), json, yaml, wide. Configuration defaults to ~/.config/flightctl/client.yaml.

For the full reference see CLI documentation.

Core Concepts

See Introduction for a full explanation of all concepts.

Documentation

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for the full workflow and then docs/developer/README.md for build and development setup.

Key rules:

• Signed commits are required (GPG or SSH).
• Commit message prefix — use a Jira issue key (EDM-1234: description) or NO-ISSUE: for trivial changes.
• Before pushing — run make unit-test, make integration-test, and make lint. Fix any failures.
• API changes — edit OpenAPI YAML and hand-maintained types, then run make generate. Do not edit *.gen.go by hand.

For larger changes, consider opening a Flight Control Enhancement Proposal (FEP) under docs/developer/enhancements/ before implementing.

Related Projects

• flightctl-ansible — Ansible collection for Flight Control
• flightctl-ui — Web UI

License

Flight Control is licensed under the Apache License 2.0.