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 using the role variable npm_api_hosts:

# group_vars/npm.yml or --extra-vars
npm_api_hosts:
  - domain_name: "site-a.example.com"
    host: "172.16.1.10"
    ssl_forced: false
  - domain_name: "site-b.example.com"
    host: "172.16.1.20"
    ssl_forced: true
    letsencrypt_email: "admin@example.com"
  - domain_name: "site-c.example.com"
    host: "172.16.1.30"
    host_port: 3000
    ssl_forced: true
    letsencrypt_email: "admin@example.com"

- name: NPM - batch create proxy hosts
  hosts: localhost
  gather_facts: no
  roles:
    - role: npm-management

How batch execution works

The role automatically splits the list into two phases:

1. Without SSL — hosts where ssl_forced is false (or inherits npm_api_ssl_forced: false default). These run in parallel with no throttle, since no certificate provisioning is needed (timeout: 30s).

2. With SSL — hosts where ssl_forced is true. These run sequentially (throttle: 1) because each host triggers a Let's Encrypt certificate request via certbot, which can take 10-30 seconds. Running them in parallel would cause timeouts or rate-limit errors (timeout: 120s).

You do not need to separate the list manually — the role handles the split automatically based on each item's ssl_forced value (or the global npm_api_ssl_forced default).

Tip: If all your hosts need SSL, set the global default and omit ssl_forced per item:

npm_api_ssl_forced: true
npm_api_letsencrypt_email: "admin@example.com"
npm_api_hosts:
  - domain_name: "site-a.example.com"
    host: "172.16.1.10"
  - domain_name: "site-b.example.com"
    host: "172.16.1.20"

All hosts will be processed sequentially with SSL.

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