Customizing certificates during installation on Kubernetes

How to customizing your user-facing and internal API Connect certificates during installation.

Note: The recommended best practice is to not customize your internal certificates, and to customize your user-facing certificates after API Connect is installed. If you do customize certificates, then you are responsible for maintaining those certificates. Ensure that your custom certificates meet the requirements that are defined in the Certificate reference tables (which are subject to change in future fix packs), and that you renew them before they expire. Follow the topics in this section only if you must customize internal certificates.

To deploy API Connect with custom internal certificates, some additional preparation and steps are required before any API Connect subsystem CRs are created. Review the topics in this section before you start the installation process.

Remember: As per the DNS specification, wildcard certificates apply only to one level of subdomain and not more than that. For example, a certificate for *.example.com is not valid for foo.bar.example.com.
Customization of the following certificates is supported:
Table 1. Management subsystem certificates
Certificate name Issuer Description
analytics-ingestion-client or a7s-ing-client ingress-issuer Client certificate used for communication with the analytics subsystem on the ingestion endpoint. This certificate must have:
  • The same CA as the server certificate analytics-ai-endpoint on the analytics subsystem.
  • The common name must match the spec.clientSubjectDN in the analytics CR:
    kubectl describe cert analytics-admin-client

Spec:
  Common Name:  a7s-ing-client
    kubectl get a7s -o yaml

  spec:
    clientSubjectDN: CN=a7s-ing-client

For a two data center disaster recovery deployment, both data centers must have an identical subject name. For example, both data centers subject name could be CN=a7s-ingestion-client, or they could both be CN=a7s-ingestion-client, O=cert-manager, but they must be identical.

To update this certificate, use kubectl. Restart the apim, taskmanager, and analytics-proxy pods after the update. This certificate is also used by the gateways for sending API events to the analytics subsystem. The updated certificate is sent by the management subsystem to the gateways, it is not necessary to restart any gateway pods.

This certificate is loaded by the management subsystem into the Analytics ingestion TLS client profile that you can see in the Cloud Manager UI (see TLS profiles). If you want the management subsystem to present a different client certificate to the analytics subsystem, then create a new profile and specify it when you register the analytics service.
portal-admin-client or ptl-adm-client ingress-issuer
Client certificate used for communication with the portal subsystem on the portalAdminEndpoint. This certificate must have:
  • The same CA as the server certificate portal-admin or ptl-director on the portal subsystem.
  • The common name must match the spec.adminClientSubjectDN in the portal CR:
    kubectl describe cert portal-admin-client

Spec:
  Common Name:  ptl-adm-client
    kubectl get ptl -o yaml

  spec:
    adminClientSubjectDN: CN=ptl-adm-client

For a two data center disaster recovery deployment, both data centers must have an identical subject name. For example, both data centers subject name could be CN=portal-admin-client, or they could both be CN=ptl-adm-client, O=cert-manager, but they must be identical.

This certificate is loaded by the management subsystem into the Portal Director TLS client profile that you can see in the Cloud Manager UI (see TLS profiles). If you want the management subsystem to present a different client certificate to the portal, then create a new profile and specify it when you register the portal service.
gateway-client-client or gw-dr-client ingress-issuer

Client certificate for communications with the gateway service. Restart the apim and taskmanager pods after update. This certificate must have the same CA as the gwv6-manager-endpoint or gw-gateway-manager certificate on the gateway.

This certificate is loaded by the management subsystem into the Gateway management client TLS client profile that you can see in the Cloud Manager UI (see TLS profiles). If you want the management subsystem to present a different client certificate to the gateway, then create a new profile and specify it when you register the gateway service.
cm-endpoint or mgmt-admin ingress-issuer Cloud Manager UI server certificate.
apim-endpoint or mgmt-api-manager ingress-issuer API Manager UI server certificate.
api-endpoint or mgmt-platform-api ingress-issuer Platform API endpoint server certificate. The certificate that is presented to callers of the platform REST API, and to the toolkit CLI.
consumer-endpoint or mgmt-consumer-api ingress-issuer Consumer API endpoint server certificate. The certificate presented that is presented to callers of the consumer REST API, and to the toolkit CLI.
Table 2. Analytics subsystem certificates
Certificate name Issuer Description
analytics-ai-endpoint or a7s-ai-endpoint ingress-issuer

