clarify how to use a DNS provider like Route53

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 FIX: Docker share examples had incorrect default path for zrok environment mountpoint
 
+CHANGE: Use port 80 for the default Ziti API endpoint in the zrok Docker instance sample (https://github.com/openziti/zrok/issues/793).
+
+FIX: Clarify how to use DNS providers like Route53 with the zrok Docker instance sample.
+
 ## v0.4.45
 
 FEATURE: Minimal support for "organizations". Site admin API endpoints provided to create, list, and delete "organizations". Site admin API endpoints provided to add, list, and remove "organization members" (zrok accounts) with the ability to mark accounts as a "organization admin". API endpoints provided for organization admins to list the members of their organizations, and to also see the overview (environments, shares, and accesses) for any account in their organization. API endpoint for end users to see which organizations their account is a member of (https://github.com/openziti/zrok/issues/537)
@@ -20,9 +24,6 @@ FIX: Docker reserved private share startup error (https://github.com/openziti/zr
 
 FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
 
-
-CHANGE: Let the zrok instance for Docker use port 80 as an edge listener instead of HTTP redirect (https://github.com/openziti/zrok/issues/793)
-
 ## v0.4.44
 
 FIX: Fix for goreleaser build action to align with changed ARM64 build path.

docker/compose/zrok-instance/README.md

@@ -65,6 +65,10 @@ ZROK_ADMIN_TOKEN=zroktoken
 
 ```bash title=".env options"
 # Caddy TLS option: rename compose.caddy.yml to compose.override.yml and set these vars; allow 80,443 in firewall
+
+#
+## set these in .env for providers other than Route53
+#
 # plugin name for your DNS provider
 CADDY_DNS_PLUGIN=cloudflare
 # API token from your DNS provider
@@ -72,22 +76,34 @@ CADDY_DNS_PLUGIN_TOKEN=abcd1234
 # use the staging API until you're sure everything is working to avoid hitting the rate limit
 CADDY_ACME_API=https://acme-staging-v02.api.letsencrypt.org/directory
 
-# no TLS option: publish the insecure ports to the internet and allow them in the firewall 
-ZROK_INSECURE_INTERFACE=0.0.0.0
+#
+## set these in .env for Route53
+#
+# AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
+# AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+# AWS_REGION: ${AWS_REGION}
+# AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}  # if temporary credential, e.g., from STS
+
+#
+## if not using Caddy for TLS, uncomment to publish the insecure ports to the internet
+#
+#ZROK_INSECURE_INTERFACE=0.0.0.0
+
+# these insecure ports must be proxied with TLS for security
 ZROK_CTRL_PORT=18080
 ZROK_FRONTEND_PORT=8080
 ZROK_OAUTH_PORT=8081
 
-# ziti ports must be published to the internet and allowed by firewall
+# these secure ziti ports must be published to the internet
 ZITI_CTRL_ADVERTISED_PORT=80
 ZITI_ROUTER_PORT=3022
 
-# configure oauth for public shares
-ZROK_OAUTH_HASH_KEY=oauthhashkeysecret
-ZROK_OAUTH_GITHUB_CLIENT_ID=abcd1234
-ZROK_OAUTH_GITHUB_CLIENT_SECRET=abcd1234
-ZROK_OAUTH_GOOGLE_CLIENT_ID=abcd1234
-ZROK_OAUTH_GOOGLE_CLIENT_SECRET=abcd1234
+# optionally configure oauth for public shares
+#ZROK_OAUTH_HASH_KEY=oauthhashkeysecret
+#ZROK_OAUTH_GITHUB_CLIENT_ID=abcd1234
+#ZROK_OAUTH_GITHUB_CLIENT_SECRET=abcd1234
+#ZROK_OAUTH_GOOGLE_CLIENT_ID=abcd1234
+#ZROK_OAUTH_GOOGLE_CLIENT_SECRET=abcd1234
 
 # zrok version, e.g., 1.0.0
 ZROK_CLI_TAG=latest
@@ -223,22 +239,11 @@ See "My internet connection can only send traffic to common ports" below about c
 
 1. My DNS provider credential is composed of several values, not a single API token.
 
-    As long as your DNS provider is supported by Caddy then it will work. You can modify the Caddyfile to use a different set of properties than the example. Here's how the `tls` section should look for Route53. You must declare any environment variables introduced in the `.env` file in `docker.compose.override` on the `caddy` service to ensure they are passed through to the Caddy container.
+    As long as your DNS provider is supported by Caddy then it will work. Here's a checklist for DNS providers like Route53 with credentials expressed as multiple values, e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`.
 
-    ```json
-    tls {
-      dns {$CADDY_DNS_PLUGIN} {
-        access_key_id {$AWS_ACCESS_KEY_ID}
-        secret_access_key {$AWS_SECRET_ACCESS_KEY}
-      }
-    }
-    ```
-
-    ```bash title=".env"
-    CADDY_DNS_PLUGIN=route53
-    AWS_ACCESS_KEY_ID=abcd1234
-    AWS_SECRET_ACCESS_KEY=abcd1234
-    ```
+    1. Define env vars in `.env` file.
+    1. Declare env vars in `compose.override.yml` file on `caddy`'s `environment`.
+    1. Modify `Caddyfile` according to the DNS plugin author's instructions ([link to Route53 README](https://github.com/caddy-dns/route53)). This means modifying the `Caddyfile` to reference the env vars. The provided file `route53.Caddyfile` serves as an example.
 
 1. My internet connection can only send traffic to common ports like 80, 443, and 3389.
 

docker/compose/zrok-instance/compose.caddy.yml

@@ -8,8 +8,21 @@ services:
         CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN} # e.g., "digitalocean" (see github.com/caddy-dns)
     restart: unless-stopped
     environment:
+      #
+      ## set these in .env for providers other than Route53
+      #
       CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN}  # e.g., "digitalocean" (see github.com/caddy-dns)
       CADDY_DNS_PLUGIN_TOKEN: ${CADDY_DNS_PLUGIN_TOKEN}  # API token from DNS provider used by plugin to solve the ACME challenge
+
+      #
+      ## for DNS providers like Route53 with multiple credential variables, you must define in .env and declare
+      ## here before referencing them in the Caddyfile
+      #
+      # AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
+      # AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
+      # AWS_REGION: ${AWS_REGION}
+      # AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}  # if temporary credential, e.g., from STS
+
       ZROK_USER_EMAIL: ${ZROK_USER_EMAIL}  # email address sent to CA for ACME account and renewal notifications
       CADDY_ACME_API: ${CADDY_ACME_API:-https://acme-v02.api.letsencrypt.org/directory}  # ACME API endpoint
       ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"

docker/compose/zrok-instance/route53.Caddyfile

@@ -0,0 +1,51 @@
+{
+	email {$ZROK_USER_EMAIL}
+	acme_ca {$CADDY_ACME_API}
+	admin 0.0.0.0:2019
+}
+
+# http:// {
+# 	redir https://{host}{uri} permanent
+# }
+
+*.{$ZROK_DNS_ZONE} {
+	tls {
+		dns route53 {
+			access_key_id {$AWS_ACCESS_KEY_ID}
+			secret_access_key {$AWS_SECRET_ACCESS_KEY}
+			session_token {$AWS_SESSION_TOKEN}
+			region {$AWS_REGION}
+			# profile {$AWS_PROFILE}
+			# max_retries 10
+			# max_wait_dur 60
+			# wait_for_propagation false
+			# hosted_zone_id {$AWS_HOSTED_ZONE_ID}
+
+		}
+		propagation_timeout 60m
+	}
+
+	log {
+		output stdout
+		format console
+		level INFO
+	}
+
+	# ziti administration console uses :443 for the benefit of a web UI cert and accesses the ziti edge-management API
+	@ziti host ziti.{$ZROK_DNS_ZONE}
+	reverse_proxy @ziti ziti-quickstart:{$ZITI_CTRL_ADVERTISED_PORT:80} {
+		transport http {
+			tls_insecure_skip_verify
+		}
+	}
+
+	@oauth host oauth.{$ZROK_DNS_ZONE}
+	reverse_proxy @oauth zrok-frontend:{$ZROK_OAUTH_PORT}
+
+	@ctrl host zrok.{$ZROK_DNS_ZONE}
+	reverse_proxy @ctrl zrok-controller:{$ZROK_CTRL_PORT}
+
+	reverse_proxy zrok-frontend:{$ZROK_FRONTEND_PORT} {
+		header_up Host {http.request.host}
+	}
+}