Variable #

In large-scale infrastructure automation, flexibility is one of the main pillars of success. You don’t want to create dozens of nearly identical playbooks just because a few small parameters — like service ports, database names, or backup directory locations — differ on each server. Ansible solves this through the Variables mechanism. By separating static playbook logic from dynamic parameter data in the inventory, you can use one identical playbook to manage hundreds of different servers. This article breaks down inventory variable definition methods, complex variable folder structures, important connection variables, precedence order, and per-environment variable management.

Dynamic Configuration Abstraction #

Philosophically, variables in the Ansible inventory act as a dynamic abstraction bridge. Through variables, you can apply object-oriented programming concepts to server management: you set the basic behavior (methods) at the playbook level, while property data (properties) is injected dynamically when the playbook executes based on the target host.

This provides three huge operational advantages:

Reusability: Your playbooks are free of hardcoded values, so they’re safe to share in public repositories.
Sensitive Data Security: You can separate secret-valued variables (like API tokens) for special encryption, while the playbook code remains clearly readable.
Environment Portability: You can easily replicate the production infrastructure layout to a local development environment just by changing the relevant variable files.

Three Variable Definition Methods #

Ansible provides three main places to put variables at the inventory level. Choosing where affects ease of maintenance as your team grows.

1. Directly in the Inventory File (Inline Variables) #

This method defines variables right next to the IP address or hostname in the hosts.ini or hosts.yml file.

INI Format (Inline Variables):

# File: inventory/hosts.ini
[webservers]
web-01.example.com http_port=80 max_clients=200
web-02.example.com http_port=8080 max_clients=100

[webservers:vars]
nginx_version=1.24
deploy_dir=/opt/nginx

YAML Format (Inline Variables):

# File: inventory/hosts.yml
---
webservers:
  hosts:
    web-01.example.com:
      http_port: 80
      max_clients: 200
    web-02.example.com:
      http_port: 8080
      max_clients: 100
  vars:
    nginx_version: "1.24"
    deploy_dir: /opt/nginx

# ANTI-PATTERN: Piling variables directly into the inventory file
# hosts.ini
web-01.example.com http_port=80 max_clients=200 db_user=root db_pass=secret log_level=debug path=/opt/app

# CORRECT: Keep the inventory file clean with only the host and group list
# hosts.ini
web-01.example.com

Writing inline variables like the anti-pattern example above is strongly discouraged for long-term projects because it ruins inventory file readability and makes tracking variable changes through Git commit history harder.

2. Using the group_vars/ Directory (Group-Level Variables) #

Ansible automatically loads all variables from a directory named group_vars/ placed adjacent to your inventory file or playbook file. The YAML file names inside this folder must represent the target server group names.

inventory/
  ├── hosts.ini
  └── group_vars/
      ├── all.yml          # Global variables for all hosts
      ├── webservers.yml   # Only for hosts in the webservers group
      └── dbservers.yml    # Only for hosts in the dbservers group

Example contents of the group_vars/webservers.yml file:

# File: inventory/group_vars/webservers.yml
---
nginx_version: "1.24"
http_port: 80
https_port: 443
nginx_worker_processes: 4
deploy_path: /opt/webapp

3. Using the host_vars/ Directory (Host-Level Variables) #

For cases where a server has special parameters different from other servers in the same group (for example a primary database server needs a larger memory cache than the replica), you put its variables in the host_vars/ directory.

inventory/
  ├── hosts.ini
  └── host_vars/
      ├── db-primary.example.com.yml
      └── db-replica-01.example.com.yml

Example contents of the host_vars/db-primary.example.com.yml file:

# File: inventory/host_vars/db-primary.example.com.yml
---
db_max_connections: 500
db_shared_buffers: "4GB"
# Primary server status indicator
db_is_primary: true

Folder Structure for Complex Variables #

When your automation project manages dozens of complex services, a single group_vars/webservers.yml file can balloon to hundreds of lines mixing Nginx, SSL, PHP, and monitoring system variables. This makes parameter modification harder.

