Configuring custom certificates before installation

Configure custom certificates for your API Connect deployment before you begin the installation procedures.

About this task

To deploy API Connect with custom certificates, complete the following steps to configure your custom certificates before applying any subsystem installation CRs to the cluster.


  1. Determine which certificates you want to customize.

    For a list of certificates that can be customized, see Custom certificates reference.

    You can customize the following types of certificates:

    • Endpoint (External Frontend/Ingress) certificates:

      These are the certificates for external, public-facing endpoints where users interact with API Connect. You can customize none, some, or all of the endpoint certificates.

      If you initially deploy APIC using default certificates for endpoints, you can convert them to custom certificates later as explained in Converting to custom certificates for external endpoints.

    • Internal (CA, Client, Server, and Common Subsystem Communication) cerificates:

      These are the certificates used within API Connect, so that subsystems can communicate. If you want to customize any of the internal certificates, then you must customize all of them; however you don’t have to create them all yourself. Any custom certs that are not specifically named in your deployment CR will be generated automatically during installation.

      If you initially deploy API Connect using default certificates for internal certificates, you cannot convert them to custom certificates later.

  2. Prepare your custom certificates.

    If you don’t have a set of custom certificates already, you can use Kubernetes Cert-manager to generate them as explained in Generating custom certificates.

    When preparing your custom certificates, remember that certain pairs of certificates must by signed by the same Certificate Authority, as noted in Custom certificates reference.

    If you're installing a two data center disaster recovery configuration, and are using custom certificates, then the subject names of any client certificates must be the same in both data centers, as noted in Custom certificates reference. 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.

  3. If needed, create a Kubernetes secret for each custom certificate.

    Each custom certificate that you use must be captured in a TLS secret. To create a secret, use the following commnad:

    kubectl create secret generic my-tls-secret --from-file=tls.crt=<path_to_cert_file> --from-file=tls.key=<path_to_key_file> --from-file=ca.crt=<path_to_cacert_file>

    When you create each secret, it's helpful to reference its purpose or its corresponding certificate in the secret name, to ensure you specify the correct secret for each custom certificate.

  4. Edit the ingress-issuer-v1-alpha1.yaml file and delete the default definitions for the certificates that you will customize.

    The ingress-issuer-v1-alpha1.yaml file is provided as part of the installation helper_files archive.

    This file is used for generating the default certificates. To use a custom certificate, you must delete the default definition to ensure that API Connect uses your certificate instead of the default certificate. If you customize all of the default certificates and delete those definitions from the file, then you don't need to use the file during installation.

  5. Customize endpoint (External Frontend/Ingress) certificates in the corresponding subsystem CRs.

    For each custom endpoint certificate, delete the annotation that specifies the default issuer, and replace the secret name with your own custom secret name.

    1. Open the subsystem CR for editing and locate the endpoint definition.

      For example, the following snippet shows the definition for the cloudManagerEndpoint in the Management CR:

          - name:
            secretName: cm-endpoint
    2. Delete the annotation for the

      Delete the field name as well as the value; you can leave the annotations: label in place.

    3. Replace the default secret name with the name of the Kubernetes secret that you created for that endpoint’s custom certificate.

      In the following example, cm-endpoint is the default secret name, which must be replaced. Make sure to reference the correct secret for the custom certificate.

          - name:
            secretName: my_cm-endpoint
  6. Customize internal (CA, Client, Server, and Common Subsystem Communication) certificates.
    1. Open the subsystem CR for editing.
    2. Set the microServiceSecurity setting to custom.

      By default, the setting is configured for certManager as shown in the following example:

      microServiceSecurity: certManager
          name: selfsigning-issuer
          kind: Issuer
    3. Delete (or comment-out) the certManagerIssuer block.

      In the following example, microServiceSecurity is set to custom and the certManagerIssuer block is commented out:

      microServiceSecurity: custom
      #    name: selfsigning-issuer
      #    kind: Issuer
  7. Add the customCertificates block and list the secret name for each internal custom certificate that you created for the subsystem.

    Each subsystem supports a different set of Common Subsystem Communication and External Frontend/Ingress certificates. You do not have to provide a custom version of every certificate supported by the subsystem. Just list the custom certificates that you created; any certificates that you omit from the list will be generated automatically during installation.

    For example, your customCertificates list for the Management subsystem might look like the following example:

       - name: caCertificate
         secretName: my_ingress-ca
       - name: clientCertificate
         secretName: my_management-client
       - name: serverCertificate
         secretName: my_management-server
       - name: dbServerCertificate
         secretName: my_db-server-certificate
       - name: pgBouncerServerCertificate
         secretName: my_pg-bouncer-server-certificate
       - name: PGOTLSCertificate
         secretName: my_pgo.tls
       - name: NATSTLSCertificate
         secretName: my_management-natscluster-mgmt
       - name: dbClientPostgres
         secretName: my_db-client-postgres
       - name: dbClientReplicator
         secretName: my_db-client-replicator
       - name: dbClientPgbouncer
         secretName: my_db-client-pgbouncer
       - name: dbClientApicuser
         secretName: my_db-client-apicuser
       - name: dbClientPrimaryuser
         secretName: my_db-client-primaryuser

What to do next

Deploy API Connect: