Optional post-upgrade steps for upgrade to 10.0.5.3 from earlier 10.0.5 release

Version 10.0.5.3 introduces some new features that are related to inter-subsystem communication. This topic explains how to configure these features when you upgrade from a previous 10.0.5 release to v10.0.5.3 or later.

Note: If you are using a top-level CR, you must edit the top-level CR instead of the subsystem CR. If the section you want to edit is missing from the top-level CR, copy it from the subsystem CR and paste it into the top-level CR.

Enabling management CA certification on the REST API

The portal and gateway subsystems make requests to the management subsystem through the REST API that is hosted by the management subsystem. This communication is standard TLS, where each REST API endpoint has a server certificate that is presented to the client during TLS handshaking. For additional security, validation of the management server certificate CA is enabled on all subsystems for new installations of API Connect v10.0.5.3 and later. If you are upgrading from an earlier release, and want to enable this feature for the portal and gateway then edit the portal and gateway CRs, and add the following settings to the spec: section depending on if you are using external or in-cluster inter-subsystem communications (In-cluster service communication between subsystems):
  • If you are using external inter-subsystem communication, in the portal CR add:
    spec:
      mgmtPlatformEndpointCASecret:
        secretName: ingress-ca # Or <instance-name>-ingress-ca if using top-level CR. If you have customized certs, change ingress-ca to $PLATFORM_CA_SECRET  
      mgmtConsumerEndpointCASecret:
        secretName: ingress-ca # Or <instance-name>-ingress-ca if using top-level CR. If you have customized certs, change ingress-ca to $CONSUMER_CA_SECRET
    and in the gateway CR add:
    spec:
      mgmtPlatformEndpointCASecret:
        secretName: ingress-ca # Or <instance-name>-ingress-ca if using top-level CR. If you have customized certs, change ingress-ca to $PLATFORM_CA_SECRET 
    
    where:
    • $PLATFORM_CA_SECRET is the Kubernetes secret object that contains the CA certificate that is used by the platform REST API.
    • $CONSUMER_CA_SECRET is the Kubernetes secret object that contains the CA certificate that is used by the consumer REST API.
  • If you are using in-cluster inter-subsystem communications, in the portal CR add:
    spec:
      mgmtPlatformEndpointSvcCASecret:
        secretName: management-ca # Or <instance-name>-mgmt-ca if using top-level CR. If you have customized certs, change ingress-ca to $PLATFORM_CA_SECRET  
      mgmtConsumerEndpointSvcCASecret:
        secretName: management-ca # Or <instance-name>-mgmt-ca if using top-level CR. If you have customized certs, change ingress-ca to $CONSUMER_CA_SECRET
    and in the gateway CR add:
    spec:
      mgmtPlatformEndpointSvcCASecret:
        secretName: management-ca # Or mgmt-ca or <instance-name>-mgmt-ca if using top-level CR. If you have customized certs, change ingress-ca to $PLATFORM_CA_SECRET 
    
    If changing to use in-cluster inter-subsystem communication after an upgrade, you must also reregister all subsystems: Converting existing registered subsystems to use in-cluster communications.
Note: If you are not sure of the secret name, follow these steps:
  1. Check the management subsystem CR with oc describe mgmt, and identify the issuer of the platform and consumer API endpoints:
    oc describe mgmt -n <namespace>
    
    ...
    Platform API Endpoint:
        Annotations:
          cert-manager.io/issuer:               apic-ingress-issuer
    ...
      Consumer API Endpoint:
        Annotations:
          cert-manager.io/issuer:               apic-ingress-issuer
  2. Describe the issuer with oc describe issuer, and identify the secret name:
    oc describe issuer apic-ingress-issuer -n <namespace>
    ...
    Spec:
      Ca:
        Secret Name:  apic-ingress-ca
    ...

Enable JWT security for inter-subsystem communication

