Ansible role "papanito.cloudflared"

This ansible role does download and install cloudflared on the host and optionally installs the argo-tunnel as a service.

Breaking changes with 3.0.0

This is a breaking change to reflect the new beahviour of named tunnels

The role should take care of cleanup if you used the role before v.3.0.0. However you have to update the configuration (variables) in your ansible project. I renamed the variables - usually prefixed with cf_ to make them unique to the role. If they are not unique it may happen that variables using the same name in different roles can have undesired side-effects.

Cloudflared and connecting apps to tunnels

According to 1, in order to create and manage Tunnels, you'll first need to:

1. Download and install cloudflared on your machine
2. Authenticate cloudflared

Once cloudflared has been installed and authenticated, the process to get your first Tunnel up and running includes 3 high-level steps:

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

Steps 4-5 are executed once per Tunnel, normally by an administrator, and Step 6 is executed whenever the Tunnel is to be started, normally by the owner of the Tunnel (whom may be different from the administrator).

What does the role do?

The role has actually two purposes

• Server side daemon installation
• SSH Client config

Server side daemon installation

The role only takes care of setting up the service on the nodes, i.e. steps 1, 2, 4 and 5 from above, cause

Creating tunnels and enable routing is a task which should be done by an administrator and not the role ¹

You can configure one to multiple named tunnels as well as single service - even so, with named tunnels you usually only need one daemon. The role actually performs these steps:

1. Download and install binary according to downloads

2. Install/configure the daemon - see Authenticate the daemon

3. For named tunnels a credentials file is created under {{ cf_credentials_dir }}/{{ tunnel_id }}.json similar to this

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

4. For each key in cf_tunnels create a tunnel config in /etc/cloudflare

   The file is named {{ tunnel }}.yml and will contain the minimal configuration is as follows

   named tunnels

   tunnel: {{ cf_tunnels.key }}
   credentials-file: {{ cf_credentials_dir }}/{{ tunnel_id }}.json
   ingress:
     {{ item.value.ingress }}
   

   single service

   hostname: {{ hostname }}
   url: {{ url }}
   

   Additional parameters are configured using Tunnel configuration params

5. Depending on your init system - controlled by cf_init_system - the role does the following

   • Systemd

     Create a systemd-unit-template cloudflared@{{ tunnel }}.service and start an instance for each service in the list of cf_tunnels

     cloudflared tunnel --config {{ tunnel }}.yml
     

   • Init-V Systems

     1. Install cloudflared service to /etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}
     2. Link Stop-Script to /etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}
     3. Link Start-Script to /etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}

6. If you use named tunnels the role would also create a dns route.

SSH Client config

From where you access your nodes via ssh which is proxied by cloudflared, you need to follow ssh-guide-client. You have to add the following

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

You can achieve this configuration if you enable cf_ssh_client_config. In addition you also need to specify cf_ssh_client_config_group. So let's assume your inventory looks as follows:

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

If you specify cf_ssh_client_config_group: servers you would get an entry for host001 and host002.

Requirements

none

Role Variables

Install and uninstall parameters

The following parameters control the installation and/or un-installation

Cloudflared service parameters

These are parameters required to create the system service

It's recommended to use named tunnels for cf_tunnels which require Cloudflare named tunnel parameters but you can also use Cloudflare legacy tunnel parameters

Cloudflare named tunnel parameters

  ...
    cf_tunnels:
      test:
        routes:
          dns:
            - "{{ inventory_hostname }}"
          cidr:
            - "192.168.42.0/24"
          lb:
            - hostname: website.mycompany.com
              poolname: bzh-west1.website.mycompany.com
        account_tag:  !vault....
        tunnel_secret: !vault....
        tunnel_id: !vault....
        ingress:
          - hostname: website.mycompany.com
            service: http://localhost:1313
          - hostname: hello.mycompany.com
            service: hello_world
          - hostname: ssh.mycompany.com
            service: ssh://localhost:22
          - service: http_status:404

The key of the tunnel shall match the of tunnel_id.

Routes

DNS

dns routes expect a list of CNAME's to be created as described here. If the CNAME already exists the task will be skipped but no error thrown. Also only add CNAME not a FQDN as the FQDN is determined by cloudlfared.

Private Network

private network routes expect a list of CIDR's to be created as described here. The playbook loop on the list to execute cloudflared tunnel route ip add {{ cf_cidr_entry }} {{ cf_tunnel.key }}. If the CIDR already exists, an error will thrown but ignored.

Load Balancer

lb routes expect a list of existing cloudflared load balancer (plus its pool) to route tunnel on as described here. The playbook loop on the list to execute cloudflared tunnel route lb {{ cf_tunnel.key }} {{ cf_lb_entry.host_name }} {{ cf_lb_entry.pool_name }}. If the tunnel is already bind into the pool, an ignored error will throw.

Cloudflare single service parameters

As with previous versions of this roles you can use the single service configuration style

If you need to proxy traffic to only one local service, you can do so using the config file. As an alternative, you can set up single-service configuration

cf_tunnels:
  ssh:
    hostname: xxx
    url: ssh.mycompany.com

Tunnel configuration params

These are used to configure the parameters per cloudflared service. You still can configure Per-rule configuration for named tunnels as part of the ingress under cf_tunnels.

Dependencies

none

Example Playbooks

The following example installs an single service for an 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

The following example installs an [named tunnel] servers with an ingress to {{ inventory_hostname }}.mycompany.com for ssh a hello world if you access hello-{{ inventory_hostname }}.mycompany.com via the browser

- 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

The following example simply downloads cloudflared on your local machine and configures the ssh-config file:

- hosts: localhost
  remote_user: papanito #your local user who has admin
  vars:
    cf_install_only: true
    cf_ssh_client_config: true
    cf_ssh_client_config_group: servers
  roles:
    - papanito.cloudflared

Test

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

Additional Info

Authenticate the daemon

According to authenticate-the-cloudflare-daemon when authenticate the daemon, there is a browser window opened or - if this is not possible - then the link has to be put manually. During this time the daemon waits. I could not come up with a solution how to automate this behavior so I came up with the following implementation.

• if nothing is specified, then ansible calls the cloudflared login and will continue when the authentication is done - this makes sens if you use the role to install the daemon locally on your machine and where you have a browser window

• if cf_cert_location the certificate is actually copied from the cf_cert_location, or if cf_cert_content is defined then the certificate is created directly from the value stored in it. So you could login once to cloudflare from your master node (where you run ansible) or from a remote location.

  You can encrypt the cert.pem with ansible vault and store it somewhere save.

References:

• downloads - cloudflared download instructions
• ssh-guide - ssh connections with cloudflared
• cli-args - command-line arguments
• config - The configuration file format uses YAML syntax

License

This is Free Software, released under the terms of the Apache v2 license.

Author Information

Written by Papanito - Gitlab / Github