From 9e712e8a9e00b5423d875a3496653f614587f665 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Petazzoni?= Date: Sat, 23 Nov 2024 23:40:35 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20Add=20script=20to=20detect=20dup?= =?UTF-8?q?licate=20markdown=20links;=20fix=20duplicates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When there are multiple reference-style markdown links in the same deck with the same label, they will silently clash - i.e. one will overwrite the other. The problem can become very apparent when using many links like [see the docs][docs] in different slides, where [docs] points to a different URL each time. This commit adds a crude script to detect such duplicates and display them. This script was used to detect a bunch of duplicates and fix them (by making the label unique). There are still a few duplicates left but they point to the same places, so we decided to leave them as-is for now (but might change that later). --- slides/containers/Buildkit.md | 12 +++--- .../containers/Copying_Files_During_Build.md | 4 +- slides/find-duplicate-markdown-links.sh | 5 +++ slides/k8s/argocd.md | 43 ++++++++----------- slides/k8s/bento-intro.md | 37 +++++++--------- slides/k8s/cainjector.md | 5 ++- slides/k8s/cluster-autoscaler.md | 4 +- slides/k8s/healthchecks.md | 7 ++- slides/k8s/operators.md | 2 +- slides/k8s/ytt.md | 12 +++--- 10 files changed, 60 insertions(+), 71 deletions(-) create mode 100755 slides/find-duplicate-markdown-links.sh diff --git a/slides/containers/Buildkit.md b/slides/containers/Buildkit.md index a381ccff..4956df69 100644 --- a/slides/containers/Buildkit.md +++ b/slides/containers/Buildkit.md @@ -40,7 +40,7 @@ - In multi-stage builds, all stages can be built in parallel - (example: https://github.com/jpetazzo/shpod; [before] and [after]) + (example: https://github.com/jpetazzo/shpod; [before][shpod-before-parallel] and [after][shpod-after-parallel]) - Stages are built only when they are necessary @@ -50,8 +50,8 @@ - Files are cached in the builder -[before]: https://github.com/jpetazzo/shpod/blob/c6efedad6d6c3dc3120dbc0ae0a6915f85862474/Dockerfile -[after]: https://github.com/jpetazzo/shpod/blob/d20887bbd56b5fcae2d5d9b0ce06cae8887caabf/Dockerfile +[shpod-before-parallel]: https://github.com/jpetazzo/shpod/blob/c6efedad6d6c3dc3120dbc0ae0a6915f85862474/Dockerfile +[shpod-after-parallel]: https://github.com/jpetazzo/shpod/blob/d20887bbd56b5fcae2d5d9b0ce06cae8887caabf/Dockerfile --- @@ -121,10 +121,10 @@ docker buildx build … \ - Must not use binary downloads with hard-coded architectures! - (streamlining a Dockerfile for multi-arch: [before], [after]) + (streamlining a Dockerfile for multi-arch: [before][shpod-before-multiarch], [after][shpod-after-multiarch]) -[before]: https://github.com/jpetazzo/shpod/blob/d20887bbd56b5fcae2d5d9b0ce06cae8887caabf/Dockerfile -[after]: https://github.com/jpetazzo/shpod/blob/c50789e662417b34fea6f5e1d893721d66d265b7/Dockerfile +[shpod-before-multiarch]: https://github.com/jpetazzo/shpod/blob/d20887bbd56b5fcae2d5d9b0ce06cae8887caabf/Dockerfile +[shpod-after-multiarch]: https://github.com/jpetazzo/shpod/blob/c50789e662417b34fea6f5e1d893721d66d265b7/Dockerfile --- diff --git a/slides/containers/Copying_Files_During_Build.md b/slides/containers/Copying_Files_During_Build.md index cd3696f9..aa4151ca 100644 --- a/slides/containers/Copying_Files_During_Build.md +++ b/slides/containers/Copying_Files_During_Build.md @@ -120,11 +120,11 @@ class: extra-details (and won't end up in the resulting image) -- See the [documentation] for the little details +- See the [documentation][dockerignore] for the little details (exceptions can be made with `!`, multiple directory levels with `**`...) -[documentation]: https://docs.docker.com/engine/reference/builder/#dockerignore-file +[dockerignore]: https://docs.docker.com/engine/reference/builder/#dockerignore-file ??? diff --git a/slides/find-duplicate-markdown-links.sh b/slides/find-duplicate-markdown-links.sh new file mode 100755 index 00000000..34b35dc2 --- /dev/null +++ b/slides/find-duplicate-markdown-links.sh @@ -0,0 +1,5 @@ +#!/bin/sh +for LINK in $(cat */*.md | sed -n 's/^\[\(.*\)\]:.*/\1/p' | sort | uniq -d); do + grep '^\['"$LINK"'\]:' */*.md +done + diff --git a/slides/k8s/argocd.md b/slides/k8s/argocd.md index 14092ff9..3df1d645 100644 --- a/slides/k8s/argocd.md +++ b/slides/k8s/argocd.md @@ -42,22 +42,19 @@ ArgoCD manages **applications** by **syncing** their **live state** with their * - It's OK to use local clusters (kind, minikube...) -- We need to install the ArgoCD CLI ([packages], [binaries]) +- We need to install the ArgoCD CLI ([argocd-packages], [argocd-binaries]) - **Highly recommended:** set up CLI completion! - Of course we'll need a Git service, too -[packages]: https://argo-cd.readthedocs.io/en/stable/cli_installation/ -[binaries]: https://github.com/argoproj/argo-cd/releases/latest - --- ## Setting up ArgoCD - The easiest way is to use upstream YAML manifests -- There is also a [Helm chart][argohelmchart] if we need more customization +- There is also a [Helm chart][argocd-helmchart] if we need more customization .lab[ @@ -70,8 +67,6 @@ ArgoCD manages **applications** by **syncing** their **live state** with their * ] -[argohelmchart]: https://artifacthub.io/packages/helm/argo/argocd-apps - --- ## Logging in with the ArgoCD CLI @@ -137,8 +132,6 @@ ArgoCD manages **applications** by **syncing** their **live state** with their * - Let's have a look at ArgoCD architecture! -[issue14167]: https://github.com/argoproj/argo-cd/issues/14167 - --- class: pic @@ -197,8 +190,6 @@ It is responsible for invoking any user-defined hooks for lifecycle events (*Pre - If you create a new, empty repository, add some manifests to it -[kubercoins]: https://github.com/jpetazzo/kubercoins - --- ## Add an Application @@ -268,8 +259,6 @@ It is responsible for invoking any user-defined hooks for lifecycle events (*Pre 🤔 We're getting errors! -[pollinginterval]: https://argo-cd.readthedocs.io/en/stable/faq/#how-often-does-argo-cd-check-for-changes-to-my-git-or-helm-repository - --- ## Sync failed @@ -457,8 +446,6 @@ Then click on the "CREATE" button (top left). - Today we'll just turn on automated sync for the staging namespace -[rollouts]: https://argoproj.github.io/rollouts/ - --- ## Enabling auto-sync @@ -515,7 +502,7 @@ git push origin staging - Let's how to deploy Helm charts with ArgoCD! -- In the [kubercoins] repository, there is a branch called [helm] +- In the [kubercoins] repository, there is a branch called [helm-branch] - It provides a generic Helm chart, in the [generic-service] directory @@ -523,12 +510,6 @@ git push origin staging - Let's create one application for each of the 5 components of our app! -[cmp]: https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/ -[kubercoins]: https://github.com/jpetazzo/kubercoins -[helm]: https://github.com/jpetazzo/kubercoins/tree/helm -[generic-service]: https://github.com/jpetazzo/kubercoins/tree/helm/generic-service -[values]: https://github.com/jpetazzo/kubercoins/tree/helm/values - --- ## Creating a Helm Application @@ -579,10 +560,6 @@ git push origin staging (blue/green, canary...) -[sso]: https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/#sso -[Dex]: https://github.com/dexidp/dex -[rollouts]: https://argoproj.github.io/argo-rollouts/ - --- ## Acknowledgements @@ -595,6 +572,20 @@ for contributing an initial version and suggestions to this ArgoCD chapter. All remaining typos, mistakes, or approximations are mine (Jérôme Petazzoni). +[argocd-binaries]: https://github.com/argoproj/argo-cd/releases/latest +[argocd-helmchart]: https://artifacthub.io/packages/helm/argo/argocd-apps +[argocd-packages]: https://argo-cd.readthedocs.io/en/stable/cli_installation/ +[cmp]: https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/ +[Dex]: https://github.com/dexidp/dex +[generic-service]: https://github.com/jpetazzo/kubercoins/tree/helm/generic-service +[helm-branch]: https://github.com/jpetazzo/kubercoins/tree/helm +[issue14167]: https://github.com/argoproj/argo-cd/issues/14167 +[kubercoins]: https://github.com/jpetazzo/kubercoins +[pollinginterval]: https://argo-cd.readthedocs.io/en/stable/faq/#how-often-does-argo-cd-check-for-changes-to-my-git-or-helm-repository +[rollouts]: https://argoproj.github.io/rollouts/ +[sso]: https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/#sso +[values]: https://github.com/jpetazzo/kubercoins/tree/helm/values + ??? :EN:- Implementing gitops with ArgoCD diff --git a/slides/k8s/bento-intro.md b/slides/k8s/bento-intro.md index 1e8814d6..4eccc362 100644 --- a/slides/k8s/bento-intro.md +++ b/slides/k8s/bento-intro.md @@ -40,9 +40,6 @@ class: extra-details - We're going to use Bento here, but Redpanda Connect should work fine too! -[redpanda-acquires-benthos]: https://www.redpanda.com/press/redpanda-acquires-benthos -[warpstream-forks-benthos]: https://www.warpstream.com/blog/announcing-bento-the-open-source-fork-of-the-project-formerly-known-as-benthos - --- ## Bento concepts @@ -126,7 +123,7 @@ Let's break down the work: - We need to find which `input` and `output` to use -- Check the list with `bento list` or the [documentation] +- Check the list with `bento list` or the [documentation][bento-inputs] - Then run `bento create INPUTNAME/PIPELINENAME/OUTPUTNAME` @@ -139,8 +136,6 @@ Let's break down the work: (Everything else can go away!) -[documentation]: https://warpstreamlabs.github.io/bento/docs/components/inputs/about/ - --- ## Resulting configuration @@ -250,9 +245,7 @@ pipeline: - mapping: root = deleted() ``` -(See the [docs][switch-docs] for details about the `switch` processor.) - -[switch-docs]: https://warpstreamlabs.github.io/bento/docs/components/processors/switch/ +(See the [docs][bento-switch] for details about the `switch` processor.) --- @@ -293,8 +286,6 @@ Option 1: `bento create redis_list//http_server` Option 2: [read the docs][output-http-server] -[output-http-server]: https://warpstreamlabs.github.io/bento/docs/components/outputs/http_server - --- ## 🙋 Choose your own adventure @@ -359,8 +350,6 @@ It's also possible to batch, stream... - Finally, we'll configure an [enrichment workflow][enrichment] in Bento -[enrichment]: https://warpstreamlabs.github.io/bento/cookbooks/enrichments/ - --- ## Test our prompt @@ -409,8 +398,6 @@ We need to set up: - a `result_map` to transform the Ollama response -[enrichment]: https://warpstreamlabs.github.io/bento/cookbooks/enrichments/ - --- ## Without the `branch` processor @@ -578,15 +565,11 @@ Post "http://ollama...": context deadline exceeded How should we address errors? -- Option 1: increase the timeout in the [http][doc-http] processor +- Option 1: increase the timeout in the [http][bento-http] processor -- Option 2: use a [retry][doc-retry] processor in the pipeline +- Option 2: use a [retry][bento-retry] processor in the pipeline -- Option 3: use a [reject_errored][doc-reject] output - -[doc-http]: https://warpstreamlabs.github.io/bento/docs/components/processors/http/ -[doc-retry]: https://warpstreamlabs.github.io/bento/docs/components/processors/retry -[doc-reject]: https://warpstreamlabs.github.io/bento/docs/components/outputs/reject_errored +- Option 3: use a [reject_errored][bento-reject] output --- @@ -628,3 +611,13 @@ class: title 🤔 What's that about? +[bento-http]: https://warpstreamlabs.github.io/bento/docs/components/processors/http/ +[bento-inputs]: https://warpstreamlabs.github.io/bento/docs/components/inputs/about/ +[bento-reject]: https://warpstreamlabs.github.io/bento/docs/components/outputs/reject_errored +[bento-retry]: https://warpstreamlabs.github.io/bento/docs/components/processors/retry +[bento-switch]: https://warpstreamlabs.github.io/bento/docs/components/processors/switch/ +[enrichment]: https://warpstreamlabs.github.io/bento/cookbooks/enrichments/ +[output-http-server]: https://warpstreamlabs.github.io/bento/docs/components/outputs/http_server +[redpanda-acquires-benthos]: https://www.redpanda.com/press/redpanda-acquires-benthos +[warpstream-forks-benthos]: https://www.warpstream.com/blog/announcing-bento-the-open-source-fork-of-the-project-formerly-known-as-benthos + diff --git a/slides/k8s/cainjector.md b/slides/k8s/cainjector.md index a6b5f4d7..654e63ba 100644 --- a/slides/k8s/cainjector.md +++ b/slides/k8s/cainjector.md @@ -55,6 +55,7 @@ `cert-manager.io/allow-direct-injection: "true"` -- See [cert-manager documentation][docs] for details +- See [cert-manager documentation] for details + +[cert-manager documentation]: https://cert-manager.io/docs/concepts/ca-injector/ -[docs]: https://cert-manager.io/docs/concepts/ca-injector/ diff --git a/slides/k8s/cluster-autoscaler.md b/slides/k8s/cluster-autoscaler.md index 4c19a4ee..f30a0825 100644 --- a/slides/k8s/cluster-autoscaler.md +++ b/slides/k8s/cluster-autoscaler.md @@ -272,9 +272,9 @@ This can be overridden by setting the annotation: - Can express `minAvailable` or `maxUnavailable` -- See [documentation] for details and examples +- See [documentation][doc-pdb] for details and examples -[documentation]: https://kubernetes.io/docs/tasks/run-application/configure-pdb/ +[doc-pdb]: https://kubernetes.io/docs/tasks/run-application/configure-pdb/ --- diff --git a/slides/k8s/healthchecks.md b/slides/k8s/healthchecks.md index e37f4206..9725777b 100644 --- a/slides/k8s/healthchecks.md +++ b/slides/k8s/healthchecks.md @@ -158,8 +158,6 @@ - Let's see the specific details for each of them! -[grpc]: https://grpc.github.io/grpc/core/md_doc_health-checking.html - --- ## `httpGet` @@ -296,8 +294,6 @@ class: extra-details - Leverages standard [GRPC Health Checking Protocol][grpc] -[grpc]: https://grpc.github.io/grpc/core/md_doc_health-checking.html - --- ## Timing and thresholds @@ -513,7 +509,10 @@ class: extra-details - Sometimes it can also make sense to embed a web server in the worker +[grpc]: https://grpc.github.io/grpc/core/md_doc_health-checking.html + ??? :EN:- Using healthchecks to improve availability :FR:- Utiliser des *healthchecks* pour améliorer la disponibilité + diff --git a/slides/k8s/operators.md b/slides/k8s/operators.md index 6a901936..49e825ca 100644 --- a/slides/k8s/operators.md +++ b/slides/k8s/operators.md @@ -40,7 +40,7 @@ using Kubernetes manifests and tooling.* - etc. -[ArgoCD]: https://github.com/argoproj/argo-cd +[ArgoCD]: https://argoproj.github.io/cd/ [AWS]: https://aws-controllers-k8s.github.io/community/docs/community/services/ [cert-manager]: https://cert-manager.io/ [External Secrets Operator]: https://external-secrets.io/ diff --git a/slides/k8s/ytt.md b/slides/k8s/ytt.md index 49351576..4a6b054b 100644 --- a/slides/k8s/ytt.md +++ b/slides/k8s/ytt.md @@ -245,9 +245,9 @@ - command-line flags -- Precedence of the different methods is defined in the [docs] +- Precedence of the different methods is defined in the [docs][data-values-merge-order] -[docs]: https://carvel.dev/ytt/docs/v0.41.0/ytt-data-values/#data-values-merge-order +[data-values-merge-order]: https://carvel.dev/ytt/docs/v0.41.0/ytt-data-values/#data-values-merge-order --- @@ -462,13 +462,13 @@ spec: - By default, `#@overlay/match` must find *exactly* one match - (that can be changed by specifying `expects=...`, `missing_ok=True`... see [docs]) + (that can be changed by specifying `expects=...`, `missing_ok=True`... see [docs][docs-ytt-overlaymatch]) - By default, the specified fields (here, `spec.replicas`) must exist (that can also be changed by annotating the optional fields) -[docs]: https://carvel.dev/ytt/docs/v0.41.0/lang-ref-ytt-overlay/#overlaymatch +[docs-ytt-overlaymatch]: https://carvel.dev/ytt/docs/v0.41.0/lang-ref-ytt-overlay/#overlaymatch --- @@ -573,7 +573,7 @@ metadata: ## Overlays vs data values -- The documentation has a [detailed discussion][docs] about this question +- The documentation has a [detailed discussion][data-values-vs-overlays] about this question - In short: @@ -587,7 +587,7 @@ metadata: (keeping in mind that overlays are harder to write/understand/maintain) -[docs]: https://carvel.dev/ytt/docs/v0.41.0/data-values-vs-overlays/ +[data-values-vs-overlays]: https://carvel.dev/ytt/docs/v0.41.0/data-values-vs-overlays/ ---