docs(aws): tutorial with kind and localstack

docs/scripts/requirements.txt

@@ -1,7 +1,7 @@
 mkdocs-git-revision-date-localized-plugin == 1.2.4
-mkdocs == 1.5.3
-mkdocs-macros-plugin==1.3.7
-mkdocs-material == 9.5.17
+mkdocs == 1.6.1
+mkdocs-macros-plugin == 1.3.7
+mkdocs-material == 9.7.1
 mkdocs-literate-nav == 0.6.1
 mkdocs-same-dir == 0.1.3
 mike == 2.0.0

docs/snippets/tutorials/aws-localstack/dnsendpoint-cname.yml

@@ -0,0 +1,16 @@
+# ref: docs/snippets/tutorials/aws-localstack/dnsendpoint-cname.yml
+---
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: cname-example
+  namespace: default
+  annotations:
+    dns.why/type: aws-localstack-tutorial
+spec:
+  endpoints:
+    - dnsName: www.example.com
+      recordTTL: 600
+      recordType: CNAME
+      targets:
+        - example.com

docs/snippets/tutorials/aws-localstack/dnsendpoint-multi.yml

@@ -0,0 +1,28 @@
+# ref: docs/snippets/tutorials/aws-localstack/dnsendpoint-multi.yml
+---
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: simple-example
+  namespace: default
+  annotations:
+    dns.why/type: aws-localstack-tutorial
+spec:
+  endpoints:
+    - dnsName: dnsendpoint-a.example.com
+      recordTTL: 300
+      recordType: A
+      targets:
+        - 192.168.1.100
+    - dnsName: dnsendpoint-a-lb.example.com
+      recordTTL: 200
+      recordType: A
+      targets:
+        - 10.0.1.1
+        - 10.0.1.2
+        - 10.0.1.3
+    - dnsName: dnsendpoint-aaaa.example.com
+      recordTTL: 600
+      recordType: AAAA
+      targets:
+        - 2001:0db8:85a3:0000:0000:8a2e:0370:7334

docs/snippets/tutorials/aws-localstack/dnsendpoint-txt.yml

@@ -0,0 +1,19 @@
+# ref: docs/snippets/tutorials/aws-localstack/dnsendpoint-txt.yml
+---
+apiVersion: externaldns.k8s.io/v1alpha1
+kind: DNSEndpoint
+metadata:
+  name: txt-example
+  namespace: default
+spec:
+  endpoints:
+    - dnsName: _acme-challenge.example.com
+      recordTTL: 300
+      recordType: TXT
+      targets:
+        - "validation-token-12345"
+    - dnsName: example.com
+      recordTTL: 3600
+      recordType: TXT
+      targets:
+        - "v=spf1 include:_spf.google.com ~all"

