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

Posted July 19, 2022 by Adrian Wyssmann


Role Summary

Ansible Role Ansible Quality Score Ansible Role GitHub issues GitHub pull requests

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:

  1. Create a Tunnel
  2. Route traffic to your Tunnel
  3. 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

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 [1]

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
      {{ 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

  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:


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


CLoudflare offers Argo Tunnel which allows you to establishes outbound connections (Tunnels) between your web server and the Cloudflare edge. For this, you need the cloudflared daemon. The installation is quite straightforward but installing it on various servers is best done with ansible or any suitable tool.