Skip to content

About

ExternalDNS webhook for managing DNS Records in IBM Cloud internet service (CIS)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

ExternalDNS Webhook Provider for IBM Cloud Internet Services

A ExternalDNS webhook provider that automatically manages DNS records in IBM Cloud Internet Services (CIS) from Kubernetes Ingress resources.

Overview

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)

Features

  • 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)

Prerequisites

  • 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+

Quick Start

1. Find your CIS credentials

# List CIS instances and their CRNs
ibmcloud cis instances

# List DNS zones (Domain IDs) for your instance
ibmcloud cis domains --instance <instance-name>

2. Create the secret

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"

3. Deploy

kubectl apply -f deploy/rbac.yaml
kubectl apply -f deploy/secret.yaml

4. Annotate your Ingress

apiVersion: 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.

Helm Installation

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.

1. Add the Helm repo

helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm repo update

2. Update the credentials Secret

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-uuid>"
kubectl apply -f deploy/rbac.yaml
kubectl apply -f deploy/secret.yaml

3. Install with the provided values file

Copy 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>

4. Verify

kubectl -n external-dns get pods
kubectl -n external-dns logs -l app.kubernetes.io/name=external-dns -c external-dns-ibm-cis-webhook

Enable CIS proxy by default

To proxy all A/AAAA/CNAME records by default, change the --proxied-by-default arg in the values file:

provider:
  webhook:
    args:
      - --proxied-by-default=true

Individual records can still override this with the external-dns.alpha.kubernetes.io/webhook-cis-proxied: "false" annotation.

Configuration

Environment Variables

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

Command-Line Flags

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

Private vs Public Endpoints

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.com

CIS Proxy Annotation

The 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_TTL setting is ignored for proxied records.

Architecture

Webhook HTTP API

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)

Record Reconciliation Flow

  1. ExternalDNS detects annotation changes on Ingress or Service resources
  2. Calls POST /adjustendpoints β†’ webhook normalises the webhook/cis-proxied property
  3. ExternalDNS diffs desired state against current state from GET /records
  4. Calls POST /records with a change plan: {create, updateOld, updateNew, delete}
  5. Webhook maps each change to IBM CIS API operations (create/delete record pairs for updates)

Container Image

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.

Building from Source

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.0

License

Copyright 2024 Ridecell

Licensed under the Apache License, Version 2.0 β€” see LICENSE.

About

ExternalDNS webhook for managing DNS Records in IBM Cloud internet service (CIS)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages