AlloyDB Omni on Kubernetes Connection Overview

This overview describes the critical connection and access configurations for AlloyDB Omni databases deployed on a Kubernetes cluster, and it details how to establish flexible and secure connectivity. Connection includes the following areas:

  • Networking: learn how to configure AlloyDB Omni database clusters for either internal access using a Kubernetes ClusterIP Service or external access using a LoadBalancer, including how to restrict external traffic using source Classless Inter-Domain Routing (CIDR) ranges.
  • Connection pooling: use the PgBouncer Custom Resource to implement connection pooling for efficient connection management and reduced load on database instances.
  • Authentication and authorization: secure access using supported methods like password-based and Active Directory/Kerberos integration, alongside fine-grained control implemented through Kubernetes network policies and PostgreSQL roles.

Networking

You can configure AlloyDB Omni database clusters—managed by the DBCluster custom resource—for internal or external access.

For more details on DBCluster networking options, refer to the DBCluster CRD Reference.

Internal connectivity

By default, AlloyDB Omni instances are exposed using a Kubernetes ClusterIP Service. This ensures that the instances are only accessible to other applications running in the same Kubernetes cluster. You can find the endpoint for the primary instance in the DBCluster status.

External connectivity

To allow connections from outside the Kubernetes cluster, update the DBCluster specification:

  • Enable external traffic: set spec.allowExternalIncomingTraffic: true, which typically provisions a LoadBalancer Service.
  • Implement fine-grained control: use spec.primarySpec.dbLoadBalancerOptions. For example, on Google Cloud, set gcp.loadBalancerType: "External" to obtain an IP address accessible from the public internet.

Restrict access

To secure external connections, use spec.primarySpec.sourceCidrRanges to define a list of allowed CIDR ranges. The system blocks any connections originating from IP addresses outside these ranges.

Connection pooling with PgBouncer

To manage connections efficiently and reduce instance load, use PgBouncer. The AlloyDB Omni Operator provides a PgBouncer Custom Resource (CR) to simplify this operation.

For comprehensive details on configuring PgBouncer, see the PgBouncer CRD Reference.

Deployment and configuration

Create a PgBouncer resource and reference your database cluster in spec.dbclusterRef. Key parameters in spec.parameters include the following:

  • pool_mode: determines when connections are reused (session, transaction, or statement).
  • default_pool_size: server connections per user and database.
  • max_client_conn: maximum allowed client connections.
  • max_db_connections: maximum connections opened to the AlloyDB Omni instance.

Expose PgBouncer

Use spec.serviceOptions.type to control visibility.

  • ClusterIP: internal cluster access only.
  • LoadBalancer: external access. You can restrict this with spec.serviceOptions.loadBalancerSourceRanges using CIDR blocks.

Authentication and authorization

AlloyDB Omni supports multiple methods to verify identities and control access.

Authentication methods

  • Password-based: Standard PostgreSQL username and password authentication. The administrator password is typically provided using a Kubernetes Secret, as shown in the Full DBCluster Sample.

  • Active Directory and Kerberos: Managed using the UserDefinedAuthentication CR. This supports GSSAPI and LDAP group synchronization using the following:

    • spec.keytabSecretRef: for Kerberos keytabs.
    • spec.ldapConfiguration: for group mapping and LDAP settings.
    • spec.pgHbaEntries: to configure pg_hba.conf rules–for example, gss or ldap.

    For more information, see the UserDefinedAuthentication CRD Reference.

  • Certificate-based (planned): support for passwordless TLS certificate authentication is planned for a future release.

Authorization and access control

  • Kubernetes network policies: define pod-level rules to secure traffic between applications and AlloyDB Omni or PgBouncer pods.
  • Source CIDR ranges: restrict traffic at the LoadBalancer level.
  • PostgreSQL roles: use standard database roles and privileges to manage user permissions after the users are authenticated.

What's next