Environment

• YugabyteDB Anywhere - 2.2 or higher

Issue

Yugabyte Support has provided you a patched version of the Yugabyte database that you need to deploy, or you need to provide an older version of software on your YugabyteDB Anywhere (YBA) node.

• IMPORTANT: This is NOT an attempt to upgrade the YuggabyteDB Anywhere node. Only the database software made available by YBA will be upgraded using this process - YugabyteDB Anywhere will be unmodified.

Resolution

Overview

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

Steps

NOTE: For this document, we have assumed that Yugabyte Anywhere 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 YugabyteDB Anywhere 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

- OR - 

Consult the downloads page for official releases.

3.  Obtain a copy of the latest helm chart file for the given release by running the following commands from a host with helm installed.

helm repo add yugabytedb https://charts.yugabyte.com
helm repo update
helm pull yugabytedb/yugabyte --version 2.2.5 --destination .

The resulting file will download to the present working directory in the format similar to:

yugabyte-2.2.5.tgz

4. Once the file is available on the YugabyteDB Anywhere host, a directory for the patched software will need to be created.  If the files were not directly downloaded to the Yugabyte Anywhere Host, 

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

And the helm chart file conforms to the following naming convention:

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

For the YugabyteDB 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

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

For the Yugabyte package, and helm chart file, 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
# mv /tmp/downloads/yugabyte-2.2.5.tgz ./2.2.5.0-b1/yugabyte-2.2.5.0-b1-helm.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/.

NOTE: Prior to 2.16 YBAnywhere release , we shipped the master_flags.xml and tserver_flags.xml files with YBA. Any YBA release after 2.16, the XML files are shipped as part of the DB Binaries and not as part of YBA. Please ensure the tar package's owner is yugabyte not centos/ec2-user, so that YBA can extract the xml files and place them in the required directories as needed.

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 YugabyteDB Anywhere will automatically detect the patch. 

At this point you should now see your release and corresponding helm chart file 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 K8s Deployments

Steps:

1. Using the download methods from previous section, obtain the YugabyteDB release and corresponding helm chart file.

-OR-

If provided with an S3 bucket, locate the bucket 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 YugabyteDB Anywhere (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://<yugabytedb_anywhere_hostname>/releases and click "Refresh Releases." Also, refresh the browser window. Make sure you see an entry with both the release package(FILE PATH) and CHART PATH.