API Overview

Architecture

The PowerDNS-Operator extends Kubernetes with Custom Resources, which define Zones and Records. The controller fetches ClusterZones, Zones, ClusterRRsets and RRsets from the cluster and creates PowerDNS elements (Zones and Records). Each modification on these Custom Resources will be applied on PowerDNS instance accordingly.

Resource Model

To understand the mechanics of the operator let's start with an example.

1. The ClusterZone resource, created by Platform Team, references a root Zone (example.org).

   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: ClusterZone
   metadata:
     name: example.org
   spec:
     nameservers:
       - ns1.example.org
       - ns2.example.org
     kind: Native
   

2. Some ClusterRRsets resources, created by Platofrm Team, can reference records related to the ClusterZone (such nameservers IPs, mail servers, SOA, ...).

   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: ClusterRRset
   metadata:
     name: soa.example.org
   spec:
     name: example.org.
     records:
     - ns1.example.org. admin.example.org. 1 10800 3600 604800 3600
     ttl: 3600
     type: SOA
     zoneRef:
       name: example.org
       kind: ClusterZone
   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: ClusterRRset
   metadata:
     name: mx.example.org
   spec:
     type: MX
     name: "example.org."
     ttl: 300
     records:
       - "10 mx1.example.org."
       - "20 mx2.example.org."
     zoneRef:
       name: example.org
       kind: ClusterZone
   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: ClusterRRset
   metadata:
     name: ns1.example.org
   spec:
     type: A
     name: ns1
     ttl: 300
     records:
       - "10.25.32.1"
     zoneRef:
       name: example.org
       kind: ClusterZone
   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: ClusterRRset
   metadata:
     name: ns2.example.org
   spec:
     type: A
     name: ns2
     ttl: 300
     records:
       - "10.25.32.2"
     zoneRef:
       name: example.org
       kind: ClusterZone
   

3. The Zone, in the 'myapp1' namespace, can be created by Application Team or Platform Team depending on the Authorization model choosen, reference a Sub-Zone for Application purposes.

   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: Zone
   metadata:
     name: myapp1.example.org
     namespace: myapp1
   spec:
     nameservers:
       - ns1.example.org
       - ns2.example.org
     kind: Native
   

4. The RRsets in the 'myapp1' namespace, created by Application Team, reference services provided by the Application (frontend, backend, database, ...).

   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: RRset
   metadata:
     name: soa.myapp1.example.org
     namespace: myapp1
   spec:
     name: myapp1.example.org.
     records:
     - ns1.example.org. admin.example.org. 1 10800 3600 604800 3600
     ttl: 3600
     type: SOA
     zoneRef:
       name: myapp1.example.org
       kind: Zone
   ---
   apiVersion: dns.cav.enablers.ob/v1alpha2
   kind: RRset
   metadata:
     name: front.myapp1.example.org
     namespace: myapp1
   spec:
     type: A
     name: front
     ttl: 300
     records:
       - "1.2.3.4"
     zoneRef:
       name: myapp1.example.org
       kind: Zone
   

Such a structure allows a separation of elements, the application team can only administer the RRsets linked to its services

Each RRset refers to the ClusterZone/Zone it depends on.

Behavior

The PowerDNS-Operator (PDNS-OP for brevity) reconciles ClusterZones or Zones in the following manner:

1. PDNS-OP verifies that no other Zone or ClusterZone already exists with the same FQDN (Fully Qualified Domain Name), if exists, Zone/ClusterZone status is defined as 'Failed'
2. PDNS-OP requests PowerDNS API to create/modify the corresponding resource
3. PDNS-OP requests PowerDNS API to create/modify related 'Nameservers' entries
4. PDNS-OP updates resource Status (including Serial) and its metrics

The PowerDNS-Operator reconciles ClusterRRsets or RRsets in the following manner:

1. PDNS-OP verifies that the corresponding ClusterZone/Zone already exists, if not, It schedule a new reconciliation later on
2. PDNS-OP verifies that the corresponding ClusterZone/Zone is not in 'Failed' status, in that case , RRset or ClusterRRset status is defined as 'Failed'
3. PDNS-OP requests PowerDNS API to create/modify the corresponding resource
4. PDNS-OP updates resource Status and its metrics
5. PDNS-OP schedule a reconciliation to update ClusterZone/Zone Status (including Serial)

Roles and responsibilities

The PowerDNS-Operator is designed to target the following persona:

• Cluster Operator: The cluster operator is responsible for configuring PowerDNS instance, ,
• Platform Team: The Platform team is responsible for defining the architecture ClusterZone, Zone, ClusterRRset and RRset, setting the permissions for application team (e.g. permissions to create Zones in their namespaces),
• Application Team: The Application developer is responsible for defining RRset (eventually Zone) related to their services.

Each persona will roughly map to a Kubernetes RBAC role. Depending on your environment these roles can map to a single user. Note: The PowerDNS Operator does not manage the PowerDNS instance lifecycle.