Improve sources' docs to mention '--managed-record-types'

* Also add some CRD examples for AWS and Cloudflare
2025-08-06 01:26:59 +02:00 · 2024-11-18 14:09:39 +01:00 · 2024-11-18 14:09:39 +01:00 · ee79d0da01
commit ee79d0da01
parent b2e1a607cf
7 changed files with 155 additions and 18 deletions
--- a/docs/sources/mx-record.md
+++ b/docs/sources/mx-record.md
@ -3,10 +3,10 @@
 You can create and manage MX records with the help of [CRD source](../contributing/crd-source.md)
 and `DNSEndpoint` CRD. Currently, this feature is only supported by `aws`, `azure`, `google` and `digitalocean` providers.

-In order to start managing MX records you need to set the `--managed-record-types MX` flag.
+In order to start managing MX records you need to set the `--managed-record-types=MX` flag.

 ```console
-external-dns --source crd --provider {aws|azure|google|digitalocean} --managed-record-types A --managed-record-types CNAME --managed-record-types MX
+external-dns --source crd --provider {aws|azure|google|digitalocean} --managed-record-types=A --managed-record-types=CNAME --managed-record-types=MX
 ```

 Targets within the CRD need to be specified according to the RFC 1034 (section 3.6.1). Below is an example of
--- a/docs/sources/ns-record.md
+++ b/docs/sources/ns-record.md
@ -3,6 +3,12 @@
 You can create NS records with the help of [CRD source](../contributing/crd-source.md)
 and `DNSEndpoint` CRD.

+In order to start managing NS records you need to set the `--managed-record-types=NS` flag.
+
+```console
+external-dns --source crd --managed-record-types=A --managed-record-types=CNAME --managed-record-types=NS
+```
+
 Consider the following example

 ```yaml
--- a/docs/sources/service.md
+++ b/docs/sources/service.md
@ -35,7 +35,7 @@ the value of the Pod's `spec.hostname` field and a `.`.

 ## Targets

-If the Service has an `external-dns.alpha.kubernetes.io/target` annotation, uses 
+If the Service has an `external-dns.alpha.kubernetes.io/target` annotation, uses
 the values from that. Otherwise, the targets of the DNS entries created from a service are sourced depending
 on the Service's `spec.type`:

@ -61,7 +61,7 @@ also iterates over the Endpoints's `subsets.notReadyAddresses`.

 1. If an address does not target a `Pod` that matches the Service's `spec.selector`, it is ignored.

-2. If the target pod has an `external-dns.alpha.kubernetes.io/target` annotation, uses 
+2. If the target pod has an `external-dns.alpha.kubernetes.io/target` annotation, uses
 the values from that.

 3. Otherwise, if the Service has an `external-dns.alpha.kubernetes.io/endpoints-type: NodeExternalIP`
@ -87,13 +87,13 @@ and has a `status.phase` of `Running`. Otherwise iterates over all Nodes, of any

 Iterates over each relevant Node's `status.addresses`:

-1. If there is an `external-dns.alpha.kubernetes.io/access: public` annotation on the Service, uses both addresses with 
+1. If there is an `external-dns.alpha.kubernetes.io/access: public` annotation on the Service, uses both addresses with
 a `type` of `ExternalIP` and IPv6 addresses with a `type` of `InternalIP`.

-2. Otherwise, if there is an `external-dns.alpha.kubernetes.io/access: private` annotation on the Service, uses addresses with  
+2. Otherwise, if there is an `external-dns.alpha.kubernetes.io/access: private` annotation on the Service, uses addresses with
 a `type` of `InternalIP`.

-3. Otherwise, if there is at least one address with a `type` of `ExternalIP`, uses both addresses with 
+3. Otherwise, if there is at least one address with a `type` of `ExternalIP`, uses both addresses with
 a `type` of `ExternalIP` and IPv6 addresses with a `type` of `InternalIP`.

 4. Otherwise, uses addresses with a `type` of `InternalIP`.
@ -101,9 +101,13 @@ a `type` of `ExternalIP` and IPv6 addresses with a `type` of `InternalIP`.
 Also iterates over the Service's `spec.ports`, creating a SRV record for each port which has a `nodePort`.
 The SRV record has a service of the Service's `name`, a protocol taken from the port's `protocol` field,
 a priority of `0` and a weight of `50`.
-In order for SRV records to be created, the `--managed-record-types`must have been specified, including `SRV`
+In order for SRV records to be created, the `--managed-record-types` must have been specified, including `SRV`
 as one of the values.

+```console
+external-dns ... --managed-record-types=A --managed-record-types=CNAME --managed-record-types=SRV
+```
+
 ### ExternalName

 1. If the Service has one or more `spec.externalIPs`, uses the values in that field.
--- a/docs/sources/txt-record.md
+++ b/docs/sources/txt-record.md
@ -3,10 +3,10 @@
 You can create and manage TXT records with the help of [CRD source](../contributing/crd-source.md)
 and `DNSEndpoint` CRD. Currently, this feature is only supported by `digitalocean` providers.

-In order to start managing TXT records you need to set the `--managed-record-types TXT` flag.
+In order to start managing TXT records you need to set the `--managed-record-types=TXT` flag.

 ```console
