docs(roles): add argument_specs and README for traefik, authentik, drawio, garage, nextcloud
Each of the five roles touched in this branch now ships: * meta/argument_specs.yml: typed schema for every variable in defaults/main.yml plus the optional inputs surfaced via this branch (traefik_extra_hosts, authentik_host_rewrite_domains, authentik_proxy_apps.mode / .allowed_groups, drawio_extra_domains, drawio_authentik_forward_auth*, garage_webui_authentik_forward_auth*). All five specs load cleanly through ansible-core's ArgumentSpecValidator. * README.md: replaces the ansible-galaxy boilerplate (where it was still in place) with a focused write-up — service vars, required secrets, ForwardAuth/idempotency notes, dependencies, and a working example playbook. authentik and garage READMEs are rewritten to cover the new knobs while preserving their existing content.
This commit is contained in:
Simon Bärlocher
parent
a9c33baed9
commit
1dcff92240
10 changed files with 1348 additions and 143 deletions
|
|
@ -1,38 +1,98 @@
|
|||
Role Name
|
||||
=========
|
||||
# Traefik
|
||||
|
||||
A brief description of the role goes here.
|
||||
Ansible role to deploy Traefik v3 as a reverse proxy via Docker Compose,
|
||||
either as a public-facing DMZ proxy (file provider) or as a backend
|
||||
application proxy (docker provider).
|
||||
|
||||
Requirements
|
||||
------------
|
||||
## Requirements
|
||||
|
||||
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
|
||||
- Docker and Docker Compose installed on the target host
|
||||
- Ansible collection: `community.docker`
|
||||
- For ACME DNS-01: an RFC2136-capable nameserver with a delegated zone
|
||||
for `_acme-challenge` records and a TSIG key
|
||||
|
||||
Role Variables
|
||||
--------------
|
||||
## Role variables
|
||||
|
||||
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
|
||||
Full list with types and defaults: `meta/argument_specs.yml`. The most
|
||||
common overrides:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
### Deployment mode
|
||||
|
||||
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
|
||||
- `traefik_mode`: `dmz` (file provider, routes to external backends) or
|
||||
`backend` (docker provider, discovers local containers). Default `backend`.
|
||||
- `traefik_backend_servers_to_proxy`: in `dmz` mode, restrict which
|
||||
inventory hosts the DMZ aggregates services from. Empty = all members
|
||||
of `backend_servers`.
|
||||
|
||||
Example Playbook
|
||||
----------------
|
||||
### Networking
|
||||
|
||||
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
|
||||
- `traefik_network`: docker network connecting traefik to its containers
|
||||
(default `proxy`).
|
||||
- `traefik_extra_hosts`: list of `host:ip` entries injected as the
|
||||
container's `extra_hosts`. Use when a downstream middleware
|
||||
(e.g. ForwardAuth to authentik on a sibling LAN) must resolve a public
|
||||
FQDN to an internal IP because the DMZ does not hairpin the public
|
||||
address back inside.
|
||||
|
||||
- hosts: servers
|
||||
roles:
|
||||
- { role: username.rolename, x: 42 }
|
||||
### Certificates
|
||||
|
||||
License
|
||||
-------
|
||||
- `traefik_cert_mode`: `acme` (Let's Encrypt via DNS-01) or `selfsigned`
|
||||
(local wildcard). Default `selfsigned`.
|
||||
- `traefik_acme_dns_zone`, `traefik_acme_dns_nameserver`,
|
||||
`traefik_acme_tsig_key`, `traefik_acme_tsig_secret`: RFC2136 / TSIG
|
||||
configuration for the ACME DNS-01 challenge.
|
||||
- `traefik_acme_tcp_only`: force lego's DNS lookups onto TCP/53 when the
|
||||
container cannot reach the nameserver over UDP.
|
||||
- `traefik_acme_disable_ans_checks`: skip the authoritative-NS
|
||||
propagation check when the SOA-listed NS resolves to an unreachable IP.
|
||||
|
||||
BSD
|
||||
### Dashboard
|
||||
|
||||
Author Information
|
||||
------------------
|
||||
- `traefik_enable_dashboard`: expose the traefik dashboard.
|
||||
- `traefik_dashboard_domain`: when set, publish the dashboard on this
|
||||
Host rule instead of the insecure port.
|
||||
|
||||
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
|
||||
## Dependencies
|
||||
|
||||
- Traefik network (`traefik_network`, default `proxy`) must be created
|
||||
by the `base` role or by hand before this role runs.
|
||||
- In `dmz` mode, the proxied backend services advertise themselves via
|
||||
the `traefik_services` host_var on each backend host.
|
||||
|
||||
## Example playbook
|
||||
|
||||
Backend mode (one app server per host, docker provider):
|
||||
|
||||
```yaml
|
||||
- hosts: app_servers
|
||||
roles:
|
||||
- role: digitalboard.core.traefik
|
||||
vars:
|
||||
traefik_mode: backend
|
||||
traefik_cert_mode: acme
|
||||
traefik_ssl_email: ops@example.com
|
||||
traefik_acme_dns_zone: "_acme.example.com."
|
||||
traefik_acme_dns_nameserver: "10.0.0.53:53"
|
||||
traefik_acme_tsig_key: "acme-key"
|
||||
traefik_acme_tsig_secret: "{{ vault_traefik_tsig_secret }}"
|
||||
```
|
||||
|
||||
DMZ mode (aggregates services from `backend_servers`):
|
||||
|
||||
```yaml
|
||||
- hosts: dmz_servers
|
||||
roles:
|
||||
- role: digitalboard.core.traefik
|
||||
vars:
|
||||
traefik_mode: dmz
|
||||
traefik_cert_mode: acme
|
||||
traefik_backend_servers_to_proxy:
|
||||
- app01
|
||||
- app02
|
||||
traefik_extra_hosts:
|
||||
- "auth.example.com:172.16.19.101"
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT-0
|
||||
|
|
|
|||
215
roles/traefik/meta/argument_specs.yml
Normal file
215
roles/traefik/meta/argument_specs.yml
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
---
|
||||
argument_specs:
|
||||
main:
|
||||
short_description: Deploy Traefik v3 as DMZ or backend reverse proxy via Docker Compose.
|
||||
description:
|
||||
- Renders a Docker Compose stack for Traefik with either the file provider
|
||||
(DMZ mode, routes to external backends) or the docker provider (backend
|
||||
mode, discovers local containers via labels).
|
||||
- Supports ACME DNS-01 issuance (RFC2136 / TSIG) or a self-signed cert
|
||||
bundle for local/Vagrant setups.
|
||||
options:
|
||||
docker_compose_base_dir:
|
||||
type: path
|
||||
default: /etc/docker/compose
|
||||
description: Base directory under which the per-service compose dir is created.
|
||||
docker_volume_base_dir:
|
||||
type: path
|
||||
default: /srv/data
|
||||
description: Base directory under which the per-service volume dir is created.
|
||||
service_name:
|
||||
type: str
|
||||
default: traefik
|
||||
description: Compose project / service name; also used to build the per-service paths.
|
||||
docker_compose_dir:
|
||||
type: path
|
||||
description: Compose project directory; defaults to C({{ docker_compose_base_dir }}/{{ service_name }}).
|
||||
docker_volume_dir:
|
||||
type: path
|
||||
description: Per-service volume directory; defaults to C({{ docker_volume_base_dir }}/{{ service_name }}).
|
||||
|
||||
traefik_extra_hosts:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
description:
|
||||
- Entries injected as C(extra_hosts) on the traefik container.
|
||||
- Each entry has the Docker syntax C("host:ip").
|
||||
- Useful when a downstream middleware (e.g. ForwardAuth to authentik
|
||||
on a sibling LAN) must resolve a public FQDN to an internal IP
|
||||
because the DMZ does not hairpin the public address.
|
||||
|
||||
traefik_mode:
|
||||
type: str
|
||||
choices: [dmz, backend]
|
||||
default: backend
|
||||
description:
|
||||
- C(dmz) configures the file provider so the proxy forwards to
|
||||
backend hosts (typically aggregated from the C(backend_servers) group).
|
||||
- C(backend) configures the docker provider for local container discovery.
|
||||
|
||||
traefik_use_ssl:
|
||||
type: bool
|
||||
default: true
|
||||
description: Toggle TLS on the websecure entrypoint.
|
||||
traefik_ssl_email:
|
||||
type: str
|
||||
default: admin@example.com
|
||||
description: Contact e-mail used by the ACME resolver.
|
||||
traefik_ssl_cert_resolver:
|
||||
type: str
|
||||
default: dns
|
||||
description: Certificate resolver name referenced in router labels.
|
||||
traefik_cert_mode:
|
||||
type: str
|
||||
choices: [acme, selfsigned]
|
||||
default: selfsigned
|
||||
description: C(acme) for Let's Encrypt via DNS-01, C(selfsigned) for a locally generated bundle.
|
||||
|
||||
traefik_acme_dns_zone:
|
||||
type: str
|
||||
default: ''
|
||||
description: Delegated zone used for the TSIG-signed updates (e.g. C(_acme.example.com.)).
|
||||
traefik_acme_dns_nameserver:
|
||||
type: str
|
||||
default: ''
|
||||
description: Nameserver lego talks to for the DNS challenge (C(host:port)).
|
||||
traefik_acme_tsig_algorithm:
|
||||
type: str
|
||||
default: hmac-sha256
|
||||
description: TSIG algorithm.
|
||||
traefik_acme_tsig_key:
|
||||
type: str
|
||||
default: ''
|
||||
description: TSIG key name.
|
||||
traefik_acme_tsig_secret:
|
||||
type: str
|
||||
default: ''
|
||||
description: TSIG secret (base64).
|
||||
traefik_acme_propagation_timeout:
|
||||
type: str
|
||||
default: '120'
|
||||
description: lego DNS propagation timeout in seconds.
|
||||
traefik_acme_polling_interval:
|
||||
type: str
|
||||
default: '2'
|
||||
description: lego DNS propagation polling interval in seconds.
|
||||
traefik_acme_ttl:
|
||||
type: str
|
||||
default: '60'
|
||||
description: TTL applied to the C(_acme-challenge) TXT records.
|
||||
traefik_acme_tcp_only:
|
||||
type: bool
|
||||
default: false
|
||||
description:
|
||||
- Sets C(LEGO_EXPERIMENTAL_DNS_TCP_ONLY=true) on the container so SOA
|
||||
resolution and propagation checks use TCP/53. Use when UDP/53 is
|
||||
blocked or unreliable on the container egress path.
|
||||
traefik_acme_disable_ans_checks:
|
||||
type: bool
|
||||
default: false
|
||||
description:
|
||||
- Disable lego's propagation check against the zone's authoritative
|
||||
nameservers (sets C(LEGO_DISABLE_CNAME_SUPPORT=) plus the
|
||||
authoritative-NS-check skip). Use when the SOA-listed NS hostname
|
||||
resolves to an address the proxy host cannot reach.
|
||||
|
||||
traefik_selfsigned_cert_dir:
|
||||
type: path
|
||||
description: Output directory for the self-signed bundle.
|
||||
traefik_selfsigned_cert_days:
|
||||
type: int
|
||||
default: 365
|
||||
description: Validity in days for the self-signed bundle.
|
||||
traefik_selfsigned_common_name:
|
||||
type: str
|
||||
default: '*.local.test'
|
||||
description: CN/SAN of the self-signed wildcard cert.
|
||||
|
||||
traefik_enable_dashboard:
|
||||
type: bool
|
||||
default: false
|
||||
description: Expose the traefik dashboard.
|
||||
traefik_dashboard_domain:
|
||||
type: str
|
||||
default: ''
|
||||
description:
|
||||
- When non-empty, the dashboard is published on this Host rule instead
|
||||
of the insecure port 8080.
|
||||
|
||||
traefik_enable_access_logs:
|
||||
type: bool
|
||||
default: true
|
||||
traefik_access_log_format:
|
||||
type: str
|
||||
choices: [common, json]
|
||||
default: common
|
||||
traefik_log_level:
|
||||
type: str
|
||||
choices: [DEBUG, INFO, WARN, ERROR, FATAL, PANIC]
|
||||
default: INFO
|
||||
|
||||
traefik_network:
|
||||
type: str
|
||||
default: proxy
|
||||
description: Docker network connecting traefik to its routable containers.
|
||||
|
||||
traefik_dmz_exposed_services:
|
||||
type: list
|
||||
elements: dict
|
||||
default: []
|
||||
description:
|
||||
- In C(dmz) mode, services collected from backend host_vars are
|
||||
published via the file provider. Each entry needs C(name),
|
||||
C(domain), C(port); C(protocol) and C(backend_host) are optional.
|
||||
options:
|
||||
name:
|
||||
type: str
|
||||
required: true
|
||||
domain:
|
||||
type: str
|
||||
required: true
|
||||
port:
|
||||
type: int
|
||||
required: true
|
||||
protocol:
|
||||
type: str
|
||||
choices: [http, https]
|
||||
default: http
|
||||
backend_host:
|
||||
type: str
|
||||
description: Override the auto-selected backend host.
|
||||
|
||||
traefik_services:
|
||||
type: list
|
||||
elements: dict
|
||||
default: []
|
||||
description:
|
||||
- Services defined directly on the DMZ proxy (not auto-discovered
|
||||
from a backend host). Each entry must set C(backend_host).
|
||||
options:
|
||||
name:
|
||||
type: str
|
||||
required: true
|
||||
domain:
|
||||
type: str
|
||||
required: true
|
||||
backend_host:
|
||||
type: str
|
||||
required: true
|
||||
port:
|
||||
type: int
|
||||
required: true
|
||||
protocol:
|
||||
type: str
|
||||
choices: [http, https]
|
||||
default: http
|
||||
|
||||
traefik_backend_servers_to_proxy:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
description:
|
||||
- In C(dmz) mode, explicit list of backend hosts the DMZ proxy
|
||||
should aggregate exposed services from. Empty means all members
|
||||
of the C(backend_servers) inventory group.
|
||||
Loading…
Add table
Add a link
Reference in a new issue