damex.cloudflare.cloudflare_tunnel module – Ensure Cloudflare tunnel

Note

This module is part of the damex.cloudflare collection (version 1.2.3).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install damex.cloudflare.

To use it in a playbook, specify: damex.cloudflare.cloudflare_tunnel.

Synopsis

• Ensures Cloudflare tunnels with ingress configuration.

• See the docs: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/.

• Creates the tunnel if missing, updates ingress if changed, deletes if absent.

• Returns the tunnel token for use with cloudflared.

Parameters

Parameter	Comments
account_api_key string	Cloudflare account API key. Required together with account_email if api_token is not provided.
account_email string	Cloudflare account email. Required together with account_api_key if api_token is not provided.
account_id string	Cloudflare account identifier. Required if account_name is not provided.
account_name string	Cloudflare account name. Required if account_id is not provided. Resolved to account identifier via the Cloudflare API.
api_token string	Cloudflare API token. Required if account_email and account_api_key are not provided. Can be specified in CLOUDFLARE_TOKEN environment variable.
ingress list / elements=dictionary	Ingress rules for the tunnel. Must end with a catch-all rule without hostname. Required when state is present.
hostname string	Hostname to match. Omit for the catch-all rule.
origin_request dictionary	Origin request parameters.
service string / required	Service URL or status code.
name string / required	Tunnel name.
state string	Tunnel state. Choices: "absent" "present" ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: full	Supports check mode.
diff_mode	Support: full	Supports diff mode.

Examples

- name: Ensure tunnel with ingress
  damex.cloudflare.cloudflare_tunnel:
    name: hetzner
    account_name: damex
    api_token: "{{ cloudflare_api_token }}"
    ingress:
      - hostname: forgejo.damex.org
        service: http://localhost:3000
      - hostname: nextcloud.damex.org
        service: http://localhost:8080
      - service: http_status:404

- name: Ensure tunnel is absent
  damex.cloudflare.cloudflare_tunnel:
    name: old-tunnel
    account_name: damex
    api_token: "{{ cloudflare_api_token }}"
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
tunnel dictionary	Tunnel object from the Cloudflare API. Returned: when state is present
id string	Tunnel identifier. Returned: success
name string	Tunnel name. Returned: success
status string	Tunnel status. Returned: success

Authors

• Roman Kuzmitskii (@damex)

Collection links

• Issue Tracker
• Repository (Sources)