Skip to content

Commit 799da19

Browse files
author
CodingWizKid
committed
add readme
1 parent 3915572 commit 799da19

File tree

2 files changed

+245
-10
lines changed

2 files changed

+245
-10
lines changed

‎README.md

Lines changed: 236 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,236 @@
1-
# external-dns-stackit-webhook
2-
Repo for providing the webhook for our stackit dns integration with external dns
1+
# STACKIT Webhook - ExternalDNS
2+
3+
⚠️ CAUTION: This Webhook is designed on an unreleased edition of
4+
[ExternalDNS](https://github.com/kubernetes-sigs/external-dns), specifically focusing on the novel integration
5+
method via webhooks, as deliberated and constructed
6+
in [PR-3063](https://github.com/kubernetes-sigs/external-dns/pull/3063).
7+
8+
ExternalDNS serves as an add-on for Kubernetes designed to automate the management of Domain Name System (DNS)
9+
records for Kubernetes services by utilizing various DNS providers. While Kubernetes traditionally manages DNS
10+
records internally, ExternalDNS augments this functionality by transferring the responsibility of DNS records
11+
management to an external DNS provider such as STACKIT. Consequently, the STACKIT webhook enables the management
12+
of your STACKIT domains within your Kubernetes cluster using
13+
[ExternalDNS](https://github.com/kubernetes-sigs/external-dns).
14+
15+
For utilizing ExternalDNS with STACKIT, it is mandatory to establish a STACKIT project, a service account
16+
within the project, generate an authentication token for the service account, authorize the service account
17+
to create and read dns zones, and finally, establish a STACKIT zone.
18+
19+
## Kubernetes Deployment
20+
The STACKIT webhook is presented as a standard Open Container Initiative (OCI) image released in the
21+
[GitHub container registry](https://github.com/stackitcloud/external-dns-stackit-webhook/pkgs/container/external-dns-stackit-webhook).
22+
The deployment is compatible with all Kubernetes-supported methods. The subsequent example
23+
demonstrates the deployment as a
24+
[sidecar container](https://kubernetes.io/docs/concepts/workloads/pods/#workload-resources-for-managing-pods)
25+
within the ExternalDNS pod.
26+
27+
```shell
28+
kubectl create secret generic external-dns-stackit-webhook --from-literal=auth-token='<Your-Token>'
29+
30+
kubectl apply -f - <<EOF
31+
apiVersion: v1
32+
kind: ServiceAccount
33+
metadata:
34+
name: external-dns
35+
namespace: default
36+
labels:
37+
app.kubernetes.io/name: external-dns
38+
app.kubernetes.io/instance: external-dns
39+
---
40+
apiVersion: rbac.authorization.k8s.io/v1
41+
kind: ClusterRole
42+
metadata:
43+
name: external-dns
44+
labels:
45+
app.kubernetes.io/name: external-dns
46+
app.kubernetes.io/instance: external-dns
47+
rules:
48+
- apiGroups: [""]
49+
resources: ["nodes"]
50+
verbs: ["list","watch"]
51+
- apiGroups: [""]
52+
resources: ["pods"]
53+
verbs: ["get","watch","list"]
54+
- apiGroups: [""]
55+
resources: ["services","endpoints"]
56+
verbs: ["get","watch","list"]
57+
- apiGroups: ["extensions","networking.k8s.io"]
58+
resources: ["ingresses"]
59+
verbs: ["get","watch","list"]
60+
---
61+
apiVersion: rbac.authorization.k8s.io/v1
62+
kind: ClusterRoleBinding
63+
metadata:
64+
name: external-dns-viewer
65+
labels:
66+
app.kubernetes.io/name: external-dns
67+
app.kubernetes.io/instance: external-dns
68+
roleRef:
69+
apiGroup: rbac.authorization.k8s.io
70+
kind: ClusterRole
71+
name: external-dns
72+
subjects:
73+
- kind: ServiceAccount
74+
name: external-dns
75+
namespace: default
76+
---
77+
apiVersion: v1
78+
kind: Service
79+
metadata:
80+
name: external-dns
81+
namespace: default
82+
labels:
83+
app.kubernetes.io/name: external-dns
84+
app.kubernetes.io/instance: external-dns
85+
spec:
86+
type: ClusterIP
87+
selector:
88+
app.kubernetes.io/name: external-dns
89+
app.kubernetes.io/instance: external-dns
90+
ports:
91+
- name: http
92+
port: 7979
93+
targetPort: http
94+
protocol: TCP
95+
---
96+
apiVersion: apps/v1
97+
kind: Deployment
98+
metadata:
99+
name: external-dns
100+
namespace: default
101+
labels:
102+
app.kubernetes.io/name: external-dns
103+
app.kubernetes.io/instance: external-dns
104+
spec:
105+
replicas: 1
106+
selector:
107+
matchLabels:
108+
app.kubernetes.io/name: external-dns
109+
app.kubernetes.io/instance: external-dns
110+
strategy:
111+
type: Recreate
112+
template:
113+
metadata:
114+
labels:
115+
app.kubernetes.io/name: external-dns
116+
app.kubernetes.io/instance: external-dns
117+
spec:
118+
serviceAccountName: external-dns
119+
securityContext:
120+
fsGroup: 65534
121+
containers:
122+
- name: external-dns
123+
securityContext:
124+
capabilities:
125+
drop:
126+
- ALL
127+
readOnlyRootFilesystem: true
128+
runAsNonRoot: true
129+
runAsUser: 65534
130+
image: registry.k8s.io/external-dns/external-dns:v0.13.5 # insert the image with the webhook implementation here. 0.13.5 does not provide it yet.
131+
imagePullPolicy: IfNotPresent
132+
args:
133+
- --log-level=info
134+
- --log-format=text
135+
- --interval=1m
136+
- --source=service
137+
- --source=ingress
138+
- --policy=sync
139+
- --provider=webhook
140+
- --webhook-provider-url="http://localhost:8888"
141+
ports:
142+
- name: http
143+
protocol: TCP
144+
containerPort: 7979
145+
livenessProbe:
146+
failureThreshold: 2
147+
httpGet:
148+
path: /healthz
149+
port: http
150+
initialDelaySeconds: 10
151+
periodSeconds: 10
152+
successThreshold: 1
153+
timeoutSeconds: 5
154+
readinessProbe:
155+
failureThreshold: 6
156+
httpGet:
157+
path: /healthz
158+
port: http
159+
initialDelaySeconds: 5
160+
periodSeconds: 10
161+
successThreshold: 1
162+
timeoutSeconds: 5
163+
- name: webhook
164+
securityContext:
165+
capabilities:
166+
drop:
167+
- ALL
168+
readOnlyRootFilesystem: true
169+
runAsNonRoot: true
170+
runAsUser: 65534
171+
image: ghcr.io/stackitcloud/external-dns-stackit-webhook:v0.1.0
172+
imagePullPolicy: IfNotPresent
173+
args:
174+
- --project-id="c158c736-0300-4044-95c4-b7d404279b35" # your project id
175+
ports:
176+
- name: http
177+
protocol: TCP
178+
containerPort: 8888
179+
livenessProbe:
180+
failureThreshold: 2
181+
httpGet:
182+
path: /healthz
183+
port: http
184+
initialDelaySeconds: 10
185+
periodSeconds: 10
186+
successThreshold: 1
187+
timeoutSeconds: 5
188+
readinessProbe:
189+
failureThreshold: 6
190+
httpGet:
191+
path: /healthz
192+
port: http
193+
initialDelaySeconds: 5
194+
periodSeconds: 10
195+
successThreshold: 1
196+
timeoutSeconds: 5
197+
env:
198+
- name: AUTH_TOKEN
199+
valueFrom:
200+
secretKeyRef:
201+
name: external-dns-stackit-webhook
202+
key: auth-token
203+
EOF
204+
```
205+
206+
## Configuration
207+
The configuration of the STACKIT webhook can be accomplished through command line arguments and environment variables.
208+
Below are the options that are available.
209+
- `--project-id`/`PROJECT_ID` (required): Specifies the project id of the STACKIT project.
210+
- `--auth-token`/`AUTH_TOKEN` (required): Defines the authentication token for the STACKIT API.
211+
- `--worker`/`WORKER` (optional): Specifies the number of workers to employ for querying the API. Given that we
212+
need to iterate over all zones and records, it can be parallelized. However, it is important to avoid
213+
setting this number excessively high to prevent receiving 429 rate limiting from the API (default 10).
214+
- `--base-url`/`BASE_URL` (optional): Identifies the Base URL for utilizing the API (default "https://dns.api.stackit.cloud").
215+
- `--api-port`/`API_PORT` (optional): Specifies the port to listen on (default 8888).
216+
- `--domain-filter`/`DOMAIN_FILER` (optional): Establishes a filter for DNS zone names (default []).
217+
218+
## Development
219+
Run the app:
220+
```bash
221+
export BASE_URL="https://dns.api.stackit.cloud"
222+
export PROJECT_ID="c158c736-0300-4044-95c4-b7d404279b35"
223+
export AUTH_TOKEN="your-auth-token"
224+
225+
make run
226+
```
227+
228+
Lint the code:
229+
```bash
230+
make lint
231+
```
232+
233+
Test the code:
234+
```bash
235+
make test
236+
```

‎cmd/webhook/cmd/root.go

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -77,14 +77,15 @@ func Execute() error {
7777
func init() {
7878
cobra.OnInitialize(initConfig)
7979

80-
rootCmd.PersistentFlags().StringVar(&apiPort, "api-port", "8888", "Port to listen on for the API")
81-
rootCmd.PersistentFlags().StringVar(&authBearerToken, "auth-token", "", "Bearer token to use for authentication")
82-
rootCmd.PersistentFlags().StringVar(&baseUrl, "base-url", "https://dns.api.stackit.cloud", "Base URL to use for the API")
83-
rootCmd.PersistentFlags().StringVar(&projectID, "project-id", "", "Project to use for the API")
84-
rootCmd.PersistentFlags().IntVar(&worker, "worker", 10, "Number of workers to use for querying the API. "+
85-
"Since we have to iterate over all zones and records we can parallelize it. But keep in mind to not set it too high "+
86-
"since you will receive 429 rate limiting from the API")
87-
rootCmd.PersistentFlags().StringArrayVar(&domainFilter, "domain-filter", []string{}, "Filter to filter dns zone names")
80+
rootCmd.PersistentFlags().StringVar(&apiPort, "api-port", "8888", "Specifies the port to listen on.")
81+
rootCmd.PersistentFlags().StringVar(&authBearerToken, "auth-token", "", "Defines the authentication token for the STACKIT API.")
82+
rootCmd.PersistentFlags().StringVar(&baseUrl, "base-url", "https://dns.api.stackit.cloud", " Identifies the Base URL for utilizing the API.")
83+
rootCmd.PersistentFlags().StringVar(&projectID, "project-id", "", "Specifies the project id of the STACKIT project.")
84+
rootCmd.PersistentFlags().IntVar(&worker, "worker", 10, "Specifies the number "+
85+
"of workers to employ for querying the API. Given that we need to iterate over all zones and "+
86+
"records, it can be parallelized. However, it is important to avoid setting this number "+
87+
"excessively high to prevent receiving 429 rate limiting from the API.")
88+
rootCmd.PersistentFlags().StringArrayVar(&domainFilter, "domain-filter", []string{}, "Establishes a filter for DNS zone names")
8889
}
8990

9091
func initConfig() {

0 commit comments

Comments
 (0)