From a0d1f653ae8a4f5212707e5c2ff131f8dfcb16aa Mon Sep 17 00:00:00 2001 From: Noam Zimet Date: Wed, 22 Jul 2026 08:53:19 -0700 Subject: [PATCH 1/8] add ansible-and-tbot-doc --- proof-of-concepts/ansible-and-tbot/README.md | 277 +++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 proof-of-concepts/ansible-and-tbot/README.md diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md new file mode 100644 index 0000000..7fd2e8a --- /dev/null +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -0,0 +1,277 @@ +## Overview + +This demo will cover how to use Ansible in conjunction with Teleport/tbot to provision each new desired Linux machine with Teleport and connect it to the Teleport cluster. + +Ansible will be responsible for installing Teleport and generating the associated Teleport configuration file. Most of this can be done with Ansible alone. However, one of the components of the config file is the join token that Teleport uses to join a resource to Teleport. This join token can be obtained by running `tctl tokens add --type=node`, but this command requires an authenticated Teleport identity to execute. This is where tbot comes in: it issues a short-lived identity with the requisite permission to generate join tokens. This identity is then used to run the `tctl tokens add` command and the resulting token is used by Ansible. + +An alternative join method option is TPM joining, but this demo focuses on the ephemeral join token method explained above. + +Please note that this guide is meant as a demo, and that modificiations may likely be necessary in a production environment. + +## Preparing the EC2 Instance + +1. You will need a server that will be running Ansible and tbot. If you don’t already have a server, you can launch an EC2 instance for this purpose. +2. Attach an AWS IAM role to this server so that you can make use of `iam-joining`. This makes managing of tbot simpler in the event that the Linux server stops/restarts/etc. +3. Install Teleport on the server + +## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/)) + +On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): + +1. Create a bot user using `tctl bots add [bot-name]` +2. Create an iam-join role for that bot (example below). + + ```jsx + kind: token + metadata: + expires: "0001-01-01T00:00:00Z" + name: iam-token-bot + spec: + allow: + - aws_account: "[your-account-number]" + bot_name: [bot-name-from-previous-command] + join_method: iam + roles: + - Bot + version: v2 + ``` + + +On the Linux machine (that will be running Ansible/tbot): + +1. Configure tbot.yaml file (we will use iam-joining here) + - `vi /etc/tbot` + + ```jsx + version: v2 + proxy_server: [your-proxy-server]:443 + onboarding: + join_method: iam + token: iam-token-bot + storage: + type: directory + path: /var/lib/teleport/bot + services: + - type: identity + destination: + type: directory + path: /opt/machine-id + ``` + +2. Tbot will write identity files to the /opt/machine-id directory. As needed, grant the necessary permissions to the appropriate user (i.e. Ubuntu in this case) + + ```jsx + sudo mkdir -p /var/lib/teleport/bot + sudo mkdir -p /opt/machine-id + sudo chown ubuntu:ubuntu /var/lib/teleport /var/lib/teleport/bot /opt/machine-id + sudo chmod +x /var/lib/teleport /var/lib/teleport/bot /opt/machine-id + ``` + +3. Create the systemd file for the Linux user (i.e. ubuntu) + + ```jsx + sudo tbot install systemd \ + --write \ + --config /etc/tbot.yaml \ + --user ubuntu \ + --group ubuntu \ + --pid-file /run/tbot.pid \ + --anonymous-telemetry + ``` + +1. Add the overrides so that ubuntu can write in the folder + - `sudo systemctl edit tbot` + + #### Add the following lines + + ```jsx + ### Editing /etc/systemd/system/tbot.service.d/override.conf + ### Anything between here and the comment below will become the contents of the drop-in file + + ***[Service] + User=ubuntu + Group=ubuntu + RuntimeDirectory=tbot + PIDFile=/run/tbot/tbot.pid + ExecStart= + ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot/tbot.pid*** + + ### Edits below this comment will be discarded + + ### /etc/systemd/system/tbot.service + # # teleport-update 18.9.1_ent + # # DO NOT EDIT THIS FILE + # + # # Generated by `tbot` + # [Unit] + # Description=tbot - Teleport Machine & Workload Identity Service + # After=network.target + # + # [Service] + # Type=simple + # User=root + # Group=root + # Restart=always + # RestartSec=5 + # Environment="TELEPORT_ANONYMOUS_TELEMETRY=1" + # ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot.pid + # ExecReload=/bin/kill -HUP $MAINPID + # PIDFile=/run/tbot.pid + # LimitNOFILE=524288 + # + # [Install] + # WantedBy=multi-user.target + + ``` + +2. Confirm that tbot is working + - `sudo systemctl daemon-reload` + - `sudo systemctl enable tbot` + - `sudo systemctl start tbot` + - `sudo systemctl status tbot` + - `sudo ls -l /opt/machine-id` + - You should see the credentials that will be used by the MWI in the next steps + +On local machine: + +1. Create the config for a role that can be used by a bot to create tokens + + ```jsx + #token-creator-role.yaml + kind: role + version: v6 + metadata: + name: token-creator + spec: + allow: + rules: + - resources: [token] + verbs: [create, list, read, delete] + ``` + +2. Apply the config + 1. `tctl create -f token-creator-role.yaml` +3. Add the role to the bot you just created in the previous steps + 1. `tctl bots update [bot-name] --add-roles token-creator` + +## Configuring Ansible + +Now that tbot is set up, the next step is to configure tbot to work with Ansible. Broadly speaking, you can follow this [guide](https://goteleport.com/docs/machine-workload-identity/access-guides/ansible/#step-34-configure-ansible) + +On the Linux machine: + +1. Run the following: + + ```jsx + mkdir -p ansible + cd ansible + ``` + +2. Create an ansible.cfg file + +```jsx +[defaults] +host_key_checking = True +inventory=./hosts +remote_tmp=/tmp + +[ssh_connection] +scp_if_ssh = True +#note: the ssh_args is from the doc, but isn't necessary for this config +ssh_args = -F /opt/machine-id/ssh_config +``` + +1. Ansible will need to connect via SSH to the nodes. Thus, it needs the private key of the nodes. Transfer these keys to the Ansible node (i.e. via scp) +2. Create a `hosts` file with the name of the hosts you want to connect to: + + ```jsx + [unenrolled] + [private-ip of the servers I want to connect to] + + [unenrolled:vars] + #this allows the unenrolled to connect using the private key, and allows it to specify it in the known hosts + ansible_ssh_private_key_file=[private-key-file-path] + ansible_ssh_extra_args=-o UserKnownHostsFile=/home/ubuntu/.ssh/known_hosts + ``` + +3. Create an Ansible Playbook. An example playbook is given below. + + #### Playbook + + ```jsx + - hosts: localhost + become: false + tasks: + - name: Generate node join token + command: tctl tokens add --type=node --ttl=1h --format=text -i /opt/machine-id/identity --auth-server=[your-teleport-auth-server-address]:443 + register: join_token + + - name: Save token to file + copy: + content: "{{ join_token.stdout }}" + dest: /home/ubuntu/teleport-node-token + + - name: Scan and add host keys to known_hosts + shell: | + touch /home/ubuntu/.ssh/known_hosts + chmod 600 /home/ubuntu/.ssh/known_hosts + ssh-keyscan {{ item }} >> /home/ubuntu/.ssh/known_hosts + loop: "{{ groups['unenrolled'] }}" + + - hosts: unenrolled + remote_user: ubuntu + become: true + vars: + proxy_server: "[your-teleport-proxy-server]:443" + teleport_version: "[desired-teleport-version]" + + tasks: + - name: Read token from file + set_fact: + teleport_token: "{{ lookup('file', '/home/ubuntu/teleport-node-token') }}" + + - name: Download Teleport install script + get_url: + url: https://cdn.teleport.dev/install.sh + dest: /tmp/install.sh + mode: '0755' + + - name: Check if teleport is already installed + stat: + path: /usr/local/bin/teleport + register: teleport_binary + + - name: Install Teleport Enterprise + shell: bash /tmp/install.sh "{{ teleport_version }}" "enterprise" + when: not teleport_binary.stat.exists + + - name: Write teleport.yaml + copy: + dest: /etc/teleport.yaml + content: | + version: v3 + teleport: + auth_token: "{{ teleport_token }}" + proxy_server: "{{ proxy_server }}" + auth_service: + enabled: false + proxy_service: + enabled: false + ssh_service: + enabled: true + labels: + [desired-label-key]: [desired-label-value] + + - name: Enable and start teleport + systemd: + name: teleport + enabled: true + state: started + + ``` + +4. Install Ansible on the Linux machine + 1. `sudo apt update && sudo apt install ansible-core -y` +5. Run the Ansible playbook + 1. `ansible-playbook playbook.yaml` +6. The previously `unenrolled hosts` specified in the `host` file should now be visible! \ No newline at end of file From e096cc2b7b74925190485ee7d05aaf80ce2f8691 Mon Sep 17 00:00:00 2001 From: noam-zimet-teleport Date: Wed, 22 Jul 2026 09:01:50 -0700 Subject: [PATCH 2/8] Update README.md --- proof-of-concepts/ansible-and-tbot/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 7fd2e8a..0fa718f 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -6,8 +6,8 @@ Ansible will be responsible for installing Teleport and generating the associate An alternative join method option is TPM joining, but this demo focuses on the ephemeral join token method explained above. -Please note that this guide is meant as a demo, and that modificiations may likely be necessary in a production environment. - +> [!CAUTION] +> Please note that this repository was developed for testing environments and should not be used as is in your production environment. It is intended to serve as a reference or example. Use at your own risk; no support or warranty provided. ## Preparing the EC2 Instance 1. You will need a server that will be running Ansible and tbot. If you don’t already have a server, you can launch an EC2 instance for this purpose. @@ -274,4 +274,4 @@ ssh_args = -F /opt/machine-id/ssh_config 1. `sudo apt update && sudo apt install ansible-core -y` 5. Run the Ansible playbook 1. `ansible-playbook playbook.yaml` -6. The previously `unenrolled hosts` specified in the `host` file should now be visible! \ No newline at end of file +6. The previously `unenrolled hosts` specified in the `host` file should now be visible! From 2fa762ecc41b6a047f4a101c9cffe3bf20c68320 Mon Sep 17 00:00:00 2001 From: noam-zimet-teleport Date: Wed, 22 Jul 2026 10:30:22 -0700 Subject: [PATCH 3/8] Update README.md Updated per B's suggestions --- proof-of-concepts/ansible-and-tbot/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 0fa718f..622a831 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -4,7 +4,7 @@ This demo will cover how to use Ansible in conjunction with Teleport/tbot to pro Ansible will be responsible for installing Teleport and generating the associated Teleport configuration file. Most of this can be done with Ansible alone. However, one of the components of the config file is the join token that Teleport uses to join a resource to Teleport. This join token can be obtained by running `tctl tokens add --type=node`, but this command requires an authenticated Teleport identity to execute. This is where tbot comes in: it issues a short-lived identity with the requisite permission to generate join tokens. This identity is then used to run the `tctl tokens add` command and the resulting token is used by Ansible. -An alternative join method option is TPM joining, but this demo focuses on the ephemeral join token method explained above. +An alternative join method option is [TPM-joining](https://goteleport.com/docs/reference/deployment/join-methods/#trusted-platform-module-tpm), but this demo focuses on the ephemeral join token method explained above. > [!CAUTION] > Please note that this repository was developed for testing environments and should not be used as is in your production environment. It is intended to serve as a reference or example. Use at your own risk; no support or warranty provided. @@ -12,7 +12,8 @@ An alternative join method option is TPM joining, but this demo focuses on the e 1. You will need a server that will be running Ansible and tbot. If you don’t already have a server, you can launch an EC2 instance for this purpose. 2. Attach an AWS IAM role to this server so that you can make use of `iam-joining`. This makes managing of tbot simpler in the event that the Linux server stops/restarts/etc. -3. Install Teleport on the server +> Note: No specific permissions or IAM policy is required: an IAM role with no attached policies is sufficient. Teleport processes prove that they are running in your AWS account by sending a pre-signed sts:GetCallerIdentity request to the Teleport Auth Service. The service's identity must match an allow rule configured in your AWS service joining token. +4. Install Teleport on the server ## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/)) From 529df65de1049c9e2e0820e43f5b48b2cf01e541 Mon Sep 17 00:00:00 2001 From: noam-zimet-teleport Date: Fri, 24 Jul 2026 13:28:48 -0400 Subject: [PATCH 4/8] Apply suggestion from @praveenprem Co-authored-by: Praveen Premaratne <23165760+praveenprem@users.noreply.github.com> --- proof-of-concepts/ansible-and-tbot/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 622a831..f2d0c12 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -25,7 +25,6 @@ On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): ```jsx kind: token metadata: - expires: "0001-01-01T00:00:00Z" name: iam-token-bot spec: allow: From 698867dc8682d0124d915679b3249881bb394e49 Mon Sep 17 00:00:00 2001 From: Noam Zimet Date: Fri, 24 Jul 2026 14:17:54 -0400 Subject: [PATCH 5/8] cleaned up bot creation flow --- proof-of-concepts/ansible-and-tbot/README.md | 97 +++++++------------- 1 file changed, 32 insertions(+), 65 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index f2d0c12..5464a57 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -19,17 +19,34 @@ An alternative join method option is [TPM-joining](https://goteleport.com/docs/r On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): -1. Create a bot user using `tctl bots add [bot-name]` -2. Create an iam-join role for that bot (example below). +1. Create a role which allows the ability to create and modify tokens, a bot user who will utilize this role, and an iam-join token for that bot. - ```jsx + ```yaml + kind: role + metadata: + name: token-creator + spec: + allow: + rules: + - resources: [token] + verbs: [create, list, read, delete] + version: v6 + --- + kind: bot + metadata: + name: ansible-bot + spec: + roles: + - "token-creator" + version: v1 + --- kind: token metadata: name: iam-token-bot spec: allow: - aws_account: "[your-account-number]" - bot_name: [bot-name-from-previous-command] + bot_name: ansible-bot join_method: iam roles: - Bot @@ -42,7 +59,7 @@ On the Linux machine (that will be running Ansible/tbot): 1. Configure tbot.yaml file (we will use iam-joining here) - `vi /etc/tbot` - ```jsx + ```yaml version: v2 proxy_server: [your-proxy-server]:443 onboarding: @@ -60,7 +77,7 @@ On the Linux machine (that will be running Ansible/tbot): 2. Tbot will write identity files to the /opt/machine-id directory. As needed, grant the necessary permissions to the appropriate user (i.e. Ubuntu in this case) - ```jsx + ```bash sudo mkdir -p /var/lib/teleport/bot sudo mkdir -p /opt/machine-id sudo chown ubuntu:ubuntu /var/lib/teleport /var/lib/teleport/bot /opt/machine-id @@ -69,13 +86,13 @@ On the Linux machine (that will be running Ansible/tbot): 3. Create the systemd file for the Linux user (i.e. ubuntu) - ```jsx + ```bash sudo tbot install systemd \ --write \ --config /etc/tbot.yaml \ --user ubuntu \ --group ubuntu \ - --pid-file /run/tbot.pid \ + --pid-file /run/tbot/tbot.pid \ --anonymous-telemetry ``` @@ -84,44 +101,16 @@ On the Linux machine (that will be running Ansible/tbot): #### Add the following lines - ```jsx + ```yaml ### Editing /etc/systemd/system/tbot.service.d/override.conf ### Anything between here and the comment below will become the contents of the drop-in file - ***[Service] + [Service] User=ubuntu Group=ubuntu RuntimeDirectory=tbot - PIDFile=/run/tbot/tbot.pid ExecStart= - ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot/tbot.pid*** - - ### Edits below this comment will be discarded - - ### /etc/systemd/system/tbot.service - # # teleport-update 18.9.1_ent - # # DO NOT EDIT THIS FILE - # - # # Generated by `tbot` - # [Unit] - # Description=tbot - Teleport Machine & Workload Identity Service - # After=network.target - # - # [Service] - # Type=simple - # User=root - # Group=root - # Restart=always - # RestartSec=5 - # Environment="TELEPORT_ANONYMOUS_TELEMETRY=1" - # ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot.pid - # ExecReload=/bin/kill -HUP $MAINPID - # PIDFile=/run/tbot.pid - # LimitNOFILE=524288 - # - # [Install] - # WantedBy=multi-user.target - + ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot/tbot.pid ``` 2. Confirm that tbot is working @@ -132,28 +121,6 @@ On the Linux machine (that will be running Ansible/tbot): - `sudo ls -l /opt/machine-id` - You should see the credentials that will be used by the MWI in the next steps -On local machine: - -1. Create the config for a role that can be used by a bot to create tokens - - ```jsx - #token-creator-role.yaml - kind: role - version: v6 - metadata: - name: token-creator - spec: - allow: - rules: - - resources: [token] - verbs: [create, list, read, delete] - ``` - -2. Apply the config - 1. `tctl create -f token-creator-role.yaml` -3. Add the role to the bot you just created in the previous steps - 1. `tctl bots update [bot-name] --add-roles token-creator` - ## Configuring Ansible Now that tbot is set up, the next step is to configure tbot to work with Ansible. Broadly speaking, you can follow this [guide](https://goteleport.com/docs/machine-workload-identity/access-guides/ansible/#step-34-configure-ansible) @@ -162,14 +129,14 @@ On the Linux machine: 1. Run the following: - ```jsx + ```bash mkdir -p ansible cd ansible ``` 2. Create an ansible.cfg file -```jsx +```yaml [defaults] host_key_checking = True inventory=./hosts @@ -184,7 +151,7 @@ ssh_args = -F /opt/machine-id/ssh_config 1. Ansible will need to connect via SSH to the nodes. Thus, it needs the private key of the nodes. Transfer these keys to the Ansible node (i.e. via scp) 2. Create a `hosts` file with the name of the hosts you want to connect to: - ```jsx + ```yaml [unenrolled] [private-ip of the servers I want to connect to] @@ -198,7 +165,7 @@ ssh_args = -F /opt/machine-id/ssh_config #### Playbook - ```jsx + ```yaml - hosts: localhost become: false tasks: From 3fe7ce3834d0dfd96d9f70e9c82ba5dfef8fda7d Mon Sep 17 00:00:00 2001 From: Noam Zimet Date: Fri, 24 Jul 2026 14:25:06 -0400 Subject: [PATCH 6/8] add actual create line for role-bot-token --- proof-of-concepts/ansible-and-tbot/README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 5464a57..7965f97 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -19,7 +19,10 @@ An alternative join method option is [TPM-joining](https://goteleport.com/docs/r On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): -1. Create a role which allows the ability to create and modify tokens, a bot user who will utilize this role, and an iam-join token for that bot. +1. Create a yaml file defining a role which allows the ability to create and modify tokens, a bot user who will utilize this role, and an iam-join token for that bot. + ```bash + vi role-bot-and-token.yaml + ``` ```yaml kind: role @@ -52,6 +55,10 @@ On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): - Bot version: v2 ``` + + ```bash + tctl create -f role-bot-and-token.yaml + ``` On the Linux machine (that will be running Ansible/tbot): @@ -153,7 +160,7 @@ ssh_args = -F /opt/machine-id/ssh_config ```yaml [unenrolled] - [private-ip of the servers I want to connect to] + [unenrolled:vars] #this allows the unenrolled to connect using the private key, and allows it to specify it in the known hosts From f8fc2ccbc367c862bc78f18897be6526fdee0f98 Mon Sep 17 00:00:00 2001 From: Noam Zimet Date: Mon, 27 Jul 2026 11:19:29 -0400 Subject: [PATCH 7/8] fix numbering --- proof-of-concepts/ansible-and-tbot/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 7965f97..2fd384d 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -13,9 +13,9 @@ An alternative join method option is [TPM-joining](https://goteleport.com/docs/r 1. You will need a server that will be running Ansible and tbot. If you don’t already have a server, you can launch an EC2 instance for this purpose. 2. Attach an AWS IAM role to this server so that you can make use of `iam-joining`. This makes managing of tbot simpler in the event that the Linux server stops/restarts/etc. > Note: No specific permissions or IAM policy is required: an IAM role with no attached policies is sufficient. Teleport processes prove that they are running in your AWS account by sending a pre-signed sts:GetCallerIdentity request to the Teleport Auth Service. The service's identity must match an allow rule configured in your AWS service joining token. -4. Install Teleport on the server +3. Install Teleport on the server ([doc](https://goteleport.com/docs/installation/single-machine/linux/#run-the-cluster-specific-installation-script)) -## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/)) +## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/)) for reference On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): From e65996110d287e433c1c47bcdf261665778e6ea4 Mon Sep 17 00:00:00 2001 From: Noam Zimet Date: Mon, 27 Jul 2026 12:31:59 -0400 Subject: [PATCH 8/8] simplify instructions --- proof-of-concepts/ansible-and-tbot/README.md | 90 ++++++++------------ 1 file changed, 36 insertions(+), 54 deletions(-) diff --git a/proof-of-concepts/ansible-and-tbot/README.md b/proof-of-concepts/ansible-and-tbot/README.md index 2fd384d..861a3b1 100644 --- a/proof-of-concepts/ansible-and-tbot/README.md +++ b/proof-of-concepts/ansible-and-tbot/README.md @@ -15,7 +15,7 @@ An alternative join method option is [TPM-joining](https://goteleport.com/docs/r > Note: No specific permissions or IAM policy is required: an IAM role with no attached policies is sufficient. Teleport processes prove that they are running in your AWS account by sending a pre-signed sts:GetCallerIdentity request to the Teleport Auth Service. The service's identity must match an allow rule configured in your AWS service joining token. 3. Install Teleport on the server ([doc](https://goteleport.com/docs/installation/single-machine/linux/#run-the-cluster-specific-installation-script)) -## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/)) for reference +## Deploying Tbot on Linux ([doc](https://goteleport.com/docs/machine-workload-identity/deployment/linux/) for reference) On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): @@ -63,8 +63,10 @@ On a local machine with Teleport admin access (i.e. access to the `tctl` CLI): On the Linux machine (that will be running Ansible/tbot): -1. Configure tbot.yaml file (we will use iam-joining here) - - `vi /etc/tbot` +1. Configure the tbot.yaml file (we will use iam-joining here) + ```bash + sudo vi /etc/tbot.yaml + ``` ```yaml version: v2 @@ -82,45 +84,14 @@ On the Linux machine (that will be running Ansible/tbot): path: /opt/machine-id ``` -2. Tbot will write identity files to the /opt/machine-id directory. As needed, grant the necessary permissions to the appropriate user (i.e. Ubuntu in this case) +2. Tbot will write identity files to the /opt/machine-id directory. Create the necessary file paths for tbot. ```bash sudo mkdir -p /var/lib/teleport/bot sudo mkdir -p /opt/machine-id - sudo chown ubuntu:ubuntu /var/lib/teleport /var/lib/teleport/bot /opt/machine-id - sudo chmod +x /var/lib/teleport /var/lib/teleport/bot /opt/machine-id - ``` - -3. Create the systemd file for the Linux user (i.e. ubuntu) - - ```bash - sudo tbot install systemd \ - --write \ - --config /etc/tbot.yaml \ - --user ubuntu \ - --group ubuntu \ - --pid-file /run/tbot/tbot.pid \ - --anonymous-telemetry - ``` - -1. Add the overrides so that ubuntu can write in the folder - - `sudo systemctl edit tbot` - - #### Add the following lines - - ```yaml - ### Editing /etc/systemd/system/tbot.service.d/override.conf - ### Anything between here and the comment below will become the contents of the drop-in file - - [Service] - User=ubuntu - Group=ubuntu - RuntimeDirectory=tbot - ExecStart= - ExecStart=/usr/local/bin/tbot start -c /etc/tbot.yaml --diag-socket-for-updater=/var/lib/teleport/bot/debug.sock --pid-file=/run/tbot/tbot.pid ``` -2. Confirm that tbot is working +3. Confirm that tbot is working - `sudo systemctl daemon-reload` - `sudo systemctl enable tbot` - `sudo systemctl start tbot` @@ -142,22 +113,27 @@ On the Linux machine: ``` 2. Create an ansible.cfg file + ```bash + vi ansible.cfg + ``` -```yaml -[defaults] -host_key_checking = True -inventory=./hosts -remote_tmp=/tmp + ```yaml + [defaults] + host_key_checking = True + inventory=./hosts + remote_tmp=/tmp -[ssh_connection] -scp_if_ssh = True -#note: the ssh_args is from the doc, but isn't necessary for this config -ssh_args = -F /opt/machine-id/ssh_config -``` + [ssh_connection] + scp_if_ssh = True + ``` + +3. During the first connection, Ansible will need to connect via SSH to the nodes. Thus, it needs the private SSH key of the nodes. Make sure that this node has access through the key (i.e. through agent forwarding, or if needed, through scp transfer of the key). If transfering to the requisite node via scp, then take the necessary precautions afterwards (i.e. delete and rotate the key). + +4. Create a `hosts` file with the name of the hosts you want to connect to: + ```bash + vi hosts + ``` -1. Ansible will need to connect via SSH to the nodes. Thus, it needs the private key of the nodes. Transfer these keys to the Ansible node (i.e. via scp) -2. Create a `hosts` file with the name of the hosts you want to connect to: - ```yaml [unenrolled] @@ -168,13 +144,15 @@ ssh_args = -F /opt/machine-id/ssh_config ansible_ssh_extra_args=-o UserKnownHostsFile=/home/ubuntu/.ssh/known_hosts ``` -3. Create an Ansible Playbook. An example playbook is given below. +5. Create an Ansible Playbook. An example playbook is given below. Replace the auth-server, proxy_server, teleport_version, and label with the appropriate values. - #### Playbook + ```bash + vi playbook.yaml + ``` ```yaml - hosts: localhost - become: false + become: true tasks: - name: Generate node join token command: tctl tokens add --type=node --ttl=1h --format=text -i /opt/machine-id/identity --auth-server=[your-teleport-auth-server-address]:443 @@ -245,7 +223,11 @@ ssh_args = -F /opt/machine-id/ssh_config ``` 4. Install Ansible on the Linux machine - 1. `sudo apt update && sudo apt install ansible-core -y` + ```bash + sudo apt update && sudo apt install ansible-core -y + ``` 5. Run the Ansible playbook - 1. `ansible-playbook playbook.yaml` + ```bash + ansible-playbook playbook.yaml + ``` 6. The previously `unenrolled hosts` specified in the `host` file should now be visible!