Upgrading Streams Flows

A project administrator can upgrade the Streams Flows service on IBM® Cloud Pak for Data.

Before you begin

Required role: To complete this task, you must be an administrator of the project (namespace) where Streams Flows is installed.

Before you upgrade Streams Flows, ensure that:

The Cloud Pak for Data control plane is already upgraded on your Red Hat® OpenShift® cluster. For details, see Upgrading IBM Cloud Pak for Data.
Streams Flows is backed up. For details, see Backing up and restoring Streams Flows.
The cluster meets the minimum requirements for Streams Flows. For details, see System requirements for services.
You completed the steps in Preparing to install and upgrade services.

Common core services Streams Flows requires the Cloud Pak for Data common core services. The common core services are installed once in a given Red Hat OpenShift project. If the common core services are not installed in the project where you plan to install Streams Flows or if the common core services are not at the correct version, the common core services will be automatically installed or upgraded when you upgrade Streams Flows. If the common core services need to be installed or upgraded, it might take longer to upgrade Streams Flows. For more information on the common core services, see:

If you are upgrading multiple services on your cluster, you must run the upgrades one at a time and wait until the upgrade completes before upgrading another service. You cannot run the upgrades in parallel.

Tip: For a list of all available options, enter the following command:

./cpd-cli upgrade --help

Procedure

Complete the appropriate steps to upgrade Streams Flows on your environment:
- Upgrading on clusters connected to the internet
- Upgrading on air-gapped clusters
Verifying that the upgrade completed successfully
Checking for available patches
Upgrading existing service instances
Complete the tasks listed in What to do next

Upgrading on clusters connected to the internet

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```

Run the following command to see a preview of what will change when you upgrade the service.

Important: If you are using the internal Red Hat OpenShift registry and you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.

./cpd-cli upgrade \
--repo ./repo.yaml \
--assembly streams-flows \
--arch Cluster_architecture \  
--namespace Project \
--storageclass Storage_class_name \
--transfer-image-to Registry_location \
--cluster-pull-prefix Registry_from_cluster \
--ask-pull-registry-credentials \
--ask-push-registry-credentials \
--latest-dependency \
--dry-run

Important: By default, this command gets the latest assembly. If you want to upgrade to a specific version of Streams Flows, add the following line to your command after the --assembly flag:

--version Assembly_version \

The --latest-dependency flag gets the latest version of the dependent assemblies. If you remove the --latest-dependency flag, the installer will either leave the dependent assemblies at the current version or get the minimum version of the dependent assemblies.

Replace the following values:

Variable	Replace with
`Assembly_version`	The version of Streams Flows that you want to install. The assembly versions are listed in System requirements for services.
`Cluster_architecture`	Specify the architecture of your cluster hardware: For x86-64 hardware, remove this flag or specify `x86_64`
`Project`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Storage_class_name`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. Refresh 2 or later If you are using the 3.5.2 version of the `cpd-cli`, remove the `--storageclass` flag from your command. The `cpd-cli upgrade` command uses the storage class that was specified during installation.
`Registry_location`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Registry_from_cluster`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.

Rerun the previous command without the --dry-run flag to upgrade the service.

Upgrading on air-gapped clusters

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```

Run the following command to see a preview of what will change when you upgrade the service.

Important: If you are using the internal Red Hat OpenShift registry:

Do not specify the --ask-pull-registry-credentials parameter.
If you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.

./cpd-cli upgrade \
--assembly streams-flows \
--arch Cluster_architecture \
--namespace Project \
--storageclass Storage_class_name \
--cluster-pull-prefix Registry_from_cluster \
--ask-pull-registry-credentials \
--load-from Image_directory_location \
--latest-dependency \
--dry-run

Note: If the assembly was downloaded using the delta-images command, remove the --latest-dependency flag from the command. If you don't remove the --latest-dependency flag you will get an error indicating that the flag cannot be used.

Replace the following values:

Variable	Replace with
`Cluster_architecture`	Specify the architecture of your cluster hardware: For x86-64 hardware, remove this flag or specify `x86_64`
`Project`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Storage_class_name`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. Refresh 2 or later If you are using the 3.5.2 version of the `cpd-cli`, remove the `--storageclass` flag from your command. The `cpd-cli upgrade` command uses the storage class that was specified during installation.
`Registry_from_cluster`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Image_directory_location`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.

Rerun the previous command without the --dry-run flag to upgrade the service.

Verifying that the upgrade completed successfully

From your installation node:

Run the following command:
```
./cpd-cli status \
--assembly streams-flows \
--namespace Project
```
Replace Project with the value you used in the preceding commands.
- If the upgrade completed successfully, the status of the assembly and the modules in the assembly is Ready.
- If the upgrade failed, contact IBM Support for assistance.

Checking for available patches

Determine whether there are any patches available the version of Streams Flows that you installed:

Clusters connected to the internet

Run the following command to check for patches:

./cpd-cli status \
--repo ./repo.yaml \
--namespace Project \ 
--assembly streams-flows \
--patches \
--available-updates

Air-gapped clusters

See the list of Available patches for Streams Flows.

If you need to apply patches to the service, follow the guidance in Applying patches.

Upgrading existing service instances

After you upgrade Streams Flows, the service instances that are associated with the installation must also be upgraded. This task must be completed by a Cloud Pak for Data administrator or a service instance administrator.

To upgrade service instances, you must have a cpd-cli profile on your local machine. Ensure that your profile points to the instance of Cloud Pak for Data where the service instances exist. Your profile enables Cloud Pak for Data to ensure that you have the appropriate permissions to upgrade the service instances. For details, see Creating a cpd-cli profile.

Tip: For a list of all available options, enter the following command:

./cpd-cli service-instance upgrade --help

From your installation node:

Run the following command to see the list of service instances:
```
./cpd-cli service-instance list \
--profile Profile_name
```
Replace Profile_name with the name of your local profile.

The command returns a list of all of the service instances that you have access to.
Run the following command to upgrade all of the service instances:
```
./cpd-cli service-instance upgrade \
--service-type service-type \
--profile Profile_name \
--watch \
--all
```
Replace Profile_name with the name of your local profile.
Verify that the service instances were updated and are ready to use:
1. Run the following command to see a list of the service instances:
```
./cpd-cli service-instance list \
--service-type service-type \
--profile Profile_name
```
  Replace Profile_name with the name of your local profile.
  
  The command returns a list of all of the service-type service instances that you have access to.
2. Run the following command for each service instance to verify that the instance is ready to use:
```
./cpd-cli service-instance status Instance_name\
--profile Profile_name
```
  Replace the following values:
  
  Variable Replace with
  
  Instance_name The name of the service instance for which you want to see the status.
  
  Profile_name The name of your local profile.
  
  Confirm that the service status is Running.

Variable	Replace with
`Instance_name`	The name of the service instance for which you want to see the status.
`Profile_name`	The name of your local profile.

What to do next

The service is ready to use. For more information, see Streams Flows overview.