Configuration

Configuration

Role Variables

All variables can be overridden via inventory, group_vars, host_vars, or --extra-vars.

Required Variables

Variable	Description	Default
npm_user	NPM admin email (store in Vault)	—
npm_password	NPM admin password (store in Vault)	—
npm_api_domain_name	Domain name for the proxy host	""
npm_api_host	Forward hostname / IP	""

Optional Variables

Variable	Description	Default
npm_api_url	NPM API base URL	http://localhost:81/api
npm_api_state	present to create, absent to delete	present
npm_api_ssl_forced	Force SSL on the proxy host	false
npm_api_letsencrypt_email	Email for Let's Encrypt certificates	""
npm_api_host_port	Forward port	80
npm_api_hosts	List of proxy hosts for batch operations (see below)	[]

Batch Host Item Properties (npm_api_hosts)

Each item in npm_api_hosts supports:

Property	Required	Default	Description
domain_name	yes	—	Domain name for the proxy host
host	yes	—	Forward hostname / IP
host_port	no	80	Forward port
ssl_forced	no	npm_api_ssl_forced	Force SSL (determines execution phase)
letsencrypt_email	no	npm_api_letsencrypt_email	Email for Let's Encrypt certificate
state	no	npm_api_state	present or absent

SSL vs non-SSL execution: Hosts with ssl_forced: false run in parallel (fast, 30s timeout). Hosts with ssl_forced: true run sequentially with throttle: 1 (120s timeout) because Let's Encrypt certificate provisioning via certbot takes 10-30 seconds per domain.

Module Parameters (npm_proxy)

The custom module library/npm_proxy.py accepts these parameters:

Parameter	Type	Required	Default	Description
url	str	yes	—	NPM API base URL
token	str	yes	—	API access token (obtained via /tokens endpoint)
domain	str	yes	—	Domain name for the proxy host
host	str	yes	—	Forward hostname / IP
host_port	int	no	80	Forward port
ssl_forced	bool	no	true	Force SSL
letsencrypt_email	str	no	""	Email for Let's Encrypt certificate
state	str	no	present	present to create, absent to delete

File Locations

File	Purpose
roles/npm-management/defaults/main.yml	Default values (lowest precedence, safe to override)
roles/npm-management/vars/main.yml	Role variables (higher precedence)
roles/npm-management/vars/api_secret.yml	API credentials (Ansible Vault encrypted)

Overriding Variables

Via inventory (hosts)

[npm]
localhost ansible_connection=local

[npm:vars]
npm_api_url=http://10.0.0.5:81/api

Via group_vars

# group_vars/npm.yml
npm_api_url: http://10.0.0.5:81/api
npm_api_ssl_forced: true

Via extra vars (highest precedence)

ansible-playbook pl_npm-management.yml \
  --extra-vars "npm_api_domain_name=site.example.com npm_api_host=172.16.0.10"

Variable Precedence (Ansible)

From lowest to highest:

1. defaults/main.yml
2. Inventory variables
3. group_vars/
4. host_vars/
5. vars/main.yml
6. Task vars:
7. --extra-vars

Tip: Put npm_api_url in defaults/main.yml or inventory so it can be easily overridden per environment.