diff --git a/README.md b/README.md index 45ad8e06f..74c6c5cba 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ ExternalDNS allows you to keep selected zones (via `--domain-filter`) synchroniz - [Plural](https://www.plural.sh/) - [Pi-hole](https://pi-hole.net/) - [Alibaba Cloud DNS](https://www.alibabacloud.com/help/en/dns) +- [Myra Security DNS](https://www.myrasecurity.com/en/saasp/application-security/secure-dns/) ExternalDNS is, by default, aware of the records it is managing, therefore it can safely manage non-empty hosted zones. We strongly encourage you to set `--txt-owner-id` to a unique value that doesn't change for the lifetime of your cluster. @@ -104,6 +105,7 @@ from the usage of any externally developed webhook. | IONOS | https://github.com/ionos-cloud/external-dns-ionos-webhook | | Infoblox | https://github.com/AbsaOSS/external-dns-infoblox-webhook | | Mikrotik | https://github.com/mirceanton/external-dns-provider-mikrotik | +| Myra Security | https://github.com/Myra-Security-GmbH/external-dns-myrasec-webhook | | Netcup | https://github.com/mrueg/external-dns-netcup-webhook | | Netic | https://github.com/neticdk/external-dns-tidydns-webhook | | OpenStack Designate | https://github.com/inovex/external-dns-designate-webhook | @@ -203,6 +205,7 @@ The following tutorials are provided: - [IONOS Cloud](docs/tutorials/ionoscloud.md) - [Istio Gateway Source](docs/sources/istio.md) - [Linode](docs/tutorials/linode.md) +- [Myra Security](docs/tutorials/myra.md) - [NS1](docs/tutorials/ns1.md) - [NS Record Creation with CRD Source](docs/sources/ns-record.md) - [MX Record Creation with CRD Source](docs/sources/mx-record.md) diff --git a/docs/providers.md b/docs/providers.md index 228622939..0aafa2fdd 100644 --- a/docs/providers.md +++ b/docs/providers.md @@ -20,6 +20,7 @@ Provider supported configurations | Google GCP | n/a | yes | 300 | | InMemory | n/a | n/a | n/a | | Linode | n/a | n/a | n/a | +| Myra Security | n/a | yes | 300 | | NS1 | n/a | yes | 10 | | OCI | yes | yes | 300 | | OVH | n/a | yes | 0 | diff --git a/docs/tutorials/myra.md b/docs/tutorials/myra.md new file mode 100644 index 000000000..c25e16821 --- /dev/null +++ b/docs/tutorials/myra.md @@ -0,0 +1,215 @@ +# Myra ExternalDNS Webhook + +This guide provides quick instructions for setting up and testing the [Myra ExternalDNS Webhook](https://github.com/Myra-Security-GmbH/external-dns-myrasec-webhook) in a Kubernetes environment. + +## Prerequisites + +- Kubernetes cluster (v1.19+) +- `kubectl` configured to access your cluster +- Docker for building the container image +- MyraSec API credentials (API key and secret) +- Domain registered with MyraSec + +## Quick Installation + +### 1. Build and Push the Docker Image + +```bash +# From the project root +docker build -t myra-webhook:latest . + +# Tag the image for your container registry +docker tag myra-webhook:latest YOUR_REGISTRY/myra-webhook:latest + +# Push to your container registry +docker push YOUR_REGISTRY/myra-webhook:latest +``` + +> **Important**: The image must be pushed to a container registry accessible by your Kubernetes cluster. Update the image reference in the deployment YAML file to match your registry path. + +### 2. Configure API Credentials + +Create a secret with your MyraSec API credentials: + +```bash +kubectl create secret generic myra-webhook-secrets \ + --from-literal=myrasec-api-key=YOUR_API_KEY \ + --from-literal=myrasec-api-secret=YOUR_API_SECRET \ + --from-literal=domain-filter=YOUR_DOMAIN.com +``` + +Alternatively, apply the provided secret template after editing: + +```bash +# Edit the secret file first +vi deploy/myra-webhook-secrets.yaml + +# Then apply +kubectl apply -f deploy/myra-webhook-secrets.yaml +``` + +### 3. Deploy the Webhook and ExternalDNS + +```bash +# Apply the combined deployment +kubectl apply -f deploy/combined-deployment.yaml +``` + +This deploys: + +- ConfigMap with webhook configuration +- ServiceAccount, ClusterRole, and ClusterRoleBinding for RBAC +- Deployment with two containers: + - myra-webhook: The webhook provider implementation + - external-dns: The ExternalDNS controller using the webhook provider + +### 4. Verify Deployment + +```bash +# Check if pods are running +kubectl get pods -l app=myra-externaldns + +# Check logs for the webhook container +kubectl logs -l app=myra-externaldns -c myra-webhook + +# Check logs for the external-dns container +kubectl logs -l app=myra-externaldns -c external-dns +``` + +## Manual Testing with NGINX Demo + +### 1. Deploy the NGINX Demo Application + +```bash +# Edit the domain in the nginx-demo.yaml file to match your domain +vi deploy/nginx-demo.yaml + +# Most important part is to set the correct domain in the external-dns.alpha.kubernetes.io/hostname annotation +# Example: +# annotations: +# external-dns.alpha.kubernetes.io/enabled: "true" +# external-dns.alpha.kubernetes.io/hostname: "nginx-demo.dummydomainforkubes.de" +# external-dns.alpha.kubernetes.io/target: "9.2.3.4" + +# Apply the demo resources +kubectl apply -f deploy/nginx-demo.yaml +``` + +This creates: + +- NGINX Deployment +- Service for the deployment +- Ingress resource with ExternalDNS annotations + +### 2. Verify DNS Record Creation + +After deploying the demo application, ExternalDNS should automatically create DNS records in MyraSec: + +```bash +# Check external-dns logs to see record creation +kubectl logs -l app=myra-externaldns -c external-dns | grep "nginx-demo" + +# Verify the webhook logs +kubectl logs -l app=myra-externaldns -c myra-webhook | grep "Created DNS record" +``` + +You can also verify through the MyraSec dashboard that the records were created. + +### 3. Testing Record Deletion + +To test record deletion: + +```bash +# Delete the nginx-demo resources or remove annotation from ingress +kubectl delete -f deploy/nginx-demo.yaml + +# Delete the ingress resource or remove annotation from ingress +# If resource is still active, external dns might still see the record and manage it +kubectl delete ingress nginx-demo -n default + +# Check external-dns logs to see record deletion +kubectl logs -l app=myra-externaldns -c external-dns | grep "nginx-demo" | grep "delete" + +# Verify the webhook logs +kubectl logs -l app=myra-externaldns -c myra-webhook | grep "Deleted DNS record" +``` + +## Configuration Options + +The webhook can be configured through the ConfigMap: + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `dry-run` | Run in dry-run mode without making actual changes | `"false"` | +| `environment` | Environment name (affects private IP handling) | `"prod"` | +| `log-level` | Logging level (debug, info, warn, error) | `"debug"` | +| `ttl` | Default TTL for DNS records | `"300"` | +| `webhook-listen-address` | Address and port for the webhook server | `":8080"` | + +## Troubleshooting + +### Common Issues + +1. **Webhook not receiving requests** + - Ensure the `webhook-provider-url` in the external-dns args is correct + - Check network connectivity between containers + +2. **DNS records not being created** + - Verify MyraSec API credentials are correct + - Check if the domain filter is properly configured + - Look for error messages in the webhook and external-dns logs + +3. **Permissions issues** + - Ensure the ServiceAccount has the correct RBAC permissions + +### Getting Help + +For more detailed logs: + +```bash +# Set log level to debug in the ConfigMap +kubectl edit configmap myra-externaldns-config +# Change log-level to "debug" + +# Restart the pods +kubectl rollout restart deployment myra-externaldns +``` + +## Environment Configuration + +The webhook supports different environment configurations through the `environment` setting in the ConfigMap: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: myra-externaldns-config +data: + environment: "prod" # Can be "prod", "staging", "dev", etc. +``` + +The environment setting affects how the webhook handles certain operations: + +| Environment | Behavior | +|-------------|----------| +| `prod`, `production`, `staging` | Strict mode: Skips private IP records, enforces stricter validation | +| `dev`, `development`, `test`, etc. | Development mode: Allows private IP records, more permissive validation | + +To modify the environment: + +```bash +# Edit the ConfigMap directly +kubectl edit configmap myra-externaldns-config + +# Or apply an updated YAML file +kubectl apply -f updated-config.yaml +``` + +## Advanced Configuration + +For production deployments, consider: + +1. Using a proper image registry instead of `latest` tag +2. Setting resource limits appropriate for your environment +3. Configuring horizontal pod autoscaling +4. Using Helm for deployment management