Ansible supports splitting variables using a subdirectory structure. You can turn the group_vars/webservers.yml file into a directory named group_vars/webservers/, then split it into several separate files by concern:

inventory/group_vars/
  ├── all/
  │   ├── common.yml
  │   └── security.yml
  │
  └── webservers/                  # Replaces the webservers.yml file
      ├── main.yml                 # Common group variables
      ├── nginx.yml                # Nginx web server-specific configuration
      ├── php-fpm.yml              # PHP processor configuration
      └── monitoring.yml           # Prometheus monitoring agent variables

Ansible processes every .yml or .yaml file inside the webservers/ folder alphabetically and merges them into a single webservers group variable namespace.

Breaking Down Important Connection Parameters #

Ansible has a set of special built-in variables prefixed with the ansible_ keyword. These variables aren’t for your application configuration — they control the tactical SSH connection and authentication behavior from the control node to managed nodes.

Here’s the list of connection variables you must understand:

ansible_host: The actual IP address or alternative hostname used for the connection if the hostname registered in the inventory is just an alias.
```
# Example alias usage in hosts.ini:
# prod-web-01 ansible_host=10.0.4.12
```
ansible_port: The target SSH connection port if the managed node is configured not to use the default SSH port (22).
ansible_user: The username used to log into the target server via SSH.
ansible_ssh_private_key_file: The path to the SSH private key file (for example ~/.ssh/id_ed25519) if you’re not using agent forwarding.
ansible_python_interpreter: Specifies the absolute path to the Python interpreter on the target server. Very important if the target server uses a custom Python version (like /usr/bin/python3 on modern Ubuntu or /usr/libexec/platform-python on RHEL 8).
ansible_connection: The connection type used. The default is ssh. Other options are local (to execute local mechanisms on the control node) or winrm (for Windows servers via WinRM).
ansible_ssh_common_args: Adds additional global SSH arguments. This parameter is critical in secure production network topologies where your managed node servers sit in closed private subnets without direct public IP access. You can use proxy tunneling through a Bastion machine (Jump Host):
```
# Example routing the SSH connection to the target server through a Bastion Host
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q [email protected]"'
```
ansible_ssh_extra_args: Used to add extra SSH arguments attached only to data transfer command executions (like SFTP/SCP), while interactive connections keep using the common configuration.
ansible_ssh_pass & ansible_become_pass: Store the SSH password and sudo privilege escalation password. Remember, storing this data in plaintext in variable files is a high security threat. These parameters must always be encrypted with Ansible Vault.

Example global connection parameter configuration in group_vars/all.yml:

# File: inventory/group_vars/all.yml
---
ansible_user: deployer
ansible_port: 22
ansible_ssh_private_key_file: ~/.ssh/id_ed25519
ansible_python_interpreter: /usr/bin/python3
ansible_become: true
ansible_become_method: sudo

Hierarchy and Precedence Order #

One of the aspects that most often triggers confusion and playbook execution logic failures is a wrong understanding of Precedence. When a variable with the same name is defined in several places at once, Ansible applies strict priority resolution rules.

Here’s the inventory-level special variable priority order, sorted from lowest priority (easiest to override) to highest priority (strongest override):

Inventory Variable Priority (Low to High):
  1. group_vars/all (Global Level)            ← Lowest Priority
  2. group_vars/parent (Parent Group)         ← Inherits base properties
  3. group_vars/child (Child Group)          ← More specific than the parent
  4. host_vars (Host-Specific Level)          ← Highest Inventory Priority

The visualization of this priority inheritance can be seen in the following diagram:

flowchart TD
    A["group_vars/all (Priority 1)"] -->|"Overridden by"| B["group_vars/parent (Priority 2)"]
    B -->|"Overridden by"| C["group_vars/child (Priority 3)"]
    C -->|"Overridden by"| D["host_vars/host.yml (Priority 4)"]
    D -->|"Overridden by"| E["Playbook / CLI level variables (Priority 5+)"]

Real Precedence Resolution Case Study: #

Suppose we define the application port http_port in the following files:

