diff --git a/docs/tutorials/ionoscloud.md b/docs/tutorials/ionoscloud.md new file mode 100644 index 000000000..e03d18161 --- /dev/null +++ b/docs/tutorials/ionoscloud.md @@ -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='' +``` + +Replace `` 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 ' +``` + +Replace `` 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.