docs/snippets/tutorials/aws-localstack/fetch-records.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+set -e
+
+# run docs/snippets/tutorials/aws-localstack/check-records.sh
+
+export AWS_REGION=eu-west-1
+export AWS_ACCESS_KEY_ID=foo
+export AWS_SECRET_ACCESS_KEY=bar
+export AWS_ENDPOINT_URL=http://127.0.0.1:32379
+
+MATCH="${1:-}"   # optional positional argument to filter records by name
+
+zones=$(aws route53 list-hosted-zones-by-name --query "HostedZones[].Id"  --output json)
+
+echo "$zones" | jq -r '.[]' | while IFS= read -r hosted_zone_id; do
+  zone=${hosted_zone_id#"/hostedzone/"}
+  echo "Checking records for zone: $zone"
+
+  if [ -z "$MATCH" ]; then
+    # default behaviour (unchanged)
+    aws route53 list-resource-record-sets \
+      --hosted-zone-id "$zone" \
+      --query "ResourceRecordSets[].{Name:Name, Type:Type, Value:ResourceRecords[*].Value, TTL:TTL}" \
+      --output json
+  else
+    # filtered behaviour
+    aws route53 list-resource-record-sets \
+      --hosted-zone-id "$zone" \
+      --query "ResourceRecordSets[?contains(Name, \`${MATCH}\`)].{Name:Name, Type:Type, Value:ResourceRecords[*].Value, TTL:TTL}" \
+      --output json
+  fi
+done

docs/snippets/tutorials/aws-localstack/foo-app.yml

@@ -0,0 +1,47 @@
+# ref: docs/snippets/tutorials/aws-localstack/foo-app.yml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: foo-app
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: foo-app.example.com
+    dns.why/type: aws-localstack-tutorial
+spec:
+  type: ClusterIP
+  clusterIP: None
+  ports:
+    - port: 80
+      targetPort: 80
+      protocol: TCP
+  selector:
+    app: foo
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: foo-app
+  annotations:
+    dns.why/type: aws-localstack-tutorial
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: foo
+  template:
+    metadata:
+      labels:
+        app: foo
+    spec:
+      containers:
+        - name: foo
+          image: nginx:latest
+          ports:
+            - containerPort: 80
+          resources:
+            requests:
+              memory: "5Mi"
+              cpu: "25m"
+            limits:
+              memory: "5Mi"
+              cpu: "25m"

docs/snippets/tutorials/aws-localstack/kind.yaml

@@ -0,0 +1,37 @@
+# ref: https://kind.sigs.k8s.io/docs/user/quick-start/
+# https://kind.sigs.k8s.io/docs/user/configuration/#extra-port-mappings
+
+# kind create cluster --config=docs/snippets/tutorials/aws-localstack/kind.yaml
+# kind delete cluster --name aws-localstack
+# kubectl cluster-info --context kind-aws-localstack
+# kubectl get nodes -o wide
+---
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+name: aws-localstack
+networking:
+  apiServerAddress: 127.0.0.1
+  apiServerPort: 6443
+  ipFamily: dual
+nodes:
+- role: control-plane
+  kubeadmConfigPatches:
+    - |
+      kind: InitConfiguration
+      nodeRegistration:
+        kubeletExtraArgs:
+          node-labels: "ingress-ready=true"
+  extraPortMappings:
+    - containerPort: 80
+      hostPort: 8080
+      listenAddress: "0.0.0.0"
+      protocol: TCP
+    - containerPort: 43
+      hostPort: 4443
+      listenAddress: "0.0.0.0"
+      protocol: TCP
+    - containerPort: 32379   # inside kind node
+      hostPort: 32379        # exposed on host
+      listenAddress: "0.0.0.0"
+      protocol: TCP
+- role: worker

docs/snippets/tutorials/aws-localstack/service-lb.yml

@@ -0,0 +1,18 @@
+# ref: docs/snippets/tutorials/aws-localstack/service-lb.yml
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: loadbalancer-service
+  annotations:
+    external-dns.alpha.kubernetes.io/hostname: my-loadbalancer.example.com
+    dns.why/type: aws-localstack-tutorial
+  namespace: default
+spec:
+  type: LoadBalancer
+  ports:
+  - port: 80
+    name: http
+    targetPort: 80
+  selector:
+    app: test-app

docs/snippets/tutorials/aws-localstack/values-extdns.yml

@@ -0,0 +1,29 @@
+# ref: https://github.com/kubernetes-sigs/external-dns/blob/master/charts/external-dns/values.yaml
+logLevel: info  # debug, info, warn, error
+policy: sync
+
+provider:
+  name: aws
+
+txtOwnerId: aws-localstack
+
+domainFilters:
+  - example.com
+  - local.tld
+
+sources:
+  - service
+  - ingress
+  - crd
+
+env:
+  - name: AWS_REGION
+    value: eu-west-1
+  - name: AWS_ACCESS_KEY_ID
+    value: foo-fake
+  - name: AWS_SECRET_ACCESS_KEY
+    value: bar-fake
+  - name: AWS_ENDPOINT_URL
+    value: http://localstack.localstack.svc.cluster.local:4566
+
+interval: 1m

docs/snippets/tutorials/aws-localstack/values-localstack.yml

@@ -0,0 +1,50 @@
+# ref: https://github.com/localstack/helm-charts/blob/main/charts/localstack/values.yaml
+
+debug: false
+
+extraLabels:
+  app: localstack
+
+extraEnvVars:
+  - name: SERVICES
+    value: "route53"
+
+# -- Set a fixed port for LocalStack edge service --
+service:
+  type: NodePort
+  edgeService:
+    name: edge
+    targetPort: 4566
+    nodePort: 32379
+
+enableStartupScripts: true
+startupScriptContent: |
+  #!/bin/bash
+  create_zone_if_missing() {
+  ZONE_NAME="$1"
+  COMMENT="$2"
+
+  EXISTING_ZONE_ID=$(
+    awslocal route53 list-hosted-zones-by-name \
+      --dns-name "${ZONE_NAME}." \
+      --query "HostedZones[?Name=='${ZONE_NAME}.'].Id | [0]" \
+      --output text
+  )
+
+  if [ "$EXISTING_ZONE_ID" != "None" ]; then
+    echo "Route53 zone '${ZONE_NAME}' already exists (${EXISTING_ZONE_ID})"
+    return 0
+  fi
+
+  echo "Creating Route53 zone '${ZONE_NAME}'"
+  awslocal route53 create-hosted-zone \
+    --name "$ZONE_NAME" \
+    --caller-reference "$(date +%s)" \
+    --hosted-zone-config Comment="$COMMENT"
+  }
+
+  create_zone_if_missing "local.tld" "external-dns"
+  create_zone_if_missing "example.com" "external-dns"
+
+lambda:
+  executor: "kubernetes"