-external-dns --source crd --provider {digitalocean} --managed-record-types A --managed-record-types CNAME --managed-record-types TXT
+external-dns --source crd --provider {digitalocean} --managed-record-types=A --managed-record-types=CNAME --managed-record-types=TXT
 ```

 Targets within the CRD need to be specified according to the RFC 1035 (section 3.3.14). Below is an example of
--- a/docs/tutorials/aws.md
+++ b/docs/tutorials/aws.md
@ -233,11 +233,11 @@ kubectl create secret generic external-dns \
 Follow the steps under [Deploy ExternalDNS](#deploy-externaldns) using either RBAC or non-RBAC.  Make sure to uncomment the section that mounts volumes, so that the credentials can be mounted.

 > [!TIP]
-> By default ExternalDNS takes the profile named `default` from the credentials file. If you want to use a different 
-> profile, you can set the environment variable `EXTERNAL_DNS_AWS_PROFILE` to the desired profile name or use the 
+> By default ExternalDNS takes the profile named `default` from the credentials file. If you want to use a different
+> profile, you can set the environment variable `EXTERNAL_DNS_AWS_PROFILE` to the desired profile name or use the
 > `--aws-profile` command line argument. It is even possible to use more than one profile at ones, separated by space in
-> the environment variable `EXTERNAL_DNS_AWS_PROFILE` or by using `--aws-profile` multiple times. In this case 
-> ExternalDNS looks for the hosted zones in all profiles and keeps maintaining a mapping table between zone and profile 
+> the environment variable `EXTERNAL_DNS_AWS_PROFILE` or by using `--aws-profile` multiple times. In this case
+> ExternalDNS looks for the hosted zones in all profiles and keeps maintaining a mapping table between zone and profile
 > in order to be able to modify the zones in the correct profile.

 ### IAM Roles for Service Accounts
@ -987,3 +987,67 @@ There are 3 options to control batch size for AWS provider:

 Default values for flags `aws-batch-change-size-bytes` and `aws-batch-change-size-values` are taken from [AWS documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/DNSLimitations.html#limits-api-requests) for Route53 API. **You should not change those values until you really have to.** <br>
 Because those limits are in place, `aws-batch-change-size` can be set to any value: Even if your batch size is `4000` records, your change will be split to separate batches due to bytes/values size limits and apply request will be finished without issues.
+
+
+## Using CRD source to manage DNS records in AWS
+
+[CRD source](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/contributing/crd-source.md) provides a generic mechanism and declarative way to manage DNS records in AWS using external-dns.
+
+**Not all the record types are enabled by default so we must enable the required record types using `--managed-record-types`.**
+
+```bash
+external-dns --source=crd --provider=aws \
+  --domain-filter=example.com \
+  --managed-record-types=A \
+  --managed-record-types=CNAME \
+  --managed-record-types=NS
+```
+
+* Example for record type `A`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: examplearecord
+spec:
+  endpoints:
+  - dnsName: example.com
+    recordTTL: 60
+    recordType: A
+    targets:
+    - 10.0.0.1
+```
+
+* Example for record type `CNAME`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: examplecnamerecord
+spec:
+  endpoints:
+  - dnsName: test-a.example.com
+    recordTTL: 300
+    recordType: CNAME
+    targets:
+    - example.com
+```
+
+* Example for record type `NS`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: ns-record
+spec:
+  endpoints:
+  - dnsName: zone.example.com
+    recordTTL: 300
+    recordType: NS
+    targets:
+    - ns1.example.com
+    - ns2.example.com
+```
--- a/docs/tutorials/cloudflare.md
+++ b/docs/tutorials/cloudflare.md
@ -58,7 +58,7 @@ Then apply one of the following manifests file to deploy ExternalDNS.
 Create a values.yaml file to configure ExternalDNS to use CloudFlare as the DNS provider. This file should include the necessary environment variables:

 ```yaml
-provider: 
+provider:
  name: cloudflare
 env:
  - name: CF_API_KEY
@ -76,7 +76,7 @@ env:
 Use this in your values.yaml, if you are using API Token:

 ```yaml
