From 2a1ab538b88bd821497e75385b08e8862898eb4a Mon Sep 17 00:00:00 2001 From: Lino Layani <39967417+linoleparquet@users.noreply.github.com> Date: Mon, 19 May 2025 03:43:23 -0400 Subject: [PATCH] fix(docs): resove broken links, add source description (#5413) --- README.md | 68 +++++++++++----------- docs/20190708-external-dns-incubator.md | 21 +++---- docs/contributing/sources-and-providers.md | 2 +- docs/deprecation.md | 2 +- docs/sources/about.md | 52 +++++++++-------- docs/sources/crd.md | 2 +- docs/sources/mx-record.md | 2 +- docs/sources/ns-record.md | 2 +- docs/sources/txt-record.md | 2 +- mkdocs.yml | 2 +- 10 files changed, 80 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 45841e9ab..b4eebfd14 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This README is a part of the complete documentation, available [here](https://ku Inspired by [Kubernetes DNS](https://github.com/kubernetes/dns), Kubernetes' cluster-internal DNS server, ExternalDNS makes Kubernetes resources discoverable via public DNS servers. Like KubeDNS, it retrieves a list of resources (Services, Ingresses, etc.) from the [Kubernetes API](https://kubernetes.io/docs/api/) to determine a desired list of DNS records. -*Unlike* KubeDNS, however, it's not a DNS server itself, but merely configures other DNS providers accordingly—e.g. [AWS Route 53](https://aws.amazon.com/route53/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/). +_Unlike_ KubeDNS, however, it's not a DNS server itself, but merely configures other DNS providers accordingly—e.g. [AWS Route 53](https://aws.amazon.com/route53/) or [Google Cloud DNS](https://cloud.google.com/dns/docs/). In a broader sense, ExternalDNS allows you to control DNS records dynamically via Kubernetes resources in a DNS provider-agnostic way. @@ -77,7 +77,7 @@ Note that all flags can be replaced with environment variables; for instance, ## New providers -No new provider will be added to ExternalDNS *in-tree*. +No new provider will be added to ExternalDNS _in-tree_. ExternalDNS has introduced a webhook system, which can be used to add a new provider. See PR #3063 for all the discussions about it. @@ -116,7 +116,7 @@ ExternalDNS supports multiple DNS providers which have been implemented by the [ Maintaining all of those in a central repository is a challenge, which introduces lots of toil and potential risks. This mean that `external-dns` has begun the process to move providers out of tree. See #4347 for more details. -Those who are interested can create a webhook provider based on an *in-tree* provider and after submit a PR to reference it here. +Those who are interested can create a webhook provider based on an _in-tree_ provider and after submit a PR to reference it here. We define the following stability levels for providers: @@ -126,34 +126,34 @@ We define the following stability levels for providers: The following table clarifies the current status of the providers according to the aforementioned stability levels: -| Provider | Status | Maintainers | -| -------- | ------ | ----------- | -| Google Cloud DNS | Stable | | -| AWS Route 53 | Stable | | -| AWS Cloud Map | Beta | | -| Akamai Edge DNS | Beta | | -| AzureDNS | Stable | | -| Civo | Alpha | @alejandrojnm | -| CloudFlare | Beta | | -| DigitalOcean | Alpha | | -| DNSimple | Alpha | | -| PowerDNS | Alpha | | -| CoreDNS | Alpha | | -| Exoscale | Alpha | | -| Oracle Cloud Infrastructure DNS | Alpha | | -| Linode DNS | Alpha | | -| RFC2136 | Alpha | | -| NS1 | Alpha | | -| TransIP | Alpha | | -| OVHcloud | Beta | @rbeuque74 | -| Scaleway DNS | Alpha | @Sh4d1 | -| UltraDNS | Alpha | | -| GoDaddy | Alpha | | -| Gandi | Alpha | @packi | -| IBMCloud | Alpha | @hughhuangzh | -| TencentCloud | Alpha | @Hyzhou | -| Plural | Alpha | @michaeljguarino | -| Pi-hole | Alpha | @tinyzimmer | +| Provider | Status | Maintainers | +| ------------------------------- | ------ | ---------------- | +| Google Cloud DNS | Stable | | +| AWS Route 53 | Stable | | +| AWS Cloud Map | Beta | | +| Akamai Edge DNS | Beta | | +| AzureDNS | Stable | | +| Civo | Alpha | @alejandrojnm | +| CloudFlare | Beta | | +| DigitalOcean | Alpha | | +| DNSimple | Alpha | | +| PowerDNS | Alpha | | +| CoreDNS | Alpha | | +| Exoscale | Alpha | | +| Oracle Cloud Infrastructure DNS | Alpha | | +| Linode DNS | Alpha | | +| RFC2136 | Alpha | | +| NS1 | Alpha | | +| TransIP | Alpha | | +| OVHcloud | Beta | @rbeuque74 | +| Scaleway DNS | Alpha | @Sh4d1 | +| UltraDNS | Alpha | | +| GoDaddy | Alpha | | +| Gandi | Alpha | @packi | +| IBMCloud | Alpha | @hughhuangzh | +| TencentCloud | Alpha | @Hyzhou | +| Plural | Alpha | @michaeljguarino | +| Pi-hole | Alpha | @tinyzimmer | ## Kubernetes version compatibility @@ -220,7 +220,7 @@ The following tutorials are provided: ### Running Locally -See the [contributor guide](docs/contributing/getting-started.md) for details on compiling +See the [contributor guide](docs/contributing/dev-guide.md) for details on compiling from source. #### Setup Steps @@ -244,7 +244,7 @@ Optionally, you can customize the TTL value of the resulting DNS record by using kubectl annotate service nginx "external-dns.alpha.kubernetes.io/ttl=10" ``` -For more details on configuring TTL, see [here](docs/ttl.md). +For more details on configuring TTL, see [here](docs/advanced/ttl.md). Use the internal-hostname annotation to create DNS records with ClusterIP as the target. @@ -289,7 +289,7 @@ The **tutorials** section contains examples, including Ingress resources, and sh # Note -If using a txt registry and attempting to use a CNAME the `--txt-prefix` must be set to avoid conflicts. Changing `--txt-prefix` will result in lost ownership over previously created records. +If using a txt registry and attempting to use a CNAME the `--txt-prefix` must be set to avoid conflicts. Changing `--txt-prefix` will result in lost ownership over previously created records. If `externalIPs` list is defined for a `LoadBalancer` service, this list will be used instead of an assigned load balancer IP to create a DNS record. It's useful when you run bare metal Kubernetes clusters behind NAT or in a similar setup, where a load balancer IP differs from a public IP (e.g. with [MetalLB](https://metallb.universe.tf)). diff --git a/docs/20190708-external-dns-incubator.md b/docs/20190708-external-dns-incubator.md index f86dad5f4..2a49c40f6 100644 --- a/docs/20190708-external-dns-incubator.md +++ b/docs/20190708-external-dns-incubator.md @@ -2,16 +2,15 @@ -- [Move ExternalDNS out of Kubernetes incubator]((#move-externaldns-out-of-kubernetes-incubator)) - - [Summary](#summary) - - [Motivation](#motivation) - - [Goals](#goals) - - [Proposal](#proposal) - - [Details](#details) - - [Graduation Criteria](#graduation-criteria) - - [Maintainers](#maintainers) - - [Release process, artifacts](#release-process-artifacts) - - [Risks and Mitigations](#risks-and-mitigations) +- [Summary](#summary) +- [Motivation](#motivation) + - [Goals](#goals) +- [Proposal](#proposal) +- [Details](#details) + - [Graduation Criteria](#graduation-criteria) + - [Maintainers](#maintainers) + - [Release process, artifacts](#release-process-artifacts) + - [Risks and Mitigations](#risks-and-mitigations) @@ -150,9 +149,11 @@ The following are risks that were identified: We think that the following actions will constitute appropriate mitigations: - Decoupling the providers via an API will allow us to resolve the problem of the providers. Being the project already more than 2 years old and given that there are 18 providers implemented, we possess enough information to define an API that we can be stable in a short timeframe. + - Once this is stable, the problem of testing the providers can be deferred to be a provider's responsibility. This will also reduce the scope of External DNS core code, which means that there will be no need for a further increase of the maintaining team. - We added integration testing for the main cloud providers to the roadmap for the 1.0 release to make sure that we cover the mostly used ones. + - We believe that this item should be tackled independently from the decoupling of providers as it would be capable of generating value independently from the result of the decoupling efforts. - With the move to the Kubernetes incubation, we hope that we will be able to access the testing resources of the Kubernetes project. diff --git a/docs/contributing/sources-and-providers.md b/docs/contributing/sources-and-providers.md index 9d9677cc3..77e32bbe9 100644 --- a/docs/contributing/sources-and-providers.md +++ b/docs/contributing/sources-and-providers.md @@ -26,7 +26,7 @@ All sources live in package `source`. * `ContourIngressRouteSource`: collects all Contour IngressRoutes and returns them as Endpoint objects. The desired DNS name corresponds to the `virtualhost.fqdn` listed within the spec of each IngressRoute object. * `FakeSource`: returns a random list of Endpoints for the purpose of testing providers without having access to a Kubernetes cluster. * `ConnectorSource`: returns a list of Endpoint objects which are served by a tcp server configured through `connector-source-server` flag. -* `CRDSource`: returns a list of Endpoint objects sourced from the spec of CRD objects. For more details refer to [CRD source](crd-source.md) documentation. +* `CRDSource`: returns a list of Endpoint objects sourced from the spec of CRD objects. For more details refer to [CRD source](../sources/crd.md) documentation. * `EmptySource`: returns an empty list of Endpoint objects for the purpose of testing and cleaning out entries. ## Providers diff --git a/docs/deprecation.md b/docs/deprecation.md index adc98ff3c..66db1c8bd 100644 --- a/docs/deprecation.md +++ b/docs/deprecation.md @@ -43,7 +43,7 @@ The proposal must clearly outline the rationale for inclusion, the impact on use The proposal must be formalized by submitting a `docs/proposal/EDP-XXX.md` document in a Pull Request. Pull request must be labeled with `kind/proposal`. -The proposal template location is [here](docs/proposal/design-template.md). The template is quite complete, one can remove any unnecessary or irrelevant section on a specific proposal. +The proposal template location is [here](./proposal/design-template.md). The template is quite complete, one can remove any unnecessary or irrelevant section on a specific proposal. ## Deprecation Process diff --git a/docs/sources/about.md b/docs/sources/about.md index 5a7a6d3bf..1421b9a93 100644 --- a/docs/sources/about.md +++ b/docs/sources/about.md @@ -1,26 +1,30 @@ # About -| Source | Resources | annotation-filter | label-filter | -|---------------------------------|-------------------------------------------------------------------------------|-------------------|--------------| -| ambassador-host | Host.getambassador.io | Yes | Yes | -| connector | | | | -| contour-httpproxy | HttpProxy.projectcontour.io | Yes | | -| cloudfoundry | | | | -| crd | DNSEndpoint.externaldns.k8s.io | Yes | Yes | -| f5-virtualserver | VirtualServer.cis.f5.com | Yes | | -| [gateway-grpcroute](gateway.md) | GRPCRoute.gateway.networking.k8s.io | Yes | Yes | -| [gateway-httproute](gateway.md) | HTTPRoute.gateway.networking.k8s.io | Yes | Yes | -| [gateway-tcproute](gateway.md) | TCPRoute.gateway.networking.k8s.io | Yes | Yes | -| [gateway-tlsroute](gateway.md) | TLSRoute.gateway.networking.k8s.io | Yes | Yes | -| [gateway-udproute](gateway.md) | UDPRoute.gateway.networking.k8s.io | Yes | Yes | -| gloo-proxy | Proxy.gloo.solo.io | | | -| [ingress](ingress.md) | Ingress.networking.k8s.io | Yes | Yes | -| istio-gateway | Gateway.networking.istio.io | Yes | | -| istio-virtualservice | VirtualService.networking.istio.io | Yes | | -| kong-tcpingress | TCPIngress.configuration.konghq.com | Yes | | -| node | Node | Yes | Yes | -| openshift-route | Route.route.openshift.io | Yes | Yes | -| pod | Pod | | | -| [service](service.md) | Service | Yes | Yes | -| skipper-routegroup | RouteGroup.zalando.org | Yes | | -| traefik-proxy | IngressRoute.traefik.io IngressRouteTCP.traefik.io IngressRouteUDP.traefik.io | Yes | | +A source in ExternalDNS defines where DNS records are discovered from within your infrastructure. Each source corresponds to a specific Kubernetes resource or external system that declares DNS names. + +ExternalDNS watches the specified sources for hostname information and uses it to create, update, or delete DNS records accordingly. Multiple sources can be configured simultaneously to support diverse environments. + +| Source | Resources | annotation-filter | label-filter | +| --------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | ------------ | +| ambassador-host | Host.getambassador.io | Yes | Yes | +| connector | | | | +| contour-httpproxy | HttpProxy.projectcontour.io | Yes | | +| cloudfoundry | | | | +| [crd](crd.md) | DNSEndpoint.externaldns.k8s.io | Yes | Yes | +| [f5-virtualserver](f5-virtualserver.md) | VirtualServer.cis.f5.com | Yes | | +| [gateway-grpcroute](gateway.md) | GRPCRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-httproute](gateway.md) | HTTPRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-tcproute](gateway.md) | TCPRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-tlsroute](gateway.md) | TLSRoute.gateway.networking.k8s.io | Yes | Yes | +| [gateway-udproute](gateway.md) | UDPRoute.gateway.networking.k8s.io | Yes | Yes | +| [gloo-proxy](gloo-proxy.md) | Proxy.gloo.solo.io | | | +| [ingress](ingress.md) | Ingress.networking.k8s.io | Yes | Yes | +| [istio-gateway](istio.md) | Gateway.networking.istio.io | Yes | | +| [istio-virtualservice](istio.md) | VirtualService.networking.istio.io | Yes | | +| [kong-tcpingress](kong.md) | TCPIngress.configuration.konghq.com | Yes | | +| [node](nodes.md) | Node | Yes | Yes | +| [openshift-route](openshift.md) | Route.route.openshift.io | Yes | Yes | +| [pod](pod.md) | Pod | | | +| [service](service.md) | Service | Yes | Yes | +| skipper-routegroup | RouteGroup.zalando.org | Yes | | +| [traefik-proxy](traefik-proxy.md) | IngressRoute.traefik.io IngressRouteTCP.traefik.io IngressRouteUDP.traefik.io | Yes | | diff --git a/docs/sources/crd.md b/docs/sources/crd.md index bd21ef005..a5bf3f1bb 100644 --- a/docs/sources/crd.md +++ b/docs/sources/crd.md @@ -1,6 +1,6 @@ # CRD Source -CRD source provides a generic mechanism to manage DNS records in your favourite DNS provider supported by external-dns. +CRD source provides a generic mechanism to manage DNS records in your favorite DNS provider supported by external-dns. ## Details diff --git a/docs/sources/mx-record.md b/docs/sources/mx-record.md index 3abf618a2..7b0c91c75 100644 --- a/docs/sources/mx-record.md +++ b/docs/sources/mx-record.md @@ -1,6 +1,6 @@ # MX record with CRD source -You can create and manage MX records with the help of [CRD source](../contributing/crd-source.md) +You can create and manage MX records with the help of [CRD source](../sources/crd.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. diff --git a/docs/sources/ns-record.md b/docs/sources/ns-record.md index 9baba533e..d842b032c 100644 --- a/docs/sources/ns-record.md +++ b/docs/sources/ns-record.md @@ -1,6 +1,6 @@ # NS record with CRD source -You can create NS records with the help of [CRD source](../contributing/crd-source.md) +You can create NS records with the help of [CRD source](../sources/crd.md) and `DNSEndpoint` CRD. In order to start managing NS records you need to set the `--managed-record-types=NS` flag. diff --git a/docs/sources/txt-record.md b/docs/sources/txt-record.md index 89ba458b4..31f6aa9fa 100644 --- a/docs/sources/txt-record.md +++ b/docs/sources/txt-record.md @@ -1,6 +1,6 @@ # Creating TXT record with CRD source -You can create and manage TXT records with the help of [CRD source](../contributing/crd-source.md) +You can create and manage TXT records with the help of [CRD source](../sources/crd.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. diff --git a/mkdocs.yml b/mkdocs.yml index ed0bbd5e6..486202a9b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,7 +35,7 @@ nav: - FQDN Templating: docs/advanced/fqdn-templating.md - Contributing: - Kubernetes Contributions: CONTRIBUTING.md - - Release: docs/release. + - Release: docs/release.md - Deprecation Policy: docs/deprecation.md - docs/contributing/*