Skill

ansible-secrets

Retrieves secrets securely in Ansible playbooks using Infisical vault integration, no_log directives, environment fallbacks, and reusable lookup tasks for credentials like Proxmox or DB passwords.

security

devops

Popularity

Parent stars

Parent forks

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/ansible-workflows:ansible-secrets

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

Secure secrets handling with Infisical integration and proper security practices.

Supporting Files

references/secrets-management.md

SKILL.md

351 lines · ~2.1k tokens

Stats

LanguagePython

Parent stars19

Parent forks1

MaintenanceFair

Last CommitMar 2, 2026

Actions

View Source View Plugin View on GitHub View README

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

ansible-secrets

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

ansible-secrets

Popularity

Invocation

Context Preview

Supporting Files

SKILL.md

Ansible Secrets Management

Architecture Overview

Reusable Task Pattern

Basic Usage

With Fallback

Task Parameters

Authentication

Universal Auth (Recommended)

Environment Fallback

Security Best Practices

1. Use no_log

2. Avoid Hard-Coded Secrets

3. Validate Secret Retrieval

4. Limit Secret Scope

5. Use Environment Isolation

Multiple Secrets Pattern

CI/CD Integration

GitHub Actions

Troubleshooting

Missing Authentication

Secret Not Found

Empty Secret Value

Additional Resources

Related Skills

Similar Skills

Ansible Secrets Management

Architecture Overview

Reusable Task Pattern

Basic Usage

With Fallback

Task Parameters

Authentication

Universal Auth (Recommended)

Environment Fallback

Security Best Practices

1. Use no_log

2. Avoid Hard-Coded Secrets

3. Validate Secret Retrieval

4. Limit Secret Scope

5. Use Environment Isolation

Multiple Secrets Pattern

CI/CD Integration

GitHub Actions

Troubleshooting

Missing Authentication

Secret Not Found

Empty Secret Value

Additional Resources

Related Skills

Similar Skills