If you want to use JWT security instead of mTLS for inter-subsystem communication, then follow these steps. For more information on JWT security, see: Enable JWT security instead of mTLS
Cloud Pak for Integration and OpenShift top-level CR installations
Configure JWT as described in the post-install steps: Enable JWT security and disable mTLS between subsystems.
Individual subsystem CR installations
  1. Describe the mgmt CR to get the JWKS URL:
    kubectl describe mgmt -n <namespace>
    
    status:
      - name: jwksUrl
        secretName: api-endpoint
        type: API
        uri: https://api.apic.acme.com/api/cloud/oauth2/certs
  2. For each portal, gateway, and analytics subsystem where you want to use JWT security, edit the CR corresponding that subsystem to disable mTLS and specify the jwksUrl:
    spec:
        ...
        mtlsValidateClient: false
        jwksUrl: <JWKS URL>
    <JWKS URL> is the URL identified in step 1.
  3. v10.0.5.4 and later: Enable JWT on the gateway to analytics communications flow. Enable the Use JWT switch for the registered gateway in the Topology page of the Cloud Manager UI.
    Datapower version 10.5.0.4 only: To enable JWT on the gateway to analytics communications flow, you also must add a dataPowerOverride section to the gateway CR:
       
    spec:
      jwksUrl: <JWKS URL>
      dataPowerOverride:
         image: customregistry.com/custom-image-datapower:10.5.0.5
         version: 10.5.0.5
         license: X-XXXX-XXXXXX

Converting existing registered subsystems to use in-cluster communications

If you want to change your existing portal, gateway, and analytics subsystems to use in-cluster inter-subsystem communication then they must be reregistered. For more information about in-cluster communication, see In-cluster service communication between subsystems.
Important: Understand the following points before you change the communication type of a subsystem:
  • Reregistering any of the subsystems requires an outage of that subsystem.
  • When you change communication type, any backup of the management subsystem that was taken before this change becomes unusable. Do not change the inter-subsystem communication type if you might want to restore the management subsystem from an earlier backup.
  • To reregister the portal, all portal sites must be deleted first. Deleting a portal site means that any customizations that were made to the site must manually be reapplied after the portal is reregistered and the site recreated.
  • To reregister the gateway, all published products must be deleted from the gateway.
To reregister a portal subsystem, the steps are:
  1. Delete all portal sites from the portal service. From the API Manager UI, for each catalog that has a site on the portal, delete the portal site: Edit or delete portal site.
  2. Delete the portal service in the Topology section of the Cloud Manager UI.
  3. Reregister the portal service, specifying the inter-subsystem communication type that you want, in the Topology section of the Cloud Manager UI. See Register portal service.
To reregister a gateway subsystem, the steps are:
  1. In the API Manager UI, delete all products from all catalogs that use the gateway service. See Removing a product from a catalog.
  2. In the API Manager UI, for each catalog that uses the gateway service, remove the gateway service from the catalog settings. See Configure catalog gateway service.
  3. Delete the gateway service in the Topology section of the Cloud Manager UI.
  4. Reregister the gateway service, specifying the inter-subsystem communication type that you want, in the Topology section of the Cloud Manager UI. See Registering a gateway service.
To reregister the analytics subsystem, the steps are:
  1. Unassociate the analytics service from all gateway services that it is associated with. See Unassociate analytics service.
  2. Delete the analytics service in the Topology section of the Cloud Manager UI.
  3. Reregister the analytics service, specifying the inter-subsystem communication type that you want, in the Topology section of the Cloud Manager UI. See Registering an analytics service.

Update duration of certificates

In earlier releases of API Connect, some of the certificates had a duration of 12720 hours. On new API Connect v10.0.6 installations, all certificates have a duration of 17520 hours. After you upgrade to v10.0.6, update API Connect certificates to have a duration of 17520 hours:
  1. List all the certificates that have a 12720 hour duration with the following command:
    oc -n <namespace> get certificate -o custom-columns=NAME:metadata.name,DURATION:spec.duration | grep 12720h0m0s | awk '{print $1}'
    Example output:
    small-a7s-ai-endpoint
    small-gw-gateway
    small-gw-gateway-manager
    small-mgmt-admin
    small-mgmt-api-manager
    small-mgmt-consumer-api
    small-mgmt-platform-api
    small-ptl-portal-director
    small-ptl-portal-web
  2. Trigger the recreation of each certificate by deleting the certificate:
    oc -n <namespace> delete certificate <certificate name>
    For example:
    oc -n apic delete certificate small-ptl-portal-web
    
    certificate.cert-manager.io "small-ptl-portal-web" deleted
  3. Verify that the recreated certificate has a 17520 hour duration:
    oc -n <namespace> get certificate <certificate name> -o custom-columns=DURATION:spec.duration
    For example:
    oc -n apic get certificate small-ptl-portal-web -o custom-columns=DURATION:spec.duration
    DURATION
    17520h0m0s