docs(talk,coturn): add meta/argument_specs.yml
* coturn: 31 typed options including the 3 cert modes (acme/file/ selfsigned), the RFC2136 acme.sh sidecar config and challenge alias subschema. coturn_static_auth_secret marked required. * talk: 34 typed options covering the signaling/janus/nats triplet, TURN integration, MCU (janus) tuning, trusted-proxy CIDRs and the extra_hosts pin. talk_backend_secret, talk_turn_secret, talk_session_hashkey and talk_session_blockkey marked required. Both specs load cleanly through ansible-core's ArgumentSpecValidator, have 100% defaults/spec coverage, and match the convention introduced for the other roles in this collection.
This commit is contained in:
Simon Bärlocher
parent
dc8f1e2ecd
commit
9a9039c4d3
2 changed files with 309 additions and 0 deletions
148
roles/coturn/meta/argument_specs.yml
Normal file
148
roles/coturn/meta/argument_specs.yml
Normal file
|
|
@ -0,0 +1,148 @@
|
|||
---
|
||||
argument_specs:
|
||||
main:
|
||||
short_description: Deploy a coturn TURN/STUN server with optional acme.sh sidecar.
|
||||
description:
|
||||
- "Renders a Docker Compose stack for coturn running in
|
||||
C(network_mode: host), with an optional C(acme.sh) sidecar that
|
||||
issues + renews a public TLS certificate via RFC2136 / nsupdate
|
||||
and restarts coturn on renewal."
|
||||
- Designed to be paired with the C(digitalboard.core.talk) role
|
||||
(Nextcloud Talk High Performance Backend).
|
||||
options:
|
||||
docker_compose_base_dir:
|
||||
type: path
|
||||
default: /etc/docker/compose
|
||||
docker_volume_base_dir:
|
||||
type: path
|
||||
default: /srv/data
|
||||
coturn_service_name:
|
||||
type: str
|
||||
default: coturn
|
||||
coturn_docker_compose_dir:
|
||||
type: path
|
||||
coturn_docker_volume_dir:
|
||||
type: path
|
||||
|
||||
coturn_image:
|
||||
type: str
|
||||
default: "coturn/coturn:4.6.2-r5-alpine"
|
||||
coturn_acme_image:
|
||||
type: str
|
||||
default: "neilpang/acme.sh:3.1.0"
|
||||
|
||||
coturn_realm:
|
||||
type: str
|
||||
default: stun.example.test
|
||||
description: Public DNS name used for the TURN realm and the public certificate.
|
||||
coturn_internal_realm:
|
||||
type: str
|
||||
default: ''
|
||||
description:
|
||||
- Optional second DNS name issued on the same certificate, used for
|
||||
split-horizon internal access (e.g. C(stun.int.example.test)).
|
||||
|
||||
coturn_listening_port:
|
||||
type: int
|
||||
default: 3478
|
||||
description: TURN/STUN port (TCP + UDP). IANA standard is 3478.
|
||||
coturn_tls_listening_port:
|
||||
type: int
|
||||
default: 5349
|
||||
description: TURNS port (TCP + UDP). IANA standard is 5349.
|
||||
coturn_min_relay_port:
|
||||
type: int
|
||||
default: 49160
|
||||
coturn_max_relay_port:
|
||||
type: int
|
||||
default: 49200
|
||||
|
||||
coturn_external_ip:
|
||||
type: str
|
||||
default: ''
|
||||
description:
|
||||
- coturn C(--external-ip) value. Format C("PUBLIC_IP") or
|
||||
C("PUBLIC_IP/PRIVATE_IP"). Must be set in host_vars for production.
|
||||
coturn_listening_ip:
|
||||
type: str
|
||||
default: '0.0.0.0'
|
||||
|
||||
coturn_static_auth_secret:
|
||||
type: str
|
||||
required: true
|
||||
description:
|
||||
- Shared secret used by the HPB signaling server to mint short-lived
|
||||
TURN credentials. Default lookup reads
|
||||
C(playbooks/secrets/<host>/coturn_static_auth_secret).
|
||||
|
||||
coturn_extra_args:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
description: Additional CLI flags appended verbatim to the container C(command:).
|
||||
|
||||
coturn_cert_mode:
|
||||
type: str
|
||||
choices: [acme, file, selfsigned]
|
||||
default: file
|
||||
description:
|
||||
- C(acme) runs an acme.sh sidecar that issues + renews via RFC2136
|
||||
and restarts coturn. C(file) assumes a certificate already lives
|
||||
on the host (you manage it). C(selfsigned) generates one on first
|
||||
run (vagrant/dev only).
|
||||
coturn_cert_dir:
|
||||
type: path
|
||||
coturn_cert_file:
|
||||
type: str
|
||||
default: fullchain.cer
|
||||
coturn_key_file:
|
||||
type: str
|
||||
description: Defaults to C("{{ coturn_realm }}.key").
|
||||
|
||||
coturn_acme_email:
|
||||
type: str
|
||||
default: admin@example.test
|
||||
coturn_acme_directory:
|
||||
type: str
|
||||
default: https://acme-v02.api.letsencrypt.org/directory
|
||||
coturn_acme_keylength:
|
||||
type: str
|
||||
default: ec-256
|
||||
choices: [ec-256, ec-384, '2048', '3072', '4096']
|
||||
coturn_acme_dnssleep:
|
||||
type: int
|
||||
default: 60
|
||||
coturn_acme_data_dir:
|
||||
type: path
|
||||
|
||||
coturn_acme_nsupdate_server:
|
||||
type: str
|
||||
default: ''
|
||||
description: Authoritative nameserver acme.sh sends C(nsupdate) packets to.
|
||||
coturn_acme_nsupdate_server_ip:
|
||||
type: str
|
||||
default: ''
|
||||
description: Optional C(extra_hosts) pin (string IP) for the nsupdate server.
|
||||
coturn_acme_nsupdate_zone:
|
||||
type: str
|
||||
default: ''
|
||||
description: Delegated challenge zone (e.g. C(example._acme.example.test)).
|
||||
coturn_acme_challenge_aliases:
|
||||
type: list
|
||||
elements: dict
|
||||
default: []
|
||||
description:
|
||||
- Per-name challenge alias zones (one entry per SAN). When empty,
|
||||
built automatically as C({{ realm }}._acme.{{ zone-tail }}).
|
||||
options:
|
||||
name:
|
||||
type: str
|
||||
required: true
|
||||
description: SAN the challenge is for.
|
||||
alias:
|
||||
type: str
|
||||
required: true
|
||||
description: CNAME target where the C(_acme-challenge) TXT lives.
|
||||
coturn_acme_nsupdate_key_src:
|
||||
type: path
|
||||
description: Path of the TSIG key file on the controller, mounted into the acme container.
|
||||
161
roles/talk/meta/argument_specs.yml
Normal file
161
roles/talk/meta/argument_specs.yml
Normal file
|
|
@ -0,0 +1,161 @@
|
|||
---
|
||||
argument_specs:
|
||||
main:
|
||||
short_description: Deploy the Nextcloud Talk High Performance Backend (HPB) stack.
|
||||
description:
|
||||
- Renders a Docker Compose stack with C(nextcloud-spreed-signaling)
|
||||
(Strukturag), C(janus-gateway) (canyan build) and C(nats) (internal
|
||||
message broker) behind Traefik.
|
||||
- Designed to be paired with the C(digitalboard.core.coturn) role
|
||||
(TURN/STUN) and registered in Nextcloud via
|
||||
C(digitalboard.core.nextcloud)'s C(talk.yml) task.
|
||||
options:
|
||||
docker_compose_base_dir:
|
||||
type: path
|
||||
default: /etc/docker/compose
|
||||
docker_volume_base_dir:
|
||||
type: path
|
||||
default: /srv/data
|
||||
talk_service_name:
|
||||
type: str
|
||||
default: signaling
|
||||
talk_docker_compose_dir:
|
||||
type: path
|
||||
talk_docker_volume_dir:
|
||||
type: path
|
||||
|
||||
talk_signaling_image:
|
||||
type: str
|
||||
default: "strukturag/nextcloud-spreed-signaling:1.3.4"
|
||||
talk_janus_image:
|
||||
type: str
|
||||
default: "canyan/janus-gateway:1.2.4"
|
||||
talk_nats_image:
|
||||
type: str
|
||||
default: "nats:2.10-alpine"
|
||||
|
||||
talk_traefik_network:
|
||||
type: str
|
||||
default: proxy
|
||||
talk_internal_network:
|
||||
type: str
|
||||
default: hpb_internal
|
||||
|
||||
talk_use_ssl:
|
||||
type: bool
|
||||
default: true
|
||||
talk_cert_resolver:
|
||||
type: str
|
||||
default: dns
|
||||
talk_domain:
|
||||
type: str
|
||||
default: signaling.example.test
|
||||
description: Public domain (typically routed through the DMZ Traefik).
|
||||
talk_internal_domain:
|
||||
type: str
|
||||
default: ''
|
||||
description:
|
||||
- Optional split-horizon C(*.int.*) domain for server-to-server
|
||||
traffic (e.g. C(signaling.int.example.test)).
|
||||
|
||||
talk_nextcloud_url:
|
||||
type: str
|
||||
default: https://cloud.example.test
|
||||
description: Nextcloud base URL the HPB talks back to. Must be reachable from the HPB container.
|
||||
talk_nextcloud_extra_host_ip:
|
||||
type: str
|
||||
default: ''
|
||||
description:
|
||||
- Pin the Nextcloud hostname to a backend IP via C(extra_hosts) to bypass
|
||||
DMZ hairpin / SNI issues. Empty disables the pin.
|
||||
|
||||
talk_backend_secret:
|
||||
type: str
|
||||
required: true
|
||||
description:
|
||||
- HMAC secret shared with Nextcloud Talk. Default lookup reads
|
||||
C(playbooks/secrets/<host>/talk_backend_secret).
|
||||
|
||||
talk_turn_secret:
|
||||
type: str
|
||||
required: true
|
||||
description:
|
||||
- Shared secret with coturn (must match C(coturn_static_auth_secret)
|
||||
on the TURN host). Default lookup reads
|
||||
C(playbooks/secrets/<host>/talk_turn_secret).
|
||||
talk_turn_servers:
|
||||
type: str
|
||||
default: "turns:stun.example.test:5349?transport=tcp,turn:stun.example.test:3478"
|
||||
description:
|
||||
- TURN server URI list as understood by the signaling server.
|
||||
Override to C(:443) when coturn binds on 443 in restrictive networks.
|
||||
talk_turn_realm:
|
||||
type: str
|
||||
default: stun.example.test
|
||||
talk_turn_apikey:
|
||||
type: str
|
||||
default: ''
|
||||
description: Optional explicit API key; when empty a random one is generated on first run.
|
||||
|
||||
talk_session_hashkey:
|
||||
type: str
|
||||
required: true
|
||||
description:
|
||||
- 32-byte hex string. Default lookup reads
|
||||
C(playbooks/secrets/<host>/talk_session_hashkey).
|
||||
talk_session_blockkey:
|
||||
type: str
|
||||
required: true
|
||||
description:
|
||||
- 32-byte hex string. Default lookup reads
|
||||
C(playbooks/secrets/<host>/talk_session_blockkey).
|
||||
|
||||
talk_mcu_type:
|
||||
type: str
|
||||
choices: [janus]
|
||||
default: janus
|
||||
talk_janus_public_ip:
|
||||
type: str
|
||||
default: ''
|
||||
description: Must be set in host_vars. Goes into janus C(nat_1_1_mapping).
|
||||
talk_janus_rtp_port_min:
|
||||
type: int
|
||||
default: 20000
|
||||
talk_janus_rtp_port_max:
|
||||
type: int
|
||||
default: 21000
|
||||
talk_janus_stun_server:
|
||||
type: str
|
||||
default: stun.int.example.test
|
||||
description: STUN server janus uses for its own ICE candidate gathering.
|
||||
talk_janus_stun_port:
|
||||
type: int
|
||||
default: 5349
|
||||
talk_janus_ice_lite:
|
||||
type: bool
|
||||
default: true
|
||||
talk_janus_ice_tcp:
|
||||
type: bool
|
||||
default: true
|
||||
|
||||
talk_trusted_proxies:
|
||||
type: list
|
||||
elements: str
|
||||
default:
|
||||
- "172.16.0.0/12"
|
||||
- "192.168.0.0/16"
|
||||
- "10.0.0.0/8"
|
||||
talk_allowed_hosts:
|
||||
type: list
|
||||
elements: str
|
||||
default:
|
||||
- "172.16.0.0/12"
|
||||
|
||||
talk_extra_hosts:
|
||||
type: list
|
||||
elements: str
|
||||
default: []
|
||||
description:
|
||||
- Extra C(host:ip) entries forwarded to all three containers.
|
||||
Pre-populated with the Nextcloud pin when
|
||||
C(talk_nextcloud_extra_host_ip) is set.
|
||||
Loading…
Add table
Add a link
Reference in a new issue