Configuring custom certificates before installation

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

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 Customizing user-facing certificates.

   • 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.yaml file and delete the default definitions for the certificates that you will customize.

   The ingress-issuer-v1.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:

        cloudManagerEndpoint:
          annotations:
            cert-manager.io/issuer: ingress-issuer
          hosts: 
          - name: admin.example.com
            secretName: cm-endpoint
      

   2. Delete the annotation for the cert-manager.io/issuer.

      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.

        cloudManagerEndpoint:
          annotations:
          hosts: 
          - name: admin.example.com
            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
      certManagerIssuer:
          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
      #certManagerIssuer:
      #    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:

   customCertificates:
      - name: caCertificate
        secretName: management-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