From 3773411a5ad3146008f6a059cd7e80a9a7f5d465 Mon Sep 17 00:00:00 2001 From: Michel Loiseleur Date: Wed, 10 Apr 2024 14:25:44 +0200 Subject: [PATCH 1/6] docs: upgrade mkdocs and fix warnings --- README.md | 4 ++-- docs/contributing/getting-started.md | 10 +++++----- docs/faq.md | 8 ++++---- docs/scripts/copy_docs.sh | 2 ++ docs/scripts/requirements.txt | 10 +++++----- docs/tutorials/aws.md | 2 +- docs/tutorials/mx-record.md | 2 +- docs/tutorials/ns-record.md | 2 +- docs/tutorials/webhook-provider.md | 2 +- external-dns.code-workspace | 7 +++++++ mkdocs.yml | 5 +++-- 11 files changed, 32 insertions(+), 22 deletions(-) create mode 100644 external-dns.code-workspace diff --git a/README.md b/README.md index 6efa7b4df..8123f40ae 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,7 @@ The following tutorials are provided: * [UltraDNS](docs/tutorials/ultradns.md) * [GoDaddy](docs/tutorials/godaddy.md) * [Gandi](docs/tutorials/gandi.md) -* [SafeDNS](docs/tutorials/UKFast_SafeDNS.md) +* [SafeDNS](docs/tutorials/ANS_Group_SafeDNS.md) * [IBM Cloud](docs/tutorials/ibmcloud.md) * [Nodes as source](docs/tutorials/nodes.md) * [TencentCloud](docs/tutorials/tencentcloud.md) @@ -278,7 +278,7 @@ Now you can experiment and watch how ExternalDNS makes sure that your DNS record * Add another Service to create more DNS records. * Remove Services to clean up your managed zone. -The [tutorials](docs/tutorials) section contains examples, including Ingress resources, and shows you how to set up ExternalDNS in different environments such as other cloud providers and alternative Ingress controllers. +The **tutorials** section contains examples, including Ingress resources, and shows you how to set up ExternalDNS in different environments such as other cloud providers and alternative Ingress controllers. # Note diff --git a/docs/contributing/getting-started.md b/docs/contributing/getting-started.md index c9bb78a36..3f09c927f 100644 --- a/docs/contributing/getting-started.md +++ b/docs/contributing/getting-started.md @@ -29,17 +29,17 @@ make build.push IMAGE=your-registry/external-dns # Design -ExternalDNS's sources of DNS records live in package [source](../../source). They implement the `Source` interface that has a single method `Endpoints` which returns the represented source's objects converted to `Endpoints`. Endpoints are just a tuple of DNS name and target where target can be an IP or another hostname. +ExternalDNS's sources of DNS records live in package [source](https://github.com/kubernetes-sigs/external-dns/tree/master/source). They implement the `Source` interface that has a single method `Endpoints` which returns the represented source's objects converted to `Endpoints`. Endpoints are just a tuple of DNS name and target where target can be an IP or another hostname. For example, the `ServiceSource` returns all Services converted to `Endpoints` where the hostname is the value of the `external-dns.alpha.kubernetes.io/hostname` annotation and the target is the IP of the load balancer or where the hostname is the value of the `external-dns.alpha.kubernetes.io/internal-hostname` annotation and the target is the IP of the service ClusterIP. -This list of endpoints is passed to the [Plan](../../plan) which determines the difference between the current DNS records and the desired list of `Endpoints`. +This list of endpoints is passed to the [Plan](https://github.com/kubernetes-sigs/external-dns/tree/master/plan) which determines the difference between the current DNS records and the desired list of `Endpoints`. -Once the difference has been figured out the list of intended changes is passed to a `Registry` which live in the [registry](../../registry) package. The registry is a wrapper and access point to DNS provider. Registry implements the ownership concept by marking owned records and filtering out records not owned by ExternalDNS before passing them to DNS provider. +Once the difference has been figured out the list of intended changes is passed to a `Registry` which live in the [registry](https://github.com/kubernetes-sigs/external-dns/tree/master/registry) package. The registry is a wrapper and access point to DNS provider. Registry implements the ownership concept by marking owned records and filtering out records not owned by ExternalDNS before passing them to DNS provider. -The [provider](../../provider) is the adapter to the DNS provider, e.g. Google Cloud DNS. It implements two methods: `ApplyChanges` to apply a set of changes filtered by `Registry` and `Records` to retrieve the current list of records from the DNS provider. +The [provider](https://github.com/kubernetes-sigs/external-dns/tree/master/provider) is the adapter to the DNS provider, e.g. Google Cloud DNS. It implements two methods: `ApplyChanges` to apply a set of changes filtered by `Registry` and `Records` to retrieve the current list of records from the DNS provider. -The orchestration between the different components is controlled by the [controller](../../controller). +The orchestration between the different components is controlled by the [controller](https://github.com/kubernetes-sigs/external-dns/tree/master/controller). You can pick which `Source` and `Provider` to use at runtime via the `--source` and `--provider` flags, respectively. diff --git a/docs/faq.md b/docs/faq.md index 95323580d..2e51d4cc6 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -273,7 +273,7 @@ spec: Sometimes you need to run an internal and an external dns service. The internal one should provision hostnames used on the internal network (perhaps inside a VPC), and the external one to expose DNS to the internet. -To do this with ExternalDNS you can use the `--ingress-class` flag to specifically tie an instance of ExternalDNS to an instance of a ingress controller. +To do this with ExternalDNS you can use the `--ingress-class` flag to specifically tie an instance of ExternalDNS to an instance of a ingress controller. Let's assume you have two ingress controllers, `internal` and `external`. You can then start two ExternalDNS providers, one with `--ingress-class=internal` and one with `--ingress-class=external`. @@ -295,8 +295,8 @@ Note: the `--ingress-class` flag cannot be used at the same time as the `--annot **Performance considerations** Filtering based on ingress class name or annotations means that the external-dns controller will receive all resources of that kind and then filter on the client-side. -In larger clusters with many resources which change frequently this can cause performance issues. -If only some resources need to be managed by an instance of external-dns then label filtering can be used instead of ingress class filtering (or legacy annotation filtering). +In larger clusters with many resources which change frequently this can cause performance issues. +If only some resources need to be managed by an instance of external-dns then label filtering can be used instead of ingress class filtering (or legacy annotation filtering). This means that only those resources which match the selector specified in `--label-filter` will be passed to the controller. ### How do I specify that I want the DNS record to point to either the Node's public or private IP when it has both? @@ -331,7 +331,7 @@ registry.k8s.io/external-dns/external-dns As tags, you use the external-dns release of choice(i.e. `v0.7.6`). A `latest` tag is not provided in the container registry. -If you wish to build your own image, you can use the provided [.ko.yaml](../.ko.yaml) as a starting point. +If you wish to build your own image, you can use the provided [.ko.yaml](https://github.com/kubernetes-sigs/external-dns/blob/master/.ko.yaml) as a starting point. ### Which architectures are supported? diff --git a/docs/scripts/copy_docs.sh b/docs/scripts/copy_docs.sh index 7e114b84a..114c807e5 100755 --- a/docs/scripts/copy_docs.sh +++ b/docs/scripts/copy_docs.sh @@ -7,3 +7,5 @@ cp CONTRIBUTING.md code-of-conduct.md ./docs/ cp LICENSE ./docs/LICENSE.md cp README.md ./docs/index.md + +sed -i -e 's#docs/##g' ./docs/index.md diff --git a/docs/scripts/requirements.txt b/docs/scripts/requirements.txt index cacaecf19..0cd306aee 100644 --- a/docs/scripts/requirements.txt +++ b/docs/scripts/requirements.txt @@ -1,5 +1,5 @@ -mkdocs-git-revision-date-localized-plugin == 1.0.0 -mkdocs == 1.3.0 -mkdocs-material == 8.2.8 -mkdocs-literate-nav == 0.4.0 -mike == 1.1.2 \ No newline at end of file +mkdocs-git-revision-date-localized-plugin == 1.2.4 +mkdocs == 1.5.3 +mkdocs-material == 9.5.17 +mkdocs-literate-nav == 0.6.1 +mike == 2.0.0 diff --git a/docs/tutorials/aws.md b/docs/tutorials/aws.md index 890267f9b..2e202da72 100644 --- a/docs/tutorials/aws.md +++ b/docs/tutorials/aws.md @@ -870,7 +870,7 @@ Note: ExternalDNS does not support creating healthchecks, and assumes that ` Date: Wed, 10 Apr 2024 14:35:20 +0200 Subject: [PATCH 2/6] update python version --- .github/workflows/docs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 8c46892a8..218681fd9 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,9 +18,9 @@ jobs: with: fetch-depth: 0 - - uses: actions/setup-python@v5.1.0 + - uses: actions/setup-python@v5 with: - python-version: "3.10" + python-version: "3.12" cache: "pip" cache-dependency-path: "./docs/scripts/requirements.txt" From 3b9d9e5f39a45d91dc3c8e3ff5e235ce9b0f0daf Mon Sep 17 00:00:00 2001 From: Michel Loiseleur Date: Sun, 28 Apr 2024 13:23:44 +0200 Subject: [PATCH 3/6] fix: gh actions sha --- .github/workflows/docs.yaml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 218681fd9..6aa30d180 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,15 +18,19 @@ jobs: with: fetch-depth: 0 - - uses: actions/setup-python@v5 + - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0 with: python-version: "3.12" cache: "pip" cache-dependency-path: "./docs/scripts/requirements.txt" - - uses: actions/setup-go@v5 + - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0 with: +<<<<<<< HEAD:.github/workflows/docs.yaml go-version: '^1.22.2' +======= + go-version-file: 'go.mod' +>>>>>>> 4e305930 (fix: gh actions sha):.github/workflows/docs.yml - run: | pip install -r docs/scripts/requirements.txt From a69bb161a9e5bce1c43cb178a8b20b8bde074f5f Mon Sep 17 00:00:00 2001 From: Michel Loiseleur Date: Sun, 28 Apr 2024 13:27:27 +0200 Subject: [PATCH 4/6] fix rebase --- .github/workflows/docs.yaml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 6aa30d180..d1aa2defe 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -6,6 +6,7 @@ on: - "v*" permissions: {} + jobs: release_docs: permissions: @@ -26,11 +27,7 @@ jobs: - uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0 with: -<<<<<<< HEAD:.github/workflows/docs.yaml - go-version: '^1.22.2' -======= go-version-file: 'go.mod' ->>>>>>> 4e305930 (fix: gh actions sha):.github/workflows/docs.yml - run: | pip install -r docs/scripts/requirements.txt From 233c46e83e9099667396e313f2a466678664f4af Mon Sep 17 00:00:00 2001 From: Michel Loiseleur Date: Mon, 3 Jun 2024 09:18:51 +0200 Subject: [PATCH 5/6] mkdocs on root level --- .github/workflows/docs.yaml | 5 ---- LICENSE => LICENSE.md | 0 docs/scripts/copy_docs.sh | 11 -------- docs/scripts/docs.go | 48 ----------------------------------- docs/scripts/requirements.txt | 1 + mkdocs.yml | 42 ++++++++++++++++-------------- 6 files changed, 24 insertions(+), 83 deletions(-) rename LICENSE => LICENSE.md (100%) delete mode 100755 docs/scripts/copy_docs.sh delete mode 100644 docs/scripts/docs.go diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index d1aa2defe..7240f0bcb 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -32,11 +32,6 @@ jobs: - run: | pip install -r docs/scripts/requirements.txt - - name: setup - run: | - ./docs/scripts/copy_docs.sh - go run ./docs/scripts/docs.go - - name: Configure Git user run: | git config --local user.email "github-actions[bot]@users.noreply.github.com" diff --git a/LICENSE b/LICENSE.md similarity index 100% rename from LICENSE rename to LICENSE.md diff --git a/docs/scripts/copy_docs.sh b/docs/scripts/copy_docs.sh deleted file mode 100755 index 114c807e5..000000000 --- a/docs/scripts/copy_docs.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/bash - -set -eo pipefail - -cp CONTRIBUTING.md code-of-conduct.md ./docs/ - -cp LICENSE ./docs/LICENSE.md - -cp README.md ./docs/index.md - -sed -i -e 's#docs/##g' ./docs/index.md diff --git a/docs/scripts/docs.go b/docs/scripts/docs.go deleted file mode 100644 index 59fdbd43f..000000000 --- a/docs/scripts/docs.go +++ /dev/null @@ -1,48 +0,0 @@ -/* -Copyright 2017 The Kubernetes Authors. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -*/ - -package main - -import ( - "log" - "os" - "strings" -) - -func removeLinkPrefixInIndex() { - content, err := os.ReadFile("./docs/index.md") - if err != nil { - log.Fatalf("Could not read index.md file. Make sure to run copy_docs.sh script first. Original error: %s", err) - } - - updatedContent := strings.ReplaceAll(string(content), "](./docs/", "](") - updatedContent = strings.ReplaceAll(updatedContent, "](docs/", "](") - updatedContent = strings.ReplaceAll(updatedContent, "docs/img/external-dns.png", "img/external-dns.png") - - f, err := os.OpenFile("./docs/index.md", os.O_RDWR, 0o644) - if err != nil { - log.Fatalf("Could not open index.md file to update content. Original error: %s", err) - } - defer f.Close() - - if _, err := f.WriteString(updatedContent); err != nil { - log.Fatalf("Failed writing links update to index.md. Original error: %s", err) - } -} - -func main() { - removeLinkPrefixInIndex() -} diff --git a/docs/scripts/requirements.txt b/docs/scripts/requirements.txt index 0cd306aee..5564c82cd 100644 --- a/docs/scripts/requirements.txt +++ b/docs/scripts/requirements.txt @@ -2,4 +2,5 @@ mkdocs-git-revision-date-localized-plugin == 1.2.4 mkdocs == 1.5.3 mkdocs-material == 9.5.17 mkdocs-literate-nav == 0.6.1 +mkdocs-same-dir == 0.1.3 mike == 2.0.0 diff --git a/mkdocs.yml b/mkdocs.yml index 9d8762e90..82d55858c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,38 +1,41 @@ site_name: external-dns site_author: external-dns maintainers - repo_name: kubernetes-sigs/external-dns repo_url: https://github.com/kubernetes-sigs/external-dns/ - trademark: https://www.linuxfoundation.org/legal/trademark-usage +docs_dir: . + nav: - - index.md + - README.md + - Chart: + - About: charts/external-dns/README.md + - Changelog: charts/external-dns/CHANGELOG.md - About: - - FAQ: faq.md - - Out of Incubator: 20190708-external-dns-incubator.md + - FAQ: docs/faq.md + - Out of Incubator: docs/20190708-external-dns-incubator.md - Code of Conduct: code-of-conduct.md - License: LICENSE.md - - Tutorials: tutorials/ + - Tutorials: docs/tutorials/* - Annotations: - - About: annotations/annotations.md + - About: docs/annotations/annotations.md - Sources: - - About: sources/sources.md - - Gateway: sources/gateway.md - - Ingress: sources/ingress.md - - Service: sources/service.md + - About: docs/sources/sources.md + - Gateway: docs/sources/gateway.md + - Ingress: docs/sources/ingress.md + - Service: docs/sources/service.md - Registries: - - About: registry/registry.md - - TXT: registry/txt.md - - DynamoDB: registry/dynamodb.md + - About: docs/registry/registry.md + - TXT: docs/registry/txt.md + - DynamoDB: docs/registry/dynamodb.md - Advanced Topics: - - Initial Design: initial-design.md - - TTL: ttl.md - - MultiTarget: proposal/multi-target.md + - Initial Design: docs/initial-design.md + - TTL: docs/ttl.md + - MultiTarget: docs/proposal/multi-target.md - Contributing: - Kubernetes Contributions: CONTRIBUTING.md - - Release: release.md - - contributing/* + - Release: docs/release.md + - docs/contributing/* theme: name: material @@ -94,6 +97,7 @@ markdown_extensions: custom_checkbox: true plugins: + - same-dir - search - literate-nav - git-revision-date-localized: From f7b623c82bdbd24b687b25d873dac0b6278f7598 Mon Sep 17 00:00:00 2001 From: Michel Loiseleur Date: Fri, 7 Jun 2024 08:18:23 +0200 Subject: [PATCH 6/6] add a link to documentation --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 8123f40ae..055e1635a 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ hide: ExternalDNS synchronizes exposed Kubernetes Services and Ingresses with DNS providers. +## Documentation + +This README is a part of the complete documentation, available [here](https://kubernetes-sigs.github.io/external-dns/). + ## What It Does 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/).