Administrator documentation¶
For whoever operates a Troupe deployment: the Helm chart, the PostgreSQL, object storage, OpenBao and identity provider beside it, and the teams, profiles, policy, bundles, triggers and backups on top.
| Document | What it covers |
|---|---|
| installing.md | A cluster with nothing on it, to a first team in the console; a worked example on managed services |
| worker-sandbox.md | What the nodes must give bubblewrap: the workers' seccomp and AppArmor profiles and user namespaces, what each allows, a cluster check, and what each refusal means |
| configuration.md | Every environment variable, Helm value, platform setting, expected Secret, port and NetworkPolicy |
| client-config.md | The config.yaml a session reads, and the defaults and limits an organisation gives people's machines |
| console.md | The console at /console: where it is, how it is signed in to, and what each area does |
| roles-and-permissions.md | Identity from the provider, admin roles, service principals, break-glass, session roles, how each surface authenticates, RBAC, the workers' and people's OpenBao policies, the admin methods |
| profiles-and-policy.md | Worker profiles, what the operator creates, conditions, upgrades and drains, TroupePolicy, team volumes, provisioning, sizing |
| profile-options.md | A profile that extends another, an MCP identity of its own, a repository's agents and skills, a person's own tools, memory proposals, per-tool rules, which agents it has |
| mcp-identity-keys.md | Making, registering and rotating the key a profile signs its MCP client assertions with |
| gitops.md | Profiles held in a repository: what the plane reads, the manifests, and switching a running plane |
| bundles-and-triggers.md | Config bundles and MCP servers, triggers and the scheduler, unattended terms, budgets |
| integrations.md | What the identity provider, OpenBao, PostgreSQL, object storage, the LLM gateway, Kubernetes, MCP, SCIM and the GUI require |
| openbao.md | What OpenBao must grant the plane, generated from the code that checks it at start and on the Overview, and the lines an OpenBao administrator runs |
| github.md | The plane's GitHub App: registering and installing it, giving the plane its key, the read-only token a session clones its repository with, and how far a run may go |
| github-runs.md | The fix loop: a troupe/* branch, a draft pull request and its CI, never a merge; and GitHub as the trigger |
| authentik.md | Connecting a plane's sign-in and provisioning to Authentik, in order |
| single-machine.md | A worker on a machine you already have, and what it gives up |
| plane-light.md | The plane and its own worker on one machine from one compose file, for an office without a cluster, and what that gives up |
| upgrading.md | From one release to the next: the backup, the CRDs, the chart and its migration, what to watch, what the plane checks, going back, and the restore |
| backup-restore.md | Where state lives, what can be rebuilt, restore procedures |
| monitoring.md | Health endpoints, signals, the audit log, logs worth alerting on, a troubleshooting table |
| routine-tasks.md | Step lists: teams, principals, bundles, drains, settings, client versions, lock-outs, SCIM, rotations, erasure |
| security.md | For a security reviewer: what Troupe does unasked and never does, a worker's isolation and egress, keys, signed releases, unsigned apps, the limits' strength, logs and erasure |
Also: ../a2a.md and ../egress-allowlist.md.
Before the first helm install¶
- The chart makes no Secret. Every one in
configuration.md Part D must exist
in
troupe-systemfirst; the operator copies those a worker namespace needs into it, a model or MCP key only once it is labelledtroupe.dev/worker-secret=true. - CRDs are installed once by Helm and never upgraded:
kubectl apply -f charts/troupe/crds/on every upgrade. - Name the ingress controller's namespace in
operator.ingressNamespaceand the operator labels ittroupe.dev/ingress=true; without that label the network policies keep the controller from the console, the API,/appand every worker. Left empty, the label is yours, and each profile and the Overview say so until it is there. - Platform admin comes from an identity-provider group carried in a claim; whether the claim needs a scope is the provider's (integrations.md §1).
- Bucket versioning must be on, or erasure's promise means nothing.
SecretMissingnames a Secret a worker namespace lacks and where it was looked for.- Nothing restarts a drained worker pod on the current revision. After
admin.pod.drain, delete the pod; one behind a new revision the operator replaces. - Principals, settings, the audit trail and triggers live only in PostgreSQL (in gitops mode a trigger's definition is the repository's). The session index can be rebuilt from object storage; they cannot.
- There is no metrics exporter, backup CronJob or OpenBao snapshot in the repository.
- Read security.md before people install the clients: what Troupe does unasked, how releases are verified, and how to open the unsigned apps.