chore(docs): add mkdocs-macros plugin

.github/workflows/json-yaml-validate.yml

@@ -17,7 +17,9 @@ jobs:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: json-yaml-validate
-        uses: GrantBirki/json-yaml-validate@v3.3.0
+        uses: GrantBirki/json-yaml-validate@v3.2.1 # pin @v3.2.1 bug in 3.3.0: https://github.com/GrantBirki/json-yaml-validate/issues/86
         with:
+          # ref: https://github.com/GrantBirki/json-yaml-validate?tab=readme-ov-file#inputs-
           comment: "true" # enable comment mode
           yaml_exclude_regex: "(charts/external-dns/templates.*|mkdocs.yml)"
+          allow_multiple_documents: "true"

Makefile

@@ -200,5 +200,12 @@ helm-lint:
 	scripts/helm-tools.sh --docs
 
 .PHONY: go-dependency
-go-dependency: ## Dependency maintanance
+#? go-dependency: Dependency maintanance
+go-dependency:
 	go mod tidy
+
+.PHONY: mkdocs-serve
+#? mkdocs-serve: Run the builtin development server for mkdocs
+mkdocs-serve:
+	@$(info "contribute to documentation docs/contributing/dev-guide.md")
+	@mkdocs serve

docs/contributing/dev-guide.md

@@ -304,3 +304,20 @@ Install required dependencies. In order to not to break system packages, we are
 $$ ...
 $$ Serving on http://127.0.0.1:8000/
 ```
+
+### How to add an example snippet
+
+Let's say we are improving tutorial location in `docs/tutorials/aws.md`.
+
+1. Add a snippet to `docs/snippets/aws/<snippet-name>.<snippet-extension>`
+2. Add snippet to a markdown file `docs/tutorials/aws.md`
+
+[[% raw %]]
+
+````md
+  ```extension
+    [[% include 'snippets/aws/<snippet-name>.<snippet-extension>' %]]
+  ```
+````
+
+[[% endraw %]]

docs/scripts/requirements.txt

@@ -1,5 +1,6 @@
 mkdocs-git-revision-date-localized-plugin == 1.2.4
 mkdocs == 1.5.3
+mkdocs-macros-plugin==1.3.7
 mkdocs-material == 9.5.17
 mkdocs-literate-nav == 0.6.1
 mkdocs-same-dir == 0.1.3

docs/snippets/digitalocean/deploy-nginx.yaml

@@ -0,0 +1,35 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        name: nginx
+        ports:
+        - containerPort: 80
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: my-app.example.com
+spec:
+  selector:
+    app: nginx
+  type: LoadBalancer
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80

docs/snippets/digitalocean/extdns-with-rbac.yaml

@@ -0,0 +1,64 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: external-dns
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: external-dns
+rules:
+- apiGroups: [""]
+  resources: ["services","endpoints","pods"]
+  verbs: ["get","watch","list"]
+- apiGroups: ["extensions","networking.k8s.io"]
+  resources: ["ingresses"]
+  verbs: ["get","watch","list"]
+- apiGroups: [""]
+  resources: ["nodes"]
+  verbs: ["list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: external-dns-viewer
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: external-dns
+subjects:
+- kind: ServiceAccount
+  name: external-dns
+  namespace: default
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: external-dns
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      serviceAccountName: external-dns
+      containers:
+      - name: external-dns
+        image: registry.k8s.io/external-dns/external-dns:v0.17.0
+        args:
+        - --source=service # ingress is also possible
+        - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
+        - --provider=digitalocean
+        env:
+        - name: DO_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: DO_TOKEN
+              key: DO_TOKEN

docs/snippets/digitalocean/extdns-without-rbac.yaml

@@ -0,0 +1,29 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: external-dns
+  strategy:
+    type: Recreate
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      containers:
+      - name: external-dns
+        image: registry.k8s.io/external-dns/external-dns:v0.17.0
+        args:
+        - --source=service # ingress is also possible
+        - --domain-filter=example.com # (optional) limit to only example.com domains; change to match the zone created above.
+        - --provider=digitalocean
+        env:
+        - name: DO_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: DO_TOKEN
+              key: DO_TOKEN

docs/snippets/exoscale/extdns.yaml

@@ -0,0 +1,30 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: external-dns
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      # Only use if you're also using RBAC
+      # serviceAccountName: external-dns
+      containers:
+      - name: external-dns
+        image: registry.k8s.io/external-dns/external-dns:v0.17.0
+        args:
+        - --source=ingress # or service or both
+        - --provider=exoscale
+        - --domain-filter={{ my-domain }}
+        - --policy=sync # if you want DNS entries to get deleted as well
+        - --txt-owner-id={{ owner-id-for-this-external-dns }}
+        - --exoscale-apikey={{ api-key}}
+        - --exoscale-apisecret={{ api-secret }}
+        # - --exoscale-apizone={{ api-zone }}
+        # - --exoscale-apienv={{ api-env }}

docs/snippets/exoscale/how-to-test.yaml

@@ -0,0 +1,50 @@
+---
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: nginx
+  annotations:
+    external-dns.alpha.kubernetes.io/target: {{ Elastic-IP-address }}
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: via-ingress.example.com
+    http:
+      paths:
+      - backend:
+          service:
+            name: "nginx"
+            port:
+              number: 80
+        path: /
+        pathType: Prefix
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: nginx
+spec:
+  ports:
+  - port: 80
+    targetPort: 80
+  selector:
+    app: nginx
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx
+spec:
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - image: nginx
+        name: nginx
+        ports:
+        - containerPort: 80

docs/snippets/exoscale/rbac.yaml

@@ -0,0 +1,34 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: external-dns
+  namespace: default
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: external-dns
+rules:
+- apiGroups: [""]
+  resources: ["services","endpoints","pods"]
+  verbs: ["get","watch","list"]
+- apiGroups: ["extensions","networking.k8s.io"]
+  resources: ["ingresses"]
+  verbs: ["get","watch","list"]
+- apiGroups: [""]
+  resources: ["nodes"]
+  verbs: ["list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: external-dns-viewer
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: external-dns
+subjects:
+- kind: ServiceAccount
+  name: external-dns
+  namespace: default

docs/snippets/security-context/extdns-limited-privilege.yaml

@@ -0,0 +1,26 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: external-dns
+spec:
+  strategy:
+    type: Recreate
+  selector:
+    matchLabels:
+      app: external-dns
+  template:
+    metadata:
+      labels:
+        app: external-dns
+    spec:
+      containers:
+      - name: external-dns
+        image: registry.k8s.io/external-dns/external-dns:v0.17.0
+        args:
+        - ... # your arguments here
+        securityContext:
+          runAsNonRoot: true
+          runAsUser: 65534
+          readOnlyRootFilesystem: true
+          capabilities:
+            drop: ["ALL"]