Configure client authentication

Select a documentation version:

This document describes how to configure client authentication on your Kubernetes-based AlloyDB Omni database cluster using the UserDefinedAuthentication custom resource (alloydbomni.dbadmin.goog/v1). You can customize client authentication behavior—such as restricting client subnets, enforcing SSL/TLS, specifying custom authentication methods, or configuring user mapping—by defining custom pg_hba.conf and pg_ident.conf entries independently of Active Directory setup.

This document assumes that you're familiar with applying Kubernetes manifest files and using the kubectl command-line tool. For more information, see Command line tool (kubectl).

Before you begin

To configure client authentication, you must have the following:

  • An AlloyDB Omni cluster deployed in a Kubernetes environment.
  • Database users and roles configured in the cluster.
  • The kubectl CLI installed and configured.

Apply the custom resource manifest

Apply the following user-defined authentication custom resource manifest:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: UserDefinedAuthentication
metadata:
  name: USER_DEFINED_AUTHENTICATION_NAME
  namespace: DB_CLUSTER_NAMESPACE
spec:
  dbclusterRef:
    name: DB_CLUSTER_NAME
  pgHbaEntries:
    PG_HBA_ENTRIES
  pgIdentEntries:
    PG_IDENT_ENTRIES

Replace the following:

  • USER_DEFINED_AUTHENTICATION_NAME: the name of the UserDefinedAuthentication custom resource—for example, DB_CLUSTER_NAME-client-auth.
  • DB_CLUSTER_NAMESPACE: the Kubernetes namespace for this custom resource. The namespace must match the namespace of the database cluster.
  • DB_CLUSTER_NAME: the name of your database cluster, which you assigned when you created it.
  • PG_HBA_ENTRIES: pg_hba.conf entries as a string list. These entries overwrite the default entries in pg_hba.conf. For example, to restrict connections to a specific subnet, use - "host all all 192.168.1.0/24 scram-sha-256". For more information, see The pg_hba.conf File.
  • PG_IDENT_ENTRIES: (Optional) pg_ident.conf entries as a string list. To implement username mapping, specify map= in the options field in the pg_hba.conf file. If you don't need username mapping, omit the pgIdentEntries field from the manifest. For more information, see User Name Maps.

Verify the client authentication rules

To check the status of the UserDefinedAuthentication resource, run the following command:

kubectl get userdefinedauthentication -n DB_CLUSTER_NAMESPACE

Verify that the STATE column displays Ready.

To view resource details and conditions, run the following command:

kubectl describe userdefinedauthentication USER_DEFINED_AUTHENTICATION_NAME -n DB_CLUSTER_NAMESPACE

Update client authentication rules

To update client authentication rules or user mappings, update spec.pgHbaEntries or spec.pgIdentEntries in your manifest file and re-apply it:

kubectl apply -f CLIENT_AUTH_MANIFEST.yaml

The AlloyDB Omni operator dynamically reloads the PostgreSQL configuration (pg_ctl reload) without database pod restart or downtime.

Delete client authentication rules

To delete the custom authentication rules and revert to the default authentication rules, run the following command:

kubectl delete userdefinedauthentication USER_DEFINED_AUTHENTICATION_NAME -n DB_CLUSTER_NAMESPACE

When you delete the UserDefinedAuthentication resource, the AlloyDB Omni operator dynamically reloads pg_hba.conf (pg_ctl reload) to restore the default authentication rules without requiring a database pod restart.

What's next