Upgrading IBM Cloud Pak for Security from V1.4.0 to V1.5.0.X

If you previously installed IBM Cloud Pak® for Security, you can upgrade to a later version of the software.

Before you begin

You must have IBM Cloud Pak for Security 1.4.0 installed.

After you complete the following procedure to upgrade to IBM Cloud Pak for Security 1.5.0.X, you can upgrade to Red Hat OpenShift Container Platform 4.5.14+ or 4.6.x. For more information, see Updating a cluster. Locate the appropriate document for your OpenShift version.

Check that you have all the details that are required for installation. For more information, see Preparing to install IBM Cloud Pak for Security.

About this task

You can upgrade to a later version of the software or apply updates to configuration values by running the upgrade-all action. The upgrade command completes the following operations:

Important: Complete a backup procedure before beginning the upgrade. For more information about how to back up CouchDB and IBM® Security Case Management, see Backup.

Note: During the upgrade process, the cluster is not accessible by using the cloudctl login command. Cloud Pak for Security is inaccessible until the upgrade process is completed.

Online upgrade

  1. Download and extract the content of the Cloud Pak for Security archive file in preparation for installation by running the command:

    cloudctl case save --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-cp-security-1.0.13.tgz --outputdir <working_directory> --tolerance 1
    

    Note: working_directory is the output directory in which the Cloud Pak for Security resources are placed. The output directory is created if it does not exist.

  2. Extract the content from the Cloud Pak for Security archive file by running the command:

    tar -xf <working_directory>/ibm-cp-security-1.0.13.tgz
    

    To proceed with the upgrade, complete the following steps:

  3. Ensure that you are logged in to the cluster by using either of the following oc login commands:

    • Using username and password:
      oc login <openshift_url> -u <username> -p <password> -n <namespace>
      
    • Using a token:
      oc login --token=<token> --server=<openshift_url>
      
  4. Update the parameters in the values.conf file that is located within the directory: <working_directory>/ibm-cp-security/inventory/installProduct/files/. For the full list of parameters, their description, and default values; see the table in the Configuration section.

  5. Read the Cloud Pak for Security license that is available in the directory: <working_directory>/ibm-cp-security/licenses. To accept the license, add the argument --license accept to the command that runs the installation process.

  6. To upgrade Cloud Pak for Security, run the following command:

    cloudctl case launch --case ibm-cp-security --namespace <namespace>  --inventory installProduct --action upgrade-all --args "--license accept --helm3 <path-to-helm3-cli>  --inputDir <working_directory>/" --tolerance 1
    

    The following arguments are required:

Argument Description
--namespace The namespace where Cloud Pak for Security 1.4.0.0 was installed. You can verify the namespace by running the oc projects command.
--license The license acceptance confirmation.
--helm3 Path to the Helm v3 executable file, for example: /usr/local/bin/helm3.
--inputDir <working_directory> is the output directory in which the Cloud Pak for Security is extracted by cloudctl case save.

Offline Upgrade

  1. Download and extract the content of the Cloud Pak for Security archive file in preparation for installation by running the following command:

    cloudctl case save --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-cp-security-1.0.13.tgz --outputdir <working_directory> --tolerance 1
    

    Note: working_directory is the output directory in which the Cloud Pak for Security resources are placed. The output directory is created if it does not exist.

  2. Extract the content from the Cloud Pak for Security archive file by using the following command:

    tar -xf <working_directory>/ibm-cp-security-1.0.13.tgz
    

    To upgrade, complete the following steps.

  3. Ensure that you are logged in to the cluster by using either of the following oc login commands:

    • Using username and password:
      oc login <openshift_url> -u <username> -p <password> -n <namespace>
      
    • Using a token:
      oc login --token=<token> --server=<openshift_url>
      

