Upgrading PingCentral ¶

Example Only

This example is for demonstration purposes only. It is not intended to reflect the complexities of a full production environment and will need to be adapted accordingly.

Video walkthrough

A video demonstration of this process can be found here.

Caveats ¶

Kubernetes and Helm ¶

This document will focus on deployments in a Kubernetes environment using the ping-devops Helm chart. However, the concepts should apply to any containerized PingCentral deployment.

This document will become outdated ¶

The examples referenced in this document point to a specific tag. This tag may not exist at the time of reading. To correct the issue, update the tag on your files appropriately. This example uses versions 1.10 and 1.14, but the process should be similar for other versions in the future.

MySQL is used as the PingCentral Datastore ¶

A separate MySql container is deployed manually to provide a backing store for PingCentral. In a production environment, you would likely use a managed database service.

H2 Internal Database

If you are not using an external database, and are on a version <= 1.10, you will need to be aware of possible issues with the move to the H2v2 database internally. See the PingCentral documentation for more details. It should be noted that the internal H2 database is not supported for production environments.

The Ping-provided baseline Profile is used as a starting point for PingCentral ¶

The default baseline profile is used for this guide. In a production environment, you would likely use a custom repository and profile.

Overall Process ¶

Steps:

Deploy the old (1.10) version of PingCentral with the baseline server profile
Create a test user in PingCentral and perform other validation steps
Copy the pingcentral.jwk file to your server profile
Deploy the new (1.14) PingCentral version with a custom server profile
Validate the upgrade

Prerequisites ¶

Assumptions and requirements:

You have set up your DevOps environment and can run a test deployment of the products. For more information, see Get Started.
This example was written using Docker Desktop with Kubernetes enabled on the Mac platform. The version used was 4.27.1 (136059), which includes Docker Engine v25.0.2 and Kubernetes v1.29.1. The ingress-nginx controller version was 1.9.6, deployed from Helm chart version 4.9.1.

Environment Preparation ¶

Clone the `getting-started` repository ¶

Clone the pingidentity-devops-getting-started repository to your local ${PING_IDENTITY_DEVOPS_HOME} directory.

pingctl utility

The ${PING_IDENTITY_DEVOPS_HOME} environment variable was set by running pingctl config.
```
cd "${PING_IDENTITY_DEVOPS_HOME}"
git clone \
  https://github.com/pingidentity/pingidentity-devops-getting-started.git
```

Prepare the environment with a namespace and ingress controller ¶

Create a namespace for running the stack in your Kubernetes cluster.

# Create the namespace
kubectl create ns pingcentral-upgrade
# Set the kubectl context to the namespace
kubectl config set-context --current --namespace=pingcentral-upgrade
# Confirm
kubectl config view --minify | grep namespace:

Deploy the ingress controller to Docker Desktop:

helm upgrade --install ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx --create-namespace

Wait for the Nginx ingress to reach a healthy state by running the following command. You can also observe the pod status using k9s or by running kubectl get pods --namespace ingress-nginx. You should see one controller pod running when the ingress controller is ready. This command should exit after no more than 60 seconds or so, depending on the speed of your computer:
```
kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=90s
```
Create a secret in the namespace you will be using to run the example (upgrade) using the pingctl utility. This secret will obtain an evaluation license based on your Ping DevOps username and key:
```
pingctl k8s generate devops-secret | kubectl apply -f -
```
This example will use the Helm release name demo and DNS domain suffix *pingdemo.example for accessing applications. Add the expected hostname to /etc/hosts:
```
echo '127.0.0.1 demo-pingcentral.pingdemo.example' | sudo tee -a /etc/hosts > /dev/null
```
Navigate to your local directory where you cloned the repository ("${PING_IDENTITY_DEVOPS_HOME}"/pingidentity-devops-getting-started/30-helm/) directory and run the command shown here to deploy the MySQL pod using kubectl. This deployment will be used as the backing store for PingCentral.
```
kubectl apply -f pingcentral-external-mysql-db/mysql.yaml
```

Fork or clone the Ping server profile repository ¶

Fork the pingidentity-server-profiles repository to your GitHub account. If you do not have a GitHub account, you can clone the repository instead. For this guide, the repository will be forked to test-server-profiles which will be pulled locally to ${HOME}/projects/test-server-profiles.
```
cd "${HOME}/projects"
git clone <account>/test-server-profiles.git ${HOME}/projects/
```

