From 934634a2f631079121e28722e8adbf0bf64e1d91 Mon Sep 17 00:00:00 2001 From: Story Crater Bot <19826264+Riotpiaole@users.noreply.github.com> Date: Mon, 13 Jul 2026 14:12:12 -0700 Subject: [PATCH] docs: update USAGE.md for core CLI + IAM management MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename talos → core CLI references - Add IAM management section (Authentik apps, groups, users) - Add workflows for secret rotation and user management - Link to detailed core CLI docs (~/workplace/core/USAGE.md) - Add port-forwarding and troubleshooting tips --- USAGE.md | 266 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 200 insertions(+), 66 deletions(-) diff --git a/USAGE.md b/USAGE.md index 6442ffa..616680f 100644 --- a/USAGE.md +++ b/USAGE.md @@ -73,101 +73,235 @@ sqs (Kafka + Message Queue) --- -## Custom CLI — `talos` +## Custom CLI — `core` -Homelab cluster control CLI (`core/`). Manages cluster nodes and Vault secrets. +Homelab cluster control CLI (source: `~/workplace/core/`). Manages cluster nodes, Authentik IAM, and Vault secrets. -### Secret path convention - -All secrets live under `cluster/`. The field name is always the variable name itself (SCREAMING_SNAKE_CASE), matching the `.env` key. Example paths: - -``` -cluster/ANTHROPIC_API_KEY -cluster/AUTHENTIK_FORGEJO_CLIENT_ID -cluster/AUTHENTIK_ARGOCD_CLIENT_SECRET +**Setup:** +```bash +make cli # builds + installs to ~/.local/bin/core +core auth login-oob # authenticate with Authentik (OOB flow) +core nodes # verify cluster access ``` -### `talos put` — write a secret to Vault +**Full documentation:** See [~/workplace/core/USAGE.md](../core/USAGE.md) + +--- + +### Authentication + +#### OAuth2 Out-of-Band (OOB) Login + +Browser-based login with manual code entry (recommended). ```bash -talos put cluster/VARIABLE_NAME VARIABLE_NAME="secret-value" -talos put cluster/FORGEJO_ADMIN_PASSWORD FORGEJO_ADMIN_PASSWORD="$FORGEJO_ADMIN_PASSWORD" +export CORE_CLI_SECRET="cyoVr96FB9oeq3o64DUG0BmoVzMPsOTIWxVEd8ZdTezKrEZYwrKpIRkOwrDQNEtF6QJyNUPH4mjr9jWokQY7KVBWX1KVUXFyyhgAHTqWRRWAYUJ8r3H35wLFiTfn5KsV" +core auth login-oob ``` -Field name = variable name — never `value`. +Token expires in 8 hours. Check status: +```bash +core auth status # show expiry +core auth clear # force re-auth on next command +``` -### `talos get` — fetch a secret from Vault +--- + +### Cluster Management ```bash -talos get cluster/VARIABLE_NAME --key VARIABLE_NAME # always specify --key -talos get cluster/FORGEJO_ADMIN_PASSWORD --key FORGEJO_ADMIN_PASSWORD -talos get cluster/VARIABLE_NAME --json # full secret as JSON +core nodes # list cluster nodes +core status # Talos node overview +core services # list Talos services +core logs # stream kubelet logs +core log-svc # logs for specific service (etcd, kubelet, etc.) +core pods clean # delete Failed/Evicted/Terminating pods ``` -Note: `talos get` uses `--key` (long flag), not a positional arg — unlike `talos secrets get`. +--- -### `vsource` — load a `.env` into the shell +### Secret Management (Vault) -zsh function (lives in `~/.zshrc`, not in the repo — can reference but cannot run directly). -Empty `.env` values are fetched from Vault at `cluster/`; hardcoded values pass through. +All secrets live under `cluster/`. Field name = variable name (SCREAMING_SNAKE_CASE). -```zsh -vsource # loads .env in current directory -vsource .env.local # loads a specific file -``` - -`.env` format — leave secrets empty, vsource resolves them from Vault: +#### Write Secret to Vault ```bash -ANTHROPIC_API_KEY= # fetched from cluster/ANTHROPIC_API_KEY -AUTHENTIK_ARGOCD_CLIENT_ID= # fetched from cluster/AUTHENTIK_ARGOCD_CLIENT_ID -DEBUG=true # hardcoded, passed through as-is +core put cluster/ANTHROPIC_API_KEY ANTHROPIC_API_KEY="sk-ant-..." +core put cluster/FORGEJO_ADMIN_PASSWORD FORGEJO_ADMIN_PASSWORD="secret123" ``` -### Typical workflow for a generated secret +**Key rule:** Field name must match variable name — never `value=`. + +#### Fetch Secret from Vault ```bash -# 1. Store immediately after generation (keeps secrets out of shell history) -talos put cluster/AUTHENTIK_FORGEJO_CLIENT_SECRET AUTHENTIK_FORGEJO_CLIENT_SECRET="" - -# 2. Use via subshell when creating K8s secrets -kubectl create secret generic my-secret \ - --from-literal=client-secret="$(talos get cluster/AUTHENTIK_FORGEJO_CLIENT_SECRET --key AUTHENTIK_FORGEJO_CLIENT_SECRET)" - -# 3. Or load into shell via vsource for helmfile/env-driven tools -vsource .env && helmfile apply +core get cluster/ANTHROPIC_API_KEY # default field +core get cluster/AUTHENTIK_ARGOCD_CLIENT_SECRET # full value ``` -### IAM Management (Federated OIDC, Phases 1–6 Complete) - -**Status:** ✅ Fully deployed (2026-07-02). Single federated OIDC provider (`talos-federation`) handles all service auth. - -**Quick reference:** +#### List All Secrets ```bash -# View roles and capabilities -talos iam roles list && talos iam roles describe admin - -# Service registry (Grafana, MinIO, Forgejo, etc.) -talos iam services list && talos iam services describe grafana - -# Agents (admin-bot, ci-bot with auto-rotation) -talos iam agents list && talos iam agents rotate ci-bot - -# Role bindings (user → role with TTL) -talos iam bindings grant alice@example.com devops --expires 2026-12-31 -talos iam bindings list - -# Audit trail (90-day retention, 12 event types) -talos iam audit list && talos iam audit export --format json - -# OIDC provider sync with Authentik -talos iam providers sync-authentik +core secrets list ``` -**See `homelab/CLAUDE.md` § IAM Management for full reference** (roles, services, agents, bindings, audit, providers). +#### Load into Shell (vsource) -**Vault paths:** All IAM state stored under `cluster/iam/{federation,roles,services,agents,bindings}`. +zsh function in `~/.zshrc` — fetches empty `.env` values from Vault: + +```bash +# .env format +ANTHROPIC_API_KEY= # fetched from Vault +AUTHENTIK_ARGOCD_CLIENT_ID= # fetched from Vault +DEBUG=true # hardcoded, passed through + +# Usage +vsource # loads .env in current dir +vsource .env.prod # loads specific file +eval "$(vsource .env)" && helmfile apply # inject + deploy +``` + +--- + +### IAM Management (Authentik) + +Manage OAuth2 applications, groups, and user access via Authentik. + +#### List Groups + +```bash +core iam list-groups +``` + +Output: +``` +authentik Admins (id: 9d72cbf2-9d52-4d3c-bba9-0068525d7a91) +grafana-admins (id: 5f2e1e79-7d7e-4ef0-9b99-3c6df19c0b88) +minio-admins (id: e640d887-eb85-431b-b5b2-5b6a8a7e0a44) +argocd-admins (id: 22a3c296-0d98-433f-8456-ebc2f1c8d489) +forgejo-admins (id: 4084c8d6-0c12-46af-acf8-7372172b9016) +``` + +#### List OAuth2 Applications + +```bash +core iam list-apps +``` + +#### Create New Application + +```bash +core iam create-app "my-service" --slug my-service --redirect-uri "https://my-service.riotpiao.homelab.com/callback" +``` + +Returns client ID and secret (save immediately). + +#### Describe Application + +```bash +core iam describe-app grafana +``` + +Shows: +- Client ID +- Client Secret +- Redirect URIs +- Scope claims + +#### Bind Group to Application + +```bash +core iam bind-app grafana grafana-admins +``` + +Members of `grafana-admins` can log in to Grafana via OIDC. + +#### Create Group + +```bash +core iam create-group "developers" +``` + +#### Add User to Group + +```bash +core iam add-member grafana-admins newuser +``` + +#### Rotate Application Secret + +```bash +core iam rotate-secret grafana +``` + +⚠️ Must update deployment after rotating. + +--- + +### Port Forwarding + +```bash +core pf grafana # localhost:3000 → Grafana +core pf prometheus # localhost:9090 → Prometheus +core pf minio # localhost:9001 → MinIO console +core pf iam # localhost:7000 → Authentik +``` + +--- + +### Workflow: Rotate OAuth2 Secret + +```bash +# 1. Rotate in Authentik +SECRET=$(core iam rotate-secret grafana | jq -r '.client_secret') + +# 2. Update deployment +vi k8s/logging/grafana-values.yaml +# Set: GRAFANA_OIDC_CLIENT_SECRET="$SECRET" + +# 3. Redeploy +helmfile apply -l app=grafana + +# 4. Verify +core iam describe-app grafana +``` + +--- + +### Workflow: Add User to Service + +```bash +# 1. Create or verify group exists +core iam list-groups | grep minio-admins + +# 2. Add user to group +core iam add-member minio-admins alice + +# 3. Verify +# (User will have access next login via OIDC) +``` + +--- + +### Vault Integration (Advanced) + +Vault paths for IAM state (if using federated OIDC): + +``` +cluster/iam/federation/ +cluster/iam/roles/ +cluster/iam/services/ +cluster/iam/agents/ +cluster/iam/bindings/ +``` + +Query via: +```bash +core get cluster/iam/roles/admin --key roles +``` + +**See `CLAUDE.md` § IAM for full architecture** (roles, services, agents, audit). ### CI/CD Image Registry Authentication (Forgejo + Runner)