Merge pull request #491 from aojea/feat/sam-one-zero-config-deploy

feat(sam-one): zero-config cloud deploy, link-local filtering, and developer-oriented URL docs

Author: aojea

cmd/sam-one/main.go

@@ -55,6 +55,7 @@ func main() {
 		allowedAudiencesFlag string
 		logLevel             string
 		tunnelProvider       string
+		tunnelTokenPath      string
 		tunnelInstall        bool
 		cloudflaredPath      string
 		enrollQR             bool
@@ -98,6 +99,10 @@ func main() {
 			if err != nil {
 				logger.Fatalf("Invalid --admin-token-path: %v", err)
 			}
+			tunnelToken, err := secretFromPathOrEnv(tunnelTokenPath, "SAM_TUNNEL_TOKEN")
+			if err != nil {
+				logger.Fatalf("Invalid --tunnel-token-path: %v", err)
+			}
 			if externalURL == "" {
 				externalURL = os.Getenv("SAM_EXTERNAL_URL")
 			}
@@ -114,8 +119,11 @@ func main() {
 			// port settled now rather than at bind time.
 			var tun tunnel.Tunnel
 			if tunnelProvider != "" {
-				if externalURL != "" {
-					logger.Fatal("--tunnel and --external-url are mutually exclusive: the tunnel provides the external URL")
+				if tunnelToken == "" && externalURL != "" {
+					logger.Fatal("--tunnel and --external-url are mutually exclusive unless --tunnel-token-path / SAM_TUNNEL_TOKEN is set")
+				}
+				if tunnelToken != "" && externalURL == "" {
+					logger.Fatal("--tunnel-token-path / SAM_TUNNEL_TOKEN requires --external-url (the public https:// hostname routed to the tunnel)")
 				}
 				if port == 0 {
 					var err error
@@ -131,6 +139,8 @@ func main() {
 					dataDir:         dataDir,
 					cloudflaredPath: cloudflaredPath,
 					install:         tunnelInstall,
+					token:           tunnelToken,
+					externalURL:     externalURL,
 				}); err != nil {
 					logger.Fatalf("Failed to open tunnel: %v", err)
 				}
@@ -202,6 +212,7 @@ func main() {
 	rootCmd.Flags().StringVar(&allowedAudiencesFlag, "allowed-audiences", api.DefaultAudience, "Comma-separated list of allowed OIDC audiences")
 	rootCmd.Flags().StringVar(&logLevel, "log-level", "", "Log level: debug, info, warn, error")
 	rootCmd.Flags().StringVar(&tunnelProvider, "tunnel", "", "Publish the listener on a public URL through a tunnel provider ("+strings.Join(tunnel.Names(), ", ")+"); sets the external URL")
+	rootCmd.Flags().StringVar(&tunnelTokenPath, "tunnel-token-path", "", "File containing the tunnel provider token (or env SAM_TUNNEL_TOKEN); use with --tunnel <provider> --external-url https://...")
 	rootCmd.Flags().BoolVar(&tunnelInstall, "tunnel-install", false, "Download the pinned connector binary (cloudflared "+tunnel.CloudflaredVersion+", digest-verified) into <data-dir>/bin without asking; implies accepting its license")
 	rootCmd.Flags().StringVar(&cloudflaredPath, "cloudflared-path", "", "Explicit cloudflared executable for --tunnel cloudflare (default: PATH, then <data-dir>/bin)")
 	rootCmd.Flags().BoolVar(&enrollQR, "enroll-qr", stdoutIsTerminal(), "Print a device enrollment QR code at startup (default: when stdout is a terminal)")
@@ -304,6 +315,8 @@ type tunnelOptions struct {
 	dataDir         string
 	cloudflaredPath string
 	install         bool
+	token           string
+	externalURL     string
 }
 
 // openTunnel publishes the listener that Start is about to bind. The
@@ -317,6 +330,8 @@ func openTunnel(ctx context.Context, o tunnelOptions) (tunnel.Tunnel, error) {
 		cf.Binary = o.cloudflaredPath
 		cf.InstallDir = filepath.Join(o.dataDir, "bin")
 		cf.Consent = installConsent(o.install)
+		cf.Token = o.token
+		cf.ExternalURL = o.externalURL
 	}
 	host := o.bindAddress
 	if ip := net.ParseIP(host); host == "" || (ip != nil && ip.IsUnspecified()) {

deploy/skypilot/sam-one.yaml

@@ -0,0 +1,67 @@
+# SkyPilot recipe for deploying a standalone SAM control plane + router (sam-one)
+# on any cloud provider (GCP, AWS, Azure, OCI, or Kubernetes).
+#
+# Production deployment with a permanent custom domain:
+#   sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run \
+#     --env SAM_EXTERNAL_URL=https://mesh.example.com \
+#     --secret SAM_TUNNEL_TOKEN
+#
+# Quick deployment with an automatic HTTPS tunnel:
+#   sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
+#   sky logs sam-hub 1 --no-follow
+#
+# Note: For lightweight testing, you can lower `cpus: 0.25+` and `memory: 1+`
+# to run on cloud free-tier instances (such as GCP `e2-micro` or AWS `t4g.micro`).
+
+name: sam-hub
+
+resources:
+  disk_size: 20
+  use_spot: false
+  any_of:
+    - infra: gcp
+      instance_type: e2-standard-2
+    - cpus: 2+
+      memory: 4+
+
+envs:
+  SAM_EXTERNAL_URL: ""
+
+secrets:
+  SAM_TUNNEL_TOKEN: ""
+
+setup: |
+  set -euo pipefail
+  if ! command -v sam-one >/dev/null 2>&1; then
+    ARCH="$(uname -m)"
+    case "${ARCH}" in
+      x86_64*) ARCH_NAME="x86_64" ;;
+      aarch64*|arm64*) ARCH_NAME="arm64" ;;
+      *) echo "Unsupported architecture: ${ARCH}" >&2; exit 1 ;;
+    esac
+    VERSION=$(curl -fsSL -o /dev/null -w "%{url_effective}" "https://github.com/google/sam/releases/latest" | sed 's|.*/||')
+    if [[ -z "${VERSION}" || "${VERSION}" == "releases" ]]; then
+      VERSION=$(curl -fsSL "https://api.github.com/repos/google/sam/releases?per_page=1" | grep '"tag_name":' | head -n 1 | sed -E 's/.*"([^"]+)".*/\1/')
+    fi
+    TMP_DIR=$(mktemp -d)
+    curl -fsSL -o "${TMP_DIR}/sam.tar.gz" "https://github.com/google/sam/releases/download/${VERSION}/sam_Linux_${ARCH_NAME}.tar.gz"
+    tar -xzf "${TMP_DIR}/sam.tar.gz" -C "${TMP_DIR}"
+    sudo mv "${TMP_DIR}/sam-one" "${TMP_DIR}/sam-node" /usr/local/bin/
+    rm -rf "${TMP_DIR}"
+  fi
+
+run: |
+  set -euo pipefail
+  mkdir -p "${HOME}/sam-one"
+
+  ARGS=(
+    --data-dir "${HOME}/sam-one"
+    --port 8080
+    --tunnel cloudflare
+    --tunnel-install
+  )
+  if [[ -n "${SAM_EXTERNAL_URL:-}" ]]; then
+    ARGS+=(--external-url "${SAM_EXTERNAL_URL}")
+  fi
+
+  exec sam-one "${ARGS[@]}"

internal/router/router.go

@@ -358,14 +358,15 @@ func (r *Router) Start() error {
 		libp2p.EnableAutoNATv2(),
 		libp2p.EnableNATService(),
 		libp2p.AddrsFactory(func(addrs []multiaddr.Multiaddr) []multiaddr.Multiaddr {
-			if r.config.AllowLoopback {
-				return addrs
-			}
 			var filtered []multiaddr.Multiaddr
 			for _, addr := range addrs {
-				if !isLoopbackOrLinkLocal(addr) {
-					filtered = append(filtered, addr)
+				if isLinkLocal(addr) {
+					continue
 				}
+				if !r.config.AllowLoopback && isLoopbackOrLinkLocal(addr) {
+					continue
+				}
+				filtered = append(filtered, addr)
 			}
 			return filtered
 		}),
@@ -1361,6 +1362,22 @@ func getOrGeneratePeerKey(keyPath string) (crypto.PrivKey, error) {
 	return priv, nil
 }
 
+func isLinkLocal(addr multiaddr.Multiaddr) bool {
+	for _, proto := range addr.Protocols() {
+		if proto.Code == multiaddr.P_IP4 || proto.Code == multiaddr.P_IP6 {
+			value, err := addr.ValueForProtocol(proto.Code)
+			if err == nil {
+				if ip := net.ParseIP(value); ip != nil {
+					if ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() {
+						return true
+					}
+				}
+			}
+		}
+	}
+	return false
+}
+
 func isLoopbackOrLinkLocal(addr multiaddr.Multiaddr) bool {
 	for _, proto := range addr.Protocols() {
 		if proto.Code == multiaddr.P_IP4 || proto.Code == multiaddr.P_IP6 {