Machine ID (tbot)¶

With --auth machine-id (and always with --teleport-local), a tbot container joins the cluster once with a bot join token, then renews a short-lived identity (1 hour by default) every 20 minutes. Tenantry reads that identity exactly like an identity file: same TELEPORT_IDENTITY_FILE=/identity/identity, no restart.

How to start: Quick start (same server) or variants (Teleport elsewhere). The join token is single-use: after the first join tbot renews with its own certificates kept in the tbot-storage volume, and install.sh deletes both copies of the token. If no identity appears within 60 s, the token is kept for a retry and the script exits 1.

Re-running install.sh later (upgrade, new options) needs no token: the marker <dir>/.machine-id-joined records the join.

The bot's role (`--bot-role`)¶

With --teleport-local the installer creates the role tenantry itself, from a text embedded in install.sh (never from the image it installs: the image's copy is only compared and a difference stops the installation), as one YAML document sent on tctl's stdin. It re-applies it at every run, so changing --bot-role takes effect on the next run.

Level	Rules	What works
`minimal` (default)	`role` `[list, read]`; `app` `[list, read, create, update]`; `app_server`, `cluster_auth_preference`, `instance`, `windows_desktop_service`, `windows_desktop` `[list, read]`; `app_labels` and `windows_desktop_labels` (listing only, no `windows_desktop_logins`).	Steward integration with the default role names (the installer creates `steward-admin` and `steward-helpdesk` itself), dashboard, client proxies, desktops.
`full` (opt-in)	`minimal` + `role` `create`, `token` `[list, read, create, delete]`, `lock` `[list, read, create, update, delete]`.	Also "Add a proxy" (enrolment tokens), the lock button, Steward integration with other role names, per-client Teleport roles created from Tenantry.

full is close to cluster administration

The right to create roles is the right to create a role that grants anything; a join token can enrol any agent (Teleport cannot limit token to one type); a lock can lock out anyone. With full, a stolen identity file or a compromised Tenantry is a compromised cluster for up to certificate_ttl. The installer prints this warning when --bot-role full is used. With minimal, an administrator creates those resources with tctl (the Tenantry pages show the YAML).

scripts/install.sh --print-tenantry-role minimal|full and --print-console-roles print the exact texts (for Teleport on another server: variants).

What runs (`docker/compose.machine-id.yml`)¶

Service / volume	Role
`tbot-init`	One-shot: hands the two volumes to uid 1000 (`chown`, only the `CHOWN` capability, no network).
`tbot`	`public.ecr.aws/gravitational/tbot-distroless:<version>@sha256:<digest>` (pulled by `install.sh`, which pins the digest it resolved in `.env`: the tag cannot be swapped under it later), `tbot start -c /etc/tbot/tbot.yaml`, uid 1000, read-only root, `cap_drop: ALL`. Configuration and token folder mounted read-only.
`tbot-storage`	The bot's own renewable identity. Losing it (volume deleted) means a new join token. Never copy it between hosts.
`tbot-identity`	The `identity` output, mounted read-only into Tenantry at `/identity`.

The generated tbot.yaml (v2). It uses auth_server: instead of proxy_server: when --auth-server uses port 3025, and lists the CA pins in that case:

version: v2
proxy_server: teleport.acme.ch:443
onboarding:
  join_method: token
  token: /etc/tbot/secrets/join-token   # a path: tbot reads the token from the file
storage:
  type: directory
  path: /var/lib/teleport/bot
certificate_ttl: 1h
renewal_interval: 20m
outputs:
  - type: identity
    destination:
      type: directory
      path: /identity-out

--teleport-local reaches the auth service directly at <container>:3025 on the Teleport Docker network, never through the public proxy, a WAF or Cloudflare Access.

Health¶

The Security page shows "Renewed by Machine ID" with the last renewal (the identity file's modification time) and the end of validity of the certificate. If the file was not rewritten within 2 x the renewal interval (40 minutes by default), the dashboard and the Security page warn that tbot is probably down, and the alert identity_not_renewed fires (Alerts).

docker compose -p tenantry-<name> ps tbot
docker compose -p tenantry-<name> logs --tail 100 tbot
docker compose -p tenantry-<name> logs -f tenantry

Problems and fixes: Troubleshooting.

Revoking¶

Lock the bot (tctl lock --user=bot-tenantry) or delete it (tctl bots rm tenantry): renewal stops and the current certificate expires within certificate_ttl. Teleport also refuses the renewal of a bot identity used from two places.

Private CA and host names¶

--ca-file and --add-host apply to tbot as well as to Tenantry.

Not verified in the lab¶

Based on the Teleport 17/18 documentation, not verified for every release: the tbot-distroless tag for your exact version (--tbot-image overrides it), that tbot does not re-read the token file once joined (the script deletes it), the certificate_ttl key name (newer releases may also accept credential_ttl), and the default lifetime of the token printed by tctl bots add (--ttl changes it). Check tctl bots add --help on your cluster version.