mirrors/external-dns
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/external-dns.git synced 2025-08-05 17:16:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): add mkdocs-macros plugin (#5412)

Browse Source 
* chore(docs): add mkdocs-macros plugin

* chore(docs): add mkdocs-macros plugin

Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com>

* chore(docs): add mkdocs-macros plugin

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>

---------

Signed-off-by: ivan katliarchuk <ivan.katliarchuk@gmail.com>
Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com>
This commit is contained in:
Ivan Ka 2025-05-19 09:33:15 +01:00 committed by GitHub
parent e5141de4d9
commit 84a0c6409f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 315 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/json-yaml-validate.yml vendored
View File

@ -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"

9
Makefile
View File

@ -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

17
docs/contributing/dev-guide.md
View File

@ -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 %]]

1
docs/scripts/requirements.txt
View File

@ -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

35
docs/snippets/digitalocean/deploy-nginx.yaml Normal file
View File

@ -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

64
docs/snippets/digitalocean/extdns-with-rbac.yaml Normal file
View File

@ -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

29
docs/snippets/digitalocean/extdns-without-rbac.yaml Normal file
View File

@ -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

30
docs/snippets/exoscale/extdns.yaml Normal file
View File

@ -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 }}

50
docs/snippets/exoscale/how-to-test.yaml Normal file
View File

@ -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

34
docs/snippets/exoscale/rbac.yaml Normal file
View File

@ -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

26
docs/snippets/security-context/extdns-limited-privilege.yaml Normal file
View File

@ -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"]

129
docs/tutorials/digitalocean.md
View File

@ -52,103 +52,13 @@ env:
### Manifest (for clusters without RBAC enabled)
```yaml
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
[[% include 'digitalocean/extdns-without-rbac.yaml' %]]
```
### Manifest (for clusters with RBAC enabled)
```yaml
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
[[% include 'digitalocean/extdns-with-rbac.yaml' %]]
```
## Deploying an Nginx Service
@ -156,40 +66,7 @@ spec:
Create a service file called 'nginx.yaml' with the following contents:
```yaml
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
[[% include 'digitalocean/deploy-nginx.yaml' %]]
```
Note the annotation on the service; use the same hostname as the DigitalOcean DNS zone created above.

123
docs/tutorials/exoscale.md
View File

@ -21,36 +21,7 @@ Deploying external DNS for Exoscale is actually nearly identical to deploying
it for other providers. This is what a sample `deployment.yaml` looks like:
```yaml
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 }}
[[% include 'exoscale/extdns.yaml' %]]
```
Optional arguments `--exoscale-apizone` and `--exoscale-apienv` define [Exoscale API Zone](https://community.exoscale.com/documentation/platform/exoscale-datacenter-zones/)
@ -61,43 +32,7 @@ Optional arguments `--exoscale-apizone` and `--exoscale-apienv` define [Exoscale
If your cluster is RBAC enabled, you also need to setup the following, before you can run external-dns:
```yaml
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
[[% include 'exoscale/rbac.yaml' %]]
```
## Testing and Verification
@ -107,59 +42,7 @@ subjects:
Spin up a simple nginx HTTP server with the following spec (`kubectl apply -f`):
```yaml
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
[[% include 'exoscale/how-to-test.yaml' %]]
```
**Important!**: Don't run dig, nslookup or similar immediately (until you've

27
docs/tutorials/security-context.md
View File

@ -3,30 +3,5 @@
You can run ExternalDNS with reduced privileges since `v0.5.6` using the following `SecurityContext`.
```yaml
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"]
[[% include 'security-context/limited-privilege.yaml' %]]
```

11
mkdocs.yml
View File

@ -105,3 +105,14 @@ plugins:
- git-revision-date-localized:
type: date
fallback_to_build_date: true
# https://mkdocs-macros-plugin.readthedocs.io/en/latest/
- macros:
include_dir: docs/snippets
# required, as default jinja markers are {{ and }}
# ref: https://mkdocs-macros-plugin.readthedocs.io/en/latest/rendering/#solution-5-altering-the-syntax-of-jinja2-for-mkdocs-macros
j2_block_start_string: '[[%'
j2_block_end_string: '%]]'
j2_variable_start_string: '[['
j2_variable_end_string: ']]'
j2_comment_start_string: '[#'
j2_comment_end_string: '#]'