Upgrading your console and components

IBM® Blockchain Platform 2.5.1 is now available. To take advantage of the latest features and for upgrade instructions, see [upgrading your console and components] (https://www.ibm.com/docs/en/SSVKZ7_2.5.1/howto/console-upgrade-ocp.html).

You can upgrade the IBM® Blockchain Platform without disrupting a running network. Because the platform is deployed by using a Kubernetes operator, you can pull the latest IBM Blockchain Platform images from the IBM Entitlement registry without having to reinstall the platform. You can only use these instructions to upgrade to the IBM Blockchain Platform v2.1.3.

IBM Blockchain Platform overview

You can upgrade to the IBM Blockchain Platform v2.1.3 from any previous release of the IBM Blockchain Platform. The table provides an overview of the current and past releases. IBM Blockchain Platform 2.5 is now available. To upgrade to that version see Upgrading your console and components.

Table 1. IBM Blockchain Platform versions
Version	Release date	Image tags	New features
IBM Blockchain Platform v2.1.3	24 March 2020	Console and tools 2.1.3-20200520-amd64 2.1.3-20200416-amd64 2.1.3-20200324-amd64 Fabric nodes 1.4.6-20200520-amd64 1.4.6-20200416-amd64 1.4.6-20200324-amd64 CouchDB 2.3.1-20200520-amd64 2.3.1-20200416-amd64 2.3.1-20200324-amd64	Fabric Version Upgrade Fabric version 1.4.6 Additional platforms Platform can be deployed on the OpenShift Container Platform 4.2 on LinuxONE (s390x) Improvements to the Console UI Hardware Security Module (HSM) support for node identities Ability to override CA, peer, and ordering node configuration Ability to add and remove Raft ordering nodes Java smart contract instantiation Updated create channel and create organization panels
IBM Blockchain Platform v2.1.2	17 December 2019	Console and tools 2.1.2-20191217-amd64 2.1.2-20200213-amd64 Fabric nodes 1.4.4-20191217-amd64 1.4.4-20200213-amd64 CouchDB 2.3.1-20191217-amd64 2.3.1-20200213-amd64	Fabric Version Upgrade Fabric version 1.4.4 Additional platforms Platform can be deployed on the OpenShift Container Platform 4.1 and 4.2 Improvements to the Console UI Simplified component creation flows Zone selection for ordering nodes Add peer to a channel from Channels tab Anchor peer during join Export/Import all
IBM Blockchain Platform v2.1.1	8 November 2019	Console and tools 2.1.1-20191108-amd64 Fabric nodes 1.4.3-20191108-amd64 CouchDB 2.3.1-20191108-amd64	Additional platforms Platform can be deployed on Kubernetes v1.14 - v1.16 Platform can be deployed on IBM Cloud Private 3.2.1
IBM Blockchain Platform v2.1.0	24 September 2019	Console and tools 2.1.0-20190918-amd64 Fabric nodes 1.4.3-20190918-amd64 CouchDB 2.3.1-20190918-amd64	Fabric Version Upgrade Fabric version 1.4.3 Additional platforms Platform can be deployed on the OpenShift Container Platform 3.11

If you are using IBM Blockchain Platform v2.1.0 or v2.1.1, you cannot access the console from the Chrome browser on Mac OS Catalina when the console is deployed with the default configuration that uses self-signed certificates. For more information on how you can resolve this problem, see Chrome browser on Mac OS Catalina in Known Issues.

Upgrading platforms

If you are using IBM Blockchain Platform v2.1.0 or V2.1.1 on the OpenShift Container Platform 3.11, you can upgrade your network to run on OpenShift Container Platform 4.2. Because the IBM Blockchain Platform v2.1.0 or v2.1.1 cannot run on OpenShift Container Platform 4.x, you need to upgrade your blockchain network before you upgrade your cluster. First, follow the steps to upgrade your network to the IBM Blockchain Platform v2.1.3. You can then migrate your OpenShift cluster from 3.11 to 4.2. You cannot migrate your OpenShift cluster from 3.11 to 4.1. For more information, see Migrating OpenShift Container Platform 3.7 to 4.2.

Updating the Operator triggers a restart of all components managed by this installation of the IBM Blockchain Platform including Fabric nodes. To avoid disruption of service, a multiregion setup is recommended.

Upgrade to the IBM Blockchain Platform v2.1.3

You can upgrade an IBM Blockchain Platform network by using the following steps:

Update the ClusterRole
Upgrade the IBM Blockchain Platform operator
Use your console to upgrade your running blockchain nodes

After you upgrade the IBM Blockchain Platform operator, the operator will automatically upgrade the console that is deployed on your OpenShift project. You can then use the upgraded console to upgrade your blockchain nodes.

You need to complete these steps for each network that that runs on a separate project. If you experience any problems, see the instructions for rolling back an upgrade. If you deployed your network behind a firewall, without access to the external internet, see the separate set of instructions for Upgrading the IBM Blockchain Platform behind a firewall.

You can continue to submit transactions to your network while you are upgrading your network. However, you cannot use the console to deploy new nodes, install or instantiate smart contracts, or create new channels during the upgrade process.

Roll back an upgrade

When you upgrade your operator, the operator saves the secrets, deployment spec, and network information of your console before attempting to upgrade the console. If your upgrade fails for any reason, the IBM Support can roll back your upgrade and restore your previous deployment by using the information on your cluster. If you need to roll back your upgrade, you can submit a support case from the mysupport page.

You can roll back an upgrade after you use the console to operate your network. However, after you use the console to upgrade your blockchain nodes, you can no longer roll back your console to a previous version of the platform.

Before you begin

To upgrade your network, you need to retrieve your entitlement key from the My IBM Dashboard, and create a Kubernetes secret to store the key on your OpenShift project. If the Entitlement key secret was removed from your cluster, or if your key is expired, then you need to download another key and create a new secret.

Occasionally, a five node ordering service that was deployed using v2.1.2 will be deleted by the Kubernetes garbage collector because it considers the nodes a resource that needs to be cleaned up. This process is both random and unrecoverable --- if the ordering service is deleted, all of the channels hosted on it are permanently lost. To prevent this, the ownerReferences field in the configuration of each ordering node must be removed before upgrading to v2.1.3. For the steps about how to pull the configuration file, remove ordererReferences, and apply the change, see Known issues in the v2.1.2 documentation.

Step One: Update the ClusterRole

This step is only required if you are upgrading from v2.1.0 or v2.1.1. If you are running v2.1.2 you can skip to Step two.

You need to update the ClusterRole that is applied to your project. Copy the following text to a file on your local system and save the file as ibp-clusterrole.yaml. Edit the file and replace <PROJECT_NAME> with the name of your project.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: null
  name: <PROJECT_NAME>
rules:
- apiGroups:
  - apiextensions.k8s.io
  resources:
  - persistentvolumeclaims
  - persistentvolumes
  - customresourcedefinitions
  verbs:
  - '*'
- apiGroups:
  - "*"
  resources:
  - pods
  - services
  - endpoints
  - persistentvolumeclaims
  - persistentvolumes
  - events
  - configmaps
  - secrets
  - ingresses
  - roles
  - rolebindings
  - serviceaccounts
  - nodes
  - routes
  - routes/custom-host
  verbs:
  - '*'
- apiGroups:
  - ""
  resources:
  - namespaces
  - nodes
  verbs:
  - get
- apiGroups:
  - apps
  resources:
  - deployments
  - daemonsets
  - replicasets
  - statefulsets
  verbs:
  - '*'
- apiGroups:
  - monitoring.coreos.com
  resources:
  - servicemonitors
  verbs:
  - get
  - create
- apiGroups:
  - apps
  resourceNames:
  - ibp-operator
  resources:
  - deployments/finalizers
  verbs:
  - update
- apiGroups:
  - ibp.com
  resources:
  - '*'
  - ibpservices
  - ibpcas
  - ibppeers
  - ibpfabproxies
  - ibporderers
  verbs:
  - '*'
- apiGroups:
  - ibp.com
  resources:
  - '*'
  verbs:
  - '*'
- apiGroups:
  - config.openshift.io
  resources:
  - '*'
  verbs:
  - '*'

After you save and edit the file, run the following commands. Replace <PROJECT_NAME> with your project.

oc apply -f ibp-clusterrole.yaml
oc adm policy add-scc-to-group <PROJECT_NAME> system:serviceaccounts:<PROJECT_NAME>

Step two: Upgrade the IBM Blockchain operator

You can upgrade the IBM Blockchain operator by fetching the operator deployment spec from your OpenShift project. When the operator upgrade is complete, the operator will upgrade your console and download the latest images for your blockchain nodes.

Log in to your cluster by using the OpenShift CLI. Because each IBM Blockchain network runs in a different project, you must switch to each OpenShift project and upgrade each network separately. Go to the OpenShift project of the network that you want to upgrade. Replace <PROJECT_NAME> with the name of your project.

oc project <PROJECT_NAME>

When you are operating from your project, run the following command to download the operator deployment spec to your local file system:

kubectl get deployment ibp-operator -o yaml > operator.yaml

Open operator.yaml in a text editor and save a new copy of the file as operator-upgrade.yaml. Open operator-upgrade.yaml in a text editor. You need to update the image: field with the updated version of the operator image. You can find the name and tag of the latest operator image below:

cp.icr.io/cp/ibp-operator:2.1.3-20200520-amd64

If you are upgrading from v2.1.0 or v2.1.1, then you also need to edit the env: section of the file. Find the following lines in operator-upgrade.yaml:

- name: ISOPENSHIFT
  value: "true"

Replace this section with the following lines at the same indentation:

- name: CLUSTERTYPE
  value: OPENSHIFT

When you are finished editing the file, the env: section would look similar to the following:

env:
- name: WATCH_NAMESPACE
  valueFrom:
   fieldRef:
     apiVersion: v1
     fieldPath: metadata.namespace
- name: POD_NAME
  valueFrom:
   fieldRef:
     apiVersion: v1
     fieldPath: metadata.name
- name: OPERATOR_NAME
  value: ibp-operator
- name: CLUSTERTYPE
  value: OPENSHIFT

Save the file on your local system. You can then issue the following command upgrade your operator:

kubectl apply -f operator-upgrade.yaml

You can use the kubectl get deployment ibp-operator -o yaml command to confirm that the command updated the operator spec.

After you apply the operator-upgrade.yaml operator spec to your OpenShift project, the operator will restart and pull the latest image. The upgrade takes about a minute. While the upgrade is taking place, you can still access your console UI. However, you cannot use the console to install and instantiate chaincode, or use the console or the APIs to create or remove a node.

You can check that the upgrade is complete by running kubectl get deployment. If the upgrade is successful, then you can see the following tables with four ones displayed for your operator and your console.

NAME           READY     UP-TO-DATE   AVAILABLE   AGE
ibp-operator   1/1       1            1           1m
ibpconsole     1/1       1            1           4m

If you experience a problem while you are upgrading the operator, go to this troubleshooting topic for a list of commonly encountered problems. You can run the command to apply the original operator file, kubectl apply -f operator.yaml to restore your original operator deployment.

Step three: Upgrade your blockchain nodes

After you upgrade your console, you can use the console UI to upgrade the nodes of your blockchain network. Browse to the console UI and open the nodes overview tab. You can find the Patch available text on a node tile if there is an update available for the component. You can install this patch whenever you are ready. These patches are optional, but they are recommended. You cannot patch nodes that were imported into the console.

Apply patches to nodes one at a time. Your nodes are unavailable to process requests or transactions while the patch is being applied. Therefore, to avoid any disruption of service, you need to ensure that another node of the same type is available to process requests whenever possible. Installing patches on a node takes about a minute to complete and when the update is complete, the node is ready to process requests.

To apply a patch to a node, open the node tile and click the Update available button. You cannot patch nodes that you imported to the console.

Upgrading the IBM Blockchain Platform behind a firewall

If you deployed the IBM Blockchain Platform behind a firewall, without access to the external internet, you can upgrade your network by using the following steps:

Pull the latest IBM Blockchain Platform images
Update the ClusterRole
Upgrade the IBM Blockchain Platform operator
Use your console to upgrade your running blockchain nodes

Before you begin

Step one: Pull the latest IBM Blockchain Platform images

To upgrade your network, download the latest set of IBM Blockchain Platform images and push them to a docker registry that you can access from behind your firewall.

Use the following command to log in to the IBM Entitlement Registry:

docker login --username cp --password <KEY> cp.icr.io

Replace <KEY> with your entitlement key.

After you log in, use the following command to pull the images for IBM Blockchain Platform v2.1.3:

docker pull cp.icr.io/cp/ibp-operator:2.1.3-20200520-amd64
docker pull cp.icr.io/cp/ibp-init:2.1.3-20200520-amd64
docker pull cp.icr.io/cp/ibp-peer:1.4.6-20200520-amd64
docker pull cp.icr.io/cp/ibp-orderer:1.4.6-20200520-amd64
docker pull cp.icr.io/cp/ibp-ca:1.4.6-20200520-amd64
docker pull cp.icr.io/cp/ibp-dind:1.4.6-20200520-amd64
docker pull cp.icr.io/cp/ibp-console:2.1.3-20200520-amd64
docker pull cp.icr.io/cp/ibp-grpcweb:2.1.3-20200520-amd64
docker pull cp.icr.io/cp/ibp-utilities:1.4.6-20200520-amd64
docker pull cp.icr.io/cp/ibp-couchdb:2.3.1-20200520-amd64
docker pull cp.icr.io/cp/ibp-deployer:2.1.3-20200520-amd64
docker pull cp.icr.io/cp/ibp-fluentd:2.1.3-20200520-amd64

After you download the images, you must change the image tags to refer to your docker registry. Replace <LOCAL_REGISTRY> with the url of your local registry and run the following commands:

docker tag cp.icr.io/cp/ibp-operator:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-operator:2.1.3-20200520-amd64
docker tag cp.icr.io/cp/ibp-init:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-init:2.1.3-20200520-amd64
docker tag cp.icr.io/cp/ibp-peer:1.4.6-20200520-amd64 <LOCAL_REGISTRY>/ibp-peer:1.4.6-20200520-amd64
docker tag cp.icr.io/cp/ibp-orderer:1.4.6-20200520-amd64 <LOCAL_REGISTRY>/ibp-orderer:1.4.6-20200520-amd64
docker tag cp.icr.io/cp/ibp-ca:1.4.6-20200520-amd64 <LOCAL_REGISTRY>/ibp-ca:1.4.6-20200520-amd64
docker tag cp.icr.io/cp/ibp-dind:1.4.6-20200520-amd64 <LOCAL_REGISTRY>/ibp-dind:1.4.6-20200520-amd64
docker tag cp.icr.io/cp/ibp-console:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-console:2.1.3-20200520-amd64
docker tag cp.icr.io/cp/ibp-grpcweb:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-grpcweb:2.1.3-20200520-amd64
docker tag cp.icr.io/cp/ibp-utilities:1.4.6-20200520-amd64 <LOCAL_REGISTRY>/ibp-utilities:1.4.6-20200520-amd64
docker tag cp.icr.io/cp/ibp-couchdb:2.3.1-20200520-amd64 <LOCAL_REGISTRY>/ibp-couchdb:2.3.1-20200520-amd64
docker tag cp.icr.io/cp/ibp-deployer:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-deployer:2.1.3-20200520-amd64
docker tag cp.icr.io/cp/ibp-fluentd:2.1.3-20200520-amd64 <LOCAL_REGISTRY>/ibp-fluentd:2.1.3-20200520-amd64

You can use the docker images command to check that the new tags were added. You can then push the images with the new tags to your docker registry. Log in to your registry by using the following command:

docker login --username <USER> --password <LOCAL_REGISTRY_PASSWORD> <LOCAL_REGISTRY>

Replace <USER> with your username
Replace <LOCAL_REGISTRY_PASSWORD> with the password to your registry.
Replace <LOCAL_REGISTRY> with the url of your local registry.

Then, run the following command to push the images. Replace <LOCAL_REGISTRY> with the url of your local registry.

docker push <LOCAL_REGISTRY>/ibp-operator:2.1.3-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-init:2.1.3-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-peer:1.4.6-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-orderer:1.4.6-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-ca:1.4.6-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-dind:1.4.6-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-console:2.1.3-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-grpcweb:2.1.3-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-utilities:1.4.6-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-couchdb:2.3.1-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-deployer:2.1.3-20200520-amd64
docker push <LOCAL_REGISTRY>/ibp-fluentd:2.1.3-20200520-amd64

After you complete these steps, you can use the following instructions to deploy the IBM Blockchain Platform with the images in your registry.

Step two: Update the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: null
  name: <PROJECT_NAME>
rules:
- apiGroups:
  - apiextensions.k8s.io
  resources:
  - persistentvolumeclaims
  - persistentvolumes
  - customresourcedefinitions
  verbs:
  - '*'
- apiGroups:
  - "*"
  resources:
  - pods
  - services
  - endpoints
  - persistentvolumeclaims
  - persistentvolumes
  - events
  - configmaps
  - secrets
  - ingresses
  - roles
  - rolebindings
  - serviceaccounts
  - nodes
  - routes
  - routes/custom-host
  verbs:
  - '*'
- apiGroups:
  - ""
  resources:
  - namespaces
  - nodes
  verbs:
  - get
- apiGroups:
  - apps
  resources:
  - deployments
  - daemonsets
  - replicasets
  - statefulsets
  verbs:
  - '*'
- apiGroups:
  - monitoring.coreos.com
  resources:
  - servicemonitors
  verbs:
  - get
  - create
- apiGroups:
  - apps
  resourceNames:
  - ibp-operator
  resources:
  - deployments/finalizers
  verbs:
  - update
- apiGroups:
  - ibp.com
  resources:
  - '*'
  - ibpservices
  - ibpcas
  - ibppeers
  - ibpfabproxies
  - ibporderers
  verbs:
  - '*'
- apiGroups:
  - ibp.com
  resources:
  - '*'
  verbs:
  - '*'
- apiGroups:
  - config.openshift.io
  resources:
  - '*'
  verbs:
  - '*'

After you save and edit the file, run the following commands. Replace <PROJECT_NAME> with your project.

oc apply -f ibp-clusterrole.yaml
oc adm policy add-scc-to-group <PROJECT_NAME> system:serviceaccounts:<PROJECT_NAME>

Step three: Upgrade the IBM Blockchain operator

You can upgrade the IBM Blockchain operator by fetching the operator deployment spec from your OpenShift project. You can then update the spec with the latest operator image that you pushed to your local registry. When the operator upgrade is complete, the operator will download the images that you pushed to your local registry and upgrade your console.

oc project <PROJECT_NAME>

When you are operating from your project, run the following command to download the operator deployment spec to your local file system:

kubectl get deployment ibp-operator -o yaml > operator.yaml

Open operator.yaml in a text editor and save a new copy of the file as operator-upgrade.yaml. Open operator-upgrade.yaml a text editor. You need to update the image: field with the updated version of the operator image:

<LOCAL_REGISTRY>/ibp-operator:2.1.3-20200520-amd64

If you are upgrading from v2.1.0 or v2.1.1, then you also need to edit the env: section of the file. Find the following lines in operator-upgrade.yaml:

- name: ISOPENSHIFT
  value: "true"

Replace the values above with the following lines at the same indentation:

- name: CLUSTERTYPE
  value: OPENSHIFT

When you are finished editing the file, the env: section would look similar to the following:

env:
- name: WATCH_NAMESPACE
  valueFrom:
   fieldRef:
     apiVersion: v1
     fieldPath: metadata.namespace
- name: POD_NAME
  valueFrom:
   fieldRef:
     apiVersion: v1
     fieldPath: metadata.name
- name: OPERATOR_NAME
  value: ibp-operator
- name: CLUSTERTYPE
  value: OPENSHIFT

Save the file on your local system. You can then issue the following command upgrade your operator:

kubectl apply -f operator-upgrade.yaml

You can use the kubectl get deployment ibp-operator -o yaml command to confirm that the command updated the operator spec.

NAME           READY     UP-TO-DATE   AVAILABLE   AGE
ibp-operator   1/1       1            1           1m
ibpconsole     1/1       1            1           4m

If you experience a problem while you are upgrading the operator, go to this troubleshooting topic for a list of commonly encountered problems.

If your console experiences an image pull error, you may need to update the console deployment spec with the local registry that you used to download the images.

NAME                          READY     STATUS              RESTARTS   AGE
ibp-operator-b9446759-6tmls   1/1       Running             0          1m
ibpconsole-57ff4bcbb7-79dhn   0/4       Init:ErrImagePull   0          1m

This can happen if you have changed your regsitry URL between deployments. Run the following command to download the deployment spec of the console:

kubectl get ibpconsole ibpconsole -o yaml > console.yaml

Then add the URL of your local registry to the spec: section of console.yaml. Replace <LOCAL_REGISTRY> with the url of your local registry:

spec:
   registryURL: <LOCAL_REGISTRY>

Save the updated file as console-upgrade.yaml on your local system. You can then issue the following command upgrade your console:

kubectl apply -f console-upgrade.yaml

Step four: Upgrade your blockchain nodes

After you upgrade your console, you can use the console UI to upgrade the nodes of your blockchain network. For more information, see Upgrade your blockchain nodes.