Skip to content

Commit d60d961

Browse files
smilutinovic-ionosmloiseleur
smilutinovic-ionos
and
mloiseleur
authored
docs(tutorials): add IONOS Cloud setup tutorial for ExternalDNS (#5364)
* docs(tutorials): add IONOS Cloud setup tutorial for ExternalDNS * docs(tutorials): improve formatting and clarity in IONOS Cloud tutorial * docs(tutorials): address comments, file names to use dash, and more information on ionos webhook repo and image * Update docs/tutorials/ionoscloud.md Co-authored-by: Michel Loiseleur <[email protected]> --------- Co-authored-by: Michel Loiseleur <[email protected]>
1 parent 923a6d9 commit d60d961

File tree

1 file changed

+256
-0
lines changed

1 file changed

+256
-0
lines changed

‎docs/tutorials/ionoscloud.md

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
# IONOS Cloud
2+
3+
This tutorial describes how to set up ExternalDNS for use within a Kubernetes cluster using IONOS Cloud DNS.
4+
For more details, visit the [IONOS external-dns webhook repository](https://github.com/ionos-cloud/external-dns-ionos-webhook).
5+
You can also find the [external-dns-ionos-webhook container image](https://github.com/ionos-cloud/external-dns-ionos-webhook/pkgs/container/external-dns-ionos-webhook) required for this setup.
6+
7+
## Creating a DNS Zone with IONOS Cloud DNS
8+
9+
If you are new to IONOS Cloud DNS, we recommend you first read the following instructions for creating a DNS zone:
10+
11+
- [Manage DNS Zones in Data Centre Designer](https://docs.ionos.com/cloud/network-services/cloud-dns/dcd-how-tos/manage-dns-zone)
12+
- [Creating a DNS Zone using the IONOS Cloud DNS API](https://docs.ionos.com/cloud/network-services/cloud-dns/api-how-tos/create-dns-zone)
13+
14+
### Steps to Create a DNS Zone
15+
16+
1. Log in to the [IONOS Cloud Data Center Designer](https://dcd.ionos.com/).
17+
2. Navigate to the **Network Services** section and select **Cloud DNS**.
18+
3. Click on **Create Zone** and provide the following details:
19+
- **Zone Name**: Enter the domain name (e.g., `example.com`).
20+
- **Description**: It is optional to provide a description of your zone.
21+
4. Save the zone configuration.
22+
23+
For more advanced configurations, such as adding records or managing subdomains, refer to the [IONOS Cloud DNS Documentation](https://docs.ionos.com/cloud/network-services/cloud-dns/).
24+
25+
## Creating an IONOS API Token
26+
27+
To use ExternalDNS with IONOS Cloud DNS, you need an API token with sufficient privileges to manage DNS zones and records. Follow these steps to create an API token:
28+
29+
1. Log in to the [IONOS Cloud Data Center Designer](https://dcd.ionos.com/).
30+
2. Navigate to the **Management** section in the top right corner and select **Token Manager**.
31+
3. Select the Time To Live(TTL) of the token and click on **Create Token**.
32+
4. Copy the generated token and store it securely. You will use this token to authenticate ExternalDNS.
33+
34+
## Deploy ExternalDNS
35+
36+
### Step 1: Create a Kubernetes Secret for the IONOS API Token
37+
38+
Store your IONOS API token securely in a Kubernetes secret:
39+
40+
```bash
41+
kubectl create secret generic ionos-credentials --from-literal=api-key='<IONOS_API_TOKEN>'
42+
```
43+
44+
Replace `<IONOS_API_TOKEN>` with your actual IONOS API token.
45+
46+
### Step 2: Configure ExternalDNS
47+
48+
Create a Helm values file for the ExternalDNS Helm chart that includes the webhook configuration. In this example, the values file is called `external-dns-ionos-values.yaml` .
49+
50+
```yaml
51+
logLevel: debug # ExternalDNS Log level, reduce in production
52+
53+
namespaced: false # if true, ExternalDNS will run in a namespaced scope (Role and Rolebinding will be namespaced too).
54+
triggerLoopOnEvent: true # if true, ExternalDNS will trigger a loop on every event (create/update/delete) on the resources it watches.
55+
56+
logLevel: debug
57+
sources:
58+
- ingress
59+
- service
60+
provider:
61+
name: webhook
62+
webhook:
63+
image:
64+
repository: ghcr.io/ionos-cloud/external-dns-ionos-webhook
65+
tag: latest
66+
pullPolicy: IfNotPresent
67+
env:
68+
- name: IONOS_API_KEY
69+
valueFrom:
70+
secretKeyRef:
71+
name: ionos-credentials
72+
key: api-key
73+
- name: SERVER_PORT
74+
value: "8888"
75+
- name: METRICS_PORT
76+
value: "8080"
77+
- name: DRY_RUN
78+
value: "false"
79+
```
80+
81+
### Step 3: Install ExternalDNS Using Helm
82+
83+
Install ExternalDNS with the IONOS webhook provider:
84+
85+
```bash
86+
helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
87+
helm upgrade --install external-dns external-dns/external-dns -f external-dns-ionos-values.yaml
88+
```
89+
90+
## Deploying an Example Application
91+
92+
### Step 1: Create a Deployment
93+
94+
In this step we will create `echoserver` application manifest with the following content:
95+
96+
```yaml
97+
apiVersion: apps/v1
98+
kind: Deployment
99+
metadata:
100+
name: echoserver
101+
namespace: default
102+
spec:
103+
replicas: 1
104+
selector:
105+
matchLabels:
106+
app: echoserver
107+
template:
108+
metadata:
109+
labels:
110+
app: echoserver
111+
spec:
112+
containers:
113+
- name: echoserver
114+
image: ealen/echo-server:latest
115+
ports:
116+
- containerPort: 80
117+
```
118+
119+
Deployment manifest can be saved in `echoserver-deployment.yaml` file.
120+
121+
Next, we will apply the deployment:
122+
123+
```bash
124+
kubectl apply -f echoserver-deployment.yaml
125+
```
126+
127+
### Step 2: Create a Service
128+
129+
In this step, we will create a `Service` manifest to expose the `echoserver` application within the cluster. The service will also include an annotation for ExternalDNS to create a DNS record for the specified hostname.
130+
131+
Save the following content in a file named `echoserver-service.yaml`:
132+
133+
```yaml
134+
apiVersion: v1
135+
kind: Service
136+
metadata:
137+
name: echoserver
138+
annotations:
139+
external-dns.alpha.kubernetes.io/hostname: app.example.com
140+
spec:
141+
ports:
142+
- port: 80
143+
targetPort: 80
144+
selector:
145+
app: echoserver
146+
```
147+
148+
**Note:** Replace `app.example.com` with a subdomain of your DNS zone configured in IONOS Cloud DNS. For example, if your DNS zone is `example.com`, you can use a subdomain like `app.example.com`.
149+
150+
Next, apply the service:
151+
152+
```bash
153+
kubectl apply -f echoserver-service.yaml
154+
```
155+
156+
This service will expose the echoserver application on port 80 and instruct ExternalDNS to create a DNS record for `app.example.com`.
157+
158+
### Step 3: Create an Ingress
159+
160+
In this step, we will create an `Ingress` resource to expose the `echoserver` application externally. The ingress will route HTTP traffic to the `echoserver` service and include a hostname that ExternalDNS will use to create the corresponding DNS record.
161+
162+
Save the following content in a file named `echoserver-ingress.yaml` :
163+
164+
```yaml
165+
apiVersion: networking.k8s.io/v1
166+
kind: Ingress
167+
metadata:
168+
name: echoserver
169+
spec:
170+
rules:
171+
- host: app.example.com
172+
http:
173+
paths:
174+
- path: /
175+
pathType: Prefix
176+
backend:
177+
service:
178+
name: echoserver
179+
port:
180+
number: 80
181+
```
182+
183+
**Note:** Replace `app.example.com` with a subdomain of your DNS zone configured in IONOS Cloud DNS. For example, if your DNS zone is `example.com`, you can use a subdomain like `app.example.com`.
184+
185+
Next, apply the ingress manifest:
186+
187+
```bash
188+
kubectl apply -f echoserver-ingress.yaml
189+
```
190+
191+
This ingress will expose the `echoserver` application at `http://app.example.com` and instruct ExternalDNS to create a DNS record for the specified hostname.
192+
193+
## Accessing the Application
194+
195+
Once the `Ingress` resource has been applied and the DNS records have been created, you can access the application using the hostname specified in the ingress (`app.example.com`).
196+
197+
### Verify Application Access
198+
199+
Use the following `curl` command to verify that the application is accessible:
200+
201+
```bash
202+
curl -I http://app.example.com
203+
```
204+
205+
Replace app.example.com with the subdomain you configured in your DNS zone.
206+
207+
**Note:** Ensure that your DNS changes have propagated and that the hostname resolves to the correct IP address before running the command.
208+
209+
### Expected result
210+
211+
You should see an HTTP response header indicating that the application is running, such as:
212+
213+
```bash
214+
HTTP/1.1 200 OK
215+
```
216+
217+
> **Troubleshooting:**
218+
>
219+
>If you encounter any issues, verify the following:
220+
>
221+
> - The DNS record for `app.example.com` (replace with your own subdomain configured in IONOS Cloud DNS) has been created in IONOS Cloud DNS.
222+
> - The ingress controller is running and properly configured in your Kubernetes cluster.
223+
> - The `echoserver` application is running and accessible within the cluster.
224+
225+
## Verifying IONOS Cloud DNS Records
226+
227+
Use the IONOS Cloud Console or API to verify that the A and TXT records for your domain have been created. For example, you can use the following API call:
228+
229+
```bash
230+
curl --location --request GET 'https://dns.de-fra.ionos.com/records?filter.name=app' \
231+
--header 'Authorization: Bearer <IONOS_API_TOKEN>'
232+
```
233+
234+
Replace `<IONOS_API_TOKEN>` with your actual API token.
235+
236+
The API response should include the `A` and `TXT` records for the subdomain you configured.
237+
238+
> **Note:** DNS changes may take a few minutes to propagate. If the records are not visible immediately, wait and try again.
239+
240+
## Cleanup
241+
242+
> **Optional:** Perform the cleanup step only if you no longer need the deployed resources.
243+
244+
Once you have verified the setup, you can clean up the resources created during this tutorial:
245+
246+
```bash
247+
kubectl delete -f echoserver-deployment.yaml
248+
kubectl delete -f echoserver-service.yaml
249+
kubectl delete -f echoserver-ingress.yaml
250+
```
251+
252+
## Summary
253+
254+
In this tutorial, you successfully deployed ExternalDNS webhook with IONOS Cloud DNS as the provider.
255+
You created a Kubernetes deployment, service, and ingress, and verified that DNS records were created and the application was accessible.
256+
You also learned how to clean up the resources when they are no longer needed.

0 commit comments

Comments
 (0)