The intersection of configuration management and identity-aware access control represents a critical evolution in modern DevOps practices. Ansible, as a dominant force in the automation landscape, traditionally relies on static SSH keys or passwords to manage fleets of Linux hosts. While effective, this model introduces significant security risks, such as key sprawl, the difficulty of rotating credentials, and a lack of granular auditability. Teleport transforms this paradigm by replacing static credentials with a certificate-based authentication system, acting as an identity-aware access proxy. By integrating Teleport with Ansible, organizations can transition from a permanent-access model to a zero-trust architecture where Ansible controllers utilize short-lived SSH certificates to execute automation tasks. This integration ensures that every action performed by an automation script is authenticated, authorized via Role-Based Access Control (RBAC), and fully recorded for compliance purposes.
The Architecture of Teleport-Enabled SSH Access
In a conventional Ansible deployment, the controller establishes a direct TCP connection to the target node's port 22. This requires the controller to possess a private key that matches a public key residing in the target's authorized_keys file. Teleport fundamentally alters this flow by introducing a proxy layer and a certificate authority.
The operational flow in a Teleport-integrated environment consists of three primary phases. First, the operator or the automation agent authenticates with the Teleport cluster using the tsh login command. This process verifies the user's identity against a supported identity provider. Second, upon successful authentication, the Teleport cluster issues short-lived SSH certificates. These certificates are cryptographically signed and contain the user's identity and assigned roles. Third, Ansible uses these certificates to connect to nodes registered within the Teleport cluster. Because the target nodes trust the Teleport Cluster's Certificate Authority (CA), they accept these short-lived certificates without needing a pre-shared static key.
The primary security benefit of this architecture is the elimination of long-lived credentials. If a controller is compromised, the stolen certificates will expire shortly, drastically reducing the window of opportunity for an attacker. Furthermore, because the connection is routed through the Teleport Proxy Service, all sessions are recorded, providing a definitive audit trail of every command executed by Ansible.
Technical Prerequisites and Version Compatibility
To successfully implement this integration, specific software versions and tools must be in place. Ensuring version alignment is critical to avoid protocol mismatches or missing feature sets.
Required Software Stack
The following components are mandatory for a functional setup:
- Teleport Cluster: A running instance of Teleport, ideally version 15.4.0 or above. For instance, a verified stable configuration uses Teleport cluster version 15.4.7.
- Ansible: Version 2.9.6 or higher is required. Advanced implementations may utilize Ansible 2.15.10 for enhanced feature support.
- OpenSSH: The
opensshtoolset is required, such as version 3.0.13. - Teleport Client Tools: The
tsh(Teleport Smart Helper) andtctl(Teleport Control) clients must be installed on the machine initiating the Ansible connection.
Version Alignment Strategy
A critical technical requirement for the tctl and tsh clients is that they must be at most one major version behind the Teleport cluster version. This ensures compatibility between the client's request format and the server's API. To determine the exact version of a running Teleport cluster, a GET request should be sent to the Proxy Service at the following endpoint:
GET /v1/webapi/find
By processing the resulting JSON output with a query tool, administrators can verify the cluster version and ensure the local clients are updated accordingly.
Configuring the Teleport-Ansible Connection
The integration requires a bridge between the Teleport certificate system and the Ansible SSH engine. This is achieved by generating an OpenSSH configuration file that tells Ansible how to route its traffic through the Teleport proxy.
Certificate Generation and Configuration Export
Before Ansible can communicate with a node, the environment must be authenticated. The process begins with the tsh client:
tsh login --proxy={teleport_proxy} --user={teleport_user}
Once authenticated, the Teleport configuration must be exported into a format that the standard OpenSSH client (which Ansible uses under the hood) can understand. This is done by redirecting the output of the tsh config command:
tsh config > teleport.cfg
This operation queries the Teleport cluster for the necessary proxy addresses, port mappings, and identity details, writing them into teleport.cfg. This file acts as the map that directs Ansible's SSH requests through the Teleport Proxy Service instead of attempting a direct, unauthenticated connection to the node.
Integration Methods: Global vs. Targeted
Depending on the infrastructure scale, administrators can apply the Teleport configuration in two distinct ways: globally via ansible.cfg or specifically via the inventory file.
The Global Configuration Approach
If the entire infrastructure is managed by Teleport, the most efficient method is to modify the ansible.cfg file. This ensures that every single connection made by the Ansible controller utilizes the Teleport proxy.
In the ansible.cfg file, the following settings are added under the [ssh_connection] section:
ini
[ssh_connection]
scp_if_ssh = True
ssh_args = -F ./teleport.cfg
The ssh_args = -F ./teleport.cfg directive tells the underlying SSH process to use the specified configuration file for all connections. Setting scp_if_ssh = True ensures that file transfers utilize the same secure tunnel.
The Targeted Inventory Approach
In hybrid environments where some servers are managed by Teleport and others are not, the global approach is counterproductive. In such cases, the Teleport configuration should be defined at the host or group level within the Ansible inventory.
By defining variables specifically for a Teleport group, Ansible only applies the proxy configuration to those specific targets. The inventory should be structured as follows:
yaml
teleport:
hosts:
{node_name}.{teleport_proxy}:
vars:
ansible_user: {teleport_user}
ansible_ssh_common_args: -F teleport.cfg
ansible_scp_if_ssh: true
In this scenario, ansible_ssh_common_args passes the -F teleport.cfg flag specifically to the SSH commands targeting the Teleport-managed nodes.
Practical Implementation Examples
To illustrate the application of these configurations, consider a hypothetical cluster named example.com with a node named test and a system user named teleport.
Inventory Configuration
The inventory.yml file would be structured as follows to isolate the Teleport-managed environment:
yaml
all:
children:
teleport_dp_dev:
hosts:
test.example.com:
vars:
ansible_user: devop
ansible_ssh_common_args: -F teleport.cfg
ansible_scp_if_ssh: true
Execution of Commands
Once the inventory and teleport.cfg are in place, Ansible can be executed as usual. The complexity of the proxy and certificates is abstracted away from the command line.
For an ad-hoc shell command to update a system:
ansible all -i inventory.yml -m shell -a "sudo apt update && sudo apt upgrade -y" --become --limit test.example.com
For executing a comprehensive playbook:
ansible-playbook -i inventory.yml Ansible/playbooks/42m.example.yml --limit test.example.com
Advanced Automation: Machine & Workload Identity
For fully automated pipelines—such as those running in CI/CD environments where a human cannot manually run tsh login—Teleport provides the Machine & Workload Identity agent, known as tbot.
tbot is designed to automate the issuance of short-lived certificates for machines. Instead of a human interactive login, tbot uses a machine identity to request certificates from the Teleport cluster. This allows Ansible to run in a non-interactive mode while still benefiting from the security of short-lived certificates. tbot manages the lifecycle of the credentials and the OpenSSH configuration, ensuring that the teleport.cfg file is updated and the certificates are rotated before they expire. This is essential for integrating Ansible with tools like Ansible AWX or the Ansible Automation Platform, where the automation is triggered by events rather than manual user intervention.
Dynamic Inventory Integration
To further streamline the workflow, the integration can be extended to the inventory discovery phase. Using specialized scripts, such as those found in the teleport-ansible package, Teleport can serve as a dynamic inventory source.
In a standard setup, the inventory is a static file. With a dynamic Teleport inventory script, Ansible queries the Teleport API to retrieve a real-time list of all nodes registered in the cluster. The script reads the machine data from Teleport and returns it in a JSON format that Ansible understands. This removes the need to manually update inventory.yml whenever a new node is added to the Teleport cluster, ensuring that the automation target list is always synchronized with the actual infrastructure state.
Integrating Teleport with ARA for Centralized Logging
For organizations requiring high visibility into their automation, Teleport can be used to provide secure access to ARA (Ansible Records and presents), a tool that logs Ansible execution data and presents it in a collaborative web interface.
By leveraging Teleport Applications, the ARA server can be exposed through the Teleport proxy, ensuring that only authorized users can access the automation logs. This is configured within the teleport.yaml file on the ARA server:
yaml
app_service:
enabled: true
debug_app: false
apps:
- name: ara
uri: http://127.0.0.1:8000
insecure_skip_verify: true
rewrite:
redirect:
- "127.0.0.1:8000"
- "127.0.0.1"
This configuration maps the ARA service running on port 8000 to a Teleport application, allowing administrators to access the ARA dashboard securely through the Teleport identity-aware proxy.
Technical Specification Summary
The following table summarizes the technical requirements and configuration parameters for the Teleport and Ansible integration.
| Component | Requirement/Value | Purpose |
|---|---|---|
| Teleport Cluster | $\ge$ 15.4.0 | Minimum version for full compatibility |
| Ansible Version | $\ge$ 2.9.6 | Minimum version for SSH argument support |
| OpenSSH Version | 3.0.13 (Example) | Base transport layer |
| Client Versioning | $\le$ 1 major version behind cluster | Ensures API compatibility |
| Configuration File | teleport.cfg |
Directs SSH traffic to Teleport Proxy |
| SSH Flag | -F teleport.cfg |
Specifies the config file for OpenSSH |
| Automation Agent | tbot |
Handles non-interactive certificate rotation |
| Logging Tool | ARA | Provides centralized Ansible execution logs |
Conclusion
The integration of Teleport with Ansible represents a sophisticated shift toward secure, identity-driven infrastructure management. By replacing static SSH keys with a certificate-based proxy system, organizations resolve the inherent tension between the need for widespread automation and the requirement for strict security controls. The transition from manual tsh login workflows to automated tbot identity management allows this security model to scale into CI/CD pipelines and large-scale enterprise environments.
The ability to choose between global configuration in ansible.cfg and targeted configuration in the inventory provides the necessary flexibility for hybrid environments. When combined with dynamic inventory scripts and centralized logging through ARA, the resulting system is not merely an automation framework, but a secure, auditable, and scalable orchestration platform. The removal of long-lived credentials and the introduction of session recording ensure that the "blast radius" of any potential credential leak is minimized and that every administrative action is fully transparent.