Authoritative Server

The PowerDNS Authoritative Server (Auth) is a versatile authoritative server for hosting domain names.

Backends

When deployed with Cloud Control, the following backends are supported for Auth:

Lightning Stream with S3
Postgres
MySQL
GeoIP

Note: We recommend Lightning Stream with S3 for all Cloud Control deployments which require persistent storage of authoritative zone data.

Lightning Stream with S3

This backend allows you to utilise an S3 bucket to store & replicate data. If you are able to replicate your S3 bucket across multiple datacenters you can easily keep your dataset replicated across a complicated topology without having to use zone transfers.

Overview

Components

When Lightning Stream is used, each Auth instance has a local, memory-backed LMDB database into which it writes all updates and from which it reads all data. An additional container running the Lightning Stream software runs as a sidecar and is responsible for the synchronization between the LMDB and the S3 bucket.

Image title — Single Auth Pod with Lightning Stream

Migrator

An additional Migrator pod will be deployed to monitor the different schema versions (based on Auth version) for which snapshots are available in the S3 bucket. When you initially deploy an environment with this backend the migrator will not have anything to do. However, once you upgrade to a newer version of Cloud Control, there might be changes to the schema used by Auth. The Migrator will ensure a seamless transition to the new schema without having to bring the environment offline for schema upgrading and/or manual maintenance.

Synchronization "Mode"

You can configure a set of Auth instances to be in these modes:

"sync": Bidirectional synchronization between each Auth instance and the S3 bucket ("Primary")
"receive": Each Auth instance pulls updates from the S3 bucket ("Secondary")

The default mode for Auth instances with this backend is: "sync"

Deployment topologies

Single datacenter

Below diagram shows an Auth deployment with 2 replicas, each having its own local LMDB which is synchronised with the other instance via Lightning Stream and the S3 bucket.

Multiple primary datacenters

Below diagram shows 2 Auth deployments in different datacenters. With bidirectional replication enabled between the S3 buckets you can create an active-active replication topology. Any change to the dataset of any of these Auth instances is now replicated to all other Auth instances. If your S3 replication mechanism allows for it, you can expand this topology beyond 2 datacenters.

Primary & secondary datacenters

Below diagram shows 2 Auth deployments in different datacenters, but the deployment in datacenter #2 has been configured to be in "receive" mode. This creates a primary -> secondary replication setup.

Postgres

If you have a Postgres (or compatible) database available, you can configure Auth to store its data in a Postgres database. Example with 2 Auth instances connected to the same Postgres database:

Or when you have a replicated Postgres database which you want to use from multiple Userplane deployments:

MySQL

If you have a MySQL (or compatible) database available, you can configure Auth to store its data in a MySQL database. Example with 2 Auth instances connected to the same MySQL database:

Or when you have a replicated MySQL database which you want to use from multiple Userplane deployments:

GeoIP

The GeoIP backend allows zones to be managed via a YAML format included in the backend configuration and the inclusion of a GeoIP database. The records managed via this backend can make use of the GeoIP database to respond to DNS queries with an answer based on the request's origin. When deployed, it looks as follows:

Configuration Reference

Instance Sets

Sets of instances of Auth can be defined under the root node auths. Each instance set should be a key-value pair, with:

key: Name of the instance set
value: Dictionary holding the configuration of the instance set

auths:
  myauth:
    < Auth configuration >

Parameters which can be used to configure Auth instances for a specific instance set are shown in the below table.

