How googlecloudplatform/alloydb-auth-proxy works
Project type and purpose
• This is an open-source, command-line proxy written in Go.
• Purpose: listen on local TCP ports, acquire IAM-authorized ephemeral certificates, tunnel PostgreSQL-protocol traffic securely to an AlloyDB instance, and optionally expose admin/metrics endpoints.
File structure
• Top-level “cmd/…” and “main.go” ⇒ CLI entry points and flag parsing.
• “internal/…” packages ⇒ core modules:
• internal/proxy ⇒ connection setup, TLS layering, FUSE support
• internal/gcloud ⇒ gcloud metadata & IAM token retrieval
• internal/healthcheck ⇒ readiness/liveness checks
• internal/log ⇒ structured logging
• “docs/” and “examples/” ⇒ usage patterns, deployment examples (Docker, K8s sidecar).
• “Dockerfile*” ⇒ container variants.
• “tests/” ⇒ integration & unit tests around proxy behavior.
README for extra insights
• Describes interactions with:
• AlloyDB Admin API (for ephemeral certs & instance metadata)
• Cloud IAM (via ADC or service-account key)
• Metrics sinks: Cloud Monitoring, Cloud Trace, Prometheus
• Optional SOCKS5 proxy for outbound API calls
• Local admin HTTP server on port 9091 for /debug/pprof and /quitquitquit
a. Main components:
1. Client Application (e.g., psql or app driver)
2. AlloyDB Auth Proxy CLI (process)
– Config Loader (flags + config file)
– Core Proxy Engine (internal/proxy)
– gcloud Module (internal/gcloud)
– Healthcheck & Logging Modules
– Admin HTTP Server (pprof, quit endpoint)
– Metrics Exporter (Prometheus handler + Cloud Monitoring/Trace SDK)
3. AlloyDB Instance (PostgreSQL wire protocol endpoint)
4. External Services:
– AlloyDB Admin API (ephemeral certificate CSR & metadata)
– Google Cloud IAM (token issuance via ADC or key file)
– Metrics Backends (Cloud Monitoring, Cloud Trace, Prometheus)
– Optional SOCKS5 Proxy (via ALL_PROXY, HTTPS_PROXY env)
b. Relationships & data flow:
• Client → TCP (“localhost:port”) → Proxy listens.
• Proxy reads config, invokes internal/gcloud to fetch an IAM token or metadata.
• Proxy → AlloyDB Admin API (HTTPS) to request ephemeral cert.
• Proxy → (optionally via SOCKS5) Cloud IAM & Admin API.
• Proxy sets up TLS connection to AlloyDB instance’s IP/port.
• Proxy relays PostgreSQL protocol back to client.
• Proxy emits metrics & traces to configured sinks.
• Optional Admin HTTP server serves /metrics or /debug endpoints.
c. Architectural patterns & design principles:
• Modular internal packages for separation of concerns.
• Single-process, multi-port listener pattern (one port per instance).
• Pluggable credential providers (flags, ADC, service-account).
• Env-driven proxy chaining (SOCKS5 for HTTP/API calls).
• Sidecar/Container deployment (see examples/k8s-sidecar).
d. Key technologies & frameworks:
• Go modules & standard library (net, http, tls).
• Google Cloud Go SDK for IAM & AlloyDB Admin API calls.
• Prometheus client library.
• pprof for profiling.
• FUSE support on some platforms (internal/proxy/fuse.go).
Capturing essential architectural elements
• Don’t over-break; group related internal packages under “Auth Proxy Process.”
• Both the “control plane” (certificate/API calls) and “data plane” (PostgreSQL TCP).
• Admin HTTP server as a secondary listener.
• Which ports are used (5432, 9091, etc.) and which flags (—address, —port, —admin-port) govern them.