ansible-secrets
This skill should be used when working with secrets in Ansible playbooks, integrating Infisical vault, using no_log directive, retrieving credentials securely, or implementing fallback patterns for secrets. Covers the reusable Infisical lookup task.
When & Why to Use This Skill
This Claude skill streamlines secure secrets management within Ansible playbooks by integrating with the Infisical vault. It provides a standardized, reusable framework for retrieving credentials, implementing the no_log directive to prevent data leakage, and establishing robust fallback patterns. By automating secure lookups and enforcing DevSecOps best practices, it ensures that sensitive information like API keys and passwords remain protected throughout the automation lifecycle.
Use Cases
- Automating secure credential retrieval from Infisical for database and cloud infrastructure provisioning.
- Implementing environment-specific secret isolation (Dev/Staging/Prod) within unified Ansible automation workflows.
- Enhancing pipeline security by preventing sensitive data exposure in CI/CD logs using no_log and secure lookup patterns.
- Configuring secure authentication for third-party integrations like Proxmox or cloud providers without hardcoding secrets.
- Setting up resilient automation that falls back to environment variables when vault services are unavailable during local development.
| name | ansible-secrets |
|---|---|
| description | > |
Ansible Secrets Management
Secure secrets handling with Infisical integration and proper security practices.
Architecture Overview
┌──────────────┐
│ Ansible │
│ Playbook │
└──────┬───────┘
│
│ include_tasks: infisical-secret-lookup.yml
│
▼
┌──────────────────┐
│ Infisical Lookup │
│ Task │
└──────┬───────────┘
│
├─> Try Universal Auth (preferred)
│ - INFISICAL_UNIVERSAL_AUTH_CLIENT_ID
│ - INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET
│
├─> Fallback to Environment Variable (optional)
│ - Uses specified fallback_env_var
│
▼
┌──────────────┐
│ Infisical │ (Vault)
│ API │
└──────────────┘
Reusable Task Pattern
The repository provides a reusable task for secret retrieval at ansible/tasks/infisical-secret-lookup.yml.
Basic Usage
- name: Retrieve Proxmox password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'PROXMOX_PASSWORD'
secret_var_name: 'proxmox_password'
infisical_project_id: '7b832220-24c0-45bc-a5f1-ce9794a31259'
infisical_env: 'prod'
infisical_path: '/proxmox-cluster'
# Now use the secret
- name: Create Proxmox user
community.proxmox.proxmox_user:
api_password: "{{ proxmox_password }}"
# ... other config ...
no_log: true
With Fallback
- name: Retrieve database password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
fallback_env_var: 'DB_PASSWORD' # Falls back to $DB_PASSWORD
infisical_project_id: '7b832220-24c0-45bc-a5f1-ce9794a31259'
infisical_env: 'prod'
infisical_path: '/database'
Task Parameters
| Variable | Required | Default | Description |
|---|---|---|---|
secret_name |
Yes | - | Name of secret in Infisical |
secret_var_name |
Yes | - | Variable name to store secret |
infisical_project_id |
No | (repo default) | Infisical project ID |
infisical_env |
No | prod |
Environment (prod, dev, staging) |
infisical_path |
No | /apollo-13/vault |
Path within project |
fallback_env_var |
No | - | Env var to use as fallback |
allow_empty |
No | false |
Allow empty secret values |
Authentication
Universal Auth (Recommended)
Set environment variables before running playbooks:
export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="ua-abc123"
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="secret-xyz789"
cd ansible
uv run ansible-playbook playbooks/my-playbook.yml
Environment Fallback
For local development or CI without Infisical:
export PROXMOX_PASSWORD="local-dev-password"
cd ansible
uv run ansible-playbook playbooks/my-playbook.yml
Security Best Practices
1. Use no_log
On tasks that handle secrets:
- name: Set database password
ansible.builtin.command: set-password {{ password }}
no_log: true
- name: Deploy config with secrets
ansible.builtin.template:
src: config.j2
dest: /etc/app/config.yml
no_log: true
2. Avoid Hard-Coded Secrets
# BAD - Exposes secrets
- name: Create user
community.proxmox.proxmox_user:
api_password: "my-password-123" # EXPOSED!
# GOOD
- name: Retrieve password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'PROXMOX_PASSWORD'
secret_var_name: 'proxmox_password'
- name: Create user
community.proxmox.proxmox_user:
api_password: "{{ proxmox_password }}"
no_log: true
3. Validate Secret Retrieval
Add validation for critical secrets:
- name: Get database password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
- name: Validate password complexity
ansible.builtin.assert:
that:
- db_password | length >= 16
fail_msg: "Password doesn't meet complexity requirements"
no_log: true
4. Limit Secret Scope
Retrieve secrets only when needed:
# GOOD - Retrieve only when needed
- name: System tasks (no secrets)
ansible.builtin.apt:
name: nginx
state: present
- name: Get credentials (only when needed)
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
- name: Configure database connection
ansible.builtin.template:
src: db-config.j2
dest: /etc/app/db.yml
no_log: true
5. Use Environment Isolation
Separate secrets by environment:
# Production
- name: Get prod secret
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
infisical_env: 'prod'
infisical_path: '/production/database'
# Development
- name: Get dev secret
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
infisical_env: 'dev'
infisical_path: '/development/database'
Multiple Secrets Pattern
---
- name: Deploy application with secrets
hosts: app_servers
become: true
vars:
infisical_project_id: '7b832220-24c0-45bc-a5f1-ce9794a31259'
infisical_env: 'prod'
infisical_path: '/app-config'
tasks:
- name: Retrieve database password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'DB_PASSWORD'
secret_var_name: 'db_password'
- name: Retrieve API key
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'API_KEY'
secret_var_name: 'api_key'
- name: Retrieve Redis password
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'REDIS_PASSWORD'
secret_var_name: 'redis_password'
- name: Deploy application config
ansible.builtin.template:
src: app-config.j2
dest: /etc/app/config.yml
owner: app
group: app
mode: '0600'
no_log: true
CI/CD Integration
GitHub Actions
name: Deploy
on: push
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Infisical
env:
INFISICAL_CLIENT_ID: ${{ secrets.INFISICAL_CLIENT_ID }}
INFISICAL_CLIENT_SECRET: ${{ secrets.INFISICAL_CLIENT_SECRET }}
run: |
echo "INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=$INFISICAL_CLIENT_ID" >> $GITHUB_ENV
echo "INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=$INFISICAL_CLIENT_SECRET" >> $GITHUB_ENV
- name: Run Ansible
run: |
cd ansible
uv run ansible-playbook playbooks/deploy.yml
Troubleshooting
Missing Authentication
Error: Missing Infisical authentication credentials
Solution:
export INFISICAL_UNIVERSAL_AUTH_CLIENT_ID="ua-abc123"
export INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET="secret-xyz789"
Secret Not Found
Error: Failed to retrieve secret from Infisical
Check:
- Secret exists at specified path in Infisical
- Correct project_id/env/path
- Service account has read permission
Empty Secret Value
Error: Secret validation failed (empty value)
Solutions:
# Option 1: Allow empty (not recommended for required secrets)
- name: Get optional secret
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'OPTIONAL_KEY'
secret_var_name: 'optional_key'
allow_empty: true
# Option 2: Use fallback
- name: Get secret with fallback
ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
vars:
secret_name: 'API_KEY'
secret_var_name: 'api_key'
fallback_env_var: 'DEFAULT_API_KEY'
Additional Resources
For detailed secrets management patterns, consult:
references/secrets-management.md- Infisical integration patterns, no_log best practices, credential security
Related Skills
- ansible-fundamentals - Core Ansible patterns
- ansible-error-handling - Error handling for secret retrieval failures