CASMINST-2683 - PowerDNS documentation updates

Author: spillerc-hpe

img/operations/dns.svg

@@ -61,6 +61,9 @@ For more description of these settings and the default values, see [Default IP A
 | --application-node-config-yaml application_node_config.yaml | Name of `application_node_config.yaml` |
 | --cabinets-yaml cabinets.yaml | Name of `cabinets.yaml` |
 | --bgp-peers aggregation | Override the default BGP peers, using aggregation switches instead of spines |
+| --primary-server-name primary | Desired name for the primary DNS server |
+| --secondary-servers "" | Comma seperated list of FQDN/IP for all DNS servers to be notified on DNS zone update |
+| --notify-zones "" | A comma separated list of DNS zones to transfer |
 
    * This is a long list of options. It can be helpful to create a Bash script file to call the `csi` command with all of these options, and then edit that file to adjust the values for the particular system being installed.
    * The `bootstrap-ncn-bmc-user` and `bootstrap-ncn-bmc-pass` must match what is used for the BMC account and its password for the management nodes.
@@ -75,6 +78,7 @@ For more description of these settings and the default values, see [Default IP A
    * Set `ntp-pool` to a reachable NTP server.
    * The `application_node_config.yaml` file is required. It is used to describe the mapping between prefixes in `hmn_connections.csv` and HSM subroles. This file also defines aliases application nodes. For details, see [Create Application Node YAML](create_application_node_config_yaml.md).
    * For systems that use non-sequential cabinet id numbers, use `cabinets-yaml` to include the `cabinets.yaml` file. This file can include information about the starting ID for each cabinet type and number of cabinets which have separate command line options, but is a way to specify explicitly the id of every cabinet in the system. See [Create Cabinets YAML](create_cabinets_yaml.md).
+  * The PowerDNS zone transfer arguments `primary-server-name`, `secondary-servers`, and `notify-zones` are optional unless zone transfer is being configured. For more information see the [PowerDNS Configuration Guide](../operations/network/dns/PowerDNS_Configuration.md#zone-transfer)
 
 <a name="configuration_payload_files"></a>
 ### Configuration Payload Files

install/prepare_configuration_payload.md

@@ -404,39 +404,92 @@ with system-specific customizations.
         ldapSearchBase: dc=dcldap,dc=dit
         ```
 
-1.  If you need to resolve outside hostnames, you will need to configure
-    forwarding in the cray-dns-unbound service. For example, if you are using a
-    hostname and not an IP address for the upstream LDAP server in step 4 above, you
-    will need to be able to resolve that hostname.
+1.  Configure the Unbound DNS resolver.
 
-    Default configuration:
+  If a valid DNS server was defined using the CSI `--site-dns` option then no further action is required and the default configuration will suffice.
 
-    ```
-    cray-dns-unbound:
+  Default configuration:
+
+  ```
+  cray-dns-unbound:
       domain_name: '{{ network.dns.external }}'
       forwardZones:
         - name: "."
           forwardIps:
             - "{{ network.netstaticips.system_to_site_lookups }}"
-    ```
-    Remove the `forwardZones` configuration for the `cray-dns-unbound` service:
+  ```
+    
+   If there is no requirement to resolve external hostnames or no upstream DNS server
+    then remove the DNS forwarding configuration from the `cray-dns-unbound` service. 
 
-    ```bash
-    linux# yq delete -i /mnt/pitdata/prep/site-init/customizations.yaml spec.kubernetes.services.cray-dns-unbound.forwardZones
-    ```
+ 
+   1. Remove the `forwardZones` configuration for the `cray-dns-unbound` service:
 
-    Review the `cray-dns-unbound` values.
+      ```bash
+      linux# yq delete -i /mnt/pitdata/prep/site-init/customizations.yaml spec.kubernetes.services.cray-dns-unbound.forwardZones
+      ```
 
-    ```bash
-    linux# yq read /mnt/pitdata/prep/site-init/customizations.yaml spec.kubernetes.services.cray-dns-unbound
-    ```
+    1. Review the `cray-dns-unbound` values.
+
+      ```bash
+      linux# yq read /mnt/pitdata/prep/site-init/customizations.yaml spec.kubernetes.services.cray-dns-unbound
+      ```
+
+      Expected output is:
+
+      ```
+	  domain_name: '{{ network.dns.external }}'
+      ```
+      > **`IMPORTANT`** **Do not** remove the `domain_name` entry, it is required for Unbound to forward requests to PowerDNS correctly.
+
+1. Configure PowerDNS zone transfer and DNSSEC (optional)
+
+   * If zone transfer is to be configured review `customizations.yaml` and ensure the `primary_server`, `secondary_servers`, and `notify_zones` values are set correctly.
+
+   * If DNSSEC is to be used then add the desired keys into the `dnssec` SealedSecret.
+
+   Please see the [PowerDNS Configuration Guide](../operations/network/dns/PowerDNS_Configuration.md) for more information.
+
+1.  Review `customizations.yaml` in the `site-init` directory and replace remaining `~FIXME~` values with
+    appropriate settings.
+
+    1. Create backup copy of `customizations.yaml`:
+
+        ```bash
+        linux# cp -v /mnt/pitdata/prep/site-init/customizations.yaml /mnt/pitdata/prep/site-init/customizations.yaml-prefixme
+        ```
+
+    1. Edit `customizations.yaml`
+        For the following `~FIXME~` values, use the example provided and just remove the `~FIXME~ e.g.`
+
+        ```
+           sma-rsyslog-aggregator:
+             cray-service:
+               service:
+                 loadBalancerIP: ~FIXME~ e.g. 10.92.100.72
+             rsyslogAggregatorHmn:
+               service:
+                 loadBalancerIP: ~FIXME~ e.g. 10.94.100.2
+
+           sma-rsyslog-aggregator-udp:
+             cray-service:
+               service:
+                 loadBalancerIP: ~FIXME~ e.g. 10.92.100.75
+             rsyslogAggregatorUdpHmn:
+               service:
+                 loadBalancerIP: ~FIXME~ e.g. 10.94.100.3
+        ```
+
+    1. Review your changes:
+        ```bash
+        linux# diff /mnt/pitdata/prep/site-init/customizations.yaml /mnt/pitdata/prep/site-init/customizations.yaml-prefixme
+        ```
+
+    1. Verify that no `FIXME` strings remain in the file:
+        ```bash
+        linux# grep FIXME /mnt/pitdata/prep/site-init/customizations.yaml
+        ```
 
-    Expected output is:
-    
-    ```
-	domain_name: '{{ network.dns.external }}'
-    ```
-Do not remove the `domain_name` entry.
 
 <a name="generate-sealed-secrets"></a>
 ### 4. Generate Sealed Secrets

install/prepare_site_init.md

@@ -29,22 +29,28 @@ The most noteworthy changes since the previous release are described here.
          * Rome-Based HPE DL 385(v1) Gen10
    * Node consoles are now managed by cray-console-node which is based on conman.
    * HSM now has a v2 REST API
+   * PowerDNS authoriative DNS server
+      * Introduces the cray-dns-powerdns, cray-dns-powerdns-postgres, and cray-powerdns-manager pods
+      * Supports zone transfer to external DNS servers via AXFR query and DNSSEC
+      * Please refer to the [DNS overview](../operations/network/dns/DNS.md) and [PowerDNS Configuration Guide](../operations/network/dns/PowerDNS_Configuration.md) for further information.
 
 <a name="deprecating_features"></a>
 ### Deprecating Features
 
    * HSM v1 REST API has been deprecated as of CSM version 0.9.3. The v1 HSM APIs will be removed in the CSM version 1.3 release.
    * Many CAPMC v1 REST API and CLI features are being deprecated as part of CSM version 1.0; Full removal of the deprecated CAPMC features will happen in CSM version 1.3. Further development of CAPMC service or CLI has stopped. CAPMC has entered end-of-life but will still be generally available. CAPMC is going to be replaced with the Power Control Service (PCS) in a future release. The current API/CLI portfolio for CAPMC are being pruned to better align with the future direction of PCS. More information about PCS and the CAPMC transition will be released as part of subsequent CSM releases.
      * For more information on what features have been deprecated please view the CAPMC swagger doc or read the [CAPMC deprecation notice](../introduction/CAPMC_deprecation.md)
-
    * The Boot Orchestration Service (BOS) API is changing in the upcoming CSM-1.2.0 release:
         * The `--template-body` option for the Cray CLI `bos` command will be deprecated.
         * Performing a GET on the session status for a boot set (i.e. `/v1/session/{session_id}/status/{boot_set_name}`) currently returns a status code of 201, but instead it should return a status code of 200. This will be corrected to return 200.
+   * PowerDNS will replace Unbound as the authoritative DNS source in CSM version 1.2.
+        * The cray-dns-unbound-manager CronJob will be deprecated when all DNS records are migrated to PowerDNS.
 
 <a name="deprecated_features"></a>
 ### Deprecated Features
 
    * cray-conman pod. This has been replaced by cray-console-node.
+   * The cray-externaldns-coredns, cray-externaldns-etcd, and cray-externaldns-wait-for-etcd pods have been removed. PowerDNS is now the provider of the external DNS service.
 
 <a name="other_changes"></a>
 ### Other Changes

introduction/differences.md

@@ -1,29 +1,63 @@
-## Domain Name Service (DNS)
+# Domain Name Service (DNS) Overview
 
-The central DNS infrastructure provides the structural networking hierarchy and datastore for the system. All DNS requests are managed by resolvers, not by the central DNS infrastructure. Resolvers provide the following within DNS:
+## DNS Architecture
 
--   Security by scoping requests from clients.
+This diagram shows how the various components of the DNS infrastructure interact.
 
-    For example, disallowing cross-network DNS lookups.
+![DNS Architecture](../../../img/operations/dns.svg)
 
--   Load reduction on the central DNS infrastructure:
-    -   Caching requests and handling scoping requests.
-    -   Providing request recursion where necessary.
+## DNS Components
 
-The Data Helper Tools are used to update records, and takes in changes from the following sources:
+The DNS infrastructure is comprised of a number of components.
 
--   Hardware State Manager \(HSM\): Uses the System Layout Service \(SLS\) and the State Manager Daemon \(SMD\) to create a system-of-record for all machine hardware resources. The tooling creates and updates DNS records upon system install or during hardware changes.
--   Kubernetes: DNS records are created and updated dynamically.
+### Unbound (cray-dns-unbound)
 
-The following figure shows a high-level overview of the various components used in the DNS infrastructure.
+Unbound is a caching DNS resolver which is also used as the primary DNS server.
 
-![DNS Architecture](../../../img/operations/DNS_architecture.PNG)
+The DNS records served by Unbound include system component xnames, node hostnames, and service names and these records are read from the cray-dns-unbound ConfigMap which is populated by cray-dns-unbound-manager.
 
-### Table of Contents
+The DNS server functionality will be migrated to PowerDNS in a future release leaving Unbound acting purely as a caching DNS resolver.
 
-* [Manage the DNS Unbound Resolver](Manage_the_DNS_Unbound_Resolver.md)
-* [Enable ncsd on UANs](Enable_ncsd_on_UANs.md)
-* [Troubleshoot Common DNS Issues](Troubleshoot_Common_DNS_Issues.md)
-* [Troubleshoot DNS Configuration Issues](Troubleshoot_DNS_Configuration_Issues.md)
+Unbound also forwards queries to PowerDNS or the site DNS server if the query cannot be answered by local data.
 
+### Unbound Manager (cray-dns-unbound-manager)
 
+The cray-dns-unbound-manager cron job runs every three minutes and queries the System Layout Service, the Hardware State Manager, and the Kea DHCP server for new or changed hardware components and creates DNS records for these components in the cray-dns-unbound ConfigMap.
+
+This job also initiates a rolling restart of Unbound if the cray-dns-unbound ConfigMap was modified.
+
+### Kubernetes DNS (coredns)
+
+Kubernetes creates DNS records for services and pods. A CoreDNS server running in the kube-system namespace is used for this purpose.
+
+The CoreDNS service is also configured to forward DNS requests to Unbound in order to allow pods to resolve system hardware components and other services. This configuration is performed by the cray-dns-unbound-coredns job which is invoked whenever the cray-dns-unbound Helm chart is deployed or upgraded.
+
+See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) for more information.
+
+### ExternalDNS (cray-externaldns-external-dns)
+
+ExternalDNS creates DNS records for services that are intended to be accessible via the Customer Access Network (CAN). For example grafana.wasp.dev.cray.com.
+
+Kubernetes Services annotated with `external-dns.alpha.kubernetes.io/hostname` have DNS records created.
+
+Starting with CSM version 1.1 these DNS records are created in the PowerDNS server. Earlier versions of CSM used a dedicated CoreDNS server for ExternalDNS.
+
+> Only DNS A records are created as ExternalDNS currently does not support the creation of the PTR records required for reverse lookup.
+
+### PowerDNS (cray-dns-powerdns)
+
+PowerDNS is an authoritative DNS server which over the next few CSM releases will replace Unbound sa the primary DNS server within a CSM system.
+
+PowerDNS is able to respond to queries for services accessible via the CAN. records are externally accessible via the LoadBalancer IP address specified for the CSI `--can-external-dns` option.
+
+As with earlier CSM releases it is possible to delegate to PowerDNS to resolve CAN services and it is also possible to configure zone transfer to sync the DNS records from PowerDNS to Site DNS.
+
+### PowerDNS Manager (cray-powerdns-manager)
+
+The PowerDNS Manager serves a similar purpose to the Unbound Manager. It runs in the background and periodically queries the System Layout Service, the Hardware State Manager, and the Kea DHCP server for new or changed hardware components and creates DNS records for these components in PowerDNS.
+
+The PowerDNS Manager also configures the PowerDNS server for zone transfer and DNSSEC if required.
+
+### Site DNS
+
+This term is used to refer the external DNS server specified the CSI `--site-dns` option.