1. Configure authentication and mirror images

  1. Log in to the cluster by using the oc command:

    oc login <openshift_url> -u <username> -p <password> -n <namespace>
    
  2. Update the parameters in the values.conf file that is located in the directory: <working_directory>/ibm-cp-security/inventory/installProduct/files/. For the full list of parameters, their description, and default values; see the table in the Configuration section.

  3. Depending on the access that you are entitled to, provide your authentication credentials by using method A or B.
    A. If you are installing by using the IBM Entitled Registry, use --pass <entitled_key> as your authentication credentials. Configure the authentication credentials (URL, username, and password) for both your local Docker registry and the IBM Entitled Registry by running the following commands:

     cloudctl case launch \
         --case ibm-cp-security \
         --inventory installProduct \
         --action configure-creds-airgap \
         --args "--registry cp.icr.io --user cp --pass <entitled_key> --inputDir <working_directory>" --tolerance 1 \
    
     cloudctl case launch \
         --case ibm-cp-security \
         --inventory installProduct \
         --action configure-creds-airgap \
         --args "--registry ${LOCAL_DOCKER_REGISTRY}:5000 --user <username> --pass <password> --inputDir <working_directory>" --tolerance 1 \
    

    B. If you are installing from IBM® Passport Advantage, use --pass ppa as the authentication credentials. Configure the authentication credentials (URL, username, and password) for both your local Docker registry and the IBM® Passport Advantage by running the following commands:

     cloudctl case launch \
         --case ibm-cp-security \
         --inventory installProduct \
         --action configure-creds-airgap \
         --args "--registry cp.icr.io --user cp --pass ppa --inputDir <working_directory>" --tolerance 1 \
    
     cloudctl case launch \
         --case ibm-cp-security \
         --inventory installProduct \
         --action configure-creds-airgap \
         --args "--registry ${LOCAL_DOCKER_REGISTRY}:5000 --user <username> --pass <password> --inputDir <working_directory>" --tolerance 1 \
    
  4. Configure the global image pull secret and imageContentSourcePolicy resource by running the following command:

    cloudctl case launch \
     --case ibm-cp-security \
     --inventory installProduct \
     --action configure-cluster-airgap \
     --args "--registry ${LOCAL_DOCKER_REGISTRY}:5000 --inputDir <working_directory>" --tolerance 1 \
    

    Note: Running the command against the Red Hat OpenShift cluster causes a restart of all the nodes. By listing the Red Hat OpenShift nodes, as the change is applied you might see node status Ready,SchedulingDisabled. Wait until the configuration is propagated to all nodes.

  5. Mirror the images to the Docker registry by running the following command:

    cloudctl case launch \
    --case ibm-cp-security \
    --inventory installProduct \
    --action mirror-images \
    --args "--registry ${LOCAL_DOCKER_REGISTRY}:5000  --inputDir <working_directory>" --tolerance 1 \
    
  6. Verify that the imageContentSourcePolicy resource is created:

    oc get imageContentSourcePolicy | grep ibm-cp-security
    

2. Upgrade Cloud Pak for Security

To upgrade Cloud Pak for Security, run the following command:

cloudctl case launch --case ibm-cp-security --namespace <namespace>  --inventory installProduct --action upgrade-all --args "--license accept --helm3 <path-to-helm3-cli> --inputDir <working_directory> --airgap" --tolerance 1

The following arguments are required:

Argument Description
--namespace The namespace where Cloud Pak for Security will be installed. The namespace will be created automatically if it does not exist.
--helm3 The path to the Helm v3 executable file, for example: /usr/local/bin/helm3
--license The license acceptance confirmation.
--inputDir offline_dir is the output directory in which the Cloud Pak for Security is extracted by cloudctl case save.
--airgap The flag to indicate offline installation.

Configuration

The following table lists the configurable parameters for the Cloud Pak for Security installation, their description, and default values.

Note: For IBM Cloud, you can use the TLS certificates from your IBM Cloud OpenShift cluster. For more information, see Getting started with IBM Cloud.

*Not required if you use IBM Cloud and the IBM Cloud TLS certs.

Parameter Description Default Required
adminUserId The user that is to be assigned as an Administrator in the default account after the installation. The user must exist in the LDAP directory that is to be connected to Common Services after deployment. NA Yes
cloudType The cloud environment where cluster is deployed. Set to aws for AWS, ibmcloud for IBM Cloud/Red Hat OpenShift Kubernetes Service, azure for Azure, and ocp for other cloud environments. ocp Yes
cp4sapplicationDomain The Fully Qualified Domain Name (FQDN) created for Cloud Pak for Security. NA Yes*
cp4sdomainCertificatePath The path of the TLS cert that is associated with the Cloud Pak for Security domain. NA Yes*
cp4sdomainCertificateKeyPath The path of the TLS key that is associated with the Cloud Pak for Security domain. NA Yes*
cp4scustomcaFilepath The path of the custom TLS certificate that is associated with the Cloud Pak for Security domain. NA Only required if you are using custom or self-signed certificate.
cp4sImagePullPolicy The Pull policy for the images - Always or IfNotPresent. IfNotPresent Yes
cp4sOpenshiftAuthentication Enable Red Hat OpenShift authentication. Only supported on IBM Cloud® ROKS clusters. False No
defaultAccountName The name for the default account. Only valid for a clean install, not for an upgrade. Cloud Pak For Security No
defaultAccountName The name for the default account. Only valid for a clean install, not for an upgrade. Cloud Pak for Security No
enableCloudSecurityAdvisor Required only if you are installing IBM Cloud Security Advisor Adapter. NA No
entitledRegistryUrl The repository from which the images are pulled. cp.icr.io Only required for online installation.
entitledRegistryPassword The password to access the entitled registry URL. This is the entitlement key retrieved from IBM Container Library. NA Only required for online installation.
entitledRegistryUsername The username to access the entitled registry URL. cp Only required for online installation.
localDockerRegistry The local Docker host registry URL. NA Required for offline installation.
localDockerRegistryUsername The username to access the local Docker host registry. NA Required for offline installation.
localDockerRegistryPassword The password to access the local Docker host registry. NA Required for offline installation.
registryType The type of repository from which the images are pulled.
entitled for online installation.
local for airgap installation.
entitled Yes
storageClass Dynamically provisioned block storage class for all the PVCs. NA Yes
storageClassFsGroup The fsgroup for the Postgres Operator Primary pod. 26 No
storageClassSupplementalGroups SupplementalGroups for the Postgres Operator Primary pod NA No
backupStorageClass The storage class for the backup and restore pod. If not set, it will take the default storage class in the cluster. NA No
backupStorageSize The storage size for the backup and restore pod. 100Gi No