Parameter	Type	Default	Description
`affinity`	`k8s:`Affinity		Pod affinity (Kubernetes docs: Affinity and anti-affinity). If unset, a default anti-affinity is applied using `antiAffinityPreset` to spread pods across nodes
`agentLogLevel`	`string`	`"info"`	Verbosity of logging for the agent container. Available options: `"debug"` `"info"` `"warn"` `"error"`
`agentLogFormat`	`string`	`"text"`	Format of logging for the agent container. Available options: `"text"` `"json"`
`agentResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'agent' container if `resourceDefaults` is `true`
`antiAffinityPreset`	`string`	`"preferred"`	Pod anti affinity preset. Available options: `"preferred"` `"required"`
`api`	Auth API		Auth API service and ingress configuration
`apiKey`	`string`		API key used to access the /api endpoint, used to configure a static key (default: generated and stored in a secret)
`apiKeySecret`	`string`		Name of the secret from which to take the API key, used when there is a pre-provisioned secret holding the api key
`apiKeySecretItem`	`string`		Name of the data item within `apiKeySecret` which holds the API key, used when there is a pre-provisioned secret holding the api key (default: `api_key`)
`backends`	List of Backend		Backend configuration
`config`	`dictionary`	`{}`	Set of `key:value` pairs to configure Auth. Parameters can be found here: Auth documentation Parameters reserved by Cloud Control: `"webserver"` `"local"` `"disable-syslog"` `"daemon"` `"chroot"` `"socket"` `"config"` `"primary"` `"secondary"` `"autosecondary"`
`containerSecurityContext`	`k8s:`SecurityContext	`allowPrivilegeEscalation: false readOnlyRootFilesystem: true seccompProfile: type: RuntimeDefault capabilities: drop: - "ALL"`	SecurityContext applied to each container
`dnsdist`	dnsdistConfig		Settings to be applied to each Auth instance when added to dnsdist as a server
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`hpa`	HPA		Horizontal Pod Autoscaling settings
`initResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'auth-init' container if `resourceDefaults` is `true`
`ixfrdist`	IXFRDist		IXFRDist configuration
`ixfrdistResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'ixfrdist' container if `resourceDefaults` is `true`
`lightningStreamResources`	`k8s:`Resources	`limits: cpu: 1 memory: 2Gi`	Resources allocated to the 'ls' container if `resourceDefaults` is `true`
`lsMigratorInitResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'migrator-init' container if `resourceDefaults` is `true`
`lsMigratorResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'migrator' container if `resourceDefaults` is `true`
`nodeSelector`	`k8s:`NodeSelector	`{}`	Kubernetes pod nodeSelector
`podAnnotations`	`k8s:`Annotations	`{}`	Annotations to be added to each pod
`podDisruptionBudget`	`k8s:`PodDisruptionBudgetSpec	`{}`	Spec of PodDisruptionBudget to be applied to deployment
`podLabels`	`k8s:`Labels	`{}`	Labels to be added to each pod
`podSecurityContext`	`k8s:`PodSecurityContext	`fsGroup: 953 runAsUser: 953 runAsGroup: 953 runAsNonRoot: true`	SecurityContext applied to each pod
`replicas`	`integer`	`2`	Default number of replicas in a Deployment
`resources`	`k8s:`Resources	`limits: cpu: 2 memory: 2Gi`	Resources allocated to the 'auth' container
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`tolerations`	List of `k8s:`Tolerations	`[]`	Kubernetes pod Tolerations

dnsdist Configuration

Using these parameters you can configure additional behaviour when instances of this instance set are added to dnsdist for loadbalancing:

Parameter	Type	Default	Description
`checkClass`	`integer`	`1`	Number to use as QCLASS in the health-check query. Defaults to DNSClass.IN (`1`)
`checkInterval`	`integer`		The time in seconds between health checks
`checkName`	`string`	`"a.root-servers.net"`	String to use as QNAME in the health-check query
`checkTimeout`	`integer`	`1000`	The timeout (in milliseconds) of a health-check query
`checkType`	`string`	`"A"`	String to use as QTYPE in the health-check query
`disableZeroScope`	`boolean`	`false`	If true, disable the EDNS Client Subnet `zero scope` feature, which does a cache lookup for an answer valid for all subnets (ECS scope of 0) before adding ECS information to the query and doing the regular lookup. This requires the `parseECS` option of the corresponding cache to be set to true
`healthCheckMode`	`string`	`"auto"`	Type of health-check to perform, default is `"auto"` which is configured using the checkName, checkType, etc parameters. Alternatives are `"up"` (no healthcheck - always available for traffic) and `"down"` (no healthcheck - never available for traffic)
`maxCheckFailures`	`integer`	`1`	Allow this amount of check failures before declaring the backend down
`mustResolve`	`boolean`	`false`	If true, the health check must return a RCODE different from NXDomain, ServFail and Refused. Default is false, meaning that every RCODE except ServFail is considered valid
`order`	`integer`		The order of servers in this set, used by the `leastOutstanding` and `firstAvailable` policies
`qps`	`integer`		Limit the number of queries per second to this amount, when using the `firstAvailable` policy
`reconnectOnUp`	`boolean`	`false`	If true, close and reopen the sockets when a server transits from Down to Up
`retries`	`integer`		The number of TCP connection attempts to servers for a given query
`rise`	`integer`	`1`	Require NUM consecutive successful checks before declaring the backend up
`setCD`	`boolean`	`false`	Set the CD (Checking Disabled) flag in the health-check query
`sockets`	`integer`	`1`	Number of sockets (and thus source ports) used toward the backend server
`source`	`string`		Name of the interface which Dnsdist will use to try to send traffic to this Recursor
`tcpConnectTimeout`	`integer`		The timeout (in seconds) of a TCP connection attempt
`tcpFastOpen`	`boolean`	`false`	Whether to enable TCP Fast Open
`tcpRecvTimeout`	`integer`		The timeout (in seconds) of a TCP read attempt
`tcpSendTimeout`	`integer`		The timeout (in seconds) of a TCP write attempt
`useClientSubnet`	`boolean`	`false`	Add the client IP address in the EDNS Client Subnet option when forwarding the query to this backend
`useProxyProtocol`	`boolean`	`false`	Add a proxy protocol header to the query, passing along the client IP address and port along with the original destination address and port
`weight`	`integer`	`1`	The weight of servers in this set, used by the `wrandom`, `whashed` and `chashed` policies

HPA

Horizontal Pod Autoscaling (HPA) can be enabled by configuring the necessary parameters and setting enabled: true. For example:

auths:
  myauth:
    hpa:
      enabled: true
      minReplicas: 2
      maxReplicas: 6
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 70

Parameters which can be used to configure HPA:

Parameter	Type	Required	Default	Description
`behavior`	`k8s`HorizontalPodAutoscalerBehavior			Behavior of the Horizontal Pod Autoscaler
`enabled`	`boolean`	`yes`	`false`	If true, enable Horizontal Pod Autoscaling
`maxReplicas`	`integer`		`4`	Maximum number of replicas
`metrics`	List of `k8s`MetricSpec			Metric(s) upon which to make decisions regarding scaling
`minReplicas`	`integer`		`2`	Minimum number of replicas

IXFRDist

IXFRDist can be enabled by configuring the necessary parameters and setting enabled: true. For example:

auths:
  myixfrauth:
    ixfrdist:
      enabled: true
      domains:
        - domain: "zone1.ixfrdist.local"
        - domain: "zone3.ixfrdist.local"

Above will enable IXFRDist for a static list of domains: zone1.ixfrdist.local and zone3.ixfrdist.local. Alternatively, you can configure IXFRDist to learn zones from the Auth instance with which it shares a pod:

auths:
  myixfrauth:
    ixfrdist:
      enabled: true
      learn:
        enabled: true

Parameters which can be used to configure IXFRDist:

Parameter	Type	Required	Default	Description
`acl`	List of `string`		`- "0.0.0.0/0" - "::/0"`	A list of netmasks that are allowed to query ixfrdist and request AXFRs and IXFRs
`axfrMaxrecords`	`integer`		`0`	Maximum number of records allowed in an AXFR transaction requested by ixfrdist. Default: `0` (unlimited)
`axfrTimeout`	`integer`		`20`	Timeout in seconds an AXFR transaction requested by ixfrdist may take
`compress`	`boolean`		`false`	If true, record compression is enabled, leading to smaller answers at the cost of an increased CPU and memory usage
`domains`	List of IXFRDistDomain			List of zones ixfrdist should attempt to transfer and re-serve over AXFR and IXFR
`domainsConfigMap`	`string`			Name of a pre-existing configmap from which to grab the `domains.yaml` containing a YAML representation of the `domains` argument (including `domains:` as root element)
`enabled`	`boolean`	`yes`	`false`	If true, enable IXFRDist
`failedSOARetry`	`integer`		`30`	Time in seconds between retries of the SOA query for a zone we have never transferred
`keep`	`integer`		`20`	Amount of older copies/IXFR diffs to keep for every domain
`learn`	IXFRDistLearning			Configuration of automated learning of zones from Auth
`notify`	List of `string`			A list of destinations to relay notify to for each zone redistributed by ixfrdist. Only relayed by ixfrdist when it receives a notify.
`tcpInThreads`	`integer`		`10`	Number of threads to spawn for TCP connections from downstream hosts. This limits the number of concurrent AXFRs to clients
`webserverACL`	List of `string`		`- "127.0.0.0/8" - "::1/128"`	A list of networks that are allowed to access the ixfrdist webserver
`webserverLogLevel`	`string`		`"normal"`	Verbosity of the webserver. Available options: `"none"` `"normal"` `"detailed"`

IXFRDist Domains

Parameters to configure IXFRDist domains. For example:

auths:
  myixfrauth:
    ixfrdist:
      enabled: true
      domains:
        - domain: "zone1.ixfrdist.local"
          max-soa-refresh: 3600
        - domain: "zone3.ixfrdist.local"

Parameters available for each domain in the list:

Parameter	Type	Required	Description
`domain`	`string`	`yes`	Name of the zone
`master`	`string`		IP:port of master from which to attempt to transfer the zone. Default: Automatically configured to the Auth instance
`max-soa-refresh`	`integer`		Maximum refresh time. Default: None, respects the refresh time on the SOA record for the corresponding zone
`notify`	List of `string`		A list of destinations to relay notify to for this domain. Only relayed by ixfrdist when it receives a notify.

IXFRDist Learning

Parameters to configure IXFRDist learning from Auth. For example:

auths:
  myixfrauth:
    ixfrdist:
      enabled: true
      learn:
        enabled: true

Parameters available to further configure learning:

Parameter	Type	Required	Default	Description
`enabled`	`boolean`	`yes`	`false`	Enable learning
`exclude`	List of `string`		`[]`	If learning is enabled, exclude any zones which match this list of regular expressions (this is processed after the `include` filter)
`include`	List of `string`		`[]`	If learning is enabled, include only zones which match this list of regular expressions (this is processed before the `exclude` filter)
`interval`	`integer`		`5`	Interval in seconds between consecutive attempts to learn zones from Auth
`maxSOARefresh`	`integer`			Maximum refresh time. Default: None, respects the refresh time on the SOA record for the corresponding zone

Auth API

Parameters to configure the Auth API. You can use these to configure access to the Auth API:

Parameter	Type	Default	Description
`ingress`	AuthAPIIngress	`{}`	Ingress configuration
`service`	AuthAPIService		Service object for Auth API. Default: A `ClusterIP` service listening on port 8080

Auth API Ingress

Parameters to configure an Ingress for Auth API. For example:

auths:
  myauth:
    api:
      ingress:
        enabled: true
        ingressClassName: "nginx"
        hosts:
          - authapi.example.local

Parameter	Type	Default	Description
`annotations`	`k8s:`Annotations	`{}`	Annotations for the ingress
`enabled`	`boolean`	`false`	If true, create an ingress object
`hosts`	List of `string`	`[]`	List of hosts for which the ingress should accept traffic (If using `tls`, this should also include the `hosts` listed on the `tls` object)
`ingressClassName`	`string`		Name of the ingress class
`tls`	List of AuthAPIIngressTLS	`[]`	List of ingress tls configurations

Auth API Ingress TLS

Parameters to configure TLS for an ingress. For example:

auths:
  myauth:
    api:
      ingress:
        enabled: true
        ingressClassName: "nginx"
        hosts:
          - authapi.example.local
        tls:
          - secretName: authapi-ingress-cert
            hosts:
            - authapi.example.local

The above example will result in an ingress for Auth API listening for authapi.example.local and serving the certificate contained in the secret authapi-ingress-cert.

Note: tls is a list of configurations. Below shows the parameters which can be used for each entry in that list:

Parameter	Type	Default	Description
`hosts`	List of `string`	`[]`	List of hosts for which the ingress should accept TLS traffic
`secretName`	`string`	`""`	Name of a secret containing the certificate to be used for this ingress

Auth API Service

Parameters to configure the service object for Auth API. For example:

auths:
  myauth:
    api:
      service:
        type: LoadBalancer
        annotations:
          metallb.universe.tf/address-pool: name_of_pool

Parameter	Type	Default	Description
`allocateLoadBalancerNodePorts`	`boolean`	`true`	If true, services with type `LoadBalancer` automatically assign NodePorts. Can be set to `false` if the LoadBalancer provider does not rely on NodePorts
`annotations`	`k8s:`Annotations	`{}`	Annotations for the service
`clusterIP`	`string`		Static cluster IP, must be in the cluster's range of cluster IPs and not in use. Randomly assigned when not specified.
`clusterIPs`	List of `string`		List of static cluster IPs, must be in the cluster's range of cluster IPs and not in use.
`externalIPs`	List of `string`		List of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes and must be user-defined on the cluster's nodes
`externalTrafficPolicy`	`string`	`Cluster`	Can be set to `Local` to let nodes distribute traffic received on one of the externally-facing addresses (`NodePort` and `LoadBalancer`) solely to endpoints on the node itself
`healthCheckNodePort`	`integer`		For services with type `LoadBalancer` and externalTrafficPolicy `Local` you can configure this value to choose a static port for the NodePort which external systems (LoadBalancer provider mainly) can use to determine which node holds endpoints for this service
`internalTrafficPolicy`	`string`	`Cluster`	Can be set to `Local` to let nodes distribute traffic received on the `ClusterIP` solely to endpoints on the node itself
`labels`	`k8s:`Labels	`{}`	Labels to be added to the service
`loadBalancerIP`	`string`		Deprecated Kubernetes feature, available for backwards compatibility: IP address to attempt to claim for use by this LoadBalancer. Replaced by `annotations` specific to each LoadBalancer provider
`loadBalancerSourceRanges`	List of `string`		If supported by the LoadBalancer provider, restrict traffic to this LoadBalancer to these ranges
`loadBalancerClass`	`string`		Used to select a non-default type of LoadBalancer class to ensure the appropriate LoadBalancer provisioner attempt to manage this LoadBalancer service
`publishNotReadyAddresses`	`boolean`	`false`	Service is populated with endpoints regardless of readiness state
`sessionAffinity`	`string`	`None`	Can be set to `ClientIP` to attempt to maintain session affinity.
`sessionAffinityConfig`	`k8s:`SessionAffinityConfig	`{}`	Configuration of session affinity
`type`	`string`	`ClusterIP`	Type of service. Available options: `"ClusterIP"` `"LoadBalancer"` `"NodePort"`

Backend Configuration

Parameters which can be used to configure a backend:

Parameter	Type	Required	Default	Description
`type`	`string`	`yes`		Type of backend. Available options: `"ls"` `"postgres"` `"mysql"` `"geoip"` See below for more configuration options specific to each destination type.

Lightning Stream with S3

To configure Auth for Lightning Stream with S3, you need to configure at least the following:

auths:
  myauth:
    backends:
      - type: ls
        bucket: myBucket
        endpoint: https://my.s3.endpoint
        secretName: my-s3-credentials

The full range of options available for this backend:

Parameter	Type	Required	Default	Description
`access_key`	`string`			S3 access key. Use of `secretName` is recommended for security reasons
`bucket`	`string`	`yes`		Name of the S3 bucket
`cleanupDisabled`	`boolean`		`false`	If true, disable the cleanup mechanism
`cleanupInterval`	`go:`DurationString		`5m`	Interval between cleanup runs
`cleanupMustKeepInterval`	`go:`DurationString		`10m`	Determines how long snapshots must be kept after they appear in the bucket, even if a newer snapshot is available
`cleanupRemoveOldInstancesInterval`	`go:`DurationString		`168h`	Determines when an instance is considered stale and the latest snapshot for the instance can be considered for removal
`endpoint_url`	`string`	`yes`		Endpoint of the S3 service to connect to
`loglevel`	`string`		`"info"`	Log level. Available options: `"debug"` `"info"` `"warning"` `"error"` `"fatal"`
`lmdbEmptyDir`	`k8s`EmptyDirVolumeSource		`medium: "Memory"`	Configuration of the EmptyDir volume used to store LMDB
`lmdbPollInterval`	`go:`DurationString		`1s`	Minimum time between checking for new LMDB transactions
`lmdbLogStatsInterval`	`go:`DurationString		`30m`	Interval for logging LMDB stats
`mapSize`	`integer`		`1000`	Size (in megabytes) of the LMDB databases. Should be increased for large datasets
`memoryDownloadedSnapshots`	`integer`		`3`	Maximum amount of downloaded snapshots queued in memory before decompression
`memoryDecompressedSnapshots`	`integer`		`2`	Maximum amount of decompressed snapshots in memory before processing
`migratorInterval`	`go:`DurationString		`5s`	Time between checks performed by the migrator to see if a migration is required
`migratorLogFormat`	`string`		`"text"`	Migrator log format. Available options: `"text"` `"json"`
`migratorLogLevel`	`string`		`"info"`	Migrator log level. Available options: `"trace"` `"debug"` `"info"` `"warn"` `"error"`
`migratorPodAnnotations`	`k8s:`Annotations		`{}`	Annotations to be added to the Migrator pod
`migratorPodLabels`	`k8s:`Labels		`{}`	Labels to be added to the Migrator Pod
`mode`	`string`		`"sync"`	Synchronization mode. Available options: `"sync"` `"receive"`
`region`	`string`		`"us-east-1"`	Region used when connecting to the S3 endpoint
`removeOldSchemaAge`	`go:`DurationString		`672h`	Time since the last successful migration of an old schema before removing it, if no updates have been made to the schema since then
`removeOldSchemaEnabled`	`boolean`		`true`	Whether or not the migrator should clean up old schemas if they have been migrated successfully and not seen any updates since
`secret_key`	`string`			S3 secret key. Use of `secretName` is recommended for security reasons
`secretAccessKey`	`string`		`"access_key"`	If `secretName` is specified: name of the item inside the Secret which holds the access key
`secretName`	`string`			Name of a pre-existing Kubernetes Secret containing a username & password for authentication with Elastic
`secretSecretKey`	`string`		`"secret_key"`	If `secretName` is specified: name of the item inside the Secret which holds the secret key
`storageForceSnapshotInterval`	`go:`DurationString		`4h`	Interval between forced snapshots created by an instance, if no changes have been observed
`storagePollInterval`	`go:`DurationString		`1s`	Minimum time between polling the storage backend for new snapshots
`storageRetryInterval`	`go:`DurationString		`5s`	Interval to retry a storage operation after failure
`storageRetryCount`	`integer`		`10`	Number of times to retry a storage operation after failure, before giving up (only active if storageRetryForever is `false`)
`storageRetryForever`	`boolean`		`true`	Retry failed storage operations forever before giving up
`tls`	TLSConfig		`{}`	TLS configuration options
`unreadyIfError`	`boolean`		`true`	Set readiness of LightingStream container to `NotReady` if LightningStream healthz endpoint reports any errors
`unreadyIfWarning`	`boolean`		`false`	Set readiness of LightingStream container to `NotReady` if LightningStream healthz endpoint reports any warnings
`waitForInitialSync`	`boolean`		`true`	Keep readiness of LightningStream container at `NotReady` until LightningStream has successfully finished the initial sync between the Auth container and the s3 bucket

S3 TLS Config

You can configure TLS for Lightning Stream with the following parameters:

Parameter	Type	Required	Default	Description
`ca`	`string`			CA in PEM format to use for validation
`insecure_skip_verify`	`boolean`		`false`	Skip validation of the storage backend's certificate chain and hostname

Postgres

To configure Auth for Postgres, you can configure the following:

auths:
  myauth:
    backends:
      - type: postgres
        host: pg.host.local
        dbname: mydb
        user: some_user
        password: some_password

The full range of options available for this backend:

Parameter	Type	Required	Default	Description
`dbname`	`string`	`yes`		Name of the database
`host`	`string`	`yes`		Host/IP of the Postgres endpoint
`password`	`string`			Password to use for authentication. Using `secretName` is preferred
`port`	`integer`		`5432`	Port over which to access the Postgres endpoint
`secretName`	`string`			Name of a pre-existing Kubernetes Secret containing a username & password for authentication
`secretPasswordKey`	`string`		`"password"`	If `secretName` is specified: name of the item inside the Secret which holds the password
`secretUsernameKey`	`string`		`"username"`	If `secretName` is specified: name of the item inside the Secret which holds the username
`sslmode`	`string`			Postgres `sslmode` to use while connecting. Optional, omitted if no value is provided
`user`	`string`			Username to use for authentication. Using `secretName` is preferred

MySQL

To configure Auth for MySQL, you can configure the following:

auths:
  myauth:
    backends:
      - type: mysql
        host: mysq.host.local
        dbname: mydb
        user: some_user
        password: some_password

The full range of options available for this backend:

Parameter	Type	Required	Default	Description
`dbname`	`string`	`yes`		Name of the database
`dnssec`	`string`		`"no"`	If `"yes"`, enable DNSSEC processing for this backend
`group`	`string`		`"client"`	Group to connect as
`host`	`string`	`yes`		Host/IP of the MySQL endpoint
`innodbReadCommitted`	`string`		`"no"`	If `"yes"`, Use the InnoDB READ-COMMITTED transaction isolation level
`password`	`string`			Password to use for authentication. Using `secretName` is preferred
`port`	`integer`		`3306`	Port over which to access the MySQL endpoint
`secretName`	`string`			Name of a pre-existing Kubernetes Secret containing a username & password for authentication
`secretPasswordKey`	`string`		`"password"`	If `secretName` is specified: name of the item inside the Secret which holds the password
`secretUsernameKey`	`string`		`"username"`	If `secretName` is specified: name of the item inside the Secret which holds the username
`ssl`	`string`			Can be set to `yes` to force connecting via SSL. Optional, default behaviour is to use SSL if the server announces this capability
`timeout`	`integer`		`10`	Timeout in seconds for each attempt to read from, or write to the server. A value of 0 will disable the timeout
`user`	`string`			Username to use for authentication. Using `secretName` is preferred

GeoIP

To configure Auth for GeoIP, you can configure the following:

auths:
  myauth:
    backends:
      - type: geoip
        databases: <Configuration of one or more GeoIP databases>
        domains: <Configuration of domains>

For the domains parameter, please refer to the PowerDNS Authoritative Server documentation: GeoIP domains

For the databases parameter there are several options. Cloud Control currently supports the following:

MaxMind Database via HTTP: Prebuilt databases by MaxMind, obtained via HTTP
MaxMind Database via OCI: Prebuilt databases by MaxMind, obtained via OCI
Custom: A database built by the Auth init container based on data you provide in the Helm configuration values

GeoIP: MaxMind via HTTP

To configure a MaxMind database which is available via HTTP, you can use the following:

auths:
  myauth:
    backends:
      - type: geoip
        domains: <Configuration of domains>
        databases:
          - name: MyDatabase
            type: http
            url: https://some_host/my-database.mmdb

The full range of options available for this database source:

Parameter	Type	Required	Default	Description
`headers`	`dictionary`			Dictionary of `key: value` pairs, where `key` is the header name and `value` is the value of the header
`insecure`	`boolean`		`false`	If `true`, will download the database from an HTTPS URL without certificate validation
`name`	`string`	`yes`		Name of this database source
`params`	`dictionary`			Dictionary of `key: value` pairs to be supplied to Curl, where `key` is the name of the Curl parameter and `value` is the value of the parameter
`type`	`string`	`yes`		Must be `http` to use the database source
`url`	`string`	`yes`		URL of the HTTP endpoint of the database

GeoIP: MaxMind via OCI

To configure a MaxMind database which is available via OCI, you can use the following:

auths:
  myauth:
    backends:
      - type: geoip
        domains: <Configuration of domains>
        databases:
          - name: MyOCIDB
            type: oci
            artifact: my_registry/repository/geo-city-mmdb:v2.4.0
            user: MyUser
            token: MyPassword

The full range of options available for this database source:

Parameter	Type	Required	Description
`name`	`string`	`yes`	Name of this database source
`type`	`string`	`yes`	Must be `oci` to use the database source
`artifact`	`string`	`yes`	URL of the HTTP endpoint of the database
`user`	`string`	`yes`	User with which to connect to the registry
`token`	`string`	`yes`	Token for `user`

GeoIP: Custom database

Configuring a GeoIP backend using a custom database can be done via the following configuration:

auths:
  myauth:
    backends:
      - type: geoip
        domains: <Configuration of domains>
        databases:
          - name: localdb
            type: generate
            datacenters:
              <List of datacenters - see below>

Where datacenters is a list of different locations, for example:

auths:
  myauth:
    backends:
      - type: geoip
        domains: <Configuration of domains>
        databases:
          - name: localdb
            type: generate
            datacenters:
              - name: DatacenterName
                networks:
                  - 10.0.1.0/24
                lat: 52.370216
                long: 4.895168

Parameters you can use for each entry in the list:

Parameter	Type	Required	Description
`name`	`string`	`yes`	Name of this location
`networks`	List of `string`	`yes`	List of networks to be assigned to this location
`lat`	`float`	`yes`	Longitude of this location
`long`	`float`	`yes`	Latitude of this location

A real world example would be a database of locations for 2 datacenters in the Netherlands: Amsterdam and Rotterdam. We can configure those locations as follows:

auths:
  myauth:
    backends:
      - type: geoip
        domains: <Configuration of domains>
        databases:
          - name: localdb
            type: generate
            datacenters:
              - name: Amsterdam
                networks:
                  - 10.0.1.0/24
                  - 10.0.6.0/24
                lat: 52.370216
                long: 4.895168
              - name: Rotterdam
                networks:
                  - 10.1.1.0/24
                  - 10.1.6.0/24
                lat: 51.924419
                long: 4.477733

We could now use GeoIP to match source IPs and figure out if traffic is coming from a source closer to either the Amsterdam location or the Rotterdam location.