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

docs(tutorials): add IONOS Cloud setup tutorial for ExternalDNS (#5364)

Browse Source 
* 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 <97035654+mloiseleur@users.noreply.github.com>

---------

Co-authored-by: Michel Loiseleur <97035654+mloiseleur@users.noreply.github.com>
This commit is contained in:
Srdjan Milutinovic 2025-05-08 10:17:25 +02:00 committed by GitHub
parent 923a6d95c0
commit d60d96176f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 256 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
docs/tutorials/ionoscloud.md Normal file
View File

@ -0,0 +1,256 @@
# IONOS Cloud
This tutorial describes how to set up ExternalDNS for use within a Kubernetes cluster using IONOS Cloud DNS.
For more details, visit the [IONOS external-dns webhook repository](https://github.com/ionos-cloud/external-dns-ionos-webhook).
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.
## Creating a DNS Zone with IONOS Cloud DNS
If you are new to IONOS Cloud DNS, we recommend you first read the following instructions for creating a DNS zone:
- [Manage DNS Zones in Data Centre Designer](https://docs.ionos.com/cloud/network-services/cloud-dns/dcd-how-tos/manage-dns-zone)
- [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)
### Steps to Create a DNS Zone
1. Log in to the [IONOS Cloud Data Center Designer](https://dcd.ionos.com/).
2. Navigate to the **Network Services** section and select **Cloud DNS**.
3. Click on **Create Zone** and provide the following details:
- **Zone Name**: Enter the domain name (e.g., `example.com`).
- **Description**: It is optional to provide a description of your zone.
4. Save the zone configuration.
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/).
## Creating an IONOS API Token
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:
1. Log in to the [IONOS Cloud Data Center Designer](https://dcd.ionos.com/).
2. Navigate to the **Management** section in the top right corner and select **Token Manager**.
3. Select the Time To Live(TTL) of the token and click on **Create Token**.
4. Copy the generated token and store it securely. You will use this token to authenticate ExternalDNS.
## Deploy ExternalDNS
### Step 1: Create a Kubernetes Secret for the IONOS API Token
Store your IONOS API token securely in a Kubernetes secret:
```bash
kubectl create secret generic ionos-credentials --from-literal=api-key='<IONOS_API_TOKEN>'
```
Replace `<IONOS_API_TOKEN>` with your actual IONOS API token.
### Step 2: Configure ExternalDNS
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` .
```yaml
logLevel: debug # ExternalDNS Log level, reduce in production
namespaced: false # if true, ExternalDNS will run in a namespaced scope (Role and Rolebinding will be namespaced too).
triggerLoopOnEvent: true # if true, ExternalDNS will trigger a loop on every event (create/update/delete) on the resources it watches.
logLevel: debug
sources:
- ingress
- service
provider:
name: webhook
webhook:
image:
repository: ghcr.io/ionos-cloud/external-dns-ionos-webhook
tag: latest
pullPolicy: IfNotPresent
env:
- name: IONOS_API_KEY
valueFrom:
secretKeyRef:
name: ionos-credentials
key: api-key
- name: SERVER_PORT
value: "8888"
- name: METRICS_PORT
value: "8080"
- name: DRY_RUN
value: "false"
```
### Step 3: Install ExternalDNS Using Helm
Install ExternalDNS with the IONOS webhook provider:
```bash
helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/
helm upgrade --install external-dns external-dns/external-dns -f external-dns-ionos-values.yaml
```
## Deploying an Example Application
### Step 1: Create a Deployment
In this step we will create `echoserver` application manifest with the following content:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: echoserver
namespace: default
spec:
replicas: 1
selector:
matchLabels:
app: echoserver
template:
metadata:
labels:
app: echoserver
spec:
containers:
- name: echoserver
image: ealen/echo-server:latest
ports:
- containerPort: 80
```
Deployment manifest can be saved in `echoserver-deployment.yaml` file.
Next, we will apply the deployment:
```bash
kubectl apply -f echoserver-deployment.yaml
```
### Step 2: Create a Service
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.
Save the following content in a file named `echoserver-service.yaml`:
```yaml
apiVersion: v1
kind: Service
metadata:
name: echoserver
annotations:
external-dns.alpha.kubernetes.io/hostname: app.example.com
spec:
ports:
- port: 80
targetPort: 80
selector:
app: echoserver
```
**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`.
Next, apply the service:
```bash
kubectl apply -f echoserver-service.yaml
```
This service will expose the echoserver application on port 80 and instruct ExternalDNS to create a DNS record for `app.example.com`.
### Step 3: Create an Ingress
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.
Save the following content in a file named `echoserver-ingress.yaml` :
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: echoserver
spec:
rules:
- host: app.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: echoserver
port:
number: 80
```
**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`.
Next, apply the ingress manifest:
```bash
kubectl apply -f echoserver-ingress.yaml
```
This ingress will expose the `echoserver` application at `http://app.example.com` and instruct ExternalDNS to create a DNS record for the specified hostname.
## Accessing the Application
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`).
### Verify Application Access
Use the following `curl` command to verify that the application is accessible:
```bash
curl -I http://app.example.com
```
Replace app.example.com with the subdomain you configured in your DNS zone.
**Note:** Ensure that your DNS changes have propagated and that the hostname resolves to the correct IP address before running the command.
### Expected result
You should see an HTTP response header indicating that the application is running, such as:
```bash
HTTP/1.1 200 OK
```
> **Troubleshooting:**
>
>If you encounter any issues, verify the following:
>
> - The DNS record for `app.example.com` (replace with your own subdomain configured in IONOS Cloud DNS) has been created in IONOS Cloud DNS.
> - The ingress controller is running and properly configured in your Kubernetes cluster.
> - The `echoserver` application is running and accessible within the cluster.
## Verifying IONOS Cloud DNS Records
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:
```bash
curl --location --request GET 'https://dns.de-fra.ionos.com/records?filter.name=app' \
--header 'Authorization: Bearer <IONOS_API_TOKEN>'
```
Replace `<IONOS_API_TOKEN>` with your actual API token.
The API response should include the `A` and `TXT` records for the subdomain you configured.
> **Note:** DNS changes may take a few minutes to propagate. If the records are not visible immediately, wait and try again.
## Cleanup
> **Optional:** Perform the cleanup step only if you no longer need the deployed resources.
Once you have verified the setup, you can clean up the resources created during this tutorial:
```bash
kubectl delete -f echoserver-deployment.yaml
kubectl delete -f echoserver-service.yaml
kubectl delete -f echoserver-ingress.yaml
```
## Summary
In this tutorial, you successfully deployed ExternalDNS webhook with IONOS Cloud DNS as the provider.
You created a Kubernetes deployment, service, and ingress, and verified that DNS records were created and the application was accessible.
You also learned how to clean up the resources when they are no longer needed.