Add cloudflared role for managing Cloudflare Tunnel instances - #2702

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

Co-authored-by: Cursor <cursoragent@cursor.com>

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

- Remove the unused 'Restart cloudflared tunnels' handler from
  global_handlers. It referenced cloudflared__combined_tunnels without
  a safe default and was unconditionally imported from
  global_handlers/handlers/main.yml, which would break global_handlers
  evaluation on hosts where the cloudflared role is not part of the
  playbook. The handler was also never notified anywhere:
  manage_tunnel.yml already restarts the per-tunnel systemd unit
  directly (with '# noqa no-handler') on config/env/credentials
  changes, so it was dead code.

- Hardcode 'After=network-online.target' directly in the
  cloudflared@.service.j2 systemd template instead of exposing
  cloudflared__systemd_after as a role-wide variable - the ordering is
  expected to be identical for every tunnel instance. Per-instance
  overrides should go through the debops.systemd role's drop-in
  override files instead.

- Enable cloudflared__metrics by default (bound to loopback) instead
  of only proposing it via a comment example. Port 2000 is avoided as
  the default since it's already reserved for the Cisco SCCP service
  on many systems; use 127.0.0.1:20241 instead.

- Add cloudflared__etc_services__dependent_list and wire the
  debops.etc_services role into the cloudflared playbook so the
  metrics port gets a /etc/services entry when enabled, following the
  same pattern used by docker_registry, dhcpd and other roles.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Per PR debops#2702 review: the role is not part of the common.yml playbook
(it only runs on hosts in the debops_service_cloudflared inventory
group via its own playbook), so a role-wide enable/disable switch is
redundant - membership in that group already controls whether the
role runs at all. This matches the pattern used by other standalone
service roles such as docker_registry, dhcpd and mosquitto, which
have no comparable __enabled variable and rely solely on their
__deploy_state variable for present/absent state.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Complete PR debops#2702 review comment debops#3: the full 'systemd configuration'
section (restart_policy, restart_sec, after) was flagged as being
better set directly in the unit file, with systemd_after called out
as the primary example. The previous fix only hardcoded
'After=network-online.target' and left cloudflared__systemd_restart_policy
/ cloudflared__systemd_restart_sec as role-wide variables. Hardcode
'Restart=on-failure' / 'RestartSec=5' directly in cloudflared@.service.j2
as well, and drop both variables; per-instance overrides remain
available via debops.systemd drop-in files.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

