diff --git a/.env.example b/.env.example index eb2f6b6..af6e86b 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,4 @@ -MIKROTIK_BASEURL = "192.168.88.1:443" - -MIKROTIK_USERNAME = "" -MIKROTIK_PASSWORD = "" - -MIKROTIK_SKIP_TLS_VERIFY = false +MIKROTIK_BASEURL=https://192.168.88.1:443 +MIKROTIK_USERNAME=external-dns +MIKROTIK_PASSWORD=external-dns +MIKROTIK_SKIP_TLS_VERIFY=true diff --git a/README.md b/README.md index aef850c..9807e8a 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,105 @@ # ExternalDNS Webhook Provider for Mikrotik -> [!WARNING] -> This software is experimental and **NOT FIT FOR PRODUCTION USE!** +> [!IMPORTANT] +> While this software has reached version `v1.0.0`, it has not yet undergone extensive testing in large-scale, real-world environments. As such, it may still have bugs and may not yet be fully suitable for production use. +> +> I encourage users to report any issues or suggest improvements, as this project remains under active development. Thank you for contributing! [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) is a Kubernetes add-on for automatically managing DNS records for Kubernetes ingresses and services by using different DNS providers. This webhook provider allows you to automate DNS records from your Kubernetes clusters into your MikroTik router. +Supported DNS record types: + +- A +- AAAA +- CNAME +- MX +- NS +- SRV +- TXT + ## 🎯 Requirements - ExternalDNS >= v0.14.0 -- Mikrotik RouterOS (tested on 7.14.3 stable ) +- Mikrotik RouterOS (tested on 7.14.3 stable) + +## 🚫 Limitations + +- Currently, `DNSEndpoints` with multiple `targets` are *technically* not supported. Only one record will be created with the first target from the list, but eDNS will keep trying to update your DNS record in RouterOS, constantly sending `PUT` requests. +- The `Disabled` option on DNS records is currently ignored +- Support for `providerSpecific` annotations on `Ingress` objects is not **yet** supported. + +## ⚙️ Configuration Options + +### MikroTik Configuration + +| Environment Variable | Description | Default Value | +|-----------------------------|---------------------------------------------------------------------|---------------| +| `MIKROTIK_BASEURL` | URL at which the RouterOS API is available. (ex. `https://192.168.88.1:443`) | N/A | +| `MIKROTIK_USERNAME` | Username for the RouterOS API authentication. | N/A | +| `MIKROTIK_PASSWORD` | Password for the RouterOS API authentication. | N/A | +| `MIKROTIK_SKIP_TLS_VERIFY` | Whether to skip TLS verification (true or false). | `false` | +| `LOG_FORMAT` | The format in which logs will be printed. (`text` or `json`) | `json` | +| `LOG_LEVEL` | The verbosity at which logs are printed logs. (`debug`, `info`, `warn` or `error`) | `info` | + +### Webhook Server Configuration + +| Environment Variable | Description | Default Value | +|----------------------------------|------------------------------------------------------------------|---------------| +| `SERVER_HOST` | The host address where the server listens. | `localhost` | +| `SERVER_PORT` | The port where the server listens. | `8888` | +| `SERVER_READ_TIMEOUT` | Duration the server waits before timing out on read operations. | N/A | +| `SERVER_WRITE_TIMEOUT` | Duration the server waits before timing out on write operations. | N/A | +| `DOMAIN_FILTER` | List of domains to include in the filter. | Empty | +| `EXCLUDE_DOMAIN_FILTER` | List of domains to exclude from filtering. | Empty | +| `REGEXP_DOMAIN_FILTER` | Regular expression for filtering domains. | Empty | +| `REGEXP_DOMAIN_FILTER_EXCLUSION` | Regular expression for excluding domains from the filter. | Empty | + +## 🚀 Deployment + +1. Create a service account in RouterOS. This local user needs read and write access to manage static DNS. +2. Create a Kubernetes namespace for your External DNS deployment + + ```yaml + --- + apiVersion: v1 + kind: Namespace + metadata: + name: external-dns + ``` + +3. Create a Kubernetes secret with the connection details for your RouterOS instance: + + ```yaml + --- + apiVersion: v1 + kind: Secret + metadata: + name: mikrotik-credentials + namespace: external-dns + stringData: + MIKROTIK_BASEURL: "https://192.168.88.1:443" + MIKROTIK_USERNAME: "external-dns" + MIKROTIK_PASSWORD: "external-dns" + MIKROTIK_SKIP_TLS_VERIFY: "true" + ``` + +4. Add the External DNS helm repository and update your local cache + + ```bash + helm repo add external-dns https://kubernetes-sigs.github.io/external-dns/ + helm repo update + ``` + +5. Configure your helm values. Take a look at the [example values.yaml](./example/values.yaml) +6. Install the External DNS helm chart + + ```bash + helm upgrade --install --namespace external-dns external-dns external-dns/external-dns -f values.yaml + ``` + +> [!TIP] +> By default, support for MX, NS and SRV records is disabled and needs to be enabled via the `--managed-record-types` argument. +> Make sure to set `--managed-record-types=SRV` if you want to enable SRV records, and so on. ## ⭐ Stargazers diff --git a/Taskfile.yaml b/Taskfile.yaml index f58e0ad..c3b7b9a 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -21,7 +21,7 @@ tasks: - kubectl delete secret --namespace external-dns mikrotik-credentials || true - kubectl create secret generic --namespace external-dns --from-env-file=.env mikrotik-credentials || true - helm repo add external-dns https://kubernetes-sigs.github.io/external-dns && helm repo update - - helm upgrade --install --namespace external-dns external-dns external-dns/external-dns -f deploy/values.yaml + - helm upgrade --install --namespace external-dns external-dns external-dns/external-dns -f example/values.yaml kube:logs: desc: Fetch the logs from the external-dns-mikrotik webhook container to a local file. @@ -31,8 +31,8 @@ tasks: desc: Remove the external-dns-mikrotik webhook from the test cluster. cmds: - kubectl delete ns external-dns || true - - kubectl delete -f deploy/records || true - - kubectl delete -f deploy/ingress || true + - kubectl delete -f example/records || true + - kubectl delete -f example/ingress || true go:release: desc: Run goreleaser in snapshot mode. diff --git a/deploy/ingress/sample.yaml b/example/ingress/sample.yaml similarity index 100% rename from deploy/ingress/sample.yaml rename to example/ingress/sample.yaml diff --git a/deploy/records/a-record.yaml b/example/records/a-record.yaml similarity index 100% rename from deploy/records/a-record.yaml rename to example/records/a-record.yaml diff --git a/deploy/records/aaaa-record.yaml b/example/records/aaaa-record.yaml similarity index 100% rename from deploy/records/aaaa-record.yaml rename to example/records/aaaa-record.yaml diff --git a/deploy/records/cname-record.yaml b/example/records/cname-record.yaml similarity index 100% rename from deploy/records/cname-record.yaml rename to example/records/cname-record.yaml diff --git a/deploy/records/complex-record.yaml b/example/records/complex-record.yaml similarity index 100% rename from deploy/records/complex-record.yaml rename to example/records/complex-record.yaml diff --git a/deploy/records/invalid-record-fields.yaml b/example/records/invalid-record-fields.yaml similarity index 100% rename from deploy/records/invalid-record-fields.yaml rename to example/records/invalid-record-fields.yaml diff --git a/deploy/records/kustomization.yaml b/example/records/kustomization.yaml similarity index 100% rename from deploy/records/kustomization.yaml rename to example/records/kustomization.yaml diff --git a/deploy/records/mx-record.yaml b/example/records/mx-record.yaml similarity index 100% rename from deploy/records/mx-record.yaml rename to example/records/mx-record.yaml diff --git a/deploy/records/ns-record.yaml b/example/records/ns-record.yaml similarity index 100% rename from deploy/records/ns-record.yaml rename to example/records/ns-record.yaml diff --git a/deploy/records/srv-record.yaml b/example/records/srv-record.yaml similarity index 100% rename from deploy/records/srv-record.yaml rename to example/records/srv-record.yaml diff --git a/deploy/records/text-record.yaml b/example/records/text-record.yaml similarity index 100% rename from deploy/records/text-record.yaml rename to example/records/text-record.yaml diff --git a/deploy/service/service.yaml b/example/service/service.yaml similarity index 100% rename from deploy/service/service.yaml rename to example/service/service.yaml diff --git a/deploy/values.yaml b/example/values.yaml similarity index 97% rename from deploy/values.yaml rename to example/values.yaml index 5be2a94..ca136fc 100644 --- a/deploy/values.yaml +++ b/example/values.yaml @@ -14,8 +14,8 @@ provider: webhook: image: repository: ghcr.io/mirceanton/external-dns-provider-mikrotik - tag: pr-98 - pullPolicy: Always + tag: v1.0.0 + pullPolicy: IfNotPresent env: - name: LOG_FORMAT value: json