Installing API Connect on IKS with custom certificates

Complete configuration steps that enable deployment of API Connect on IKS with custom certificates.

Before you begin

You should have custom certificates ready for use in deployment.

About this task

Follow the steps below to prepare for installation.

Procedure

Ensure you have Custom Certificates for all External Frontend/Ingress and Common Subsystem Communication Certificates.

For an IKS installation, all of the External Frontend/Ingress certificates from the Custom certificates reference for IKS must be customized. Since some of these certificates must be signed by the same CA as the Common Subsystem Communication certificates, the Common Subsystem Certificates must also be customized.

Before proceeding, ensure that you are able to provide custom certificates for all of these. These can be certificates that you provide from your own sources, or certificates that you generated with Cert-Manager V0.12 as described in Generating custom certificates using default values for IKS or Generating custom certificates manually for IKS .
Disable Cert-Manager V0.10.1 Dependencies

The IBM API Connect Operator expects that Cert-Manager V0.10.1 Custom Resource Definitions (CRDs) are present on the Cluster before startup and installation, even though Cert-Manager V0.12 is being used, due to a limitation.
1. First, check if you have the cert-manager-0.10.1-crds.yaml file in the helper_files installation archive.
  If you do, apply this into your cluster with the following command:
```
kubectl create -f cert-manager-0.10.1-crds.yaml
```
  If you do not have this file, you must edit the cert-manager-0.10.1.yaml file in the helper_files installation archive file to remove all Kubernetes resources with the exception of those that are CustomResourceDefinitions. To do this, delete everything from this file after line 7514. Save the file, and then apply it into your cluster with the following command:
```
kubectl create -f cert-manager-0.10.1.yaml
```
2. Next, configure the operator so that it does not try to use Cert-Manager v0.10.1.
  Open ibm-apiconnect.yaml from the helper_files installation archive, and locate the following section in the spec.template.spec.containers.env block:
```
          - name: OPERATOR_NAME
          value: ibm-apiconnect
```
  Append the following environment variable immediately after it:
```
          - name: DISABLE_CERT_MANAGER
          value: "true"
```
  So that the section now looks like the following example:
```
        - name: OPERATOR_NAME
          value: ibm-apiconnect
        - name: DISABLE_CERT_MANAGER
          value: "true"
```
Set custom Microservice Security in subsystem CRs.
When customizing all External Frontend/Ingress and Common Subsystem Communication Certificates, Cert-Manager will not be managing the certificates for the subsystems. The CRs for each subsystem must be updated for this change.

In each subsystem CR, locate microServiceSecurity and certManagerIssuer inside the spec block:
```
microServiceSecurity: certManager
certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
```
Set microServiceSecurity to custom, and remove or comment-out the certManagerIssuer block as follows:
```
microServiceSecurity: custom
#certManagerIssuer:
#    name: selfsigning-issuer
#    kind: Issuer
```
If not using Cert-Manager V0.12, create the Kubernetes Secrets to hold the custom certificates:

If you are providing your own custom certificates, rather than using Cert-Manager V0.12 to generate them, each custom certificate that you plan to use must now be created in the Cluster as a Kubernetes Secret, of type kubernetes.io/tls. Secrets of this type must contain the three following data items: ca.crt, tls.crt, and tls.key.

Take note of the names that you use for each of these secrets. The names must match up with each of the secretName properties specified for each Endpoint in the subsystem CR. For example, in the Management CR YAML snippets above, the Secret holding the certificate for the cloudManagerEndpoint is expected to be named cm-endpoint. Therefore, the Kubernetes Secret containing the custom certificate for the cloudManagerEndpoint must be named cm-endpoint.
Take one of the following actions, based on whether or not you are customizing the API Connect internal certificates
- If you do not plan to customize all internal certificates (as recommended), once the matching host.SecretName values have been verified against the names of the Kubernetes Secrets for these custom certificates, apply the Subsystem CRs into the Cluster. Continue with Installing the API Connect subsystems
- If you plan to customize all internal certificates (not recommended), continue with6
Note:
- It is not recommended to customize internal certificates unless you have a specific requirement to do so. You must also provide custom certificates for all the Common Subsystem Communication, and External Frontend/Ingress certificates.
- For internal certificates, custom certificates must be provided for all internal certificates in each subsystem CR. Only providing custom certificates for some is not supported, and will be rejected by Operator validation
Customizing internal certificates in Management, Analytics, and Portal CRs.
1. Customize the Common Subsystem Communication and External Frontend/Ingress Certificates.
  If Internal Certificates are to be customized, then you must customize all the Common Subsystem Communication and External Frontend/Ingress certificates found in Custom certificates reference for IKS. To do this, follow the instructions in Generating custom certificates manually for IKS.
  
  This step is required because Cert-Manager must be completely turned off in the Subsystem CRs when internal certificates are to be customized.
