# googlecloudplatform/alloydb-auth-proxy architecture

> Architecture diagram of the GitHub repository googlecloudplatform/alloydb-auth-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/alloydb-auth-proxy
- Repository: https://github.com/googlecloudplatform/alloydb-auth-proxy

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    ClientApp["Client Application<br/>(e.g., psql)"]:::orange

    %% Auth Proxy Process
    subgraph "Auth Proxy Process"
        CLI["AlloyDB Auth Proxy CLI"]:::green
        Config["Config Loader<br/>(flags & config file)"]:::green
        ProxyEngine["Core Proxy Engine"]:::green
        Gcloud["gcloud Module"]:::green
        Health["Healthcheck Module"]:::green
        Log["Logging Module"]:::green
        AdminServer["Admin HTTP Server<br/>(pprof, quit)"]:::green
        Metrics["Metrics Exporter"]:::green
        FUSE["FUSE Support"]:::gray
    end

    %% External Services
    AlloyAPI["AlloyDB Admin API"]:::blue
    IAM["Google Cloud IAM"]:::blue
    DB["AlloyDB Instance"]:::orange
    Prometheus["Prometheus"]:::blue
    CloudMon["Cloud Monitoring"]:::blue
    CloudTrace["Cloud Trace"]:::blue
    SOCKS["SOCKS5 Proxy<br/>(optional)"]:::gray

    %% Data Flows
    ClientApp -->|"PostgreSQL TCP"| ProxyEngine
    CLI --> Config
    Config --> ProxyEngine
    ProxyEngine -->|"TLS PostgreSQL"| DB
    ProxyEngine -->|"HTTPS API"| AlloyAPI
    ProxyEngine -->|"HTTPS API"| IAM
    ProxyEngine --> Metrics
    Metrics --> Prometheus
    Metrics --> CloudMon
    Metrics --> CloudTrace
    ProxyEngine --> FUSE
    ProxyEngine --> AdminServer
    %% Optional SOCKS5 chaining
    ProxyEngine -->|"via ALL_PROXY"| SOCKS
    SOCKS --> AlloyAPI
    SOCKS --> IAM

    %% Click Events
    click CLI "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/main.go"
    click CLI "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/root.go"
    click CLI "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/errors.go"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/root.go"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/config_test.go"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/testdata/config-json.json"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/testdata/config-toml.toml"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/testdata/config-yaml.yaml"
    click Config "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/testdata/two-instances.toml"
    click ProxyEngine "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/proxy.go"
    click ProxyEngine "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/proxy_other.go"
    click ProxyEngine "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/unix.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse_darwin.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse_freebsd.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse_linux.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse_openbsd.go"
    click FUSE "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/proxy/fuse_windows.go"
    click Gcloud "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/gcloud/gcloud.go"
    click Gcloud "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/gcloud/gcloud_test.go"
    click Health "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/healthcheck/healthcheck.go"
    click Health "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/healthcheck/healthcheck_test.go"
    click Log "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/internal/log/log.go"
    click AdminServer "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/root.go"
    click AdminServer "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/main.go"
    click Metrics "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/cmd/root.go"
    click AlloyAPI "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/docs/cmd/alloydb-auth-proxy.md"
    click AlloyAPI "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/docs/cmd/alloydb-auth-proxy_wait.md"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/tree/main/Dockerfile"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/tree/main/examples/k8s-sidecar/"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/tree/main/examples/multi-container/ruby/"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/tree/main/examples/go/"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/tests/alloydb_test.go"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/tests/connection_test.go"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/tests/fuse_test.go"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/tests/common_test.go"
    click DB "https://github.com/googlecloudplatform/alloydb-auth-proxy/blob/main/tests/other_test.go"

    %% Styles
    classDef green fill:#c6f6d5,stroke:#2f855a,color:#22543d;
    classDef blue fill:#bee3f8,stroke:#2b6cb0,color:#2a4365;
    classDef orange fill:#fbd38d,stroke:#dd6b20,color:#975a16;
    classDef gray fill:#e2e8f0,stroke:#718096,color:#2d3748;
    class CLI,Config,ProxyEngine,Gcloud,Health,Log,AdminServer,Metrics green
    class AlloyAPI,IAM,Prometheus,CloudMon,CloudTrace blue
    class ClientApp,DB orange
    class SOCKS,FUSE gray
```