The 'Restart vmagent instances' handler in global_handlers referenced
vmagent__combined_instances without a safe default, unconditionally
imported from global_handlers/handlers/main.yml - the same pattern
flagged by review on the cloudflared role (PR debops#2702), which breaks
global_handlers evaluation on hosts where the vmagent role is not
part of the playbook.

The handler was also never notified anywhere: manage_instance.yml
already restarts the per-instance systemd unit directly (with
'# noqa no-handler') when its config/env/secret/binary changes, so
the global_handlers copy was dead code left over from following the
cloudflared role as a template.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Same pattern flagged by drybjed on PR debops#2702 (cloudflared): the role
is not part of common.yml and its playbook already restricts
execution to the debops_service_vmagent inventory group, so a
role-wide enable/disable switch is redundant. Other roles imported
into layer/agent.yml (telegraf, filebeat, metricbeat, zabbix_agent)
have no comparable __enabled variable either; __deploy_state alone
controls present/absent state.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Same pattern flagged by drybjed on PR debops#2702 (cloudflared, comment debops#3):
role-wide vmagent__systemd_after / vmagent__systemd_restart_policy /
vmagent__systemd_restart_sec are better hardcoded directly in the
vmagent@.service template unit, since they're expected to be uniform
across instances; per-instance overrides remain available via
debops.systemd drop-in files. vmagent__systemd_timeout_stop_sec and
vmagent__systemd_limit_nofile are left as role-wide variables since
they document legitimate workload-scaling use cases (queue flush time,
open file limits for busy aggregators), unlike ordering/restart policy.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

…variable

Same pattern flagged by drybjed on PR debops#2702 (cloudflared): the role
is not part of common.yml and its playbook already restricts
execution to the debops_service_prometheus_exporter inventory group,
so a role-wide enable/disable switch is redundant. Individual
exporters already carry their own per-item 'state' (present/absent)
handled in manage_exporter.yml.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

ansible-lint requires Jinja templates to appear only at the end of a
task's 'name' field; otherwise log lines emitted by Ansible can become
ambiguous when the rendered name contains additional text after the
template.

All 14 tasks in the per-tunnel include file referenced '{{ tunnel.name }}'
in the middle of their human-readable description. Rewrite each name as
'<verb> <description> for cloudflared tunnel {{ tunnel.name }}' so the
template lands at the end of the string. The behaviour of every task
is unchanged.

Fixes 10 'name[template]' violations reported by ansible-lint in CI for
PR debops#2702.

The CI documentation/debops-sdist/debops-wheel/docker-image jobs all
failed with the same warning (treated as error by '-W' in test-docs and
test-man Makefile targets):

  Warning, treated as error:
  /.../docs/ansible/roles/cloudflared/defaults-detailed.rst:document
  isn't included in any toctree

The DebOps documentation root toctree (docs/ansible/roles/index.rst)
globs '*/index' for every role directory, and conf.py iterates the same
directory list to register manpages from each role's 'man_index.rst' or
'index.rst'. The cloudflared role shipped neither, so its existing
.rst files (defaults-detailed, getting-started, guide-*) were treated
as orphaned documents.

Add the standard set of role documentation index files following the
established DebOps convention (cf. docs/ansible/roles/slapd/ for the
'guide-*.rst' variant of the layout):

- docs/ansible/roles/cloudflared/index.rst -- main entry, declares the
  '.. _debops.cloudflared:' label and lists the role's RST documents in
  a toctree (getting-started, guide-docker-integration,
  guide-nginx-integration, defaults/main, defaults-detailed).

- docs/ansible/roles/cloudflared/man_description.rst -- short prose
  description used by both the HTML index and the Sphinx manpage
  builder (':start-line: 7' import in index.rst).

- docs/ansible/roles/cloudflared/man_index.rst -- ':orphan:' entry
  point used when conf.py registers 'debops.cloudflared(5)' as a
  manpage target.

- docs/ansible/roles/cloudflared/man_synopsis.rst -- standard
  'debops run/check service/cloudflared' invocation synopsis.

- ansible/roles/cloudflared/COPYRIGHT -- conf.py reads the role's
  COPYRIGHT to populate manpage description and authors.

Update docs/ansible/role-index.rst to use ':ref:`debops.cloudflared`'
instead of the literal '``debops.cloudflared``' (now that the label
exists), matching every other entry in the role catalogue.

Fixes the CI 'documentation', 'debops-sdist', 'debops-wheel' and
'docker-image' job failures reported on PR debops#2702.

- Remove the unused 'Restart cloudflared tunnels' handler from
  global_handlers. It referenced cloudflared__combined_tunnels without
  a safe default and was unconditionally imported from
  global_handlers/handlers/main.yml, which would break global_handlers
  evaluation on hosts where the cloudflared role is not part of the
  playbook. The handler was also never notified anywhere:
  manage_tunnel.yml already restarts the per-tunnel systemd unit
  directly (with '# noqa no-handler') on config/env/credentials
  changes, so it was dead code.

- Hardcode 'After=network-online.target' directly in the
  cloudflared@.service.j2 systemd template instead of exposing
  cloudflared__systemd_after as a role-wide variable - the ordering is
  expected to be identical for every tunnel instance. Per-instance
  overrides should go through the debops.systemd role's drop-in
  override files instead.

- Enable cloudflared__metrics by default (bound to loopback) instead
  of only proposing it via a comment example. Port 2000 is avoided as
  the default since it's already reserved for the Cisco SCCP service
  on many systems; use 127.0.0.1:20241 instead.

- Add cloudflared__etc_services__dependent_list and wire the
  debops.etc_services role into the cloudflared playbook so the
  metrics port gets a /etc/services entry when enabled, following the
  same pattern used by docker_registry, dhcpd and other roles.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Per PR debops#2702 review: the role is not part of the common.yml playbook
(it only runs on hosts in the debops_service_cloudflared inventory
group via its own playbook), so a role-wide enable/disable switch is
redundant - membership in that group already controls whether the
role runs at all. This matches the pattern used by other standalone
service roles such as docker_registry, dhcpd and mosquitto, which
have no comparable __enabled variable and rely solely on their
__deploy_state variable for present/absent state.

Generated-By: LLM (Claude Sonnet 5 via Cursor)

Complete PR debops#2702 review comment debops#3: the full 'systemd configuration'
section (restart_policy, restart_sec, after) was flagged as being
better set directly in the unit file, with systemd_after called out
as the primary example. The previous fix only hardcoded
'After=network-online.target' and left cloudflared__systemd_restart_policy
/ cloudflared__systemd_restart_sec as role-wide variables. Hardcode
'Restart=on-failure' / 'RestartSec=5' directly in cloudflared@.service.j2
as well, and drop both variables; per-instance overrides remain
available via debops.systemd drop-in files.

Generated-By: LLM (Claude Sonnet 5 via Cursor)