A webhook provider for ExternalDNS that manages DNS records in Thalassa Cloud using the client-go DNS package.
Authentication is resolved in this order:
- OIDC token exchange — set
THALASSA_SERVICE_ACCOUNT_IDandTHALASSA_ORGANISATION_ID. The pod service account JWT is used automatically from/var/run/secrets/kubernetes.io/serviceaccount/tokenunlessTHALASSA_SUBJECT_TOKENorTHALASSA_SUBJECT_TOKEN_FILEis set. - Personal access token — set
THALASSA_TOKENor mount a token atTHALASSA_TOKEN_FILE. - OIDC client credentials — set
THALASSA_CLIENT_IDwithTHALASSA_CLIENT_SECRETorTHALASSA_CLIENT_SECRET_FILE.
THALASSA_ORGANISATION_ID is always required.
| Variable | Required | Default | Description |
|---|---|---|---|
THALASSA_ORGANISATION_ID |
Yes | - | Organisation identity |
THALASSA_SERVICE_ACCOUNT_ID |
Auth* | - | Service account for OIDC token exchange |
THALASSA_SUBJECT_TOKEN |
No | - | Subject JWT for OIDC token exchange |
THALASSA_SUBJECT_TOKEN_FILE |
No | K8s SA token path | Path to subject JWT file |
THALASSA_TOKEN |
Auth* | - | Personal access token |
THALASSA_TOKEN_FILE |
Auth* | - | Path to personal access token file |
THALASSA_CLIENT_ID |
Auth* | - | OIDC client ID |
THALASSA_CLIENT_SECRET |
Auth* | - | OIDC client secret |
THALASSA_CLIENT_SECRET_FILE |
Auth* | - | Path to OIDC client secret file |
THALASSA_OIDC_TOKEN_URL |
No | {THALASSA_API_URL}/oidc/token |
OIDC token exchange URL |
THALASSA_ACCESS_TOKEN_LIFETIME |
No | - | Requested access token lifetime |
THALASSA_PROJECT_ID |
No | - | Project identity for project-scoped DNS |
THALASSA_API_URL |
No | https://api.thalassa.cloud |
Thalassa Cloud API base URL |
THALASSA_INSECURE |
No | false |
Disable TLS certificate verification |
THALASSA_DOMAIN_FILTER |
No | - | Comma-separated list of zones to manage |
THALASSA_DRY_RUN |
No | false |
Enable dry-run mode |
THALASSA_HTTP_RETRY_MAX |
No | 3 |
Maximum HTTP retries |
THALASSA_HTTP_RETRY_WAIT_MIN |
No | 1s |
Minimum wait between retries |
THALASSA_HTTP_RETRY_WAIT_MAX |
No | 30s |
Maximum wait between retries |
THALASSA_WORKERS |
No | 10 |
Concurrent zone workers when listing records |
*One authentication method from the precedence list above is required.
All Thalassa settings are registered via flags with defaults taken from the corresponding THALASSA_* environment variables. Flags override env when both are set.
--log-level Log level (debug, info, warn, error) [default: info]
--log-format Log format (text, json) [default: text]
--host Webhook server host [default: 0.0.0.0]
--port Webhook server port [default: 8888]
--dry-run Enable dry-run mode
--retry-max Maximum HTTP retries [default: 3]
--retry-wait-min Minimum wait between retries [default: 1s]
--retry-wait-max Maximum wait between retries [default: 30s]
--workers Concurrent zone workers [default: 10]
--domain-filter Comma-separated list of DNS zones to manage
--thalassa-url Thalassa Cloud API base URL
--organisation Organisation identity
--thalassa-project Project identity
--thalassa-token Personal access token
--thalassa-token-file Path to personal access token file
--thalassa-service-account-id Service account for OIDC token exchange
--thalassa-subject-token Subject JWT for OIDC token exchange
--thalassa-subject-token-file Path to subject JWT file
--thalassa-oidc-token-url OIDC token exchange URL
--thalassa-access-token-lifetime Requested access token lifetime
--thalassa-client-id OIDC client ID
--thalassa-client-secret OIDC client secret
--thalassa-client-secret-file Path to OIDC client secret file
--thalassa-insecure Disable TLS certificate verification
Recommended for Kubernetes: no long-lived personal token in a Secret.
provider:
name: webhook
webhook:
image:
repository: ghcr.io/thalassa-cloud/external-dns-thalassa-webhook
tag: latest
serviceAccount:
create: true
name: external-dns-thalassa
env:
- name: THALASSA_ORGANISATION_ID
value: "my-org"
- name: THALASSA_SERVICE_ACCOUNT_ID
value: "sa-external-dns"
- name: THALASSA_DOMAIN_FILTER
value: "example.com"
args:
- --port=8080
- --log-level=info
securityContext:
runAsUser: 65532
runAsGroup: 65532
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
livenessProbe:
httpGet:
path: /healthz
port: http-webhook
initialDelaySeconds: 10
periodSeconds: 10
readinessProbe:
httpGet:
path: /healthz
port: http-webhook
initialDelaySeconds: 5
periodSeconds: 5Install the chart:
helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm upgrade --install external-dns external-dns/external-dns -f values.yamlNote: The
--port=8080flag is required because the ExternalDNS Helm chart expects the webhook to listen on port 8080 (http-webhook), while the binary defaults to 8888.
provider:
name: webhook
webhook:
image:
repository: ghcr.io/thalassa-cloud/external-dns-thalassa-webhook
tag: latest
env:
- name: THALASSA_TOKEN
valueFrom:
secretKeyRef:
name: thalassa-credentials
key: token
- name: THALASSA_ORGANISATION_ID
value: "my-org"
- name: THALASSA_DOMAIN_FILTER
value: "example.com"
args:
- --port=8080
- --log-level=infoapiVersion: v1
kind: ServiceAccount
metadata:
name: external-dns-thalassa
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: external-dns
spec:
template:
spec:
serviceAccountName: external-dns-thalassa
containers:
- name: external-dns
image: registry.k8s.io/external-dns/external-dns:v0.21.0
args:
- --source=ingress
- --source=service
- --provider=webhook
- --webhook-provider-url=http://localhost:8888
- --policy=sync
- --registry=txt
- --txt-owner-id=my-cluster
- --interval=1m
- name: thalassa-webhook
image: ghcr.io/thalassa-cloud/external-dns-thalassa-webhook:latest
securityContext:
runAsUser: 65532
runAsGroup: 65532
runAsNonRoot: true
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop:
- ALL
args:
- --log-level=info
- --organisation=my-org
- --thalassa-service-account-id=sa-external-dns
env:
- name: THALASSA_DOMAIN_FILTER
value: "example.com"
ports:
- containerPort: 8888
name: http
livenessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 10
periodSeconds: 10
readinessProbe:
httpGet:
path: /healthz
port: http
initialDelaySeconds: 5
periodSeconds: 5apiVersion: v1
kind: Secret
metadata:
name: thalassa-credentials
type: Opaque
stringData:
token: "your-thalassa-personal-access-token"- Go 1.25+
- Make
- GoReleaser (required for Docker image builds)
# Run tests
make test
# Build binary locally
make build
# Build Docker image (uses GoReleaser snapshot artifacts)
make docker-build
# Run locally with personal token
THALASSA_TOKEN=your-token \
THALASSA_ORGANISATION_ID=your-org \
make runReleases are published with GoReleaser when a version tag matching v* is pushed. Container images are published to ghcr.io/thalassa-cloud/external-dns-thalassa-webhook.
git tag v0.1.0
git push origin v0.1.0The webhook exposes Prometheus metrics at /metrics:
| Metric | Description |
|---|---|
thalassa_api_requests_total |
Total number of Thalassa Cloud API requests |
thalassa_api_errors_total |
Total number of failed API requests |
thalassa_api_rate_limits_total |
Total number of rate limit hits |
Apache License 2.0. See LICENSE for details.