![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Ansible
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
Ansible uses the OpenSSH client by default. Teleport supports SSH protocol and works as SSH jumphost.
In this guide we will configure OpenSSH client to work with Teleport Proxy and run a sample ansible playbook.
Prerequisites
-
A running Teleport cluster version 16.2.1 or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
-
The
tctl
admin tool andtsh
client tool.Visit Installation for instructions on downloading
tctl
andtsh
.
ssh
openssh toolansible
>= 2.9.6- Optional tool
jq
to processJSON
output. - To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 16.2.1
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
commands on the computer that hosts the Teleport Auth Service for full permissions.
Step 1/3. Login and configure SSH
Log into Teleport with tsh
:
tsh login --proxy=example.com
Generate openssh
configuration using tsh config
shortcut:
tsh config > ssh.cfg
You can edit matching patterns used in ssh.cfg
if something
is not working out of the box.
Step 2/3. Configure Ansible
Create a folder ansible
where we will collect all generated files:
mkdir -p ansibleCopy the openssh configuration from the previous step to the ansible dir
cp ssh.cfg ansible/cd ansible
Create a file ansible.cfg
:
[defaults]
host_key_checking = True
inventory=./hosts
remote_tmp=/tmp
[ssh_connection]
scp_if_ssh = True
ssh_args = -F ./ssh.cfg
You can create an inventory file hosts
manually or use a script below to generate it from your environment. Set your
cluster name (e.g. teleport.example.com
or in the form mytenant.teleport.sh
for Teleport Enterprise Cloud)
and this script will generate the host names to match the openssh
configuration:
tsh ls --format=json | jq '.[].spec.hostname + ".teleport.example.com"' > hosts
Step 3/3. 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:
- hosts: all
remote_user: ubuntu
tasks:
- name: "hostname"
command: "hostname"
From the folder ansible
, run the ansible playbook:
ansible-playbook playbook.yamlPLAY [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 are now using short-lived SSH certificates and Teleport can now record all ansible commands in the audit log.
Troubleshooting
In case if ansible can not 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 example.host: Name or service not known",
"unreachable": true
}
You can examine and tweak patterns matching the inventory hosts in ssh.cfg
.
Try the SSH connection using ssh.cfg
with verbose mode to inspect the error:
ssh -vvv -F ./ssh.cfg [email protected]
If ssh
works, try running the playbook with verbose mode on:
ansible-playbook -vvvv playbook.yaml