Skip to main contentIBM Cloud Pak Playbook

Installing Cloud Pak for Security

In this section we describe the installation of IBM Cloud Pak for Security. This document was written based on our experience with installation on Red Hat OpenShift 4.2 running on x86 architecture. However, the purpose of this document is to be agnostic. In other words, Cloud Pak for Security (P4S) just requires OpenShift 4.2 to be installed as a base platform. It does not matter if it is on-premises, in the cloud, installed on bare-metal or on virtual machines.

In the sections below, we will discuss both the Online and Offline install options for the Cloud Pak. You only need to choose one. The Online option involves installing by directly accessing installation images from an entitiled registry location on the internet. The Offline option involves downloading a large archive file containing all the installation image files, extracting that archive, and installing using those extracted files. Depending on your cluster environment and policies, you will choose one option or the other. The Offline option is often appropriate for “air-gapped” installations, where access to the internet is restricted or not allowed.

Prerequisites

This installation chapter does not describe how to install or configure the underlying OpenShift platform. Prior to installing make sure you have a working OpenShift cluster with the required capacity. The installation of OpenShift is described here.

  • Check the prerequisites chapter to make sure you have sized your cluster appropriately and you have sufficient capacity
  • For offline installs make sure you have downloaded the Cloud Pak for Security Passport Advantage Archive (PPA) file and copied it to the installation server. See the prerequisites chapter for more details.
  • Offline installation will require the docker client to be installed on the installation server
  • For online installs make sure you have an entitlement key to access the IBM Entitled Docker Registry

Cloud Pak for Security Installation

Cloud Pak for Security 1.2 requires Common Services to be installed first. After that, Cloud Pak for Security can be installed using either the Offline or Online option.

