Variables, Credentials & Field Mapping
Define host, inventory, and reusable variable sets, and understand the canonical ciel_* to ansible_* connection parameter mapping.
CIEL manages configuration values and credentials across host entities, inventory scopes, and reusable variable sets, projecting them into executable Ansible inventory structures at runtime.
1. Variable Scopes in CIEL
Configuration variables can be applied at four distinct levels depending on required scope:
A. Host Entity Variables
- Location: Defined on individual servers under Hosts (
/hosts). - Use Case: Parameters specific to a single physical or virtual machine, such as a custom SSH port, unique network interface, or node ID.
- Example:
yaml
cluster_node_id: 3 bind_interface: "eth1" ciel_port: 2222
B. Inventory Variables
- Location: Configured in an inventory workspace under the Variables tab.
- Use Case: Shared configuration applied across all hosts assigned to that inventory group, such as common sudo privilege flags or regional internal mirrors.
- Example:
yaml
ciel_become: true ciel_become_user: "root" ciel_python_interpreter: "/usr/bin/python3"
C. Reusable Variable Sets (/variables)
- Location: Created and managed under Variable Sets (
/variables). - Use Case: Named YAML or key-value bundles assigned across multiple playbooks, inventories, or scheduled runs without duplicating configuration.
- Examples:
database-production: Database endpoints, replica hosts, connection pool sizes.observability-agent: Prometheus scrape ports, Loki endpoints, retention limits.
D. Runtime Extra Variables
- Location: Passed dynamically in the Run Options drawer, through webhook payloads, or via automated schedules.
- Use Case: Ephemeral deployment overrides (e.g.
app_version: "v2.1.0",migration_dry_run: true). Runtime extra variables take absolute precedence over all static scopes.
2. Canonical ciel_* Variable Mapping
When compiling inventory data for Ansible execution, CIEL automatically translates canonical ciel_* variables into standard Ansible connection variables (documented in the Ansible Connection Methods & Details Guide). You can use either naming convention interchangeably:
Connection & Authentication
| CIEL Variable | Ansible Parameter | Description |
|---|---|---|
ciel_connection | ansible_connection | Connection plugin (ssh, winrm, local) |
ciel_host | ansible_host | Target IP address or hostname |
ciel_port | ansible_port | Remote connection port (e.g. 22 or 5986) |
ciel_user | ansible_user | Login username for remote access |
ciel_password | ansible_password | Password for SSH or WinRM authentication |
SSH Options & Keys
| CIEL Variable | Ansible Parameter | Description |
|---|---|---|
ciel_key | ansible_ssh_private_key_file | Explicit path to SSH private key |
ciel_ssh_common_args | ansible_ssh_common_args | Arguments passed to ssh, sftp, and scp |
ciel_ssh_extra_args | ansible_ssh_extra_args | Extra arguments passed to ssh only |
ciel_ssh_pipelining | ansible_ssh_pipelining | Enable or disable SSH pipelining (boolean) |
ciel_ssh_timeout | ansible_ssh_timeout | SSH connection timeout in seconds |
Privilege Escalation (Become)
| CIEL Variable | Ansible Parameter | Description |
|---|---|---|
ciel_become | ansible_become | Enable privilege escalation (true or false) |
ciel_become_user | ansible_become_user | Target privilege user (defaults to root) |
ciel_become_method | ansible_become_method | Escalation method (sudo, su, runas) |
ciel_become_password | ansible_become_password | Sudo or escalation password |
ciel_become_flags | ansible_become_flags | Flags passed to the become command |
Python Interpreter & Shell
| CIEL Variable | Ansible Parameter | Description |
|---|---|---|
ciel_python_interpreter | ansible_python_interpreter | Target Python binary path (or auto_silent) |
ciel_shell_type | ansible_shell_type | Target shell type (sh, bash, powershell) |
ciel_shell_executable | ansible_shell_executable | Absolute path to target shell |
Windows WinRM & Networking
| CIEL Variable | Ansible Parameter | Description |
|---|---|---|
ciel_winrm_transport | ansible_winrm_transport | WinRM transport (ntlm, ssl, basic) |
ciel_winrm_server_cert_validation | ansible_winrm_server_cert_validation | Validation policy (validate or ignore) |
ciel_winrm_scheme | ansible_winrm_scheme | Connection scheme (http or https) |
ciel_network_os | ansible_network_os | Operating system for network hardware modules |
3. Secret Variables and Masking
For sensitive values such as database passwords, API tokens, and sudo credentials:
- Granular
isSecretToggle: In the variable mapping editor, toggle the secret flag on individual keys. Only marked keys are treated as confidential; other configuration values remain visible in plaintext. - Encryption at Rest: Sensitive values are encrypted using AES-256-GCM before writing to the database.
- Projection Masking: In the inventory YAML preview and API responses delivered to unauthorized users, secret variable values are replaced with
********. - Runtime Resolution: The execution engine decrypts secret variables only when assembling the execution environment for an active job, passing them to the runner process without exposing them in unprivileged logs.
4. External References
For upstream Ansible parameter documentation and connection behavior:
- Ansible Connection Methods & Details: Complete reference for Ansible connection plugins and transport variables.
- Ansible Privilege Escalation (Become): Documentation on sudo, su, and become configuration flags.
- Ansible Windows Remoting (WinRM): Transport types, NTLM/Kerberos authentication, and certificate validation.
- Ansible Python Interpreter Discovery: Behavior of
auto_silentand explicit Python path definitions.