Using Teleport Machine ID with Ansible

In this guide, you will set up an Ansible playbook to run the OpenSSH client with a configuration file that is automatically managed by Machine ID.

Prerequisites

You will need the following tools to use Teleport with Ansible.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21

tsh version
Teleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com

• ssh OpenSSH tool

• ansible >= 2.9.6

• Optional: jq to process JSON output

• If you already have not done so, follow the Machine ID Getting Started Guide to create a bot user and start Machine ID.

• If you followed the above guide, note the --destination-dir=/opt/machine-id flag, which defines the directory where SSH certificates and OpenSSH configuration used by Ansible will be written.

  In particular, you will be using the /opt/machine-id/ssh_config file in your Ansible configuration to define how Ansible should connect to Teleport Nodes.

• To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands on your administrative workstation using your current credentials. For example:

  tsh login --proxy=teleport.example.com --user=[email protected]
  tctl status
  Cluster  teleport.example.com
  Version  14.0.1
  CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

  If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/2. Configure Ansible

Create a folder named ansible where all Ansible files will be collected.

mkdir -p ansible
cd ansible

Create a file called ansible.cfg. We will configure Ansible to run the OpenSSH client with the configuration file generated by Machine ID, /opt/machine-id/ssh_config. Note, example.com here is the name of your Teleport cluster.

[defaults]host_key_checking = Trueinventory=./hostsremote_tmp=/tmp
[ssh_connection]scp_if_ssh = True
Replace ".example.com" below with the name of your cluster.
ssh_args = -F /opt/machine-id/ssh_config -o CanonicalizeHostname=yes -o CanonicalDomains=example.com

You can create an inventory file called hosts manually or use a script like the one below to generate it from your environment.

tsh ls --format=json | jq -r '.[].spec.hostname' > hosts

Step 2/2. Run a playbook

Finally, let's create a simple Ansible playbook, playbook.yaml.

The playbook below runs hostname on all hosts. Make sure to set the remote_user parameter to a valid SSH username that works with the target host and is allowed by Teleport RBAC. If you followed the Machine ID getting started guide, this user will be root. Assign root to the username.

- hosts: all  remote_user: root  tasks:    - name: "hostname"      command: "hostname"

From the folder ansible, run the Ansible playbook:

ansible-playbook playbook.yaml

PLAY [all] *****************************************************************************************************************************************
TASK [Gathering Facts] *****************************************************************************************************************************
ok: [terminal]
TASK [hostname] ************************************************************************************************************************************
changed: [terminal]
PLAY RECAP *****************************************************************************************************************************************
terminal                   : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

You are all set. You have provided your machine with short-lived certificates tied to a machine identity that can be rotated, audited, and controlled with all the familiar Teleport access controls.

Troubleshooting

In case if Ansible cannot connect, you may see error like this one:

example.host | UNREACHABLE! => {
    "changed": false,
    "msg": "Failed to connect to the host via ssh: ssh: Could not resolve hostname node-name: Name or service not known",
    "unreachable": true
}

You can examine and tweak patterns matching the inventory hosts in ssh_config.

Try the SSH connection using ssh_config with verbose mode to inspect the error:

ssh -vvv -F /opt/machine-id/ssh_config [email protected]

If ssh works, try running the playbook with verbose mode on:

ansible-playbook -vvv playbook.yaml