Deploy the old version of PingCentral with the Ping baseline server profile ¶

Install the initial version by running the command shown here. In this example, the release demo forms the prefix for all objects created. The ingress is configured to use the ping-local domain:
```
cd "${PING_IDENTITY_DEVOPS_HOME}"/pingidentity-devops-getting-started/30-helm/
helm upgrade --install demo pingidentity/ping-devops -f pingcentral-upgrade/01-original.yaml
```

This command will take a few minutes to complete. You can monitor the progress using kubectl get pods or k9s.

Access the PingCentral Console ¶

Login to the PingCentral Administrative Console using the credentials administrator/2Federate. The URL is https://demo-pingcentral.pingdemo.example.
Select Users from the left navigation menu and click Add User. Create a user to be used to validate PingCentral after the upgrade (the user specifics and role do not matter for this example).

The left navigation panel should indicate version 1.10.0 at the bottom as shown here: PingCentral 1.10 Navigation Menu

Confirm Database Entries ¶

Shell into the MySQL pod and confirm that the user you created is present in the database. Also, verify the version of PingCentral in the DATABASECHANGELOG table.

kubectl exec -it mysql-0 -- bash
# Use the password from the mysql.yaml file (2Federate)
mysql -u root -p
use pingcentral;
# The user will be listed here
select * from users;
# The version will be listed here, with the last lines of the table showing the most recent entries 
# at version v1.10 and v1.11 (46 lines total at the time of this writing)
select * from DATABASECHANGELOG;

Add the `pingcentral.jwk` file to your server profile ¶

Copy the pingcentral.jwk file from the PingCentral pod. This file will be used in the next step to configure the new PingCentral instance. This example places the file in the repository directory from the fork created earlier.
```
kubectl cp demo-pingcentral-6d4bb97c98-m7vwb:/opt/out/instance/conf/pingcentral.jwk ${HOME}/projects/test-server-profiles/baseline/pingcentral/external-mysql-db/instance/conf/pingcentral.jwk
```
Check to see that the pingcentral.jwk file has been updated in your server-profile and push these changes to your repository.
```
cd "${HOME}/projects/test-server-profiles"
git add .
git commit -m "Added pingcentral.jwk file"
git push
```

Pod Name

The pod name from which you copy will vary.

JWK Unique to PingCentral Instance

The pingcentral.jwk file is used to encrypt and decrypt the PingCentral configuration. It is unique to each PingCentral instance and must be copied to the new server profile. Otherwise, the new pod will fail to start.

Security Warning

Storing the pingcentral.jwk file in the server profile is not recommended for production environments. In a production environment, you would likely use a managed key store service, vault, or other encrypted mechanism.

Deploy the new version of PingCentral with a custom server profile ¶

Update the /pingidentity-devops-getting-started/30-helm/pingcentral-upgrade/02-upgraded.yaml file to point to the repository and profile directory that contains the JWK file. This example uses the test-server-profiles repository, but you should use your own information.

helm upgrade --install demo pingidentity/ping-devops -f pingcentral-upgrade/02-upgraded.yaml

The new pod will spin up, and when it is healthy, the old pod will be terminated. At this time, you should have an upgraded PingCentral instance. Log in to the administrative console as before. The user you created earlier should still exist, and the version information at the lower left should indicate version 1.14.0. In addition, a new left navigation item (Management) will be present that was not there before:

PingCentral 1.14 Navigation Menu

Finally, a check of the DATABASECHANGELOG table in the MySQL pod should show the new version of PingCentral as the last few entries in that table (51 entries as of this writing). These updated entries indicate the database migration was successful.

Not all versions have database migrations

The 1.10 -> 1.14 upgrade involved database updates. Not all versions will have database updates, and corresponding DATABASECHANGELOG entries might not be present.

Cleanup ¶

After you have finished this demonstration, you can uninstall the Helm release and MySQL deployment, and delete the namespace:

helm uninstall demo
kubectl delete -f pingcentral-external-mysql-db/mysql.yaml
kubectl delete ns pingcentral-upgrade

Remove the entry from /etc/hosts if you do not plan to use the same hostname again:

sudo sed -i '' '/demo-pingcentral.pingdemo.example/d' /etc/hosts

You can also remove the test-server-profiles repository from your local machine and delete the forked repository from GitHub:

rm -rf "${HOME}/projects/test-server-profiles"