Skip to main content

Ansible Collection

Ansible collection for managing secrets with Arcan. Includes a lookup plugin for fetching secrets and modules for creating/updating secrets and realms.

Installation​

ansible-galaxy collection install getarcan.arcan

Or from source:

cd integrations/ansible
ansible-galaxy collection build
ansible-galaxy collection install getarcan-arcan-1.0.0.tar.gz

Authentication​

All plugins accept arcan_url and arcan_token as parameters. You can also set them via environment variables:

export ARCAN_URL=https://arcan.internal:9797
export ARCAN_TOKEN=arc_your_token_here

For playbooks, store the token in Ansible Vault:

ansible-vault encrypt_string 'arc_your_token' --name 'vault_arcan_token'

Plugins​

Lookup Plugin: getarcan.arcan.secret​

Fetch secrets for use in playbooks and templates.

# Single secret
- name: Get database URL
  debug:
    msg: "{{ lookup('getarcan.arcan.secret', 'DATABASE_URL', realm='production', env='prod') }}"

# Multiple secrets
- name: Get credentials
  debug:
    msg: "{{ lookup('getarcan.arcan.secret', 'DB_HOST', 'DB_PORT', realm='production') }}"

# With explicit auth
- name: Get secret
  debug:
    msg: >-
      {{ lookup('getarcan.arcan.secret', 'API_KEY',
         realm='myapp',
         arcan_url='https://arcan.internal:9797',
         arcan_token=vault_arcan_token) }}

# Self-signed certificates
- name: Get secret (skip cert check)
  debug:
    msg: "{{ lookup('getarcan.arcan.secret', 'KEY', realm='myapp', validate_certs=false) }}"

Module: getarcan.arcan.arcan_secret​

Create, update, or delete secrets.

# Create or update a secret
- name: Store database URL
  getarcan.arcan.arcan_secret:
    key: DATABASE_URL
    value: "postgres://user:pass@host:5432/db"
    realm: production
    env: prod
    state: present

# Delete a secret
- name: Remove old key
  getarcan.arcan.arcan_secret:
    key: OLD_API_KEY
    realm: production
    env: prod
    state: absent

The module is idempotent -- it only reports changed: true when the secret value actually differs.

Module: getarcan.arcan.arcan_realm​

Create or list realms.

# Create a realm
- name: Create production realm
  getarcan.arcan.arcan_realm:
    name: Production
    slug: production
    state: present

# List all realms
- name: List realms
  getarcan.arcan.arcan_realm:
    state: list
  register: result

- debug:
    var: result.realms

SSL / Self-Signed Certificates​

Arcan generates a self-signed CA by default. To skip certificate verification:

# Lookup
"{{ lookup('getarcan.arcan.secret', 'KEY', realm='app', validate_certs=false) }}"

# Modules
- getarcan.arcan.arcan_secret:
    key: MY_KEY
    value: my_value
    realm: app
    validate_certs: false

For production, configure a trusted CA or add the Arcan CA to your system trust store.

Security​

  • Use valid TLS certificates in production (not self-signed)
  • Store API tokens in Ansible Vault (not hardcoded)
  • Use read-only tokens (arcan token create --scopes read) for applications that only need to read secrets
  • Enable audit logging on the Arcan server to track all secret access

Requirements​

  • Python >= 3.8
  • Ansible >= 2.9