Environment

• Yugabyte Platform - 2.2 or higher

Issue

Yugabyte Support has provided you a patched version of the Yugabyte database that you need to deploy. 

• IMPORTANT: This is NOT an attempt to upgrade the platform. Only the database software will be upgraded using this process - Yugabyte Platform will be unmodified.

Resolution

Overview

This procedure will guide you through uploading the new database version to your Yugabyte Platform so that it is available to the Platform to be applied to your universes, new or existing.

Steps

NOTE: For this document, we have assumed that Yugabyte Platform is installed in '/opt/yugabyte'. If this is not the case, please see Appendix A for instructions on how to find the releases directory appropriate to your installation and replace '/opt/yugabyte/releases' in any steps with the directory for your installation.

The following steps must be run with sudo if you are not logged in as the root user.

1. Create a directory, on the Yugabyte Platform host, where you can safely download the patch or yugabundle. 

# mkdir /tmp/downloads

2. With the URL provided to you from Yugabyte Support, download the patch or bundle into the newly created directory.

$ cd /tmp/downloads
$ wget https://downloads.yugabyte.com/yugabyte-2.2.5.0-linux.tar.gz

-  OR -

$ cd /tmp/downloads
$ wget https://downloads.yugabyte.com/yugabundle-2.2.5.0-b25.tar.gz

3. Once the file is available on the Yugabyte Platform host, a directory for the patched software will need to be created.

NOTE: It is important that it conforms to the following naming convention:

/opt/yugabyte/releases/{$version-$build}/yugabyte-{$version-$build}-centos-x86_64.tar.gz

For the Yugabyte package:

# cd /opt/yugabyte/releases
# mkdir 2.2.5.0-b25

For the Yugabundle extract the contents of the Yugabundle so that we have the

# tar xvf yugabundle-2.2.5.0-b25.tar.gz
# ls yugabyte-2.2.5.0-b25/
-rw-r--r-- 1 devops-2.2.5.0-b25-centos-x86_64.tar.gz
-rw-r--r-- 1 yugabyte-2.2.5.0-b25-centos-x86_64.tar.gz
-rw-r--r-- 1 yugaware-2.2.5.0-b25-centos-x86_64.tar.gz
# cd /opt/yugabyte/releases
# mkdir 2.2.5.0-b25

4. Copy, or move the downloaded patch into the {$version-$build} directory.

For the Yugabyte package, you will need to rename with the correct suffix: 

 # mv /tmp/downloads/yugabyte-2.2.5.0-linux.tar.gz ./2.2.5.0-b1/yugabyte-2.2.5.0-b1-centos-x86_64.tar.gz

For theYugabundle package, you can mv the package to the correct location, as the name includes the correct suffix:

 # mv /tmp/downloads/yugabyte-2.2.5.0-b25/yugabyte-2.2.5.0-b25-centos-x86_64.tar.gz ./2.2.5.0-b1/.

5. With the patch in the correct location, log into the Yugabyte Admin Console (Yugaware) and navigate to the releases page.

NOTE: This will be located in the top right corner, under the drop down options under your user icon 

6. Once on the releases page, select the refresh button in the top right of the screen and Yugabyte Platform will automatically detect the patch. 

At this point you should now see your release listed in the UI. 

7. Now, you can upgrade the universe software version by going to the appropriate universe, then selecting More -> Upgrade Software

You can select the appropriate server version in the dropdown.

Appendix A

How to find the host path that contains the releases directory:

The 'docker inspect' command will show the host path as can be seen in the following snippet:

sudo docker inspect yugaware | jq '.[0].Mounts[] | select(.Destination == "/opt/yugabyte/releases") | {Host: .Source, Container: .Destination}'
{
  "Host": "/app/yugaware-platform/releases",
  "Container": "/opt/yugabyte/releases"
}

The command above requires that the platform host have jq installed. The new Yugabyte database package needs to be placed in an appropriately named subdirectory inside the “Host” path above.

If jq is unavailable, the following command uses only basic system tools:
sudo docker inspect yugaware | grep "Source\|Destination" | grep -B1 "Destination.*releases" "Source": "/app/yugaware-platform/releases", "Destination": "/opt/yugabyte/releases"

For Customers using K8's 

Steps:

1. Locate the S3bucket for the release to obtain the db release package and helm charts file from it

EXAMPLE:

Release package : s3://releases.yugabyte.com/2.13.2.0-b135/yugabyte-2.13.2.0-b135-centos-x86_64.tar.gz  
Helm chart : s3://releases.yugabyte.com/2.13.2.0-b135/helm/yugabyte-2.13.2.tgz.

2. Make sure there is a docker image for the required release.

1. For an alpha or production build, there should be a docker image in the regular repo: https://quay.io/repository/yugabyte/yugabyte?tab=tags
2. For a nightly release, the docker image is published to a different repo: https://quay.io/repository/yugabyte/yugabyte-itest?tab=tags
           NOTE: We do not recommend use of any unstable releases in critical environments. If you intend to use unstable releases you will need to create a new Kubernetes provider  with a new registry. [Configure the Kubernetes cloud provider | YugabyteDB Docs ]
           quay.io/yugabyte/yugabyte-itest 
   
   1. When mirroring Yugabyte docker images to an internal artifactory, you will need to copy this image to that artifactory.

3. From the Platform (Yugaware) pod, run the below command to create a directory for the release (assuming an env var IMAGE_TAG similar to below)

IMAGE_TAG=2.13.2.0-b135

kubectl exec -n <namespace of yugaware pod> -c yugaware <yugaware pod name> -- bash -c "mkdir /opt/yugabyte/releases/$IMAGE_TAG:

EXAMPLE:

# example: export 

kubectl exec -n yb-platform -c yugaware yb-yugaware-0 -- bash -c "mkdir /opt/yugabyte/releases/2.13.2.0-b135;”

4. Copy the db release package AND the helm chart from the S3bucket to the new directory inside the pod

kubectl cp -n <yugaware namespace> -c yugaware <db-release-package.tar.gz> <yugaware pod name>:/opt/yugabyte/releases/$IMAGE_TAG/yugabyte-$IMAGE_TAG-centos-x86_64.tar.gz


kubectl cp -n <yugaware namespace> -c yugaware <helm-package-path.tgz> <yugaware pod name>:/opt/yugabyte/releases/$IMAGE_TAG/yugabyte-$IMAGE_TAG-helm.tar.gz

For example,

kubectl cp -n yb-platform -c yugaware  yugabyte-2.14.0.0-b32-centos-x86_64.tar.gz yb-yugaware-0:/opt/yugabyte/releases/2.14.0.0-b32/yugabyte-2.14.0.0-b32-centos-x86_64.tar.gz

kubectl cp -n yb-platform -c yugaware yugabyte-2.14.0.tgz yb-yugaware-0:/opt/yugabyte/releases/2.14.0.0-b32/yugabyte-2.14.0.0-b32-helm.tar.gz

5.  Browse to the release page http://<platform_url>/releases and hit Refresh Releases. Also, refresh the browser window. Make sure you see an entry with both the release package(FILE PATH) and CHART PATH.