mdsketch.teleport

Ansible Role: Teleport Node Service

This role installs or updates the Teleport Node Service and its configuration on systems that use Debian.

It works on any architecture where Teleport has a supported version. You can find available Teleport downloads.

If you create your own template for the Teleport configuration file, you can run any node services you need (like SSH, apps, databases, or Kubernetes).

For more details and to ensure everything is set up correctly, please refer to the Teleport configuration file documentation.

TODO:

Add tests to check that Teleport is updated correctly (including configuration, service, and binary).
Include tests for variable templates.
Secure versions of the linting tools.
Explore the possibility of installing Teleport in a Docker container (not currently supported).

Requirements

You need a running Teleport cluster to provide this information:

Auth token (either dynamic or static). Example command: tctl nodes add --ttl=5m --roles=node | grep "invite token:" | grep -Eo "[0-9a-z]{32}"
CA pin.
Address of the authentication server.

Role Variables

These are default variables with their initial values as found in defaults/main.yml.

teleport_version

The version of Teleport to install. You can check available versions at Teleport Downloads.

teleport_architecture

Adjust teleport_architecture to any of the following based on your device:

arm-bin for ARMv7 (32-bit) devices.
arm64-bin for ARM64/ARMv8 (64-bit) devices.
amd64-bin for x86_64/AMD64 devices.
386-bin for i386/Intel devices.

teleport_config_template

The template for the Teleport configuration file. The default is templates/default_teleport.yaml.j2, which provides a basic setup to enable the SSH service and show node uptime.

You can find many options available and use your own template with additional variables.

teleport_service_template

The template for the Teleport service file. The default is templates/default_teleport.service.j2. You can replace it with your own template and add more variables as needed.

teleport_ca_pin

The CA pin for the Teleport configuration. This is optional but recommended.

teleport_config_path

The location of the Teleport configuration file. The default path is /etc/teleport.yaml.

teleport_auth_servers

List of authentication servers used in the Teleport configuration. Examples are provided in the defaults above.

backup_teleport_config

Allows you to back up the Teleport configuration file before making changes. The default is yes. For more details, see Upgrading Teleport.

teleport_control_systemd

Default value is yes. It controls whether this role modifies the Teleport service.

teleport_template_config

Default value is yes. It controls whether this role updates the Teleport config file.

Upgrading Teleport

When the role runs, it checks if the installed version matches the version specified in teleport_version. If they differ, the role downloads and installs the latest version.

During an upgrade, it creates a backup of the current configuration file specified in teleport_config_path and generates a new configuration file from a template. You don't need to provide teleport_auth_token and teleport_ca_pin during this process since they are extracted from the existing configuration file and included in the new one.

This way, you can update values like labels and commands in the configuration file without having to store the auth token and CA pin separately.

The role restarts teleport.service after any of these events:

Teleport is installed or upgraded.
The Teleport configuration file is updated.
The Teleport service file is updated.

Dependencies

None

Example Playbook

To install Teleport on a node, use the following playbook:

- hosts: all
  roles:
    - mdsketch.teleport
  vars:
    # optional SSH labels
    teleport_ssh_labels:
      - k: "label_key"
        v: "label_value"
    teleport_auth_token: "super secret auth token"
    teleport_ca_pin: "not as secret ca pin"
    teleport_auth_server: "auth server"
    teleport_proxy_server: "proxy server"

Generated Teleport Config at /etc/teleport.yaml

---
version: v3
teleport:
  auth_token: "super secret auth token"
  ca_pin: "not as secret ca pin"
  auth_server: auth server
  proxy_server: proxy server
  log:
    output: stderr
    severity: INFO
    format:
      output: text
  diag_addr: ""
ssh_service:
  enabled: "yes"
  labels:
    label_key: label_value
  commands:
  - name: hostname
    command: [hostname]
    period: 60m0s
  - name: uptime
    command: [uptime, -p]
    period: 5m0s
  - name: version
    command: [teleport, version]
    period: 60m0s
proxy_service:
  enabled: "no"
  https_keypairs: []
  https_keypairs_reload_interval: 0s
  acme: {}
auth_service:
  enabled: "no"