Enrolling Linux VM Servers with Teleport Using Machine ID and Ansible (Without Long-Lived Certificates)

[pnrao1983]

Enrolling Linux VMs to a Teleport cluster efficiently without long-lived certificates is essential for secure, automated workflows. This guide details how to dynamically use Machine ID with Ansible to join Linux VMs to a Teleport cluster, minimizing the need for long-lived certificates.

Steps Overview

1. Log in to the Teleport cluster.
2. Generate an identity file using tctl if Machine ID is not enabled for your environment.
3. Configure Ansible Tower with the identity file and essential configurations.
4. Set up an Ansible playbook to install Teleport, configure the server, and start the Teleport service on each VM.
5. Run the playbook to enroll the servers automatically.

1. Log in to the Teleport cluster
tsh login --proxy example.teleport.sh --user user@your_domain.com

2. Generating an Identity File
You must create an identity file using Machine ID to generate certificates automatically. Follow the MachineID guide to create the Identity and rotate it or save it in a secret store based on your use case and as per your infra process: https://goteleport.com/docs/enroll-resources/machine-id/deployment/deployment/
Alternatively, execute the following command to create an identity file (cert), ensuring permissions in your role allow token management:
tctl auth sign --user=user@your_domain.com --out=ansible-identity

Note: Ensure your role has the following permissions:

- resources:
  - token
  verbs:
  - list
  - create
  - read
  - update
  - delete

Once generated, copy the ansible-identity file to Ansible Tower.

3. Configure Ansible for Teleport Enrollment
Create or modify the ansible.cfg configuration file for Ansible:

[defaults]
host_key_checking = True
inventory=/etc/ansible/hosts
remote_tmp=/tmp

[ssh_connection]
scp_if_ssh = True
#ssh_args = -F ./ssh.cfg   # Not needed if you're connecting to the instances outside of Teleport and not modifying the ssh params through an ssh parameterized config in other ways

Copy your ansible-identity file into the same directory as ansible.cfg

4. Writing the Ansible Playbook
Below is the ssh-node-join-ansible-playbook.yaml playbook. This playbook will:

• Stop any existing Teleport service.
• Remove previous Teleport binaries and configurations.
• Create a short-lived token for node enrollment.
• Install the Teleport Binary.
• Download and execute the join script to enroll the node.
• Start the Teleport service.

- name: Teleport SSH node join setup
  hosts: all
  gather_facts: false
  vars:
    teleport_identity_file: "/root/identity"  # Update with actual ansible identity file path
    teleport_auth_server: "example.teleport.sh:443"  # Replace with actual proxy server path

  pre_tasks:
    - name: Stop Teleport service if running
      become: true
      command: systemctl stop teleport
      ignore_errors: true

    - name: Remove existing Teleport data and binaries
      become: true
      command: >
        rm -rf /var/lib/teleport/ /usr/local/bin/teleport
        /usr/local/bin/tctl /usr/local/bin/tsh /etc/teleport.yaml
      ignore_errors: true

    - name: Remove existing Teleport packages
      become: true
      command: yum remove -y teleport-ent*
      ignore_errors: true

    - name: Generate a temporary Teleport node join token locally
      local_action:
        module: command
        args:
          cmd: "tctl tokens add --type=node --format=text --ttl=2m --identity {{ teleport_identity_file }} --auth-server {{ teleport_auth_server }}"
      delegate_to: localhost
      register: token_result
      failed_when: token_result.rc != 0

    - name: Set join token URL variable
      set_fact:
        teleport_join_url: "https://{{ teleport_auth_server }}/scripts/{{ token_result.stdout | trim }}/install-node.sh"  # Update the URI with your proxy instance URL

  tasks:
    - name: Transfer join script to remote host
      ansible.builtin.get_url:
        url: "{{ teleport_join_url }}"
        dest: ~/install-node.sh
        mode: '0755'

    - name: Execute join script on remote host
      command: sudo bash ~/install-node.sh

    - name: Start Teleport service
      become: true
      command: systemctl start teleport

Note: If you are going to join the node for the first time, then please remove the first three tasks(stop teleport service, remove the data dir and packages) under pre_tasks

5. Executing the Playbook
Run the playbook using the following command:
ansible-playbook ssh-node-join-ansible-playbook.yaml

Expected Output
Upon successful execution, you’ll see output indicating each step’s completion:

PLAY [Teleport SSH node join setup] ********************************************************************************************************************************************************************

TASK [Stop Teleport service if running] ****************************************************************************************************************************************************************
changed: [my_teleport_node]

TASK [Remove existing Teleport data and binaries] ******************************************************************************************************************************************************
changed: [my_teleport_node]

TASK [Remove existing Teleport packages] ***************************************************************************************************************************************************************
changed: [my_teleport_node]

TASK [Generate a temporary Teleport node join token locally] *******************************************************************************************************************************************
changed: [my_teleport_node -> localhost]

TASK [Set join token URL variable] *********************************************************************************************************************************************************************
ok: [my_teleport_node]

TASK [Transfer join script to remote host] *************************************************************************************************************************************************************
changed: [my_teleport_node]

TASK [Execute join script on remote host] **************************************************************************************************************************************************************
changed: [my_teleport_node]

TASK [Start Teleport service] **************************************************************************************************************************************************************************
changed: [my_teleport_node]

PLAY RECAP *********************************************************************************************************************************************************************************************
my_teleport_node           : ok=8    changed=7    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Verification
Log into your Teleport cluster and verify the node appears in your list of active nodes:

tsh ls
Node Name        Address    Labels
---------------- ---------- -----------------------
enroll-test1 ⟵ Tunnel
ip-1-0-12-6   ⟵ Tunnel   hostname=ip-1-0-12-6

In the destination Node, you can see below:

[root@enroll-test1 ~]# teleport version
-bash: /usr/local/bin/teleport: No such file or directory
[root@enroll-test1 ~]# teleport version
Teleport Enterprise v16.4.3 git:v16.4.3-0-gd506b62 go1.22.8
[root@enroll-test1 ~]#

Summary
This approach leverages Ansible and short-lived tokens to automate the enrollment of Linux VM servers into a Teleport cluster without using long-lived certificates. It’s a secure, efficient solution for maintaining dynamic access across a fleet of servers.