{"id":38111092,"url":"https://github.com/datum-cloud/dns-operator","last_synced_at":"2026-01-16T21:59:19.969Z","repository":{"id":321667111,"uuid":"1083446941","full_name":"datum-cloud/dns-operator","owner":"datum-cloud","description":"Datum DNS Operator","archived":false,"fork":false,"pushed_at":"2026-01-10T06:36:37.000Z","size":352,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T01:54:12.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datum-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T03:09:52.000Z","updated_at":"2025-12-31T14:49:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"99d627d4-764a-479a-923e-c934bd73c49c","html_url":"https://github.com/datum-cloud/dns-operator","commit_stats":null,"previous_names":["datum-cloud/dns-operator"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/datum-cloud/dns-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdns-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdns-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdns-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdns-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datum-cloud","download_url":"https://codeload.github.com/datum-cloud/dns-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdns-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28484545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T21:59:19.167Z","updated_at":"2026-01-16T21:59:19.964Z","avatar_url":"https://github.com/datum-cloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## datum-dns-operator\n\nKubernetes operator for managing DNS zones and records, with a pluggable backend architecture. This repository provides:\n- Custom resources to model zones, recordsets, and zone classes\n- Controllers for two runtime roles:\n  - \"downstream\" agent that programs a DNS backend (PowerDNS supported)\n  - \"replicator\" that mirrors resources from an upstream cluster to a downstream cluster and synthesizes status\n- Kustomize overlays to deploy either role\n\n### CRDs\n- **`DNSZoneClass`** (cluster-scoped)\n  - `spec.controllerName`: selects backend controller (e.g., \"powerdns\")\n  - `spec.nameServerPolicy`: currently supports `Static` with `servers: []`\n  - `spec.defaults.defaultTTL`: optional default TTL for zones\n\n- **`DNSZone`** (namespaced)\n  - `spec.domainName`: required zone FQDN (e.g., `example.com`)\n  - `spec.dnsZoneClassName`: optional reference to a `DNSZoneClass`\n  - `status.nameservers`: authoritative nameservers (derived from class policy)\n  - `status.conditions`: `Accepted`, `Programmed`\n\n- **`DNSRecordSet`** (namespaced)\n  - `spec.dnsZoneRef`: `LocalObjectReference` to a `DNSZone` in the same namespace\n  - `spec.recordType`: one of `A, AAAA, CNAME, TXT, MX, SRV, CAA, NS, SOA, PTR, TLSA, HTTPS, SVCB`\n  - `spec.records[]`: owners with typed fields per record type (or `raw` strings). TTL per-owner optional.\n  - `status.conditions`: `Accepted`, `Programmed`\n\n### Controllers and Roles\n\n- **Downstream role** (`--role=downstream`)\n  - `DNSZoneReconciler`: when `DNSZone.spec.dnsZoneClassName` references a class with `controllerName: powerdns`, ensures the zone exists in PowerDNS and honors static nameserver policy.\n  - `DNSRecordSetReconciler`: for PowerDNS-backed zones, applies recordsets to PDNS using an authoritative mode that REPLACEs desired owners and DELETEs extraneous owners of the same type. Requeues while the zone is not ready.\n\n- **Replicator role** (`--role=replicator`)\n  - Multicluster manager discovers one or many upstream clusters (single-cluster or Milo discovery) and mirrors `DNSZone`/`DNSRecordSet` into a configured downstream cluster using a mapped-namespace strategy.\n  - `DNSZoneReplicator`:\n    - Mirrors upstream `spec` into a downstream shadow object\n    - Ensures an operator-managed upstream `DNSRecordSet` named `soa` exists (typed SOA targeting `@`) for PowerDNS-backed zones\n    - Updates upstream `status`: sets `Accepted=True` and currently treats `Programmed=True` optimistically; fills `status.nameservers` from `DNSZoneClass` when `Static` policy is set\n  - `DNSRecordSetReplicator`:\n    - Mirrors upstream `spec` into a downstream shadow object\n    - Updates upstream `status`: `Accepted` reflects `DNSZone` presence; `Programmed=True` once downstream shadow ensured\n\n### Backends\n- **PowerDNS (Authoritative)**\n  - Enabled when `DNSZoneClass.spec.controllerName: powerdns`\n  - The downstream agent uses environment variables to connect:\n    - `PDNS_API_URL` (default `http://127.0.0.1:8081`)\n    - `PDNS_API_KEY` or `PDNS_API_KEY_FILE`\n  - Recordset translation supports typed fields for all declared RR types and sensible normalization of names and quoting for TXT/targets.\n\n### Deployment Overlays\n\n- `config/agent/`\n  - Namespace: `dns-agent-system`\n  - Runs the operator with `--role=downstream`\n  - Merges a `pdns` sidecar container into the controller Deployment to run PowerDNS alongside the manager\n  - Mounts a shared `emptyDir` to exchange an auto-generated API key, and sets `PDNS_API_KEY_FILE` in the manager\n  - Provides a `Service` exposing PDNS ports 53/udp, 53/tcp, and 8081/tcp\n  - ConfigMap `server-config` wired to `--server-config`\n\n- `config/overlays/replicator/`\n  - Namespace: `dns-replicator-system`\n  - Runs the operator with `--role=replicator`\n  - Requires a Secret `downstream-kubeconfig` containing key `kubeconfig` to target the downstream cluster\n  - ConfigMap `server-config` sets discovery mode (defaults to `single`) and points `downstreamResourceManagement.kubeconfigPath` to `/downstream/kubeconfig`\n\n### Quickstart: Agent with embedded PowerDNS\n1. Install CRDs and default manifests:\n   - `kubectl apply -k config/agent`\n2. Create a `DNSZoneClass` for PowerDNS with static nameservers, for example:\n```yaml\napiVersion: dns.networking.miloapis.com/v1alpha1\nkind: DNSZoneClass\nmetadata:\n  name: powerdns\nspec:\n  controllerName: powerdns\n  nameServerPolicy:\n    mode: Static\n    static:\n      servers: [\"ns1.example.net.\", \"ns2.example.net.\"]\n```\n3. Create a `DNSZone` and a `DNSRecordSet`:\n```yaml\napiVersion: dns.networking.miloapis.com/v1alpha1\nkind: DNSZone\nmetadata:\n  name: example-com\n  namespace: default\nspec:\n  domainName: example.com\n  dnsZoneClassName: powerdns\n---\napiVersion: dns.networking.miloapis.com/v1alpha1\nkind: DNSRecordSet\nmetadata:\n  name: www-a\n  namespace: default\nspec:\n  dnsZoneRef:\n    name: example-com\n  recordType: A\n  records:\n    - name: www\n      a:\n        content: [\"192.0.2.10\", \"192.0.2.11\"]\n      ttl: 300\n```\n\n### Quickstart: Replicator (upstream → downstream)\n1. Create Secret on the replicator namespace containing the downstream kubeconfig (`data.kubeconfig`):\n```bash\nkubectl -n dns-replicator-system create secret generic downstream-kubeconfig \\\n  --from-file=kubeconfig=/path/to/downstream/kubeconfig\n```\n2. Deploy replicator overlay:\n```bash\nkubectl apply -k config/overlays/replicator\n```\n3. Create `DNSZoneClass` (cluster-scoped), `DNSZone` and `DNSRecordSet` on the upstream cluster. The replicator will mirror them into the downstream cluster and update upstream `status` conditions.\n\n### Conditions\n- `Accepted`: resource is valid and has required dependencies (e.g., `DNSRecordSet` sees its `DNSZone`)\n- `Programmed`: desired state is realized (shadow exists downstream; for downstream agent, recordsets applied to backend)\n\n### Configuration CRD (server config)\n- `kind: DNSOperator` (internal config consumed by the binary via `--server-config`)\n  - `discovery.mode`: `single` or `milo`\n  - `downstreamResourceManagement.kubeconfigPath`: path inside the Pod to the downstream kubeconfig\n  - `controllers.dnsRecordSetPowerDNS.maxConcurrentReconciles`: concurrent reconciles for the PowerDNS recordset controller (default: 4)\n  - `controllers.dnsRecordSetPowerDNS.rateLimiterBaseDelay`: exponential backoff base delay (default: `1s`)\n  - `controllers.dnsRecordSetPowerDNS.rateLimiterMaxDelay`: exponential backoff max delay (default: `30s`)\n\n### Development\n- Build: `make docker-build` (see `Makefile`)\n- Generate code/manifests: `make generate` and `make manifests`\n- Local e2e: see `test/e2e/chainsaw-test.yaml` and sample manifests under `config/samples/`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatum-cloud%2Fdns-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatum-cloud%2Fdns-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatum-cloud%2Fdns-operator/lists"}