Feature Request: Full GitOps Setup

[JohnnyElvis]

Status: FEATURE REQUEST — Fleet cannot be fully set up without manual/interactive steps

Problem Statement

Fleet's GitOps workflow (fleet-gitops repo) covers day-2 operations — policies, queries, agent options, SSO settings, org info, MDM config, etc. However, day-0 and day-1 setup still requires manual intervention before GitOps can take over.

The goal is zero-touch Fleet deployment: deploy the container, provide configuration, and have Fleet fully operational without any UI interaction or manual CLI commands.

A side goal is to eliminate human admin accounts for Fleet configuration — Fleet's own setup (SSO, org settings, policies, queries, agent options) is managed exclusively by a GitOps API-only account via Git. Human operators still authenticate via SSO to manage devices, run live queries, and perform day-to-day operations — but Fleet's configuration itself is never changed through the UI.

Current Setup Flow

1. Access UI → complete setup wizard                       ← MANUAL ❌
   - Create initial admin user (email, name, password)
   - Set organization name
2. Create API-only user with GitOps role                   ← MANUAL ❌
3. Generate API token for GitOps user                      ← MANUAL ❌
4. Store token as CI/CD secret                             ← MANUAL (one-time) ❌
5. Run `fleetctl gitops -f default.yml ...`                ← automatable ✅

Steps 1–4 break the GitOps model. You cannot fully provision Fleet from a Git repo + env vars alone.

What Already Works

Server Configuration (env vars — requires restart)

All infrastructure settings are already configurable via FLEET_* env vars:

Category	Env var prefix	Status
MySQL	FLEET_MYSQL_*	✅
Redis	FLEET_REDIS_*	✅
Server (address, TLS, URL prefix)	FLEET_SERVER_*	✅
Logging	FLEET_LOGGING_*	✅
MDM (WSTEP certs, SCEP)	FLEET_MDM_*	✅
S3 (software installers)	FLEET_S3_*	✅
Vulnerabilities	FLEET_VULNERABILITIES_*	✅
Prometheus	FLEET_PROMETHEUS_*	✅
License	FLEET_LICENSE_KEY	✅

GitOps YAML (via fleetctl gitops — no restart)

Setting	GitOps key	Status
SSO	org_settings.sso_settings	✅ Already supported
SMTP	org_settings.smtp_settings	✅ Already supported
Org info	org_settings.org_info	✅ Already supported
Server URL	org_settings.server_settings.server_url	✅ Already supported
Enroll secrets	org_settings.secrets	✅ Already supported
Integrations (Jira, Zendesk, Calendar)	org_settings.integrations	✅ Already supported
MDM settings	org_settings.mdm	✅ Already supported
Webhooks	org_settings.webhook_settings	✅ Already supported
Features	org_settings.features	✅ Already supported
Fleet Desktop	org_settings.fleet_desktop	✅ Already supported
Certificate Authorities	org_settings.certificate_authorities	✅ Premium

What's Missing (3 Gaps)

Gap 1: Headless Initial Setup via Env Vars

Problem: The only ways to create the first user is the setup wizard (UI). There are no FLEET_SETUP_* env vars or features in fleetctl setup

No user = no API = nothing works.

Proposed solution — env vars for auto-setup on first boot:

FLEET_SETUP_ADMIN_EMAIL=admin@example.com
FLEET_SETUP_ADMIN_NAME=Admin
FLEET_SETUP_ADMIN_PASSWORD=<from-secret>
FLEET_SETUP_ORG_NAME=My Organization
FLEET_SETUP_ORG_LOGO_URL=https://example.com/logo.png
FLEET_SETUP_SERVER_URL=https://fleet.example.com

When these are set and SetupRequired() == true, Fleet should automatically:

1. Create the admin user
2. Set org name, logo URL
3. Set Fleet server URL (web address)
4. Mark setup as complete (so normal API routing begins)

This way a Kubernetes Deployment + ConfigMap + SealedSecret is sufficient for day-0. No init container running fleetctl setup needed.

Gap 2: Bootstrap GitOps API User via Env Vars

Problem: After initial setup, you need to create an API-only user with the gitops role to run fleetctl gitops. Currently the only way is:

fleetctl user create --email gitops@example.com --name GitOps \
  --password <password> --global-role gitops --api-only

This requires an authenticated fleetctl session (from setup step) and cannot be done declaratively.

Note from GitOps docs:

"Currently, managing users [...] are only supported using Fleet's UI or API."

Proposed solution — env vars for bootstrapping the GitOps API token:

FLEET_SETUP_GITOPS_USER_EMAIL=gitops@example.com
FLEET_SETUP_GITOPS_USER_API_TOKEN=<pre-generated-token-from-secret>

On first boot (when SetupRequired() == true), in addition to creating the admin user, Fleet creates an API-only user with the gitops role and the specified pre-generated API token. The same token is stored in CI/CD secrets ahead of time, so fleetctl gitops can run immediately after boot — zero human interaction.

Gap 3: Import Configuration from File on Startup (nice to have)

Problem: Even with Gaps 1 and 2 solved, applying org settings (SSO, SMTP, policies, queries, agent options) still requires a separate fleetctl gitops run from CI/CD. This means the instance is not fully configured until an external pipeline runs against it.

Other identity/infrastructure tools solve this with a config-import-on-startup pattern:

Tool	Mechanism
Keycloak	--import-realm /path/to/realm.json — imports realm config on first boot
Authentik	Blueprints directory (/blueprints/) — auto-applied YAML on startup
Vault	VAULT_LOCAL_CONFIG env var or /vault/config/ mount
Grafana	Provisioning from /etc/grafana/provisioning/ on startup

Proposed solution — env var pointing to GitOps YAML:

FLEET_SETUP_CONFIG_IMPORT_PATH=/etc/fleet/config/default.yml

On first boot (after setup completes), Fleet reads the file at this path and applies it using the same logic as fleetctl gitops. The file uses the existing GitOps YAML format — no new schema needed.

In Kubernetes, this file is mounted from a ConfigMap:

volumes:
  - name: fleet-config
    configMap:
      name: fleet-gitops-config
volumeMounts:
  - name: fleet-config
    mountPath: /etc/fleet/config

This closes the loop: a single container start with env vars + a mounted config file produces a fully configured Fleet instance — no external CI/CD pipeline needed for initial setup.

Recommendation

Priority order for Fleet team:

1. Gap 1 (env var setup) — Highest impact, smallest change. Add FLEET_SETUP_* env vars so fleet serve auto-completes setup on first boot. This unblocks all downstream automation.

2. Gap 2 (bootstrap GitOps token) — Medium impact. Allow pre-seeding an API token during setup so CI/CD can use it immediately without an interactive step.

3. Gap 3 (config import on startup) — Eliminates the need for an external CI/CD pipeline entirely. Fleet reads a mounted GitOps YAML file on first boot and applies it, like Keycloak's --import-realm.

References

• Fleet GitOps repo
• GitOps YAML reference
• Fleet server configuration
• fleetctl CLI docs
• Setup endpoint: server/service/endpoint_setup.go
• Setup check: server/service/service_appconfig.go:99 (SetupRequired)
• Setup gating: cmd/fleet/serve.go:1398 (WithSetup middleware)
• fleetctl setup: cmd/fleetctl/fleetctl/setup.go

[noahtalerman]

Current Setup Flow

1. Access UI → complete setup wizard                       ← MANUAL ❌
   - Create initial admin user (email, name, password)
   - Set organization name
2. Create API-only user with GitOps role                   ← MANUAL ❌
3. Generate API token for GitOps user                      ← MANUAL ❌
4. Store token as CI/CD secret                             ← MANUAL (one-time) ❌
5. Run `fleetctl gitops -f default.yml ...`                ← automatable ✅

Hey @JohnnyElvis thanks for tracking this. I think we can automate the manual steps today...

Today, we can automate setup w/ fleetctl setup.

We can automate creating the API-only users via Fleet's "Create user" API and retrieving the API token via the API.

It looks like (haven't tried it myself), we can also automate storing the token in GitHub (CI/CD) via GitHub's API: https://docs.github.com/en/rest/actions/secrets?apiVersion=2022-11-28

What do you think?

[JohnnyElvis]

fleetctl setup should do what I was looking for. I found this well-hidden gem as well: api-for-contributors.md.

fleetctl setup could use better documentation - I completely missed it. Adding the usage and options references to Fleet server configuration would help others.

Creating the initial admin user is possible, which is great. I’ll check the API token topic soon.