|
| 1 | +--- |
| 2 | +sidebar_position: 8 |
| 3 | +sidebar_label: Assets & Credentials |
| 4 | +--- |
| 5 | + |
| 6 | +# Asset & Credential Automation |
| 7 | + |
| 8 | +`opsctl` can create every registered built-in asset type through one generic command and can discover existing managed credentials and SSH Agent identities without returning secret material. |
| 9 | + |
| 10 | +## Create an Asset |
| 11 | + |
| 12 | +```bash |
| 13 | +opsctl create asset --name <name> [flags] |
| 14 | +``` |
| 15 | + |
| 16 | +Use `--type` to select a registered built-in type (the default is `ssh`). The selected type owns its required fields, defaults, legal combinations, and unknown-field validation. Run `opsctl help <type>` for its exact configuration contract. |
| 17 | + |
| 18 | +Type-specific configuration can be passed as a JSON object or read from a file: |
| 19 | + |
| 20 | +```bash |
| 21 | +opsctl create asset \ |
| 22 | + --type database \ |
| 23 | + --name "Production DB" \ |
| 24 | + --config '{"driver":"mysql","host":"db.internal","username":"app"}' \ |
| 25 | + --credential-id 4 |
| 26 | + |
| 27 | +opsctl create asset \ |
| 28 | + --type k8s \ |
| 29 | + --name "Production Cluster" \ |
| 30 | + --kubeconfig-file ~/.kube/config \ |
| 31 | + --context production |
| 32 | +``` |
| 33 | + |
| 34 | +`--config` and `--config-file` are mutually exclusive. Existing convenience flags such as `--host`, `--port`, `--username`, `--driver`, `--database`, `--read-only`, `--ssh-asset`, and the Kubernetes flags remain available. Only explicitly supplied convenience flags override matching non-secret values from generic configuration. |
| 35 | + |
| 36 | +Validation and credential-reference checks finish before desktop approval. The asset is written only after approval succeeds. |
| 37 | + |
| 38 | +## Passwords and Authentication References |
| 39 | + |
| 40 | +The supported secret/reference inputs are mutually exclusive: |
| 41 | + |
| 42 | +| Input | Behavior | |
| 43 | +|---|---| |
| 44 | +| `--password-stdin` | Reads plaintext from standard input without a prompt or echo. This is the recommended plaintext path. | |
| 45 | +| `--password <value>` | Accepts plaintext in argv and prints a warning because the value may be exposed in shell history, process listings, or CI logs. | |
| 46 | +| `--credential-id <id>` | Reuses an existing compatible managed password or SSH-key credential. | |
| 47 | +| `--agent-source-id <id>` with `--agent-key-fingerprint <fingerprint>` | Selects an existing SSH Agent source and identity for SSH Agent authentication. | |
| 48 | + |
| 49 | +For example: |
| 50 | + |
| 51 | +```bash |
| 52 | +printf '%s\n' "$APP_PASSWORD" | \ |
| 53 | + opsctl create asset --type redis --name cache \ |
| 54 | + --config '{"host":"redis.internal","username":"default"}' \ |
| 55 | + --password-stdin |
| 56 | +``` |
| 57 | + |
| 58 | +Plaintext supplied through `--password-stdin`, `--password`, or an accepted JSON secret field is encrypted in the asset. It does **not** create a reusable managed credential. Create managed passwords and SSH keys explicitly in the desktop key manager, then reference them with `--credential-id`. |
| 59 | + |
| 60 | +Do not put SSH private keys or passphrases into automation configuration. Import the key in the desktop key manager and reference its credential ID. Kubernetes kubeconfig remains encrypted directly in the asset. Asset types without password authentication reject password inputs. |
| 61 | + |
| 62 | +If a JSON config file contains plaintext secrets, restrict its file permissions, do not commit it, and remove it when it is no longer needed. |
| 63 | + |
| 64 | +## Discover Credentials Safely |
| 65 | + |
| 66 | +List the unified key-management inventory: |
| 67 | + |
| 68 | +```bash |
| 69 | +opsctl list credentials |
| 70 | +opsctl list credentials --type password |
| 71 | +opsctl list credentials --type ssh_key |
| 72 | +opsctl list credentials --type ssh_agent |
| 73 | +``` |
| 74 | + |
| 75 | +Every item has an unambiguous typed reference. Use that reference for detail lookup: |
| 76 | + |
| 77 | +```bash |
| 78 | +opsctl get credential credential:4 |
| 79 | +opsctl get credential agent-source:2 |
| 80 | +``` |
| 81 | + |
| 82 | +Bare numeric IDs are rejected for credential detail because managed credentials and SSH Agent sources use different ID spaces. |
| 83 | + |
| 84 | +These commands return identification and usage metadata only. Depending on the kind, that can include names, usernames, fingerprints, key type/size, sanitized comments, availability, referencing assets, and an SSH key's public key. They never return password plaintext or ciphertext, SSH private keys or passphrases, master keys, SSH Agent endpoint values, signatures, or challenge secrets. |
| 85 | + |
| 86 | +AI automation exposes the same safe discovery model through `list_credentials` and `get_credential`, and uses the same asset-write boundary through `put_asset`. |
| 87 | + |
| 88 | +## Approval, Output, and Audit |
| 89 | + |
| 90 | +Approval details and successful asset results omit write-only secrets. The `put_asset` audit producer also writes an allowlisted request projection: password, Secret Access Key, kubeconfig, private-key, and passphrase fields are absent rather than replaced with `<redacted>`. |
| 91 | + |
| 92 | +This special asset-write projection does not describe every audit record. Other audited tools store the command, request, result, and error received by the audit writer, subject to their existing canonical-command, limited-buffer, and truncation behavior. See [Audit & Approval](../guide/audit.md#audit-payload-boundaries). |
0 commit comments