A ExternalDNS webhook provider that automatically manages DNS records in IBM Cloud Internet Services (CIS) from Kubernetes Ingress resources.
ExternalDNS watches Kubernetes resources and reconciles DNS records in your provider. This webhook provider runs as a sidecar in the same pod as ExternalDNS, translating the generic webhook protocol into IBM CIS DNS API calls.
βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Kubernetes Pod β
β β
β ββββββββββββββββββββ HTTP localhost:8888 β
β β ExternalDNS β βββββββββββββββββββββββββββΊ β
β β (controller) β β
β ββββββββββββββββββββ β
β ββββββββββββββββββββββ β
β β IBM CIS Webhook β β
β β (sidecar) β β
β βββββββββββ¬βββββββββββ β
ββββββββββββββββββββββββββββββββββββββββΌβββββββββββββ
β IBM Cloud API
βΌ
IBM Cloud Internet Services
(CIS DNS Zone)
- Sidecar pattern β communicates with ExternalDNS over localhost, no network exposure
- CIS Proxy support β enable/disable the Cloudflare-compatible proxy per record or globally
- Private network β defaults to IBM Cloud private VPC endpoints; no public gateway required
- Pagination β handles large zones transparently (100 records per page)
- Record types β A, AAAA, CNAME, TXT, MX, NS
- TTL control β configurable default; proxied records automatically use TTL=1 (Automatic)
- Kubernetes cluster
- IBM Cloud Internet Services instance with at least one DNS zone
- IBM Cloud IAM API key with Manager role on the CIS instance
- ExternalDNS v0.21+
# List CIS instances and their CRNs
ibmcloud cis instances
# List DNS zones (Domain IDs) for your instance
ibmcloud cis domains --instance <instance-name>Edit deploy/secret.yaml with your values:
apiVersion: v1
kind: Secret
metadata:
name: external-dns-ibmcis
namespace: external-dns
type: Opaque
stringData:
IBM_CLOUD_API_KEY: "<your-iam-api-key>"
IBM_CIS_CRN: "<crn:v1:bluemix:public:internet-svcs:global:...>"
IBM_CIS_ZONE_ID: "<zone-id>"
DOMAIN_FILTER: "example.com"
DEFAULT_TTL: "1"kubectl apply -f deploy/rbac.yaml
kubectl apply -f deploy/secret.yamlapiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
annotations:
# Optional: Tells ExternalDNS target to set in DNS recort. If not specified ingress.status.loadBalancer.hostname is set as target.
external-dns.alpha.kubernetes.io/target: example-app.lb.appdomain.cloud
# Optional: enable CIS proxy (CDN + DDoS protection)
external-dns.alpha.kubernetes.io/webhook-cis-proxied: "true"
spec:
...ExternalDNS will detect the annotation and reconcile the DNS record in IBM CIS automatically.
The recommended way to install ExternalDNS with this webhook is via the official ExternalDNS Helm chart. The chart runs the webhook as a sidecar container in the same pod β no extra Deployment or Service needed.
helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm repo updateapiVersion: v1
kind: Secret
metadata:
name: external-dns-ibmcis
namespace: external-dns
type: Opaque
stringData:
IBM_CLOUD_API_KEY: "<your-iam-api-key>"
IBM_CIS_CRN: "<crn:v1:bluemix:public:internet-svcs:global:...>"
IBM_CIS_ZONE_ID: "<zone-uuid>"kubectl apply -f deploy/rbac.yaml
kubectl apply -f deploy/secret.yamlCopy deploy/values.yaml and edit the required fields:
| Field | What to set |
|---|---|
provider.webhook.image.tag |
Image tag from Docker Hub |
domainFilters |
Your DNS zone(s), e.g. ["example.com"] |
txtOwnerId |
A unique name for this cluster, e.g. "prod-cluster" |
helm install external-dns external-dns/external-dns \
--namespace external-dns \
--create-namespace \
-f deploy/values-ibmcis.yaml \
--set provider.webhook.image.tag=<tag>kubectl -n external-dns get pods
kubectl -n external-dns logs -l app.kubernetes.io/name=external-dns -c external-dns-ibm-cis-webhookTo proxy all A/AAAA/CNAME records by default, change the --proxied-by-default arg in the values file:
provider:
webhook:
args:
- --proxied-by-default=trueIndividual records can still override this with the external-dns.alpha.kubernetes.io/webhook-cis-proxied: "false" annotation.
| Variable | Required | Default | Description |
|---|---|---|---|
IBM_CLOUD_API_KEY |
yes | β | IBM Cloud IAM API key |
IBM_CIS_CRN |
yes | β | Full CRN of the CIS service instance |
IBM_CIS_ZONE_ID |
yes | β | Zone ID (Domain ID) of the CIS DNS zone |
DOMAIN_FILTER |
no | (all zones) | Comma-separated domains this instance manages |
DEFAULT_TTL |
no | 1 |
Default TTL in seconds; 1 = Automatic |
IBM_IAM_ENDPOINT |
no | private VPC endpoint | Override IAM endpoint (for non-VPC deployments) |
IBM_CIS_SERVICE_URL |
no | private VPC endpoint | Override CIS API endpoint |
| Flag | Default | Description |
|---|---|---|
--webhook-address |
:8888 |
Listen address for the webhook API (ExternalDNS connects here) |
--health-address |
:8080 |
Listen address for /healthz liveness and readiness probes |
--proxied-by-default |
false |
Proxy all A/AAAA/CNAME records unless overridden by annotation |
By default the provider targets IBM Cloud's private network endpoints (reachable from VPC without a public gateway):
| Service | Default Endpoint |
|---|---|
| IAM | https://private.iam.cloud.ibm.com |
| CIS API | https://api.private.cis.cloud.ibm.com |
If your cluster does not have VPC private connectivity, set IBM_IAM_ENDPOINT and IBM_CIS_SERVICE_URL to the public equivalents:
IBM_IAM_ENDPOINT=https://iam.cloud.ibm.com
IBM_CIS_SERVICE_URL=https://api.cis.cloud.ibm.comThe proxy annotation mirrors Cloudflare's annotation naming convention in ExternalDNS. Only A, AAAA, and CNAME records can be proxied.
| Annotation | Value | Effect |
|---|---|---|
external-dns.alpha.kubernetes.io/webhook-cis-proxied |
"true" |
Enable CIS proxy for this record |
external-dns.alpha.kubernetes.io/webhook-cis-proxied |
"false" |
Disable proxy (direct DNS) |
| (absent) | β | Falls back to --proxied-by-default flag |
Note: IBM CIS enforces TTL=1 (Automatic) for all proxied records. The
DEFAULT_TTLsetting is ignored for proxied records.
The provider implements the ExternalDNS webhook provider protocol:
| Method | Path | Description |
|---|---|---|
GET |
/ |
Negotiate β returns the configured domain filter |
GET |
/records |
List all DNS records as ExternalDNS Endpoints |
POST |
/records |
Apply create/update/delete changes |
POST |
/adjustendpoints |
Normalize proxy annotation before ExternalDNS diffs |
GET |
/healthz |
Liveness and readiness probe (health server only) |
- ExternalDNS detects annotation changes on Ingress or Service resources
- Calls
POST /adjustendpointsβ webhook normalises thewebhook/cis-proxiedproperty - ExternalDNS diffs desired state against current state from
GET /records - Calls
POST /recordswith a change plan:{create, updateOld, updateNew, delete} - Webhook maps each change to IBM CIS API operations (create/delete record pairs for updates)
Images are automatically built and pushed to Docker Hub on every merge to main (or any commit whose message contains BUILD_CONTAINER_IMAGE):
docker pull ridecellhub/external-dns-ibm-cis-webhook:<timestamp>-main-<sha>Tags follow the pattern <unix-timestamp>-<branch>-<short-sha>, produced by the CI workflow. The image is based on scratch with only the TLS CA bundle and the static binary β under 20 MB.
Requirements: Go 1.23+, Docker (for image builds)
# Clone
git clone https://github.com/ridecell/external-dns-ibmcis-webhook.git
cd external-dns-ibmcis-webhook
# Build binary
make build
# Run tests
make test
# Build Docker image
make image TAG=v1.0.0
# Build and push to registry
make push TAG=v1.0.0Copyright 2024 Ridecell
Licensed under the Apache License, Version 2.0 β see LICENSE.