teleport-ansible 0.0.1
Teleport driven ansible inventory script.
Requires Python: >=3.6

# Teleport Inventory Documentation

This is a very simple package which will use Teleport as a dynamic inventory
source for Ansible. The script assumes you've logged in and have access to the
teleport service. Examples of all the base requirements are provided within this
readme.

> Checkout https://cloudnull.io/2022/09/ansible-inventory-via-teleport for a more
  indepth review of integrating Teleport with Ansible.


## Using the teleport-ansible inventory script

The script will read machines and return JSON information from teleport. Once the
return information is sourced, it will format the inventory using the node name
as the target host and the labels as hostvars and groups.

Using teleport-ansible requires a little setup, mostly client side for Teleport itself.


## Installing teleport-ansible and using it

Installing the `teleport-ansible` inventory script can be accomplished with `pip`.

``` shell
pip install teleport-ansible
```

The teleport-inventory script can also be installed using the git repository directly.

``` shell
pip install git+https://github.com/cloudnull/teleport-ansible
```

If you don't want to install the script, you can also simply download the script using
the hard link and run it from wherever you want.

``` shell
curl https://raw.githubusercontent.com/cloudnull/teleport-ansible/master/teleport-inventory.py -o teleport-inventory.py
```


### Example SSH configuration connect through Teleport

Create a compatible SSH configuration for Teleport.

``` shell
export TELEPORT_DOMAIN=teleport.example.com
export TELEPORT_USER=cloudnull
cat > ~/.ssh/teleport.cfg <<EOF
Host * !${TELEPORT_DOMAIN}
    UserKnownHostsFile "${HOME}/.tsh/known_hosts"
    IdentityFile "${HOME}/.tsh/keys/${TELEPORT_DOMAIN}/${TELEPORT_USER}"
    CertificateFile "${HOME}/.tsh/keys/${TELEPORT_DOMAIN}/${TELEPORT_USER}-ssh/${TELEPORT_DOMAIN}-cert.pub"
    PubkeyAcceptedKeyTypes +ssh-rsa-cert-v01@openssh.com
    Port 3022
    CheckHostIP no
    ProxyCommand "$(which tsh)" proxy ssh --cluster=${TELEPORT_DOMAIN} --proxy=${TELEPORT_DOMAIN} %r@%h:%p
EOF
```

> The above ssh configuration needs to have all variables replaced to work.


### Example Ansible Setup

When running this inventory, Ansible requires some basic instructions which can
be set via environment variables or through an Ansible config file.

``` shell
export ANSIBLE_SCP_IF_SSH=False
export ANSIBLE_SSH_ARGS="-F ${HOME}/.ssh/teleport.cfg"
export ANSIBLE_INVENTORY_ENABLED=script
export ANSIBLE_HOST_KEY_CHECKING=False
export ANSIBLE_INVENTORY="$(command -v teleport-ansible)"
```

> The ${HOME}/.ssh/teleport.cfg file is generated by using the
  `tsh config` command then customized based on individual needs.


### Example login process

``` shell
tsh login --proxy=teleport.example.com --user=teleport-admin

If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:42337/83facfc0-e899-44dc-aa6c-32179e3d5b0b
> Profile URL:        https://teleport.example.com:443
  Logged in as:       teleport-admin
  Cluster:            teleport.example.com
  Roles:              access
  Logins:             root, ubuntu, debian, fedora, centos, -teleport-internal-join
  Kubernetes:         enabled
  Valid until:        2022-09-16 08:03:05 -0500 CDT [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty
```

> The above tsh login will provide access to the teleport cluster, which
  will allow you to run inventory script which will return an Ansible
  inventory JSON.


### Example inventory return

Running the teleport inventory command `teleport-inventory` will return something
like this.

``` python
>>> {
...     "_meta": {
...         "hostvars": {
...             "alluvial-0": {
...                 "ansible_user": "ubuntu",
...                 "teleport_id": 1663292578982084621,
...                 "arch": "x86_64",
...                 "codename": "jammy",
...                 "environment": "dev"
...             },
...             "compute-0": {
...                 "ansible_user": "carter",
...                 "teleport_id": 1663292546493240726,
...                 "arch": "x86_64",
...                 "codename": "jammy",
...                 "environment": "prod"
...             },
...             "curator-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292584620339609,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "plexmediaserver-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292540612813467,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "rtmprelay-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292583673456110,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "teleport-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292588270337453,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "thelounge-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292533524229273,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "unbound-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292535344206453,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "unifi-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292528952201832,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             },
...             "wireguard-0": {
...                 "ansible_user": "debian",
...                 "teleport_id": 1663292535570354336,
...                 "arch": "x86_64",
...                 "codename": "bullseye",
...                 "environment": "prod"
...             }
...         }
...     },
...     "all": {
...         "hosts": [
...             "alluvial-0",
...             "compute-0",
...             "curator-0",
...             "plexmediaserver-0",
...             "rtmprelay-0",
...             "teleport-0",
...             "thelounge-0",
...             "unbound-0",
...             "unifi-0",
...             "wireguard-0"
...         ],
...         "children": []
...     },
...     "x86_64": {
...         "hosts": [
...             "alluvial-0",
...             "compute-0",
...             "curator-0",
...             "plexmediaserver-0",
...             "rtmprelay-0",
...             "teleport-0",
...             "thelounge-0",
...             "unbound-0",
...             "unifi-0",
...             "wireguard-0"
...         ],
...         "children": []
...     },
...     "jammy": {
...         "hosts": [
...             "alluvial-0",
...             "compute-0"
...         ],
...         "children": []
...     },
...     "dev": {
...         "hosts": [
...             "alluvial-0"
...         ],
...         "children": []
...     },
...     "teleport_cloudnull_dev": {
...         "hosts": [
...             "wireguard-0"
...         ],
...         "children": []
...     },
...     "prod": {
...         "hosts": [
...             "compute-0",
...             "curator-0",
...             "plexmediaserver-0",
...             "rtmprelay-0",
...             "teleport-0",
...             "thelounge-0",
...             "unbound-0",
...             "unifi-0",
...             "wireguard-0"
...         ],
...         "children": []
...     },
...     "bullseye": {
...         "hosts": [
...             "curator-0",
...             "plexmediaserver-0",
...             "rtmprelay-0",
...             "teleport-0",
...             "thelounge-0",
...             "unbound-0",
...             "unifi-0",
...             "wireguard-0"
...         ],
...         "children": []
...     }
... }
```

> Once the ssh config is in place, the Ansible configuration is set, and
  teleport is logged in, Ansible can be run natively.


### Example Ansible Ad-Hoc command

You'll notice that the command is SUPER basic. There's nothing special here.

``` shell
ansible -m ping all
```

### Example Ansible Playbook command

Just like the ad-hoc command, there's nothing special when running playbooks either.

``` shell
ansible-playbook example-playbook.yaml
```