In group_vars/all.yml (all servers):
```
http_port: 80
```
In group_vars/webservers.yml (web group):
```
http_port: 8080
```
In host_vars/web-01.example.com.yml (specific host):
```
http_port: 9090
```

The final resolution result when Ansible processes the variables:

For the web-01.example.com server, the http_port value is 9090 (because host_vars overrides everything).
For the web-02.example.com server (also a member of the webservers group), the http_port value is 8080 (because group_vars/webservers overrides it).
For the db-01.example.com server (not a member of the webservers group), the http_port value is 80 (using the global value from group_vars/all).

Multi-Environment Strategy #

In modern application release cycles, you must isolate configuration between Development, Staging, and Production environments. You use the same playbook but inject different variables for each environment using a separate inventory folder architecture.

The multi-environment layout implementation path:

environments/
  ├── staging/
  │   ├── hosts.ini
  │   └── group_vars/
  │       ├── all.yml          # Global variables for the Staging environment
  │       └── webservers.yml   # Staging web server configuration
  │
  └── production/
      ├── hosts.ini
      └── group_vars/
          ├── all.yml          # Global variables for the Production environment
          └── webservers.yml   # Production web server configuration

Variable Value Differences by Environment #

Staging (environments/staging/group_vars/all.yml):

env_label: "staging"
db_host: "staging-db.internal"
enable_debug_mode: true
log_level: "debug"

Production (environments/production/group_vars/all.yml):

env_label: "production"
db_host: "prod-db-cluster.internal"
enable_debug_mode: false
log_level: "error"

When you trigger an execution, these behavioral differences are controlled explicitly from your terminal command line:

# Run deployment to staging
ansible-playbook -i environments/staging/ playbooks/deploy.yml

# Run deployment to production
ansible-playbook -i environments/production/ playbooks/deploy.yml

Anti-Patterns and Mitigation #

Here are some common mistakes (anti-patterns) in inventory variable management along with how to fix them.

1. Storing Sensitive Credentials in Plaintext #

Storing API tokens, database passwords, or SSH private keys directly in YAML files in plaintext format that anyone can read.

# ANTI-PATTERN: Plaintext credentials in group_vars/all.yml
db_password: "MySuperSecretDBPassword123"

Mitigation: Always use Ansible Vault to encrypt sensitive variables. You’re recommended to separate non-sensitive variables from sensitive ones into separate files in the same group folder:
- Non-sensitive file: group_vars/webservers/vars.yml
- Encrypted file: group_vars/webservers/vault.yml (encrypted with the ansible-vault encrypt command)

2. Excessive Variable Duplication #

Repeatedly defining parameters with the same value in every group variable file.

# ANTI-PATTERN: Duplicated data in group_vars/webservers.yml and group_vars/dbservers.yml
# group_vars/webservers.yml
timezone: "Asia/Jakarta"
ntp_server: "time.unisbadri.com"

# group_vars/dbservers.yml
timezone: "Asia/Jakarta"
ntp_server: "time.unisbadri.com"

Mitigation: Move all homogeneous parameters (the same for all servers) into the global group_vars/all.yml file. Group-specific files should only contain variables unique to that group.

Summary #

Logic & Parameter Separation — Variables separate static playbook execution flow from dynamic target server configuration data to optimize reusability.
Three Declaration Methods — Inventory-level variables can be written inline in the hosts file, in group_vars/ files (groups), or host_vars/ files (specific hosts).
Complex Folder Abstraction — Replacing a single group YAML file with a directory of concern-based files (like nginx.yml, ssl.yml) makes long-term maintenance easier.
Special Authentication Variables — Connection behavior options are managed by internal parameters like ansible_user, ansible_port, and ansible_python_interpreter.
Strict Precedence Rules — Variable inheritance follows a priority order: host_vars overrides group_vars/child, which then overrides group_vars/parent, which in turn overrides group_vars/all.
Multi-Environment Isolation — Dev/staging/production parameter data separation is managed through physically separate inventory directories under the environments/ folder.
Credential Leak Prevention — Always use Ansible Vault encryption to protect sensitive parameters (secret keys, passwords) before uploading automation code to Git.

← Previous: What is Inventory? Next: Cloud →