Server certificate used on the analytics ingestion endpoint, in the mtls-gw pod. Management and gateway subsystems communicate with the analytics subsystem on this endpoint. The client certificates that are used by the management and gateway subsystems must use the same CA certificate as the analytics-ai-endpoint certificate.

If this certificate is updated, restart the mtls-gw pod for the update to take effect.
Table 3. Gateway certificates
Certificate name Issuer Description
gwv6-manager-endpoint or gw-gateway-manager ingress-issuer

The gatewayManager endpoint certificate. This is the server certificate on the gateway director endpoint, which the management subsystem communicates with.

This certificate must be signed by the same CA as the gateway-client-client certificate on management subsystem

If you update this certificate, then all gateway pods are restarted automatically.
gwv5-manager-endpoint or gw-gateway-manager ingress-issuer

The gatewayManager endpoint certificate for the v5 compatible gateway. This is the server certificate on the gateway director endpoint, which the management subsystem communicates with.

This certificate must be signed by the same CA as the gateway-client-client certificate on management subsystem

If you update this certificate, then all gateway pods are restarted automatically.
gwv6-endpoint or gw-gateway ingress-issuer Legacy certificate that is not used.
gwv5-endpoint or gw-gateway ingress-issuer Legacy certificate that is not used.
Table 4. Portal subsystem certificates
Certificate name Issuer Description
portal-admin or ptl-director or portal-director ingress-issuer

Server certificate used on the portalAdminEndpoint. The management subsystem communicates with the portal subsystem on this endpoint. The corresponding client certificate used in the management to portal communication is the portal-admin-client certificate.

This certificate must have the same CA as the portal-admin-client certificate on the management subsystem.

This certificate is used by the portal-nginx pod.
portal-web ingress-issuer

The server certificate used on the portalUIEndpoint. It is the server certificate that is presented to portal site users, and which their browser authenticates. If there is a problem with this certificate, then users see an error message about an invalid or insecure certificate in their browser when they access a portal site.

The default portal-web certificate is issued by the ingress-issuer, which has a self-signed root certificate. Portal users might see a browser warning about use of a self-signed certificate.

This certificate is used by the portal-web ingress (portal-web route on OpenShift).
Table 5. Internal intra-subsystem certificates
Certificate name spec.customCertificates name Description
management-ca caCertificate The issuer for the management subsystems intra-subsystem certificates: management-client, management-server, postgres, and nats certificates. Communication between management subsystem pods fails if there is a problem with this certificate.

This certificate is also used as the CA for REST API calls to the management subsystem from the other subsystems, when using in-cluster communication. See In-cluster service communication between subsystems
portal-ca caCertificate

The issuer for the portal-client and portal-server certificates. Communication between portal subsystem pods fails if there is a problem with this certificate.

This certificate is used by all portal pods.
analytics-ca caCertificate The issuer for the analytics-client and analytics-server certificates. Communication between analytics subsystem pods fails if there is a problem with this certificate.
If you update this certificate, you must then update the analytics-client and analytics-server server certificates, and then ensure that the following pods are restarted:
  • storage: Restarts automatically.
  • warehouse: Restarts automatically.
  • ingestion: Restart manually.
  • director: Restart manually.
management-client clientCertificate Client certificate used in communication between management subsystem pods. Communication between management subsystem pods fails if there is a problem with this certificate.
portal-client clientCertificate

Client certificate used in communication between portal subsystem pods. Communication between portal subsystem pods fails if there is a problem with this certificate.

This certificate is used by all portal pods.
analytics-client clientCertificate Client certificate used in communication between analytics subsystem pods. Communication between analytics subsystem pods fails if there is a problem with this certificate.

