--- path: onboarding/devops-onboarding/vault-structure.mdx title: Vault structure for DevOps sidebar_position: 3 slug: vault-structure-devops pagination_next: null pagination_prev: null description: >- How to design a Passwork vault and folder hierarchy for infrastructure secrets: environment-based structure, naming conventions for CI/CD access, field usage for non-password secrets, and CSE considerations. keywords: - Passwork - vault structure - infrastructure secrets - CI/CD - folder hierarchy - naming conventions - custom fields - tags - secret store --- ## Why structure matters for automation When a human uses Passwork, they can search by name and navigate visually. Automation cannot. A CI/CD pipeline or script needs to retrieve secrets by a **predictable identifier** — a folder ID or vault ID — and expects all required secrets to be in that location. A well-designed structure means: - A single `--folder-id` fetches all secrets a pipeline needs, with no manual assembly - Adding a new secret to a pipeline requires adding a record to the right folder — not changing code - Access control maps cleanly to team boundaries --- ## Recommended hierarchy Organize infrastructure secrets by **environment first**, then by **service type**: ```text Infrastructure (vault) ├── production/ │ ├── databases/ │ │ ├── postgres-order-service │ │ ├── postgres-analytics │ │ └── redis-sessions │ ├── cloud/ │ │ ├── aws-credentials │ │ └── gcp-service-account │ ├── message-brokers/ │ │ └── rabbitmq-backend │ └── external-apis/ │ ├── stripe-secret-key │ └── twilio-auth-token ├── staging/ │ ├── databases/ │ ├── cloud/ │ └── external-apis/ └── development/ ├── databases/ └── local/ ``` This layout means: - A production deploy pipeline uses `--folder-id ` to get all production secrets - Access control is per-environment: the `svc-deploy-staging` account has Read Only access to `staging/`, not `production/` - A developer's laptop script uses `--folder-id ` without touching production --- ## Naming conventions Use names that are descriptive and machine-recognizable. When `passwork-cli exec` injects secrets into environment variables, it uses the **item name** (and custom field names) as the variable name, normalizing spaces and special characters to underscores. | Item name | Injected variable | |-----------|------------------| | `POSTGRES_PASSWORD` | `POSTGRES_PASSWORD` | | `postgres order service` | `POSTGRES_ORDER_SERVICE` | | `AWS_SECRET_ACCESS_KEY` | `AWS_SECRET_ACCESS_KEY` | | `Stripe Secret Key` | `STRIPE_SECRET_KEY` | **Recommended pattern:** use `SCREAMING_SNAKE_CASE` for infrastructure items that are injected as environment variables. This makes the mapping explicit and avoids surprises. --- ## What to put in which field Passwork password records have several fields. Use them intentionally: | Field | What to store | |-------|--------------| | **Login** | Username, service account name, key ID (e.g. `AKIAIOSFODNN7EXAMPLE`) | | **Password** | The primary secret value (password, token, private key) | | **URL** | Service endpoint or console URL (useful for human reference) | | **Custom fields** | Named additional secrets: `AWS_SECRET_ACCESS_KEY`, `DB_HOST`, `DB_PORT`, connection strings | | **Description** | Configuration notes, rotation procedure, owner team | | **Tags** | Environment, service type (`production`, `k8s`, `db`) | ### Multi-secret records When a service needs several related credentials, store them in **one record** using custom fields: ``` Record: "AWS production credentials" Login: AKIAIOSFODNN7EXAMPLE Password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Custom fields: AWS_REGION: eu-central-1 S3_BUCKET: company-backups-prod ROLE_ARN: arn:aws:iam::123456789:role/deploy-role ``` `passwork-cli exec --password-id ` will inject all of these as separate environment variables. ### Storing SSH keys and certificates For multi-line secrets (SSH private keys, TLS certificates, kubeconfig files), use a **custom field** with the full content. The CLI handles multi-line values correctly. Alternatively, use **attachments** for binary files. ### TOTP codes If a service account requires 2FA, Passwork can generate TOTP codes. Add a custom field of type **TOTP** and paste the authenticator seed. The CLI and Python SDK can retrieve the current TOTP code programmatically. --- ## Tags for environment filtering Apply tags to every infrastructure record: - Environment tag: `production`, `staging`, `development` - Service type tag: `db`, `cloud`, `k8s`, `messaging`, `external-api` - Status tag: `active`, `deprecated`, `rotation-pending` `passwork-cli exec --tags "production,db"` retrieves all records matching both tags. This is useful for scripts that operate across multiple services of the same type. --- ## CSE considerations When **client-side encryption is enabled**: - The **password field** and **custom field values** are encrypted on the client before storage - The **item name**, **login**, **URL**, **tags**, and **description** are NOT encrypted on the client — they are searchable on the server This means you should **not** put sensitive data in the item name, description, or tags. Keep secrets in the password and custom fields. The CLI and Python SDK handle CSE transparently when `PASSWORK_MASTER_KEY` is set. No code changes are needed when switching between CSE-enabled and CSE-disabled Passwork instances — only the presence or absence of the master key parameter changes. --- ## Separating infrastructure vaults from business vaults Keep infrastructure secrets in a dedicated vault (e.g. `Infrastructure` or `DevOps`). Do not mix them with business credentials (CRM logins, marketing tools). This makes: - Access control cleaner: give CI/CD service accounts access only to the infrastructure vault - Security reviews simpler: the security team knows exactly where to look for privileged credentials - Rotation scope clearer: infrastructure rotation scripts operate on a known vault For secret management best practices, see [Secret management: concepts](https://passwork.pro/tech-guides/secret-management/concepts/).