Ansible Role "papanito.cloudflared"

This Ansible role helps you download and install cloudflared on a server and optionally set up the [argo-tunnel] as a service.

Important Changes in Version 3.0.0

This version introduces changes based on new behavior regarding named tunnels.

Make sure to update your configuration (variables) in your Ansible project, as some variable names have changed. The previous cf_ variables have been renamed to avoid confusion in different roles.

Cloudflared and Connecting Applications

To create and manage Tunnels, first you need to:

1. Install cloudflared on your machine
2. Authenticate cloudflared

After installation and authentication, setting up your first Tunnel involves three main steps:

3. Create a Tunnel
4. Route traffic to your Tunnel
5. Run your Tunnel

Steps 4 and 5 are usually done once per Tunnel by an administrator, while step 6 is executed each time the Tunnel starts.

What Does This Role Do?

The role serves two main purposes:

• Server-side daemon installation
• SSH Client Configuration

Server-side Daemon Installation

This role mainly sets up the service on the servers, which refers to steps 1, 2, 4, and 5 listed above because:

Managing tunnels and routing should be done by an administrator, not the role.

You can configure multiple [named tunnels] or a [single service]. It performs the following actions:

1. Download and install the binary from [downloads].

2. Install and configure the daemon - see authenticate the daemon.

3. For [named tunnels], a credentials file is created as {{ cf_credentials_dir }}/{{ tunnel_id }}.json with contents similar to this:

   {"AccountTag":"{{ account_tag }}","TunnelSecret":"{{ tunnel_secret }}","TunnelID":"{{ tunnel_id }}","TunnelName":"{{ cf_tunnels.key }}"}
   

4. For each key in cf_tunnels, a tunnel config is created in /etc/cloudflare, named {{ tunnel }}.yml, containing the necessary configuration.

5. Depending on your system-init type (controlled by cf_init_system), the role performs the following:

   • Systemd: Creates a [systemd-unit-template] cloudflared@{{ tunnel }}.service and starts an instance for each service in cf_tunnels.
   • Init-V Systems: Sets up the cloudflared service in /etc/init.d/.

6. If using [named tunnels], the role will create a [DNS route].

SSH Client Configuration

To connect to your servers via SSH through cloudflared, you should add the following to your SSH configuration:

Host xxx.mycompany.com
  ProxyCommand /usr/bin/cloudflared access ssh --hostname %h

You can automate this setup by enabling cf_ssh_client_config and specifying cf_ssh_client_config_group. For example, if your inventory lists servers like this:

all:
  children:
    servers:
      hosts:
        host001:
        host002:

Setting cf_ssh_client_config_group: servers will include entries for both host001 and host002.

Requirements

None

Role Variables

Here are parameters to control installation or uninstallation:

Cloudflared Service Parameters

These parameters are needed to create the system service:

Using [named tunnels] for cf_tunnels is suggested to ensure proper configuration.

Example Playbooks

Here's a playbook to install a single SSH tunnel for each server:

- hosts: servers
  vars:
    cf_systemd_user: root
    cf_systemd_group: root
    cf_cert_location: /home/papanito/cert.pem
    services:
      ssh:
        hostname: "{{ inventory_hostname }}.mycompany.com"
        url: ssh://localhost:22
  roles:
    - papanito.cloudflared

This playbook installs a [named tunnel] servers with ingress to {{ inventory_hostname }}.mycompany.com.

- hosts: servers
  remote_user: ansible
  become: true
  vars:
    cf_cert_location: /home/papanito/.cloudflared/cert.mycompany.com.pem
    cf_tunnels:
      test:
        account_tag: !vault...
        tunnel_secret: !vault...
        tunnel_id: !vault...
        routes:
          dns:
          - "{{ inventory_hostname }}"
          - "hello-{{ inventory_hostname }}"
        ingress:
        - hostname: "hello-{{ inventory_hostname }}.mycompany.com"
          service: hello_world
        - hostname: "{{ inventory_hostname }}.mycompany.com"
          service: ssh://localhost:22
        - service: http_status:404
  roles:
    - papanito.cloudflared

This playbook simply downloads cloudflared and configures the SSH config file:

- hosts: localhost
  remote_user: papanito
  vars:
    cf_install_only: true
    cf_ssh_client_config: true
    cf_ssh_client_config_group: servers
  roles:
    - papanito.cloudflared

Test

To test, run:

ansible-playbook tests/test.yml -i tests/inventory

Additional Info

Authenticate the Daemon

When authenticating the daemon, a browser window opens, or if it’s unavailable, the link must be entered manually. This process requires some manual steps:

• If not specified, Ansible calls cloudflared login and continues once authentication is done.
• If cf_cert_location is provided, the certificate is simply copied. If cf_cert_content is provided, it creates a certificate directly from the pasted content.

References:

• [downloads] - cloudflared download instructions
• [ssh-guide] - SSH connections using cloudflared

License

This is Free Software, licensed under the Apache v2 license.

Author Information

Written by Papanito - Gitlab / Github

For further details on various topics, visit the provided references in the original document.