Connect through self-deployed runtime
Connect Atlan to a private AlloyDB for PostgreSQL instance with the self-deployed runtime - a small service in your network that reads AlloyDB locally and sends metadata out over outbound-only HTTPS.
The recommended path for AlloyDB instances with private IP only (the default). You run a small Atlan-provided service inside your network; it reads AlloyDB locally and sends metadata out over encrypted, outbound-only HTTPS. Five phases, each labeled with who performs it.
Read How AlloyDB connectivity works first (5 minutes). It explains VPC, private IP, SDR, and why "outbound-only" matters to your security team.
Prerequisites
- Somewhere to run the runtime inside a network that can reach your AlloyDB's private IP: Docker Compose on a VM, or a Kubernetes cluster (GKE if you want Workload Identity Federation auth).
- Outbound HTTPS (port 443) from that subnet to your Atlan tenant URL. No inbound rules needed.
- A secret store for the database credentials: AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, HashiCorp Vault, or Kubernetes Secrets.
- A database administrator to create the crawl user and grants (Phase 3).
Five phases at glance
| Phase | What happens | Owner | Typical time |
|---|---|---|---|
| 1. Plan | Pick the platform (Docker/K8s) and the subnet with a route to AlloyDB | Your infra/network team | 1 hour |
| 2. Deploy | Install and register the runtime; it appears in Atlan | Your infra/network team | Half a day |
| 3. Database user | Create the read-only crawl user and grants | Database admin | 30 minutes |
| 4. Secrets | Store credentials in your vault; point the runtime at them | Your infra/network team | 30 minutes |
| 5. Connect & verify | Configure the crawler with the runtime selected; test | Atlan User | 30 minutes |
Phase 1 - Plan deployment
Owner: Your infra/network team
- Choose Docker Compose (simplest - one VM) or Kubernetes (best for fleets and for GKE Workload Identity Federation).
- Place the runtime in a subnet that can open a TCP connection to the AlloyDB private IP on port 5432. Verify from that subnet before deploying:
# 10.52.0.7 is an illustrative private IP - use your instance's
nc -vz 10.52.0.7 5432
# expect: Connection to 10.52.0.7 5432 port [tcp/postgresql] succeeded!
- Confirm outbound HTTPS to
https://tenant.atlan.com(your tenant URL) is allowed through any egress proxy or firewall.
Phase 2 - Deploy and register runtime
Owner: Your infra/network team
Follow the Self-Deployed Runtime install guide for your platform (Docker Compose or Kubernetes). During install you'll generate an API token in Atlan and place it in the runtime's configuration; once running, the runtime registers itself and appears as a selectable deployment in Atlan's workflow setup.
The same runtime can crawl every source it can route to - all your AlloyDB instances, Cloud SQL, on-prem databases. You do not deploy one runtime per database.
Phase 3 - Create database user and grants
Owner: Database admin
CREATE ROLE atlan_user_role;
GRANT USAGE ON SCHEMA <schema> TO atlan_user_role;
GRANT SELECT, REFERENCES ON ALL TABLES IN SCHEMA <schema> TO atlan_user_role;
GRANT atlan_user_role TO <username>;
Repeat the schema grants for every schema you want crawled. A missing USAGE grant on a single schema surfaces later as a preflight or crawl failure for that schema only - grant everything up front.
Enable IAM database authentication on the AlloyDB instance, add the IAM user or service account as a database user, and grant it the same role above. You will also need the instance URI (projects/…/locations/…/clusters/…/instances/…) when configuring the crawler. On GKE, Workload Identity Federation lets the runtime authenticate with no stored key at all - this option exists only in the runtime path, not Direct.
Phase 4 - Store credentials in your vault
Owner: Your infra/network team
Put the database username/password (or service-account key) in your secret store and reference it in the runtime's workflow configuration, following Configure workflow execution (section "Configure secrets for workflow execution"). Credentials never leave your network - Atlan Cloud stores only the reference.
Phase 5 - Connect and verify
Owner: Atlan User
- In Atlan, open New workflow → AlloyDB Assets.
- Switch the extraction toggle from Direct to Self-Deployed Runtime and select your runtime.
- Enter the private IP or internal DNS name as Host, port
5432, the database name, and the credential reference. - Click Test connection.
Success checklist
- Test connection passes in the Atlan UI
- Preflight checks pass (they validate database/schema existence and grants)
- A crawl scoped to one small schema completes
- A full crawl completes - for very large instances see Special cases first
Next steps
Crawl AlloyDB for PostgreSQL: Configure and run the crawler to extract metadata from AlloyDB