Estructura de bóvedas para DevOps
Por qué es importante la estructura para la automatización
Cuando una persona utiliza Passwork, puede buscar por nombre y navegar visualmente. La automatización no puede. Una canalización de CI/CD o un script necesita recuperar los secretos mediante un identificador predecible —un ID de carpeta o un ID de bóveda— y espera que todos los secretos necesarios estén en esa ubicación.
Una estructura bien diseñada significa:
- Un único
--folder-idobtiene todos los secretos que necesita una canalización, sin montaje manual - Añadir un nuevo secreto a una canalización requiere añadir un registro a la carpeta correcta, no cambiar el código
- El control de acceso se corresponde de forma clara con los límites de los equipos
Jerarquía recomendada
Organice los secretos de infraestructura primero por entorno y luego por tipo de servicio:
Infrastructure (bóveda)
├── 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/
Esta disposición significa que:
- Una canalización de despliegue de producción utiliza
--folder-id <ID de la carpeta de producción>para obtener todos los secretos de producción - El control de acceso es por entorno: la cuenta
svc-deploy-stagingtiene acceso de solo lectura astaging/, no aproduction/ - Un script en el portátil de un desarrollador utiliza
--folder-id <ID de la carpeta de desarrollo>sin tocar producción
Convenciones de nomenclatura
Utilice nombres que sean descriptivos y reconocibles por máquinas. Cuando passwork-cli exec inyecta secretos en variables de entorno, utiliza el nombre del elemento (y los nombres de los campos personalizados) como nombre de la variable, normalizando los espacios y los caracteres especiales a guiones bajos.
| Nombre del elemento | Variable inyectada |
|---|---|
POSTGRES_PASSWORD | POSTGRES_PASSWORD |
postgres order service | POSTGRES_ORDER_SERVICE |
AWS_SECRET_ACCESS_KEY | AWS_SECRET_ACCESS_KEY |
Stripe Secret Key | STRIPE_SECRET_KEY |
Patrón recomendado: utilice SCREAMING_SNAKE_CASE para los elementos de infraestructura que se inyectan como variables de entorno. Esto hace que la correspondencia sea explícita y evita sorpresas.
Qué poner en cada campo
Los registros de contraseñas de Passwork tienen varios campos. Utilícelos de forma intencionada:
| Campo | Qué almacenar |
|---|---|
| Login | Nombre de usuario, nombre de la cuenta de servicio, ID de clave (p. ej., AKIAIOSFODNN7EXAMPLE) |
| Contraseña | El valor del secreto principal (contraseña, token, clave privada) |
| URL | Endpoint del servicio o URL de la consola (útil como referencia para humanos) |
| Campos personalizados | Secretos adicionales con nombre: AWS_SECRET_ACCESS_KEY, DB_HOST, DB_PORT, cadenas de conexión |
| Descripción | Notas de configuración, procedimiento de rotación, equipo propietario |
| Etiquetas | Entorno, tipo de servicio (production, k8s, db) |
Registros con varios secretos
Cuando un servicio necesita varias credenciales relacionadas, almacénelas en un solo registro utilizando campos personalizados:
Registro: "AWS production credentials"
Login: AKIAIOSFODNN7EXAMPLE
Password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Campos personalizados:
AWS_REGION: eu-central-1
S3_BUCKET: company-backups-prod
ROLE_ARN: arn:aws:iam::123456789:role/deploy-role
passwork-cli exec --password-id <id> inyectará todos estos como variables de entorno separadas.
Almacenamiento de claves SSH y certificados
Para secretos de varias líneas (claves privadas SSH, certificados TLS, archivos kubeconfig), utilice un campo personalizado con el contenido completo. La CLI gestiona correctamente los valores de varias líneas. Como alternativa, utilice adjuntos para los archivos binarios.
Códigos TOTP
Si una cuenta de servicio requiere 2FA, Passwork puede generar códigos TOTP. Añada un campo personalizado de tipo TOTP y pegue la semilla del autenticador. La CLI y el SDK de Python pueden recuperar el código TOTP actual de forma programática.
Etiquetas para el filtrado por entorno
Aplique etiquetas a cada registro de infraestructura:
- Etiqueta de entorno:
production,staging,development - Etiqueta de tipo de servicio:
db,cloud,k8s,messaging,external-api - Etiqueta de estado:
active,deprecated,rotation-pending
passwork-cli exec --tags "production,db" recupera todos los registros que coinciden con ambas etiquetas. Esto es útil para los scripts que operan en varios servicios del mismo tipo.
Consideraciones sobre el CSE
Cuando el cifrado del lado del cliente está activado:
- El campo de contraseña y los valores de los campos personalizados se cifran en el cliente antes de almacenarse
- El nombre del elemento, el login, la URL, las etiquetas y la descripción NO se cifran en el cliente: se pueden buscar en el servidor
Esto significa que no debe poner datos confidenciales en el nombre del elemento, la descripción o las etiquetas. Mantenga los secretos en el campo de contraseña y en los campos personalizados.
La CLI y el SDK de Python gestionan el CSE de forma transparente cuando se establece PASSWORK_MASTER_KEY. No se necesitan cambios en el código al cambiar entre instancias de Passwork con el CSE activado y desactivado: solo cambia la presencia o ausencia del parámetro de la clave maestra.
Separar las bóvedas de infraestructura de las bóvedas de negocio
Mantenga los secretos de infraestructura en una bóveda dedicada (p. ej., Infrastructure o DevOps). No los mezcle con las credenciales de negocio (inicios de sesión de CRM, herramientas de marketing). Esto hace que:
- El control de acceso sea más limpio: conceda a las cuentas de servicio de CI/CD acceso únicamente a la bóveda de infraestructura
- Las revisiones de seguridad sean más sencillas: el equipo de seguridad sabe exactamente dónde buscar las credenciales privilegiadas
- El alcance de la rotación sea más claro: los scripts de rotación de infraestructura operan sobre una bóveda conocida
Para conocer las prácticas recomendadas de gestión de secretos, consulte Gestión de secretos: conceptos.