Use Cases

Best Practices: Planning your upgrade

Upgrading your software is essential to maintaining a secure environment that responds to your business needs. This planning guide is intended to supplement your internal upgrade protocols.

If you have questions about your upgrade, post them to our Support Community for expert answers from other Ping users. Tag your questions with the "Upgrade" topic. If you’re new to the community, check out Getting Started with Ping Community.

If you have an urgent upgrade request, please open a support ticket in the Support portal.

If this is your first time upgrading Ping products, or if your environment has grown in complexity, we recommend connecting with your account team to ensure you have the right resources in place. Ping Identity and our partners are available to consult on upgrades or even perform them for you as part of a Professional Services engagement.

Ping Identity products are designed using open standards and can be upgraded in any order. However, we recommend that you upgrade one product at a time. Use the following templates to create a separate upgrade plan for each Ping product you use.

Upgrade planning guide

Use the following checklist to assess the scope of the upgrade process before beginning.

Before you begin

Note the product name, current version, and upgrade version for each product that you’re upgrading.

Product name Current version Upgrade version

 
 
 
 

Steps

  1. Validate upgrade scope requirements:

    Pre-upgrade task Assignees Completion Date

    Identify the number of deployed environments.

     
     
     
     

    Identify the number of nodes (admin plus runtime) per deployed environment.

     
     
     
     

    Read the upgrade guide and release notes for your target upgrade version.

    If you skip versions (for example, if you’re upgrading from version 2.0 to version 5.0) we recommend reviewing the upgrade guides, release notes, and system requirements for versions 3.0 and 4.0, as well as version 5.0, to ensure that your upgrades go smoothly.

     
     
     
     

    Review the differences between current and target versions. Note any incompatibilities or dependencies.

     
     
     
     

    Read the tuning guides for your target upgrade version to ensure that you’re aware of significant changes and new tuning recommendations, especially when Java versions have been upgraded.

     
     
     
     

    Review the new JDK defaults and make and relevant changes.

     
     
     
     

    Collect and review the deployment requirements, use cases, and architecture and design documents.

     
     
     
     

    Accept the changes and features from the release notes.

     
     
     
     

    Obtain a new license key for upgraded version.

     
     
     
     

  2. Identify external services that might be affected by the upgrade:

    External Service Type External Service Name

    Directories

     
     
     
     

    Databases

     
     
     
     

    Application integrations

     
     
     
     

     
     
     
     

     
     
     
     

     
     
     
     

     
     
     
     

  3. Assess upgrade readiness.

    Do you have the team and tools to complete this upgrade successfully? If not, please reach out to your Ping Account Team to discuss resources.

Upgrade process

This upgrade process is recommended for all Ping products.

Steps

  1. Identify the key contacts:

    Ping primary contacts Contact phone or email

    Account executive

     
     
     
     

    Ping Technical Support

    • North America: 1-855-355-PING (7464)

    • EMEA: 44 0 808 196 0788

    • APJ: 61 1800 370 672

    Other

     
     
     
     
    Internal primary contacts

    Project manager

     
     
     
     

    Technical team

     
     
     
     

    Technical team

     
     
     
     

    Additional stakeholders

     
     
     
     

  2. Review the release notes for the upgrade version:

    Pre-upgrade task Completion date Assignee

    Review release notes for upgrade.

    If you skip versions (for example, if you’re upgrading from version 2.0 to version 5.0) we recommend reviewing the upgrade guides, release notes, and system requirements for versions 3.0 and 4.0, as well as version 5.0, to ensure that your upgrade goes smoothly.

     
     
     
     

    Perform any pre-upgrade tasks.

     
     
     
     

    Define your rollback plan.

     
     
     
     

    Review the post-upgrade requirements and note any applicable tasks.

     
     
     
     

  3. Perform a trial upgrade:

    Trial upgrade task Completion date Assignee

    Schedule a trial upgrade on a duplicate image or staging environment..

    If your staging upgrade environment differs significantly from your production upgrade environment, making a copy of the production environment (for PingFederate and PingAccess, at a minimum, the admin server and one runtime server) can help you find any anomalies that you need to address prior to a full production upgrade.

     
     
     
     

    Review the upgrade log. Note the anomalies, differences, and results.

     
     
     
     

    Review your custom templates, compare them to the original versions, and determine if these customizations need to be carried over to the templates in the new version. This review is especially important if adapter templates were added or updated.

     
     
     
     

    Migrate your custom .jar files.

     
     
     
     

    Migrate your HTML templates.

     
     
     
     

    Migrate your velocity templates.

     
     
     
     

    Verify upgrade reliability according to your company standards.

     
     
     
     

    Create the timeline and tasks for your production upgrade.

     
     
     
     

  4. Perform your production platform upgrade:

    Production upgrade task Completion date Assignee

    Create the upgrade task list for your production environment.

     
     
     
     

    Schedule your upgrade to minimize downtime.

     
     
     
     

    Notify Ping support of scheduled upgrade.

    Create a case in the Support Portal with the type = "Upgrade" and include important details such as the date and time of your move, which products you are upgrading, the old and new version, and helpful architectural details.

     
     
     
     

General upgrade best practices

These tips will help you avoid common pitfalls, no matter which Ping product you are upgrading.

  1. If you are migrating to a new server platform/operating system, copy the engines and consoles from the original servers to the new ones.

  2. If your new environment needs unlimited Java Cryptography Extension (JCE):

    • Install the new Java and unlimited JCE on the new servers.

    • Upgrade the old console installations on the new servers.

    • Upgrade the old engines on the new servers.

    • Update the run.properties file to reflect new IP addresses on the new servers.

  3. Configure load balancers for the new clusters:

    • Validate that the new configuration is working by updating a few host files on desktops using the new load balancer address.

      Reference adapters and OAuth aren’t very testable in any scenario other than on the cutover platform.

    • Switch DNS to the new clusters after you’ve successfully unit tested the configurations.

Product-specific upgrade guides

These links go to the upgrade pages and release notes for each Ping Identity product. These pages are updated with each product release.

PingFederate

PingAccess

PingDirectory suite of products

PingAuthorize

PingCentral