Generating custom certificates manually for IKS

You can manually prepare Certificate definitions for use when generating custom certificates for IKS.

1. Create a Certificate Authority (CA) and an Issuer for Signing

   1. The following YAML definition can be used to generate a CA named ingress-ca, and an Issuer named ingress-issuer using that CA:

      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: ingress-ca
      spec:
          secretName: ingress-ca
          commonName: "ingress-ca"
          usages:
          - digital signature
          - key encipherment
          - cert sign
          isCA: true
          issuerRef:
              name: selfsigning-issuer
              kind: Issuer
      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Issuer
      metadata:
      name: ingress-issuer
      spec:
          ca:
              secretName: ingress-ca
      

      This should be placed into a file, e.g. ingress-ca.yaml.

   2. Apply this file into the Cluster:

      kubectl apply -f ingress-ca.yaml -n
          <namespace>

      . This will create a CA Certificate named ingress-ca, and also a Secret named ingress-ca. This CA will be used to sign the rest of the custom certificates.
   3. Verify the presence of both files:

      kubectl get certificate -n <namespace>
      kubectl get secret -n <namespace>

2. Generating Common Subsystem Communication Certificates with Cert-Manager for Management CR:
   1. Use the following YAML definition to generate the following Common Certificates and Secrets - analytics-ingestion-client, and portal-admin-client:

      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: analytics-ingestion-client
      spec:
          commonName: analytics-ingestion-client
          secretName: analytics-ingestion-client
          issuerRef:
              name: ingress-issuer
          usages:
          - "client auth"
          - "signing"
          - "key encipherment"
          duration: 17520h # 2 years
          renewBefore: 48h
      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: portal-admin-client
      spec:
          commonName: portal-admin-client
          secretName: portal-admin-client
          issuerRef:
              name: ingress-issuer
          usages:
          - "client auth"
          - "signing"
          - "key encipherment"
          duration: 17520h # 2 years
          renewBefore: 48h
      ---
      

      Note that the issuerRef uses the Issuer created in Step 1. These certificates must be signed by the CA associated with that Issuer, ingress-ca. This should be placed into a file, e.g. common-certs.yaml.

   2. Apply this file into the Cluster:

      kubectl apply -f icommon-certs.yaml -n <namespace>

      This will create Client Certificates and Secrets named analytics-ingestion-client, and portal-admin-client.
   3. Verify the presence of both files:

      kubectl get certificate -n <namespace>
      kubectl get secret -n <namespace>

3. External Frontend/Endpoint Certificates with Cert-Manager

   1. For each Endpoint in each subsystem CR, the following YAML definition may be used to generate a Server Certificate:

      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: <endpoint-host.secretName>
      spec:
          commonName: <endpoint.host.secretName>
          secretName: <endpoint.host.secretName>
          dnsNames:
          - <endpoint.host.Name>
          issuerRef:
              name: ingress-issuer
          usages:
          - "server auth"
          - "signing"
          - "key encipherment"
          duration: 17520h # 2 years
          renewBefore: 48h

      Replace <endpoint.host.secretName> with the secretName in the host block of the Endpoint in the CR. For example, if the Endpoint in the CR is:

      cloudManagerEndpoint:
          hosts:
          - name: admin.example.com
            secretName: cm-endpoint
      

      The Certificate YAML should be updated as follows:

      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: cm-endpoint
      spec:
          commonName: cm-endpoint
          secretName: cm-endpoint
          dnsNames:
          - admin.example.com
          issuerRef:
              name: ingress-issuer
          usages:
          - "server auth"
          - "signing"
          - "key encipherment"
          duration: 17520h # 2 years
          renewBefore: 48h
      

      Note that the issuerRef uses the Issuer created previously. This certificate will be signed by the CA associated with that Issuer, ingress-ca. This should be placed into a file, for example <subsystem>-server.yaml.

   2. Apply this file into the Cluster:

      kubectl apply -f <subsystem>-server.yaml -n <namespace>

      This will create a Server Certificate named <subsystem>-server, and also a Secret named <subsystem>-server.
   3. Verify the presence of both files:

      kubectl get certificate -n <namespace>
      kubectl get secret -n <namespace>

   4. Repeat Steps 3.a 3.b and 3.c for each subsystem. In each case, the Certificates must use the same Issuer created in Step 1. This will ensure that all custom certificates are signed by the same CA Certificate.

      Note that the issuerRef uses the Issuer created in 1. These certificates must be signed by the CA associated with that Issuer, ingress-ca.

   5. Place the YAML definitions for each Certificate into a YAML file, e.g. endpoint-certs.yaml. This will create Server Certificates and Secrets for each Endpoint named <endpoint.host.secretName>. .
   6. Apply this file into the Cluster:

      kubectl apply -f endpoint-certs.yaml

   7. Verify the presence of both:

      kubectl get certificate -n <namespace>
      kubectl get secret -n <namespace>

4. Choose one of the following actions, based on whether or not you are customizing internal API certificates:
   • If you do not plan to customize internal certificates, continue with Installing API Connect on IKS with custom certificates.
   • If you plan to customize internal certificates, continue with Step 5.

   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 described in the previous sections.
   • 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.
5. Generate custom internal certificates using custom-cert-ingresses-internal.yaml[

   Each of the Internal certificates listed in Custom certificates reference for IKS have differing strict requirements for Common Names and DNS Names (i.e. Subject Alternative Names).

   To generate custom certificates that meet these requirements, use the provided custom-certs-internal.yaml file, which can be found in the helper_files installation archive.

   This file contains Certificate YAML definitions for all Internal certificates, CA, and Issuer that can be customized for each subsystem of IBM API Connect. The Certificate definitions file is already populated with the recommended default values.

   1. When using custom internal certificates, you are required to specify a site name. The site name is used as the identifier for the PostgreSQL database Cluster used by API Connect. The site name chosen is added to the Management Subsystem CR YAML file before installing the Management Subsystem.

      In addition, this name is also required for use with the custom internal certificates, so a site name should be chosen now before proceeding.

   2. Open custom-certs-internal.yaml in a text-editor. Find and replace each occurrence of <namespace> with the desired namespace for the deployment. This must be done even if the default namespace is to be used.
   3. Also in custom-certs-internal.yaml, if the default namespace is not being used for the deployment, find the following db-server-certificate Certificate definition:

      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: db-server-certificate
      spec:
      commonName: management-pgo_cluster_id-postgres
      secretName: db-server-certificate
      dnsNames:
          - "*.default"
          - "*.default.svc"
          - "*.management-pgo_cluster_id-postgres.default.svc"
          - "management-pgo_cluster_id-postgres"
      

      Replace the instances of default with the namespace being used for the deployment. For example, if a namespace called apic is being used, the definition should be updated to appear as follows:

      ---
      apiVersion: cert-manager.io/v1alpha2
      kind: Certificate
      metadata:
      name: db-server-certificate
      spec:
      commonName: management-pgo_cluster_id-postgres
      secretName: db-server-certificate
      dnsNames:
          - "*.apic"
          - "*.apic.svc"
          - "*.management-pgo_cluster_id-postgres.apic.svc"
          - "management-pgo_cluster_id-postgres"

   4. Also in custom-certs-internal.yaml, replace each occurrence of pgo_cluster_id with the chosen site name described in Step 5.a.
   5. Apply the file to the Cluster:

      kubectl apply -f custom-certs-internal.yaml -n <namespace>

   6. Continue with Installing API Connect on IKS with custom certificates.