PingOne

Upgrading an Authorize gateway instance

Take advantage of new policy features and enhancements by upgrading your gateway instance.

Deployment of policy versions to gateway instances could fail if the policy version includes features that aren’t compatible with or supported by the current gateway instance version. When an attempt is made to deploy a policy version not supported by the gateway instance, the Docker container console for that instance logs a message such as:

Supported config versions are [1.0…1.0] but deployment of 2.0 was attempted

Upgrading a gateway instance ensures policy version compatibility and minimizes downtime by updating components such as the application code, image, configuration, and associated services.

Learn more about best practices for publishing policy versions in Policies published to Authorize gateways.

To ensure a successful upgrade process, do the following:

  • Test the upgrade in a staging or pre-production environment.

  • Back up data and configurations before starting the upgrade.

  • Use strategies like blue-green deployment or rolling updates to minimize downtime.

Use the Docker run command or Docker Compose to upgrade your gateway instance. ​

  • Docker run

  • Docker Compose

Use the Docker run command

Steps

  1. Stop the gateway instance container.

  2. To remove the old container and ensure the new gateway instance is deployed, run the docker rm <container-name> command.

  3. Modify the docker run command to include the new gateway instance version.

    For example, to upgrade the gateway instance to version 1.1, the command should look something like this (line breaks are included for readability and are not necessary in your command):

    docker run --init \
  -e PING_IDENTITY_ACCEPT_EULA=yes \
  -e gatewayCredential=<your-gateway-credential> \
  -p 8080:8080 pingidentity/pingone-authorize-gateway:1.1.0

    Use the same port mappings, volumes, and environment variables that were used in the original docker run command to ensure the new container behaves the same way.

  4. Run the command.

Use Docker Compose

Before you begin

Make sure you have installed Docker Compose.

Steps

  1. To stop the gateway instance container, run the docker compose down command.

  2. Update the image tag in the docker-compose.yml file to the desired version.

    For example, to upgrade the gateway instance to version 1.1.0, the docker-compose.yml file should look something like this:

    services:
  authorize-gateway:
    image: pingidentity/pingone-authorize-gateway:1.1.0
    init: true
    environment:
      PING_IDENTITY_ACCEPT_EULA: "yes"
      gatewayCredential: <your-gateway-credential>
    ports:
      - "8080:8080"

  3. To remove the old container and ensure the new gateway instance is deployed, run the docker compose rm command.

  4. To start the upgraded gateway instance, run the docker compose up command.

  5. To verify the upgraded gateway instance is running correctly, run the docker inspect <container-name> command and check the image version.

Next steps

Publish new policy versions to your gateway instance.