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

Author: smilutinovic-ionos

docs/tutorials/ionoscloud.md

@@ -0,0 +1,255 @@
+# IONOS Cloud
+
+This tutorial describes how to set up ExternalDNS for use within a Kubernetes cluster using IONOS Cloud DNS.
+
+## 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
+  annotations:
+    kubernetes.io/ingress.class: nginx
+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.