Installing IBM Cloud Paks
The following tasks represent the typical task flow for performing your IBM Cloud Pak® installation:
- Install Red Hat OpenShift Container Platform
- (Optional) Mirroring IBM Cloud Pak images to a private container registry using the IBM Catalog Management Plug-in for IBM Cloud Paks (ibm-pak plugin)
- Add the IBM operator catalog and prepare your cluster
- Install IBM operator
- Attach entitlement key
- Create your IBM Cloud Pak instance
Note: While the overall steps in this process apply to the IBM Cloud Paks, you should still consult your IBM Cloud Pak Installation documentation for additional steps that might be required.
Important: Some steps require you to have cluster admin access.
1. Install Red Hat OpenShift Container Platform
Review the Planning section.
Most IBM Cloud Paks require OpenShift to be installed and running. For detailed steps about how to install OpenShift, see Installing Red Hat OpenShift Container Platform.
Note: Ensure that you have a supported version of OpenShift installed. For more information about OpenShift compatibility, see IBM Cloud Pak and Red Hat OpenShift Container Platform compatibility.
For any steps that use the Red Hat® OpenShift® Container Platform command line interface (CLI), you must be logged in to your OpenShift cluster with oc login
.
After you install OpenShift, you can verify and gain access to your container software by using your IBM entitlement key that you create in Create the entitlement keys.
Important: Having access to an entitlement key implies that you have access to Passport Advantage®, where the software was purchased from.
You can have one central account (a functional ID) that can be associated with the entitlement key that you want to use for your installation. You also need to create an IBM ID to associate with your functional ID to use the Passport Advantage “Manage Access” tools so that you can grant your functional id download access to your Passport Advantage site. However, note that a primary contact, administrative contact or site technical contact cannot be a functional ID since they are accepting legal terms of responsibility for managing the site. For more information about how entitlement works, see Managing entitlements.
2. (Optional) Mirroring IBM Cloud Pak images to a private container registry using the IBM Catalog Management Plug-in for IBM Cloud Paks (ibm-pak plugin)
The IBM Catalog Management Plug-in for IBM Cloud Paks simplifies the process for discovering required IBM product images and and uses standard Red Hat tooling for registry and cluster access. The metadata is packaged within 1-n CASEs (Container Application Software for Enterprise) which specify the composition of the product (for example, OLM packages, channels, and so on) and ultimately images that must be copied into an air-gapped environment.
Additionally, the ibm-pak
plug-in extends the OpenShift CLI (oc
command) capability to streamline the process of delivering installation images to the IBM Cloud Pak in an air-gapped environment.
Note: The IBM Catalog Management Plug-in for IBM Cloud Paks will be referred to in the documentation as ibm-pak
plug-in.
For more information about installing an IBM Cloud Pak by using a private container registry, see Installing your IBM Cloud Pak by mirroring Cloud Pak images to a private container registry (with ibm-pak plug-in). For more information about available CASE names and versions, see IBM: Product CASE to Application Version.
Red Hat OpenShift Container Platform requires you to have cluster admin access to run the install-operator
command.
3. Add the IBM operator catalog and prepare your cluster
Add the IBM operator catalog
The IBM operator catalog is an index of operators available to automate deployment and maintenance of IBM Software products into Red Hat® OpenShift® Container Platform clusters. Operators within this catalog are built following Kubernetes
best practices and IBM standards to provide a consistent, integrated set of capabilities. The catalog can be added to any Red Hat OpenShift Container Platform 4.6 and newer cluster by application of the CatalogSource
resource.
On Red Hat OpenShift Container Platform clusters that run Red Hat OpenShift Container Platform 4.8 and earlier, the catalog tag in the CatalogSource is set to latest
to obtain the most recent version of the catalog. On Red Hat OpenShift
Container Platform clusters that run Red Hat OpenShift Container Platform 4.9 or later, the olm.catalogImageTemplate
annotation is used to switch the catalog tag from latest
to a different tag based on the Kubernetes
version used by the cluster. Setting the annotation causes the catalog to automatically switch to a catalog that is compatible with the cluster whenever the cluster is updated to a new Kubernetes version. For example, for Red Hat OpenShift Container
Platform 4.9, the tag updates to v1.22
instead of latest
. On Red Hat OpenShift Container Platform clusters that run Red Hat OpenShift Container Platform 4.9 and earlier, the olm.catalogImageTemplate
annotation
has no effect.
Notes:
-
In February, 2023, the IBM Operator Catalog will be changing from the deprecated SQLITE format to the file-based Catalog format. This change is largely transparent and will not affect CatalogSources installed on OpenShift Container Platform. Customers using the
opm
command-line utility with deprecated subcommands and flags that require the SQLITE format will fail, such asopm index prune
. For more information about working with custom, file-based catalogs, see the Red Hat OpenShift Container Platform version 4.11 documentation. -
If you deploy your catalog to the
openshift-marketplace
namespace, you must have cluster admin access. If you deploy the catalog to another IBM Cloud Pak-specific namespace, only namespace admin access is required.
Creating CatalogSource with OpenShift
- Log in to your Red Hat OpenShift Container Platform cluster.
- Click Home > Search > Resources, then select CatalogSource.
- Click Create CatalogSource.
- In the CatalogSource name field, enter
ibm-operator-catalog
. - In the Publisher name field, enter
IBM
. - In the Image (URL of container image) field, enter
icr.io/cpopen/ibm-operator-catalog:latest
. - Under Availability, select the Cluster-wide CatalogSource option.
You can verify successful CatalogSource creation by going into the OperatorHub where the IBM Operator Catalog now exists as a source value. You are also provided with a confirmation after the CatalogSource value is completed in Red Hat OpenShift Container Platform. It can sometimes take approximately 5 minutes for the CatalogSource to appear in OperatorHub after successful completion.
CLI enablement
The catalog can be added by applying the following YAML file to the Red Hat OpenShift Container Platform cluster. Create this file and name it catalog_source.yaml
.
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
name: ibm-operator-catalog
namespace: openshift-marketplace
annotations:
olm.catalogImageTemplate: "icr.io/cpopen/ibm-operator-catalog:v{kube_major_version}.{kube_minor_version}"
spec:
displayName: IBM operator Catalog
publisher: IBM
sourceType: grpc
image: icr.io/cpopen/ibm-operator-catalog:latest
updateStrategy:
registryPoll:
interval: 45m
Apply the YAML file by using the command:
oc apply -f catalog_source.yaml -n openshift-marketplace
Verify the CLI installation
oc get CatalogSources ibm-operator-catalog -n openshift-marketplace
You receive this output on error:
Error from server (NotFound): catalogsources.operators.coreos.com "ibm-operator-catalog" not found
You receive this output on success:
NAME DISPLAY TYPE PUBLISHER AGE
ibm-operator-catalog IBM operator Catalog grpc IBM 28s
4. Install the operator
You can install your operator by using the OpenShift console or the OpenShift CLI. Operators span all of your clusters. As such, cluster admin access is required to deploy operators.
Note: A project is a Kubernetes namespace.
Option 1: Install the operator with the OpenShift console
- Log in to your OpenShift cluster's console.
- Click Operators > OperatorHub. The OperatorHub page is displayed.
- In the All Items field, enter the full name of your IBM Cloud Pak. The operator is displayed.
- Click the tile that has the full name of your IBM Cloud Pak. The window with the name of your IBM Cloud Pak is displayed.
- Click Install. The Install Operator page is displayed.
-
Enter the following values:
- Set Update Channel to the latest version available for your IBM Cloud Pak.
- Set the Installation mode to
A specific namespace on the cluster
. -
Set the Namespace to the project (namespace) value that you want to install the operator into.
Note: When using the console to install the operator, you can either use an existing namespace, the default namespace that is provided by the operator, or create a new namespace. If you want to create a new namespace, you can create it from this form. If you want to create a namespace before installing, from the Project list, select Create Project, specify the Name of the project that you want to create, and click Create.
-
Set Approval Strategy to
Automatic
.
-
Click Install and wait for the your operator to install.
OpenShift informs you that the installation is complete. You can verify that installation by navigating to Operators > Installed Operators, and selecting your project from the Projects dropdown.
The operator that you have just installed and all of its dependent operators in the project are listed with a status of Succeeded
.
Option 2: Install the operator with the OpenShift CLI
-
Determine whether you want to create a new, or reuse an existing namespace to install your operator into. To create a new namespace in the CLI, run the following command:
oc create namespace <namespace>
Where
<namespace>
is the name of the namespace that you want to create. -
Create Operator Group.
You must create an operator group in your custom project (namespace), or your operator will not install. There might be an operator group for managing a namespace for given APIs. If there is an Operator group for the namespace, do not create a second one.
Create the Operator group by running the following command:
cat << EOF | oc apply -f - apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: <your-operator-group> namespace: <namespace> spec: targetNamespaces: - <namespace> EOF
-
Install your operator with the following command:
cat << EOF | oc apply -f - apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: <your-operator-group> namespace: <namespace> spec: channel: <latest-version-of-your-cloud-pak> installPlanApproval: Automatic name: <your-operator-group> source: ibm-operator-catalog sourceNamespace: openshift-marketplace EOF
-
After a few minutes, the operator is installed. Run the following command to verify that all of the components are in the
Succeeded
state:oc get csv -n <namespace> | grep <your-operator-group>
Where
<namespace>
isopenshift-operators
if you are using theAllNamespaces
installation mode, or the project (namespace) if you are using theOwnNamespace
installation mode.
5. Create the entitlement key secret
Complete the following steps to create a docker-registry secret to enable your deployment to pull operand images from the IBM® Entitled Registry.
If you create your entitlement key at the namespace level, namespace admin access is required. If you add the key to the global pull secret, cluster admin access is required.
Important: Having access to an entitlement key implies that you have access to Passport Advantage®, where the software was purchased from.
You can have one central account (a functional ID) that can be associated with the entitlement key that you want to use for your installation. You also need to create an IBM ID to associate with your functional ID to use the Passport Advantage “Manage Access” tools so that you can grant your functional id download access to your Passport Advantage site. However, note that a primary contact, administrative contact or site technical contact cannot be a functional ID since they are accepting legal terms of responsibility for managing the site. For more information about how entitlement works, see Managing entitlements.
Option 1: Create the entitlement key secret with the OpenShift console
- Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library
with the IBMid and password details that are associated with the entitled software.
- In the OpenShift console, ensure that you are in the Project (for example,
paks
) that you installed the operator into. - Click Workloads > Secrets > Create, then select Image pull secret.
- In the Secret name field, enter
ibm-entitlement-key
. - In the Registry server address field, enter
cp.icr.io
. - In the Username field, enter
cp
. - In the Password field, enter the credential that you received from entitlement.
- (Optional) In the Email field, enter a contact email address.
Option 2: Create the entitlement key secret with the CLI
- Obtain the entitlement key that is assigned to your IBMid. Log in to MyIBM Container Software Library
with the IBMid and password details that are associated with the entitled software.
- In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
-
From the Red Hat OpenShift CLI, run the following command to create an image pull secret called ibm-entitlement-key.
oc create secret docker-registry ibm-entitlement-key \ --docker-username=cp\ --docker-password=<entitlement-key> \ --docker-server=cp.icr.io \ --namespace=<namespace>
Where:
- `<entitlement-key>` is the entitlement key that you copied in step 2. - `<namespace>` is the namespace that you installed your IBM Cloud Pak operator in.
6. Create your IBM Cloud Pak instance
- Log in to theRed Hat OpenShift Container Platform web console with your Red Hat OpenShift Container Platform cluster admin credentials.
- Change Project to the namespace where you installed the operator in. Select the namespace from the Project drop-down list.
- In the navigation panel, click Operators > Installed Operators.
- In the list on the Installed Operators panel, find and click your IBM Cloud Pak.
- Click the tab corresponding to your IBM Cloud Pak.
- Click Create
, where <instance of your IBM Cloud Pak name>
is the name of the instance type of that operator. For example, in IBM Cloud Pak for Watson AIOps, you can create an instance ofAIManager
. The instance creation panel opens, and offers two methods for configuring the resource; the Form view and the YAML view. The Form view is selected by default
Configuring in the Form view
The Form view opens a form that you can view or modify the resource configuration.
Note: Some fields might not be represented in the default form view.
- In the Name field, enter a name for the new instance or leave the default.
- Next to License, click the arrow to expand the license acceptance section.
- Set License Accept to true if you accept the license agreement of your Cloud Pak.
- For License LI, click the arrow to open the drop-down list, and select a license. For details about specific licenses, check the documentation on licensing for your particular Cloud Pak.
-
Specify the Storage class. Click the arrow to expand the Storage pane, then click the arrow for Select Storage Class and select a file storage class a file storage class that supports
ReadWriteMany (RWX)
volumes and allows read and write access to nonroot users. Supported storage providers includeibmc-file-gold-gid
, Red Hat OpenShift Data Foundation (formerly Red Hat OpenShift Container Storage), Spectrum, and Portworx. For additional details about storage support and configuration, check the documentation on storage for your particular Cloud Pak.Note: If you do not see any options in the Storage Class list, you need to create one or more storage options. See the Requirements section for more information.
-
Set any other configuration values as appropriate.
- Click Create. The creation process can take a longer amount of time depending on your environment.
Your instance of the Cloud Pak is added to the list of instances in the current project (namespace).
Configuring in the YAML view
The YAML view opens an editor containing an example YAML file for a resource. Update the values in the file per the following steps:
- Change
metadata.namespace
to your project (namespace) name. - Change
spec.license.accept
totrue
if you accept the license agreement for your Cloud Pak. - Change the value of
spec.license.license
to the license string that matches your version of Cloud Pak. Check the documentation on licensing for your particular Cloud Pak for more information. - For
spec.storage.class
, specify a file storage class a file storage class that supportsReadWriteMany (RWX)
volumes and allows read and write access to non-root users. Supported storage providers includeibmc-file-gold-gid
, OpenShift Data Foundation (formerly OpenShift Container Storage), Spectrum, and Portworx. For more details about storage support and configuration, check the documentation on storage for your particular Cloud Pak. - Click Create. The creation process can take a longer amount of time depending on your environment.
Your instance of Cloud Pak is added to the list of instances in the current project (namespace).
Verifying instance creation
You can verify that you've created an instance of your operator by completing the following steps:
- Ensure that you're in the namespace that you created your operator in.
- From the Home screen, click Operators > Installed Operators, then select the installed operator that you created the instance for.
- Click All instances. An instance of the operator that you created is listed with a positive status message, like
Succeeded
orCompleted
.
Access the console
Use the following command to get the URL to access the console:
oc get route -n <YOUR_OPERATOR_NAME> cp-console -o jsonpath=‘{.spec.host}’
The preceding command returns the following output:
cp-console.apps.mycluster.mydomain.com
Based on the example output, your console URL would be https://cp-console.apps.mycluster.mydomain.com
.
Retrieve your console username and password
The default username to access the console is admin
.
You can get the password for the admin
username by running the following command:
oc -n <YOUR_OPERATOR_NAME> get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 -d
The following password is an example of the output of the preceding command:
EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA
Based on the example output, you would then use EwK9dj9fwPZHyHTyu9TyIgh9klZSzVsA
as the password.
You have now successfully created and deployed your IBM Cloud Pak environment using a private container registry.
Assess compatibility with other IBM Cloud® Paks on the cluster
Some IBM Cloud Paks might only support installation at the AllNamespaces
(cluster) installation mode. If your IBM Cloud Pak depends on IBM® Automation foundation, if the Automation foundation operators were installed by another
IBM Cloud Pak, they must also be installed at the AllNamespaces
installation mode. If there are other IBM Cloud Paks installed on the cluster, ensure that they were also installed by using the AllNamespaces
installation
mode. Refer to the IBM Documentation for your specific IBM Cloud Paks, to determine how to configure their installation mode. For more information about configuring operator installation mode, see Adding operators to a cluster .