Copyright

Copyright © 2019 Balasys IT Ltd.. All rights reserved. This document is protected by copyright and is distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this document may be reproduced in any form by any means without prior written authorization of Balasys.

This documentation and the product it describes are considered protected by copyright according to the applicable laws.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)

Linux™ is a registered trademark of Linus Torvalds.

Windows™ 10 is registered trademarks of Microsoft Corporation.

The Balasys™ name and the Balasys™ logo are registered trademarks of Balasys IT Ltd.

The Zorp™ name and the Zorp™ logo are registered trademarks of Balasys IT Ltd.

The Proxedo™ name and the Proxedo™ logo are registered trademarks of Balasys IT Ltd.

AMD Ryzen™ and AMD EPYC™ are registered trademarks of Advanced Micro Devices, Inc.

Intel® Core™ and Intel® Xeon™ are trademarks of Intel Corporation or its subsidiaries in the U.S. and/or other countries.

All other product names mentioned herein are the trademarks of their respective owners.

DISCLAIMER

Balasys is not responsible for any third-party websites mentioned in this document. Balasys does not endorse and is not responsible or liable for any content, advertising, products, or other material on or available from such sites or resources. Balasys will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through any such sites or resources.

2022-10-12 .Copyright

1. Introduction

This guide describes the necessary steps and commands to upgrade PAS instance from version 4.0.1 to 4.1.0.

There are three main stages to describe the different phases and scenarios of the upgrade.

  1. Creating a backup for safety

  2. Upgrading PAS in Kubernetes

  3. Restoring the pre-upgrade state

2. Creating a backup for safety

Before starting the upgrade process, make sure there is a backup to which the current state of the actual PAS setup can be restored.

2.1. Bootstrap configuration

As the whole bootstrap configuration is provided at the time of installation, the directory, in which the installation was carried out, needs to be saved, so that the installation procedure can be repeated.

2.2. Creating a backup of the running configuration

  1. Log in to the Web UI as admin user and navigate to the Config Backup page from the top bar.

  2. On the Config Backup page select Running from the Export Config dropdown menu.

    Backup and restore services with Proxedo API Security configuration
    Figure 1. Backup and restore running or user configuration for Proxedo API Security

  3. To export the running configuration, press the Download button. This will save the running configuration to a file named running-config-backup.zip in the working directory.

For more details, see section Backup and restore running or user configuration for Proxedo API Security in Proxedo API Security in Kubernetes: Administration Guide.

3. Upgrading PAS in Kubernetes

This section describes how to upgrade PAS in a single node setup. In case any problem occurs during the upgrade and the version 4.0.1 needs to be restored, follow the instructions in section Restoring the pre-upgrade state.

The upgrade process needs to be carried out on a Linux machine.

3.1. Prerequisites

The following requirements need to be met before carrying out the upgrade process:

  • The management and storage components of version 4.0.1 are running and healthy.

  • The password for the administrator user of the management component is available.

  • The new Helm chart is downloaded: /tmp/proxedo-api-security-4.1.0.tgz.

  • The same resources are available that have been available at the time of the installation of the old version of PAS. For more details, see section Prerequisites for installing PAS in Proxedo API Security in Kubernetes: Administration Guide.

  • The user who carries out the upgrade, needs to be logged in to docker.balasys.hu via the docker login command line tool, and needs to have access to the PAS docker images.

3.2. Upgrade steps

During this process, the new version of PAS will replace the old version. The commands below will use proxedo-api-security for namespace.

If Windows Subsystem for Linux (WSL) is used, substitute host.docker.internal for localhost in the --frontend-baseurl flag.

  1. Set up port forward for the old frontend by running the following command. This will make the Web UI available on the localhost.

kubectl --namespace proxedo-api-security port-forward services/proxedo-api-security-frontend 8080:80

  1. Run the following command in a new shell. After the pre-upgrade process is run, a pas-config4.0.1.zip can be found in the working directory.

docker run --user $(id -u):$(id -g) --rm -it --network=host --volume $(pwd):/upgrade docker.balasys.hu/api-security/config-upgrader:4.1.0 --frontend-baseurl http://localhost:8080 pre-upgrade

  1. Run the following command in the same shell. It converts the old running configuration to be compatible with the new version. The new configuration is saved as pas-config-4.0.1.upgraded-to-4.1.0.zip.

docker run --user $(id -u):$(id -g) --rm -it --network=host --volume $(pwd):/upgrade docker.balasys.hu/api-security/config-upgrader:4.1.0 convert-config

  1. Stop the port forward process in the first shell by pressing CTRL + C.

  2. Install the new version of PAS by using the same input files as used for the old one. Follow the instructions in section Providing the necessary files for Helm installation in Proxedo API Security in Kubernetes: Administration Guide.

  3. Set up port forward now for the new frontend by running the following command. This will make the Web UI available on the localhost.

kubectl --namespace proxedo-api-security port-forward services/proxedo-api-security-frontend 8081:80

  1. Run the following command in a new shell, in the same directory where the pre-upgrade and configuration conversion steps were performed. Follow the instructions of the script to complete. A timeout value for the application of the new configuration needs to be specified in the timeout field. Select a value (number of seconds) that will probably be enough for the whole PAS deployment to be rolled out. It can depend on the number of core pod instances and the bandwith the cluster has to docker.balasys.hu.

docker run --user $(id -u):$(id -g) --rm -it --network=host --volume $(pwd):/upgrade docker.balasys.hu/api-security/config-upgrader:4.1.0 --frontend-baseurl http://localhost:8081 post-upgrade --config-apply-timeout <<timeout>>

  1. Close the port forwarding in the other shell by pressing CTRL + C.

4. Restoring the pre-upgrade state

In order to restore the state prior to the upgrade, complete the following stages:

  1. Complete a factory reset. In case a factory reset is necessary, the simplest solution is to delete the namespace, PAS is installed in. If that is not feasible, an alternative is to explicitly delete Kubernetes objects related to PAS. To do so, two main steps are required:

  1. Uninstall the PAS Helm chart using the helm uninstall proxedo-api-security command. This will remove all kubernetes objects managed by the Helm charts, including the Persistent Volume Claim associated with the storage components.

  2. Delete the core configuration objects. These objects are not managed by the Helm chart but by the management component. To complete this, run the following commands:

    • kubectl delete configmap proxedo-api-security-core-config

    • kubectl delete secrets proxedo-api-security-core-config proxedo-api-security-registry-credentials

Following these steps, PAS shall be installed from scratch. For more details, see section Installation of Proxedo API Security in Kubernetes environment in Proxedo API Security in Kubernetes: Administration Guide.

  1. Repeat the installation with the files backed up from the 4.0.1.

  1. Import the configuration with the help of the Web UI, see steps in section Restoring the running configuration.

4.1. Restoring the running configuration

  1. Log in to the Web UI as the administrator user and navigate to the Config Backup page from the top bar.

  2. To import the running configuration, on the Config Backup page choose a configuration file from the computer and press Upload to upload the configuration.

    Backup and restore services with Proxedo API Security configuration
    Figure 2. Backup and restore running or user configuration for Proxedo API Security

  3. Apply the configuration.