mirror of
https://github.com/kubernetes-sigs/external-dns.git
synced 2025-10-31 18:50:59 +01:00
d60d96176f
* 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>
257 lines
8.7 KiB
Markdown
257 lines
8.7 KiB
Markdown
# 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.
|