docs: update USAGE.md for core CLI + IAM management
- 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
This commit is contained in:
Story Crater Bot
@@ -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
|
**Setup:**
|
||||||
|
```bash
|
||||||
All secrets live under `cluster/<VARIABLE_NAME>`. The field name is always the variable name itself (SCREAMING_SNAKE_CASE), matching the `.env` key. Example paths:
|
make cli # builds + installs to ~/.local/bin/core
|
||||||
|
core auth login-oob # authenticate with Authentik (OOB flow)
|
||||||
```
|
core nodes # verify cluster access
|
||||||
cluster/ANTHROPIC_API_KEY
|
|
||||||
cluster/AUTHENTIK_FORGEJO_CLIENT_ID
|
|
||||||
cluster/AUTHENTIK_ARGOCD_CLIENT_SECRET
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### `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
|
```bash
|
||||||
talos put cluster/VARIABLE_NAME VARIABLE_NAME="secret-value"
|
export CORE_CLI_SECRET="cyoVr96FB9oeq3o64DUG0BmoVzMPsOTIWxVEd8ZdTezKrEZYwrKpIRkOwrDQNEtF6QJyNUPH4mjr9jWokQY7KVBWX1KVUXFyyhgAHTqWRRWAYUJ8r3H35wLFiTfn5KsV"
|
||||||
talos put cluster/FORGEJO_ADMIN_PASSWORD FORGEJO_ADMIN_PASSWORD="$FORGEJO_ADMIN_PASSWORD"
|
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
|
```bash
|
||||||
talos get cluster/VARIABLE_NAME --key VARIABLE_NAME # always specify --key
|
core nodes # list cluster nodes
|
||||||
talos get cluster/FORGEJO_ADMIN_PASSWORD --key FORGEJO_ADMIN_PASSWORD
|
core status <ip> # Talos node overview
|
||||||
talos get cluster/VARIABLE_NAME --json # full secret as JSON
|
core services <ip> # list Talos services
|
||||||
|
core logs <ip> # stream kubelet logs
|
||||||
|
core log-svc <ip> <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).
|
All secrets live under `cluster/<VARIABLE_NAME>`. Field name = variable name (SCREAMING_SNAKE_CASE).
|
||||||
Empty `.env` values are fetched from Vault at `cluster/<KEY>`; hardcoded values pass through.
|
|
||||||
|
|
||||||
```zsh
|
#### Write Secret to Vault
|
||||||
vsource # loads .env in current directory
|
|
||||||
vsource .env.local # loads a specific file
|
|
||||||
```
|
|
||||||
|
|
||||||
`.env` format — leave secrets empty, vsource resolves them from Vault:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
ANTHROPIC_API_KEY= # fetched from cluster/ANTHROPIC_API_KEY
|
core put cluster/ANTHROPIC_API_KEY ANTHROPIC_API_KEY="sk-ant-..."
|
||||||
AUTHENTIK_ARGOCD_CLIENT_ID= # fetched from cluster/AUTHENTIK_ARGOCD_CLIENT_ID
|
core put cluster/FORGEJO_ADMIN_PASSWORD FORGEJO_ADMIN_PASSWORD="secret123"
|
||||||
DEBUG=true # hardcoded, passed through as-is
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Typical workflow for a generated secret
|
**Key rule:** Field name must match variable name — never `value=`.
|
||||||
|
|
||||||
|
#### Fetch Secret from Vault
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. Store immediately after generation (keeps secrets out of shell history)
|
core get cluster/ANTHROPIC_API_KEY # default field
|
||||||
talos put cluster/AUTHENTIK_FORGEJO_CLIENT_SECRET AUTHENTIK_FORGEJO_CLIENT_SECRET="<paste>"
|
core get cluster/AUTHENTIK_ARGOCD_CLIENT_SECRET # full value
|
||||||
|
|
||||||
# 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### IAM Management (Federated OIDC, Phases 1–6 Complete)
|
#### List All Secrets
|
||||||
|
|
||||||
**Status:** ✅ Fully deployed (2026-07-02). Single federated OIDC provider (`talos-federation`) handles all service auth.
|
|
||||||
|
|
||||||
**Quick reference:**
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# View roles and capabilities
|
core secrets list
|
||||||
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 [email protected] 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**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)
|
### CI/CD Image Registry Authentication (Forgejo + Runner)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user