If this certificate is updated, then the storage and warehouse pods restart automatically. You must manually restart the director and ingestion pods.
management-server serverCertificate Server certificate used in communication between management subsystem pods. Communication between management subsystem pods fails if there is a problem with this certificate.
Required DNS names within the SAN section are:
*.<namespace>
*.<namespace>.svc
*.<namespace>.svc.cluster.local
*.<instance name>-server.<namespace>.svc
*.<instance name>-server.<namespace>.svc.cluster.local
<instance name>-server
portal-server serverCertificate

Server certificate used in communication between portal subsystem pods. Communication between portal subsystem pods fails if there is a problem with this certificate.

Required DNS names within the SAN section are:
*.<namespace>
*.<namespace>.svc
*.<namespace>.svc.cluster.local
*.<instance name>-server.<namespace>.svc
*.<instance name>-server.<namespace>.svc.cluster.local
<instance name>-server
*.<instance name>-<site name>-db-all.<namespace>.svc
*.<instance name>-<site name>-www-all.<namespace>.svc
*.<instance name>-<site name>-db-all.<namespace>.svc.cluster.local
*.<instance name>-<site name>-www-all.<namespace>.svc.cluster.local
*.<namespace>.svc.cluster.local
<instance name>-db
#<remote portal CR name>-db # For 2DCDR only.
<instance name> and <remote portal CR name> are truncated if more than 15 characters.

This certificate is used by all portal pods.
analytics-server serverCertificate Server certificate used in communication between analytics subsystem pods. Communication between analytics subsystem pods fails if there is a problem with this certificate.
Required DNS names within the SAN section are:
*.<namespace>
*.<namespace>.svc
*.<namespace>.svc.cluster.local
*.<instance name>-server.<namespace>.svc
*.<instance name>-server.<namespace>.svc.cluster.local
<instance name>-server
<instance name>-storage
<instance name>-director
<instance name>-ingestion
<instance name>-mtls-gw
<instance name>-storage-os-master
<instance name>-warehouse

If this certificate is updated, then the storage and warehouse pods restart automatically. You must manually restart the director and ingestion pods.
db-server dbServerCertificate Intra-subsystem certificate for the management database.
natscluster-mgmt NATSTLSCertificate Intra-subsystem certificate for the nats pods.
db-client-postgres dbClientPostgres Intra-subsystem certificate for the management database subsystem.
db-client-apicuser dbClientApicuser Intra-subsystem certificate for the management database subsystem.

To see the complete list of TLS certificates, see API Connect TLS certificates.

Note: The API invocation certificate that callers to the published APIs on your gateways see is configured in the Cloud Manager UI when you register your gateway services. For more information about API invocation certificates, see Registering a gateway service and TLS profiles overview.

You can replace the default certificates with certificates that you already own, for example DigiCert certificates, or generate new custom certificates by using software such as cert-manager.

If you want to customize API Connect internal certificates (the certificates for communication within API Connect components), then you must customize all of them, but you do not need to create all of them yourself. Any custom internal certificates that are not named in your subsystem CRs are generated automatically during installation. You cannot convert an existing API Connect installation to use custom internal certificates, these certificates must be configured at installation.

Setting an encryption-secret for the management database using OpenSSL

You can optionally create an encryption-secret for the management database. If you do not create an encryption-secret, then it is created automatically for you.

  1. The encryption-secret is a secure random bytes password that is used for field level encryption in the management database. You can generate 128 random bytes using the following command in OpenSSL:
    openssl rand -out /path/to/secret/encryption-secret.bin 128
  2. Use kubectl to put the generated secret into management-encryption-key:
    kubectl create secret generic management-encryption-key -n <namespace>
      --from-file=/path/to/secret/encryption_secret.bin

    where <namespace> is the namespace where the management CR is going to be created)

  3. Make sure that in management_cr.yaml, encryptionSecret.secretName points to the name of the secret created in the previous step.
Important: Back up the encryption-secret.bin file to a safe location. If this file is lost, then it is not possible to access the management database or its backups.