Installing IBM Cloud Private with OpenShift

You can install IBM Cloud Private with OpenShift and IBM Cloud Private with OpenShift on IBM Cloud by using the IBM Cloud Private installer.

Before you begin, ensure that your cluster meets the installation requirements. For more information, see Preparing to install IBM Cloud Private with OpenShift.

Installation can be completed in four main steps:

  1. Configure the boot node
  2. Configure your cluster
  3. Run the IBM Cloud Private installer
  4. Post installation tasks

Configure the boot node

The IBM Cloud Private with OpenShift installer can run from either a dedicated boot node or any cluster node. If the boot node is not an OpenShift node, install Docker for your boot node only.

The boot node is the node that is used for the installation of your cluster. The boot node is usually your master node. For more information about the boot node, see Boot node. For IBM Cloud Private with OpenShift, the boot node must be one of the OpenShift nodes.

For an OpenShift on IBM Cloud cluster, all nodes are not accessible. A boot node must be used to install a IBM Cloud Private cluster on top. Since IBM Cloud Private with OpenShift reuses the OpenShift image registry, additional steps are needed to enable access to the registry. For more information, see Step 4 in Configure your cluster.

You need a version of Docker that is supported by IBM Cloud Private with OpenShift installed on your boot node. All versions of Docker that are supported by OpenShift are supported for the boot node. For more information about the supported Docker versions, see OpenShift Docker installation Opens in a new tab.

For the procedure to install Docker, see Manually installing Docker.

Set up the installation environment

  1. Log in to the boot node as a user with root permissions or as a user with sudo privileges.
  2. Download the installation files. You must download the correct file or files for the type of nodes in your cluster.

    • If you are installing IBM Cloud Private version 3.2.0, download the installation files from the IBM Passport Advantage┬« Opens in a new tab website.

      • For a Linux® cluster, download the ibm-cloud-private-rhos-3.2.0.tar.gz file.
    • If you are installing IBM Cloud Private fix pack version 3.2.0.2003, these files are available for download from the IBM® Fix Central Opens in a new tab website.

      • Download the ibm-cloud-private-rhos-3.2.0.2003.tar.gz file.
  3. Extract the images and load them into Docker. Extracting the images might take a few minutes.

    • If you are installing IBM Cloud Private version 3.2.0, run the following command:

       tar xf ibm-cloud-private-rhos-3.2.0.tar.gz -O | sudo docker load
      
    • If you are installing IBM Cloud Private fix pack version 3.2.0.2003, run the following command:

       tar xf ibm-cloud-private-rhos-3.2.0.2003.tar.gz -O | sudo docker load
      
  4. Create an installation directory to store the IBM Cloud Private configuration files in and change to that directory.

    For example, to store the configuration files in /opt/ibm-cloud-private-rhos-3.2.0, run the following commands:

     mkdir /opt/ibm-cloud-private-rhos-3.2.0; \
     cd /opt/ibm-cloud-private-rhos-3.2.0
    
  5. Extract the cluster directory:

     sudo docker run --rm -v $(pwd):/data:z -e LICENSE=accept --security-opt label:disable ibmcom/icp-inception-amd64:3.2.0-rhel-ee cp -r cluster /data
    

    When you install IBM Cloud Private fix pack version 3.2.0.2003, extract the cluster directory by running the following command:

     sudo docker run --rm -v $(pwd):/data:z -e LICENSE=accept --security-opt label:disable ibmcom/icp-inception-amd64:3.2.0.2003-rhel-ee cp -r cluster /data
    
  6. Create cluster configuration files. The OpenShift configuration files are found on the OpenShift master node.

    Copy the OpenShift admin.kubeconfig file to the cluster directory. The OpenShift admin.kubeconfig file can be found in the /etc/origin/master/admin.kubeconfig directory:

     sudo cp /etc/origin/master/admin.kubeconfig cluster/kubeconfig
    

    If your boot node is different from the OpenShift master node, then the previous files must be copied to the boot node.

    For an OpenShift on IBM Cloud cluster, you can obtain or generate its Kubernetes configuration by following the steps in Creating a cluster with the console Opens in a new tab. Once you log in with oc, you can generate the configuration file by running the following command:

    oc config view > kubeconfig
    

