Merge pull request #4882 from juan-vg/fix/docs/managed-record-types

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

docs/contributing/crd-source.md → docs/sources/crd.md

@@ -82,18 +82,18 @@ Create the objects of CRD type by filling in the fields of CRD and DNS record wo
 
 ### Example
 
-Here is an example [CRD manifest](crd-source/crd-manifest.yaml) generated by kubebuilder.
+Here is an example [CRD manifest](crd/crd-manifest.yaml) generated by kubebuilder.
 Apply this to register the CRD
 
 ```
-$ kubectl apply --validate=false -f docs/contributing/crd-source/crd-manifest.yaml
+$ kubectl apply --validate=false -f docs/sources/crd/crd-manifest.yaml
 customresourcedefinition.apiextensions.k8s.io "dnsendpoints.externaldns.k8s.io" created
 ```
 
-Then you can create the dns-endpoint yaml similar to [dnsendpoint-example](crd-source/dnsendpoint-example.yaml)
+Then you can create the dns-endpoint yaml similar to [dnsendpoint-example](crd/dnsendpoint-example.yaml)
 
 ```
-$ kubectl apply -f docs/contributing/crd-source/dnsendpoint-example.yaml
+$ kubectl apply -f docs/sources/crd/dnsendpoint-example.yaml
 dnsendpoint.externaldns.k8s.io "examplednsrecord" created
 ```
 
@@ -107,6 +107,69 @@ INFO[0000] CREATE: foo.bar.com 180 IN A 192.168.99.216
 INFO[0000] CREATE: foo.bar.com 0 IN TXT "heritage=external-dns,external-dns/owner=default"
 ```
 
+#### Using CRD source to manage DNS records in different DNS providers
+
+[CRD source](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/sources/crd.md) provides a generic mechanism and declarative way to manage DNS records in different DNS providers using external-dns.
+
+**Not all the record types are enabled by default so the required record types must be enabled by using `--managed-record-types`.**
+
+```bash
+external-dns --source=crd \
+  --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
+```
+
 ### RBAC configuration
 
 If you use RBAC, extend the `external-dns` ClusterRole with:

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

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

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,23 +87,27 @@ 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`.
 
 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.

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

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,7 @@ 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
+
+Please refer to the [CRD source documentation](../sources/crd.md#example) for more information.

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,7 @@ 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
+
+Please refer to the [CRD source documentation](../sources/crd.md#example) for more information.

docs/tutorials/pdns.md

@@ -176,99 +176,4 @@ $ dig @${PDNS_FQDN} echo.example.com.
 
 ## Using CRD source to manage DNS records in PowerDNS
 
-[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.
-
-```bash
-external-dns --source=crd --provider=pdns \
-  --pdns-server={{ pdns-api-url }} \
-  --pdns-api-key={{ pdns-api-key }} \
-  --domain-filter=example.com \
-  --managed-record-types=A \
-  --managed-record-types=CNAME \
-  --managed-record-types=TXT \
-  --managed-record-types=MX \
-  --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
-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 `TXT`
-
-```yaml
-apiVersion: externaldns.k8s.io/v1alpha1
-kind: DNSEndpoint
-metadata:
-  name: exampletxtrecord
-spec:
-  endpoints:
-  - dnsName: example.com
-    recordTTL: 3600
-    recordType: TXT
-    targets:
-      - '"v=spf1 include:spf.protection.example.com include:example.org -all"'
-      - '"apple-domain-verification=XXXXXXXXXXXXX"'
-```
-
-* Example for record type `MX`
-
-```yaml
-apiVersion: externaldns.k8s.io/v1alpha1
-kind: DNSEndpoint
-metadata:
-  name: examplemxrecord
-spec:
-  endpoints:
-  - dnsName: example.com
-    recordTTL: 3600
-    recordType: MX
-    targets:
-      - "10 mailhost1.example.com"
-```
-
-* Example for record type `SRV`
-
-```yaml
-apiVersion: externaldns.k8s.io/v1alpha1
-kind: DNSEndpoint
-metadata:
-  name: examplesrvrecord
-spec:
-  endpoints:
-  - dnsName: _service._tls.example.com
-    recordTTL: 180
-    recordType: SRV
-    targets:
-      - "100 1 443 service.example.com"
-```
+Please refer to the [CRD source documentation](../sources/crd.md#example) for more information.