--- title: Upgrading PingCentral description: The pingctl utility referenced here has been deprecated and is no longer being maintained. It is recommended to use the Ping CLI utility under active development and support. component: devops page_id: devops::how-to/upgradePingCentral canonical_url: https://developer.pingidentity.com/devops/how-to/upgradePingCentral.html section_ids: devops-caveats: Caveats devops-kubernetes-and-helm: Kubernetes and Helm devops-this-document-will-become-outdated: This document will become outdated devops-mysql-is-used-as-the-pingcentral-datastore: MySQL is used as the PingCentral Datastore devops-the-ping-provided-baseline-profile-is-used-as-a-starting-point-for-pingcentral: The Ping-provided baseline Profile is used as a starting point for PingCentral devops-overall-process: Overall Process devops-prerequisites: Prerequisites devops-environment-preparation: Environment Preparation devops-clone-the-repository: Clone the getting-started repository devops-prepare-the-environment-with-a-namespace-and-ingress-controller: Prepare the environment with a namespace and ingress controller devops-fork-or-clone-the-ping-server-profile-repository: Fork or clone the Ping server profile repository devops-deploy-the-old-version-of-pingcentral-with-the-ping-baseline-server-profile: Deploy the old version of PingCentral with the Ping baseline server profile devops-access-the-pingcentral-console: Access the PingCentral Console devops-confirm-database-entries: Confirm Database Entries devops-add-the-file-to-your-server-profile: Add the pingcentral.jwk file to your server profile devops-deploy-the-new-version-of-pingcentral-with-a-custom-server-profile: Deploy the new version of PingCentral with a custom server profile devops-cleanup: Cleanup --- # Upgrading PingCentral | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The `pingctl` utility referenced here has been deprecated and is no longer being maintained. It is recommended to use the [Ping CLI](https://developer.pingidentity.com/pingcli/pingcli_landing_page.html) utility under active development and support.With few exceptions, many `pingctl` commands can be replicated using the `pingcli` utility, with gaps being addressed based on prioritization. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This example is for demonstration purposes only. It's not intended to reflect the complexities of a full production environment and will need to be adapted accordingly. | | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | A video demonstration of this process can be found [here](https://videos.pingidentity.com/detail/videos/devops/video/6343093748112/pingcentral-upgrade-demonstration). | ## 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. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](https://docs.pingidentity.com/pingcentral/latest/pingcentral_for_iam_administrators/pingcentral_installing_configuring/pingcentral_upgrading/pingcentral_upgrading_pc.html) 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: 1. Deploy the old (1.10) version of PingCentral with the baseline server profile 2. Create a test user in PingCentral and perform other validation steps 3. Copy the `pingcentral.jwk` file to your server profile 4. Deploy the new (1.14) PingCentral version with a custom server profile 5. 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](../get-started/introduction.html). * 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 1. Clone the `pingidentity-devops-getting-started` repository to your local `${PING_IDENTITY_DEVOPS_HOME}` directory. | | | | - | -------------------------------------------------------------------------------------------- | | | The `${PING_IDENTITY_DEVOPS_HOME}` environment variable was set by running `pingctl config`. | ```shell 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 1. Create a namespace for running the stack in your Kubernetes cluster. ```shell # 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: ``` 2. Deploy the ingress controller to Docker Desktop: ```shell helm upgrade --install ingress-nginx ingress-nginx \ --repo https://kubernetes.github.io/ingress-nginx \ --namespace ingress-nginx --create-namespace ``` 3. 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: ```shell kubectl wait --namespace ingress-nginx \ --for=condition=ready pod \ --selector=app.kubernetes.io/component=controller \ --timeout=90s ``` 4. 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: ```shell kubectl create secret generic devops-secret \ --from-literal=PING_IDENTITY_DEVOPS_USER="$PING_IDENTITY_DEVOPS_USER" \ --from-literal=PING_IDENTITY_DEVOPS_KEY="$PING_IDENTITY_DEVOPS_KEY" \ --from-literal=PING_IDENTITY_ACCEPT_EULA="$PING_IDENTITY_ACCEPT_EULA" \ --type=Opaque \ --dry-run=client -o yaml | kubectl apply -f - ``` 5. 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`: ```shell echo '127.0.0.1 demo-pingcentral.pingdemo.example' | sudo tee -a /etc/hosts > /dev/null ``` 6. 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. ```shell kubectl apply -f pingcentral-external-mysql-db/mysql.yaml ``` #### Fork or clone the Ping server profile repository 1. Fork the [pingidentity-server-profiles](https://github.com/pingidentity/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`. ```shell cd "${HOME}/projects" git clone /test-server-profiles.git ${HOME}/projects/ ``` ### Deploy the old version of PingCentral with the Ping baseline server profile 1. 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: ```shell 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 1. Login to the PingCentral Administrative Console using the credentials `administrator/2Federate`. The URL is . 2. 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](../_images/pingcentral110.png) #### 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. ```shell 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 1. 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. ```shell 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 ``` 2. Check to see that the `pingcentral.jwk` file has been placed in your server-profile and push these changes to your repository. ```shell cd "${HOME}/projects/test-server-profiles" git add . git commit -m "Added pingcentral.jwk file" git push ``` | | | | - | ------------------------------------------- | | | The pod name from which you copy will vary. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The `pingcentral.jwk` file encrypts and decrypts the PingCentral configuration. It's unique to each PingCentral instance and you must copy it to the new server profile; otherwise, the new pod won't start. | | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | If you get a `tar: removing leading '/' from member names` notification when copying the file, you can ignore it. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Storing the `pingcentral.jwk` file in the server profile *is not recommended* for production environments. In a production environment, you'd likely use a managed key store service, vault, or other encrypted mechanism. | ### Deploy the new version of PingCentral with a custom server profile 1. 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. ```shell 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](../_images/pingcentral114.png) 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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: ```shell 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: ```shell 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: ```shell rm -rf "${HOME}/projects/test-server-profiles" ```