Installing Common Services

    1. Obtain the entitlement key that is assigned to your ID.

      1. Log in to MyIBM Container Software Library with the IBMid and password that are associated with the entitled software.
      2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
    2. Log in to the Install server (assuming you have a separate server for install) as a user with root permissions or as a user with sudo privileges.

    3. Authenticate to the OpenShift server where you would like to install Common Services (your token can be copied from the OpenShift Console UI)

      oc login --token=<your_token> --server=<INSERT_SERVER_URL_HERE>
    4. Log in to the entitled registry.

      sudo docker login cp.icr.io --username <username> --password <entitlement_key>
    5. Create the secret.

      oc create secret docker-registry entitled-registry --docker-server=cp.icr.io --docker-username=<username> --docker-password=<entitlement_key> --docker-email=<docker_email>
    6. Create an installation directory to store the IBM Common Services configuration files, and change to that directory.

      mkdir ~/common-services ; cd ~/common-services
    7. Pull the installer image from the entitled registry by running the following command:

      docker pull cp.icr.io/cp/icp-foundation/icp-inception:3.2.4
    8. Extract the cluster directory:

      sudo docker run --rm -v $(pwd):/data:z -e LICENSE=accept --security-opt label:disable cp.icr.io/cp/icp-foundation/icp-inception:3.2.4 cp -r cluster /data
    9. The step above creates a cluster directory, creates cluster configuration files , and copies the kubeconfig file from theauth folder of the cop 4.2 installation directory into the cluster directory

      cp <ocp install dir>/auth/kubeconfig ./kubeconfig

      or

      oc config view > kubeconfig
    10. Update the config.yaml file. In the file, update the cluster_node sections with our clusters. You will need to add the nodes from your cluster. Use the exact node names from the oc get nodes command.

    • Add the storage class for your cluster in the storage_class field. The storage class must be a block storage provider. Use the exact node names from the oc get sc command.

    • Update the default_admin_password field with a suitable password

    • Define the management_services appropriate to your install

    • The following IBM® Cloud Private management services must be enabled:

      • logging
      • auth-idp
      • monitoring

      Example config.yaml file

      # Licensed Materials - Property of IBM
      # IBM Cloud private
      # @ Copyright IBM Corp. 2019 All Rights Reserved
      # US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
      ---
      # A list of OpenShift nodes
      cluster_nodes:
    • ’(.*)’

      image_repo: cp.icr.io/cp/icp-foundation private_registry_enabled: true docker_username: cp docker_password: <enttitlement key from step 1>

      You can disable following services if they are not needed

      management_services:

      Common services

      iam-policy-controller: enabled metering: enabled licensing: disabled monitoring: enabled nginx-ingress: enabled common-web-ui: enabled catalog-ui: enabled mcm-kui: enabled logging: disabled audit-logging: disabled system-healthcheck-service: disabled multitenancy-enforcement: disabled

    When this configuration is complete, you can start the installation. This could run for ~30-45min.

    ```
    sudo docker run -t --net=host -e LICENSE=accept -v $(pwd)/cluster:/installer/cluster:z -v /var/run:/var/run:z -v /etc/docker:/etc/docker:z --security-opt label:disable cp.icr.io/cp/icp-foundation/icp-inception:3.2.4 addon -v
    ```

    Offline Installation

    Follow these instructions (down to the Online Installation section) if you want to use the Offline installation option. If you can use the Online installation option, skip down to the Online Installation section now to continue.

    Installing Cloud Pak for Security Foundation Chart

      1. Create a directory for Cloud Pak for Security.

        mkdir /opt/cp4s; cd /opt/cp4s
      2. Extract the Cloud Pake for Security installation archive. For example:

        tar xf CPS_1.2_OS_EN.tgz
      3. Create a new Namespace/Project in OCP for Cloud Pak for Security.

        oc new-project cp4security
      4. Login to the ICP console.

        cloudctl login -a <icp console url> -u admin -p admin -n cp4security
      5. Load the archive into ICP console.

        cloudctl catalog load-archive --archive ibm-security-foundations-prod-1.2.0.0.tgz --registry default-route-openshift-image-registry.apps.ctocps.ocp.csplab.local/cp4security
      6. Extract the Security Foundations archive.

        tar xzf ibm-security-foundations-prod-<RELEASE>.tgz``
      7. Run the command below to get the Repo password to execute the next step.

        oc serviceaccounts get-token -n cp4security default
      8. Run the command below to create pre-requisites.

        ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/preInstall.sh -n cp4security -force -repo image-registry.openshift-image-registry.svc:5000/cp4security dfault <secret from above command> -sysctl
      9. Run the command below to check the pre requisites.

        ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/checkprereq.sh -n cp4security

        The output will display the default storage class and when successfull will indicate :

        INFO: ibm-security-foundations prerequisites are OK
      10. Execute the command below to install the chart.

        helm install --name <RELEASE_NAME> --namespace=cp4security ./ibm-security-foundations-prod --tls --values ibm-security-foundations-prod/values.yaml --set global.helmUser=admin --set global.repository=image-registry.openshift-image-registry.svc:5000/cp4security --set global.repositoryType=local
      11. Wait for all the pods’ status to be Running in the CP4Security namespace.

        watch -n5 "oc get pods -n cp4security"

      Installing Cloud Pak for Security Solution Chart

        1. Login to the IBM CLoud Platform (ICP) console.

          cloudctl login -a <icp console url> -u admin -p admin -n cp4security
        2. Load the archive into the ICP console.

          cloudctl catalog load-archive --archive ibm-security-solutions-prod-1.0.4.tgz --registry default-route-openshift-image-registry.apps.ctocps.ocp.csplab.local/cp4security
        3. Extract the Solutions archive.

          tar xzf ibm-security-solutions-prod-<RELEASE>.tgz
        4. A fully qualified domain name (FQDN) must be created for the Cloud Pak for Security application. Create a DNS CNAME record pointing to the ICP console URL. Create new certificates from Letsencrypt on any domain. Follow the letsencrypt steps to create certificates.

        5. Concatenate the certificate.crt and ca_bundle.crt to create a cert bundle (one file) that we can use for the installation. The following steps can be used for concatenation.

          cat certificate.crt > concat.crt
          echo >> concat.crt
          cat ca_bundle.crt >> concat.crt
        6. Run the command below to store the cluster administrator credentials into a secret.

          ibm-security-solutions-prod/ibm_cloud_pak/pak_extensions/pre-install/preInstall.sh -cluster admin:admin -cert concat.crt -key private.key
        7. Run the command below to check the pre-requisites.

          ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/checkprereq.sh -n <NAMESPACE> --solutions

          The output will display the default storage class and when successfull will indicate :

          INFO: ibm-security-solutions prerequisites are OK
        8. Execute the command below to install the chart.

          helm install --name <RELEASE_NAME> --namespace=cp4security ./ibm-security-solutions-prod --tls --values ibm-security-solutions-prod/values.yaml --set global.storageClass=<storage class from oc get sc> --set global.cluster.hostname=<ocp domain> --set global.domain.default.domain=<FQDN from step 5> --set global.repository=image-registry.openshift-image-registry.svc:5000/cp4security --set global.repositoryType=local
        9. Wait for all the pods’ status to be Running in the CP4Security namespace.

          watch -n5 "oc get pods"
        10. Add ldap to the cluster. For instance, IBM’ers could use the link below to add the Bluepages ldap.

          https://github.ibm.com/cp4s/cp4s-developer-tools/blob/991b8c3688dcd9f7c8e6c4c1ebf1ff74af3c9732/developer-docs/Bluepages%20LDAP.md
        11. Follow the IBM Cloud Private instructions in Add users to the team. Each IBM Cloud Pak for Security user must be assigned a suitable role.

          To assign a standard IBM Cloud Pak for Security user role, select Viewer.

          To assign an IBM Cloud Pak for Security platform administrator role, select Administrator.

        12. You can now access the dashboard using the cluster.hostname with the Viewer or Adminsitrator credentials created above.

        Online Installation

        Use the Online installation method if you have internet access to connect to the entitlement registry. If you have skipped the Offline Installation option, this is where you should continue.

        Installing Cloud Pak for Security Foundation Chart

          1. Create a directory for Cloud Pak for Security. Change your current directory to it.

            mkdir /opt/cp4s; cd /opt/cp4s
          2. Create a new Namespace/Project in OCP for Cloud Pak for Security.

            oc new-project cp4security
          3. Login to the ICP console.

            helm init; cloudctl login -a <icp console url> -u admin -p admin -n cp4security
          4. Download the charts from the Helm repo.

            1. To verify that Helm has the entitled repository, run the command:

              helm repo list

              Check in the output that the results from the previous step contains the line:

              entitled https://raw.githubusercontent.com/IBM/charts/master/repo/entitled/
            2. If the verification step fails, run the following command to add the entitled repository.

              helm repo add entitled https://raw.githubusercontent.com/IBM/charts/master/repo/entitled/
            3. Fetch and extract the charts.

              helm fetch entitled/ibm-security-foundations-prod
              helm fetch entitled/ibm-security-solutions-prod
              tar xzf ibm-security-foundations-prod-<RELEASE>.tgz
              tar xzf ibm-security-solutions-prod-<RELEASE>.tgz
          5. Run the command below to create the pre-requisites.

            ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/preInstall.sh -n cp4security -force -repo cp.icr.io cp <entitlement key> -sysctl
          6. Run the command below to check the prerequisites.

            ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/checkprereq.sh -n cp4security

            The output will display the default storage class and when successfull will indicate :

            INFO: ibm-security-foundations prerequisites are OK
          7. Execute the command below to install the chart.

            helm install --name <RELEASE_NAME> --namespace=cp4security ./ibm-security-foundations-prod --tls --values ibm-security-foundations-prod/values.yaml --set global.helmUser=admin
          8. Wait for all the pods’ status to be Running in the CP4Security namespace.

            watch -n5 "oc get pods -n cp4security"

          Installing Cloud Pak for Security Solution Chart

            1. Login to the ICP console.

              cloudctl login -a <icp console url> -u admin -p admin -n cp4security
            2. A fully qualified domain name (FQDN) must be created for the Cloud Pak for Security application. Create a DNS CNAME record pointing to the ICP console URL. Create new certificates from Letsencrypt on any domain. Follow the letsencrypt steps to create certificates.

            3. Concatenate the certificate.crt and ca_bundle.crt to create a cert bundle (one file) that we can use for the installation. The following steps can be used for concatenation.

              cat certificate.crt > concat.crt
              echo >> concat.crt
              cat ca_bundle.crt >> concat.crt
            4. Run the command below to store the cluster administrator credentials into a secret.

              ibm-security-solutions-prod/ibm_cloud_pak/pak_extensions/pre-install/preInstall.sh -cluster admin:admin -cert concat.crt -key private.key
            5. Run the command below to check the pre-requisites.

              ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/pre-install/checkprereq.sh -n <NAMESPACE> --solutions

              The output will display the default storage class and when successfull will indicate :

              INFO: ibm-security-solutions prerequisites are OK
            6. Execute the command below to install the chart.

              helm install --name <RELEASE_NAME> --namespace=cp4security ./ibm-security-solutions-prod --tls --values ibm-security-solutions-prod/values.yaml --set global.storageClass=<storage class from oc get sc> --set global.cluster.hostname=<ocp domain> --set global.domain.default.domain=<FQDN from step 5>
            7. Wait for all the pods’ status to be Running in the CP4Security namespace.

              watch -n5 "oc get pods"
            8. Add ldap to the cluster. For instance, IBM’ers could use the link below to add the Bluepages ldap.

              https://github.ibm.com/cp4s/cp4s-developer-tools/blob/991b8c3688dcd9f7c8e6c4c1ebf1ff74af3c9732/developer-docs/Bluepages%20LDAP.md
            9. Follow the IBM Cloud Private instructions in Add users to the team. Each IBM Cloud Pak for Security user must be assigned a suitable role.

              To assign a standard IBM Cloud Pak for Security user role, select Viewer.

              To assign an IBM Cloud Pak for Security platform administrator role, select Administrator.

            10. You can now access the dashboard using the cluster.hostname with the Viewer or Adminsitrator credentials created above.

            Uninstalling Cloud Pak for Security

            Run the following commands to uninstall the Cloud Pak for Security.

            Uninstalling the Cloud Pak for Security Solution Chart

            To uninstall the solution chart, run the following command.

            helm delete --purge <RELEASE_NAME> --tls

            The following script must also be run, as follows:

            ibm-security-solutions-prod/ibm_cloud_pak/pak_extensions/post-delete/Cleanup.sh <NAMESPACE> --force --all

            Uninstalling the Postgres Service

            This link provides details on how the Postgres Service can be uninstalled.

            Removing the service account for ElasticSearch

            The following command can be run to remove the ibm-dba-ek-isc-cases-elastic-bai-psp-sa service account that is created for Elasticsearch.

            oc delete serviceaccount ibm-dba-ek-isc-cases-elastic-bai-psp-sa -n <NAMESPACE>

            Uninstalling the Cloud Pak for Security Foundation Chart

            To uninstall and delete the ibm-security-foundations-prod release, run the following command:

            helm delete <RELEASE_NAME> --purge --tls

            The post-delete script must also be run, as follows:

            ibm-security-foundations-prod/ibm_cloud_pak/pak_extensions/post-delete/Cleanup.sh <NAMESPACE> --all --force

            Uninstalling Common Services

              To uninstall ICP Common Services, run the following commands.

              1. Change to the cluster directory within your ICP installation directory:

                cd /<installation_directory>/cluster
              2. Uninstall ICP by running the uninstall-with-openshift command:

                sudo docker run -t --net=host -e LICENSE=accept -v $(pwd):/installer/cluster:z -v /var/run:/var/run:z -v /etc/docker:/etc/docker:z --security-opt label:disable ibmcom/icp-inception-amd64:3.2.1-rhel-ee uninstall-with-openshift

              Additional Resources