-provider: 
+provider:
  name: cloudflare
 env:
  - name: CF_API_TOKEN
@ -307,3 +307,66 @@ Using the `external-dns.alpha.kubernetes.io/cloudflare-proxied: "true"` annotati
 Using the `external-dns.alpha.kubernetes.io/cloudflare-region-key` annotation on your ingress, you can restrict which data centers can decrypt and serve HTTPS traffic. A list of available options can be seen [here](https://developers.cloudflare.com/data-localization/regional-services/get-started/).

 If not set the value will default to `global`.
+
+## Using CRD source to manage DNS records in Cloudflare
+
+[CRD source](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/contributing/crd-source.md) provides a generic mechanism and declarative way to manage DNS records in Cloudflare using external-dns.
+
+**Not all the record types are enabled by default so we must enable the required record types using `--managed-record-types`.**
+
+```bash
+external-dns --source=crd --provider=cloudflare \
+  --domain-filter=example.com \
+  --managed-record-types=A \
+  --managed-record-types=CNAME \
+  --managed-record-types=NS
+```
+
+* Example for record type `A`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: examplearecord
+spec:
+  endpoints:
+  - dnsName: example.com
+    recordTTL: 60
+    recordType: A
+    targets:
+    - 10.0.0.1
+```
+
+* Example for record type `CNAME`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: examplecnamerecord
+spec:
+  endpoints:
+  - dnsName: test-a.example.com
+    recordTTL: 300
+    recordType: CNAME
+    targets:
+    - example.com
+```
+
+* Example for record type `NS`
+
+```yaml
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: ns-record
+spec:
+  endpoints:
+  - dnsName: zone.example.com
+    recordTTL: 300
+    recordType: NS
+    targets:
+    - ns1.example.com
+    - ns2.example.com
+```
--- a/docs/tutorials/pdns.md
+++ b/docs/tutorials/pdns.md
@ -178,6 +178,8 @@ $ dig @${PDNS_FQDN} echo.example.com.

 [CRD source](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/contributing/crd-source.md) provides a generic mechanism and declarative way to manage DNS records in PowerDNS using external-dns.

+Not all the record types are enabled by default so we can enable the required record types using `--managed-record-types`.
+
 ```bash
 external-dns --source=crd --provider=pdns \
  --pdns-server={{ pdns-api-url }} \
@ -190,8 +192,6 @@ external-dns --source=crd --provider=pdns \
  --managed-record-types=SRV
 ```

-Not all the record types are enabled by default so we can enable the required record types using `--managed-record-types`.
-
 * Example for record type `A`

 ```yaml