PingOne

Upgrading an Authorize gateway instance

Upgrade your gateway instances to take advantage of new policy features and enhancements.

Authorization policy versions sometimes include features that are incompatible with or unsupported by the current gateway instance version.

Learn more about best practices for building policies that you plan to publish to Authorize gateways in Policies published to Authorize gateways.

If deployment of an unsupported authorization policy version fails, the gateway instance’s Docker container console logs a message such as:

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

Upgrading a gateway instance ensures authorization policy version compatibility and minimizes downtime by updating components such as the application code, image, configuration, and associated services. You can find gateway instance version images on Docker Hub.

To ensure a successful upgrade:

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

  • Back up data and configurations before you start 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.0, 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’ve 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 new 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 authorization policy versions to your gateway instance.