Manage certificates

Select a documentation version:

This page describes how to use custom certificate issuers to manage Transport Layer Security (TLS) certificates on your Kubernetes-based AlloyDB Omni database cluster.

By default, the AlloyDB Omni Kubernetes operator uses cert-manager to provision a set of TLS certificates for each database cluster. Besides the database server certificate, the operator also creates certificates for control plane components to ensure internal connections are also secure. By default, each certificate is signed by an issuer managed by the operator.

Starting with AlloyDB Omni operator version 1.6.0, if you prefer all certificates, including those for control plane components, to be chained back to your own trusted root CA, you can configure the operator to use an issuer of your choice. This lets you chain all certificates to your own public key infrastructure (PKI), including certificates used for control plane functionality, without exposing the implementation details of each internal entity.

Before you begin

To configure a certificate issuer, you must first create a cert-manager issuer of type ClusterIssuer or Issuer that is associated with the CA you want to sign your certificates. The AlloyDB Omni operator references this issuer when creating certificates.

Configure custom issuers

You can configure custom certificate issuers for the database cluster, the AlloyDB Omni operator, and PgBouncer.

Database cluster certificates

This feature requires that the relevant database cluster's controlPlaneAgentsVersion in its manifest is 1.6.0 or higher.

There are two database cluster spec fields to configure certificate issuers:

  • spec.primarySpec.dataPlaneCertIssuer: reference to the cert-manager issuer that provisions data plane certificates. The issuer CA is the one that the database client can trust in order to verify the database during a TLS connection.

  • spec.primarySpec.controlPlaneAgentsCertIssuer: reference to the cert-manager issuer that provisions control plane certificates. These certificates are used for internal connections.

spec:
  primarySpec:
    tls:
      dataPlaneCertIssuer:
        name: DATA_PLANE_ISSUER_NAME
        kind: DATA_PLANE_ISSUER_KIND
      controlPlaneAgentsCertIssuer:
        name: CONTROL_PLANE_ISSUER_NAME
        kind: CONTROL_PLANE_ISSUER_KIND

Replace the following:

  • DATA_PLANE_ISSUER_NAME: name of the cert-manager issuer that provisions data plane certificates, such as for the database server.

  • DATA_PLANE_ISSUER_KIND: must be either Issuer or ClusterIssuer.

  • CONTROL_PLANE_ISSUER_NAME: name of the cert-manager issuer that provisions control plane certificates for internal components.

  • CONTROL_PLANE_ISSUER_KIND: must be either Issuer or ClusterIssuer.

Operator certificates

The steps for configuring a cert-manager issuer for operator certificates depend on the method used to install AlloyDB Omni.

Configure using Helm

If you install AlloyDB Omni operator version 1.6.0 or later for the first time, use Helm install and set the appropriate values. This assumes that you follow the installation instructions.

helm install alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \
--create-namespace \
--namespace alloydb-omni-system \
--set operatorCertIssuer.certManagerIssuerName="OPERATOR_CERT_ISSUER_NAME" \
--set operatorCertIssuer.certManagerIssuerKind="OPERATOR_CERT_ISSUER_KIND" \
--atomic \
--timeout 5m

If you already have the operator installed and need to set the certificate issuer, use helm upgrade to set the appropriate values:

helm upgrade alloydbomni-operator alloydbomni-operator-${OPERATOR_VERSION}.tgz \
--create-namespace \
--namespace alloydb-omni-system \
--set operatorCertIssuer.certManagerIssuerName="OPERATOR_CERT_ISSUER_NAME" \
--set operatorCertIssuer.certManagerIssuerKind="OPERATOR_CERT_ISSUER_KIND" \
--atomic \
--timeout 5m

Replace the following:

  • OPERATOR_CERT_ISSUER_NAME: name of the cert-manager issuer that provisions the operator certificate, which is used for internal connections.

  • OPERATOR_CERT_ISSUER_KIND: must be either Issuer or ClusterIssuer.

Configure using Operator Lifecycle Manager

If you used Operator Lifecycle Manager (OLM) to install the AlloyDB Omni operator, you can modify the Subscription resource spec.config.env field to set the CERT_MANAGER_ISSUER_NAME and CERT_MANAGER_ISSUER_KIND environment variables of the operator Deployment.

spec:
  config:
    env:
    - name: CERT_MANAGER_ISSUER_NAME
      value: OPERATOR_CERT_ISSUER_NAME
    - name: CERT_MANAGER_ISSUER_KIND
      value: OPERATOR_CERT_ISSUER_KIND

Replace the following:

  • OPERATOR_CERT_ISSUER_NAME: name of the cert-manager issuer that provisions the operator certificate, which is used for internal connections.

  • OPERATOR_CERT_ISSUER_KIND: must be either Issuer or ClusterIssuer.

PgBouncer certificates

To support custom issuers, the PgBouncer controller can check the DBCluster spec.primarySpec.tls.dataPlaneCertIssuer field and use that to provision the PgBouncer certificate. This ensures that PgBouncer uses a certificate from the same CA as the database.

Verify

To verify that the operator Deployment is healthy and that the environment variables CERT_MANAGER_ISSUER_NAME and CERT_MANAGER_ISSUER_KIND are set, run the following command:

kubectl get deployments local-controller-manager -n alloydb-omni-system -o yaml

To verify that the correct issuer is used, inspect the Certificate objects as follows:

kubectl get certificate -n NAMESPACE

Check the issuerRef field in the output for each certificate to confirm that it matches your custom issuer.