Configure your cluster

  1. Update the config.yaml file that you extracted in Step 5 with the following configurations:

       cluster_nodes:
         master:
           - <your-openshift-dedicated-node-to-deploy-icp-master-components>
         proxy:
           - <your-openshift-dedicated-node-to-deploy-icp-proxy-components>
         management:
           - <your-openshift-dedicated-node-to-deploy-icp-management-components>
    
       storage_class: <storage class available in OpenShift>
    
       openshift:
         console:
           host: <your-openshift-console-fqdn>
           port: <your-openshift-console-port>
         router:
           cluster_host: icp-console.<your-openshift-router-domain>
           proxy_host: icp-proxy.<your-openshift-router-domain>
    

    Notes:

    • The value of the master, proxy, and management parameters is an array and can have multiple nodes. Due to a limitation from OpenShift, if you want to deploy IBM Cloud Private on any OpenShift master or infrastructure node, you must label the node as an OpenShift compute node with the following command:

      oc label node <master node host name/infrastructure node host name> node-role.kubernetes.io/compute=true
      
    • You can obtain your-openshift-router-domain by running the following command:

      kubectl -n openshift-console get route console -o jsonpath='{.spec.host}'| cut -f 2- -d "."
      
    • For high availability (HA) configuration, configure more than one master, management, and proxy node.

      For an OpenShift on IBM Cloud cluster:

      • For the storage class parameter, you can use ibmc-file-gold.
      • The values for the openshift console parameter can be obtained from the overview tab in your IBM Cloud Kubernetes cluster.
      • The openshift-router-domain value follows a cluster-specific pattern of <cluster_name>-<cluster_id>.<region>.containers.appdomain.cloud. Run the following command to determine the values: oc get routes --all-namespaces.
  2. Set up a default password in the config.yaml file that meets the default password enforcement rule '^([a-zA-Z0-9\-]{32,})$'. You can also define a custom set of password rules.

    1. Open the /<installation_directory>/cluster/config.yaml file, and set the default_admin_password. The password must satisfy all regular expressions that are specified in password_rules.

    2. Optional: You can define one or more rules as regular expressions in an array list that the password must pass. For example, a rule can state that the password must be longer than a specified number of characters and must contain at least one special character. The rules are written as regular expressions that are supported by the Go programming language. To define a set of password rules, add the following parameter and values to the config.yaml file:

      password_rules:
      - '^.{10,}'
      - '.*[!@#\$%\^&\*].*'
      

      To disable the password_rule, add (.*)

      password_rules:
      - '(.*)'
      

      Note: The default_admin_password must match all rules that are defined. If password_rules is not defined, the default_admin_password must meet the default passport enforcement rule '^([a-zA-Z0-9\-]{32,})$'.

  3. Optional: Enable IBM Multicloud Manager from your config.yaml file. By default, the multicluster-hub option is enabled and the single_cluster_mode option is true, which means IBM Multicloud Manager is not configured. You cannot use IBM Multicloud Manager with the single_cluster_mode default true setting.

    For more information and other configuration scenarios for IBM Multicloud Manager, see Configuration options for IBM Multicloud Manager with IBM Cloud Private installation.

  4. For an OpenShift on IBM Cloud cluster, your boot node does not have direct access to the internal OpenShift image registry. However, you can use the Kubernetes proxy to enable access.

    1. Update /etc/hosts to resolve the docker-registry.default.svc to 127.0.0.1 by running the following command:

       echo 127.0.0.1 docker-registry.default.svc localhost > /etc/hosts
      
    2. Open a new terminal and keep it open during the installation by running the following command:

      kubectl port-forward svc/docker-registry 5000
      

Run the IBM Cloud Private installer

Run the following command:

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

Note: If you encounter errors during installation, you can retry the installation by rerunning the previous command.

Access your cluster

Access your cluster by using a different port than the one that was used for stand-alone IBM Cloud Private. From a web browser, browse to the URL of your cluster. Your URL might resemble the following hyperlink: https://<openshift.router.cluster_host>:<openshift.router.proxy_host>. For a list of supported browsers, see Supported browsers.

Note: If you installed fix pack version 3.2.0.2003, add the root CA certificate to your trust store. With this fix pack, users on macOS 10.15 or newer cannot access the management console until the root CA certificate is added to the trust store. For more information, see:

  * [Refreshing root CA certificates](../user_management/refresh_certs.md)
  * [Troubleshooting console access on macOS Catalina](../troubleshoot/console_catalina.md)

Post installation tasks

  1. Check which node runs the IBM Cloud Private components. To discover the node that runs the IBM Cloud Private components, run following command:

     kubectl --kubeconfig /etc/origin/master/admin.kubeconfig get nodes
    

    The output shows you the roles of your OpenShift node and which node runs the IBM Cloud Private components.

  2. Correct the security context constraints. To correct the security context constraints, run the following command:

       kubectl --kubeconfig /etc/origin/master/admin.kubeconfig patch scc icp-scc -p '{"allowPrivilegedContainer": true}'
    

    Example output:

       securitycontextconstraints "icp-scc" patched
    
  3. After you apply the new security context constraints, run the following command to get the updated output:

     kubectl --kubeconfig /etc/origin/master/admin.kubeconfig get scc icp-scc
    

    Example output:

     NAME      PRIV      CAPS      SELINUX     RUNASUSER   FSGROUP    SUPGROUP   PRIORITY   READONLYROOTFS   VOLUMES
     icp-scc   true      []        MustRunAs   RunAsAny    RunAsAny   RunAsAny   1          false            [configMap downwardAPI emptyDir hostPath nfs persistentVolumeClaim projected secret]