Usage Examples

Usage Examples

Create a Proxy Host

Minimal example (HTTP only)

- name: NPM - create proxy host
  hosts: localhost
  gather_facts: no
  roles:
    - role: npm-management
      npm_api_domain_name: "site.example.com"
      npm_api_host: "172.16.1.10"
      npm_api_state: present

With SSL (Let's Encrypt)

- name: NPM - create proxy host with SSL
  hosts: localhost
  gather_facts: no
  roles:
    - role: npm-management
      npm_api_domain_name: "secure.example.com"
      npm_api_host: "172.16.1.20"
      npm_api_ssl_forced: true
      npm_api_state: present

With custom port

Using the module directly to specify a non-default forward port:

- name: Create proxy host on custom port
  npm_proxy:
    url: "{{ npm_api_url }}"
    token: "{{ npm_access_token.json.token }}"
    domain: "app.example.com"
    host: "172.16.1.30"
    host_port: 8080
    ssl_forced: true
    state: present
  delegate_to: localhost

Delete a Proxy Host

Using the module directly:

- name: Delete proxy host
  npm_proxy:
    url: "{{ npm_api_url }}"
    token: "{{ npm_access_token.json.token }}"
    domain: "old-site.example.com"
    host: "172.16.1.10"
    state: absent
  delegate_to: localhost

Note: Deleting a proxy host with a certificate will also delete the associated certificate.

Batch Operations

Create multiple proxy hosts from a list:

# vars/proxy_hosts.yml
proxy_hosts:
  - domain: "site-a.example.com"
    host: "172.16.1.10"
    ssl: true
  - domain: "site-b.example.com"
    host: "172.16.1.20"
    ssl: false
  - domain: "site-c.example.com"
    host: "172.16.1.30"
    host_port: 3000
    ssl: true

- name: Create multiple proxy hosts
  npm_proxy:
    url: "{{ npm_api_url }}"
    token: "{{ npm_access_token.json.token }}"
    domain: "{{ item.domain }}"
    host: "{{ item.host }}"
    host_port: "{{ item.host_port | default(80) }}"
    ssl_forced: "{{ item.ssl | default(false) }}"
    state: present
  delegate_to: localhost
  throttle: 1
  loop: "{{ proxy_hosts }}"

Using with Ansible Vault

# Create encrypted credentials
ansible-vault create roles/npm-management/vars/api_secret.yml

# Run with vault password
ansible-playbook pl_npm-management.yml --ask-vault-pass

# Run with vault file
ansible-playbook pl_npm-management.yml --vault-password-file .vault-pass

API Token Lifecycle

The role automatically:

1. Validates credentials are defined (assert task)
2. Checks NPM API health (uri to API endpoint)
3. Obtains an access token (POST /api/tokens)
4. Uses the token for proxy host operations
5. Token is not persisted — obtained fresh each run

Module Return Values

# On success (created)
msg: "Proxy-host site.example.com created"
changed: true

# On success (already exists)
msg: "Proxy Host site.example.com already exists"
changed: false

# On success (deleted)
msg: "Proxy-host: site.example.com removed."
changed: true

# On error
msg: "Failed to connect to api host to create for proxy_host. Info: ..."
failed: true