2. Create the Kubernetes Secrets to Hold the Custom Certificates if not using Cert-Manager V0.12
  If you plan to provide these custom certificates yourself, and not generate them using Cert-manager, use custom-certs-internal.yaml in the helper_files installation archive as a guide to set the required Common Names and DNS Names (inserted into the certificates as Subject Alternative Names) for each Internal certificate listed in Custom certificates reference for IKS.
  
  Each customized Internal certificate that you provide and plan to use must now be created in the Cluster as a Kubernetes Secret, of type kubernetes.io/tls. Secrets of this type must contain the three following data items: ca.crt, tls.crt, and tls.key. The names of each of these Secrets must match the names listed in Custom certificates reference for IKS.
3. Disable Cert-Manager V0.10.1 Dependencies
  The IBM API Connect Operator expects that Cert-Manager V0.10.1 Custom Resource Definitions (CRDs) are present on the Cluster before startup and installation - this will not be the case for an IKS installation using Cert-Manager V0.12. To override this, if you have not already done so, open ibm-apiconnect.yaml from the helper_files installation archive, and add the following environment variable to the spec.template.spec.containers.env block:
```
        - name: DISABLE_CERT_MANAGER
          value: "true"
```
  To make this easier, search for the following:
```
        - name: OPERATOR_NAME
          value: ibm-apiconnect
```
  Append the new environment variable immediately afterward, so that it looks as follows:
```
        - name: OPERATOR_NAME
          value: ibm-apiconnect
        - name: DISABLE_CERT_MANAGER
          value: "true"
```
4. Set custom Microservice Security in Subsystem CRs.
  When customizing all External Frontend/Ingress, Common Subsystem Communication, and Internal Certificates, Cert-Manager will not be managing the certificates for the subsystems. The CRs for each subsystem must be updated for this change.
  
  If you have not done so already, in each subsystem CR, locate microServiceSecurity and certManagerIssuer inside the spec block:
```
microServiceSecurity: certManager
certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
```
  Set microServiceSecurity to custom, and remove or comment-out the certManagerIssuer block as follows:
```
microServiceSecurity: custom
#certManagerIssuer:
#    name: selfsigning-issuer
#    kind: Issuer
```
5. Add the Custom Certificates Block to the Subsystem CR
  - For Management CR:
```
customCertificates:
   - name: caCertificate
     secretName: ingress-ca
   - name: clientCertificate
     secretName: management-client
   - name: serverCertificate
     secretName: management-server
   - name: dbServerCertificate
     secretName: db-server-certificate
   - name: pgBouncerServerCertificate
     secretName: pg-bouncer-server-certificate
   - name: PGOTLSCertificate
     secretName: pgo.tls
   - name: NATSTLSCertificate
     secretName: management-natscluster-mgmt
   - name: dbClientPostgres
     secretName: db-client-postgres
   - name: dbClientReplicator
     secretName: db-client-replicator
   - name: dbClientPgbouncer
     secretName: db-client-pgbouncer
   - name: dbClientApicuser
     secretName: db-client-apicuser
   - name: dbClientPrimaryuser
     secretName: db-client-primaryuser
```
  - For Analytics and Portal CRs
    Replace <subsystem> with analytics or portal as required:
```
  customCertificates:
   - name: caCertificate
     secretName: ingress-ca
   - name: clientCertificate
     secretName: <subsystem>-client
   - name: serverCertificate
     secretName: <subsystem>-server
```
    The secretName field for each custom certificate must match the name of the Kubernetes Secret in the Cluster that contains that custom certificate. The values of secretName in all the previous cases are required secret names for all certificates, and should not differ from the secretNames provided.
Once the customCertificates block has been added, the Subsystem CRs can be applied into the Cluster. Continue with Installing the API Connect subsystems