papanito.cloudflared
This ansible role does download and install cloudflared on the host and optionally installs the argo-tunnel as a service.
Posted May 12, 2022 by Adrian Wyssmann
Source
https://github.com/papanito/ansible-role-cloudflared
Role Summary
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:
- Download and install cloudflared on your machine
- Authenticate cloudflared
Once cloudflared has been installed and authenticated, the process to get your first Tunnel up and running includes 3 high-level steps:
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:
-
Download and install binary according to downloads
-
Install/configure the daemon - see Authenticate the daemon
-
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 }}"}
-
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 followsnamed 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
-
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 ofcf_tunnels
cloudflared tunnel --config {{ tunnel }}.yml
-
Init-V Systems
- Install cloudflared service to
/etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}
- Link Stop-Script to
/etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}
- Link Start-Script to
/etc/init.d/{{ systemd_filename }}-{{ tunnel_name }}
- Install cloudflared service to
-
-
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
.
Background
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.