Update

The sections below will help you update Axiomatics Policy DevOps (APD).

Version check

Run the following command to check the currently installed APD version:

Windows

gradlew -q dependencies --configuration testCompileClasspath | findstr "com.axiomatics"

Linux

./gradlew -q dependencies --configuration testCompileClasspath | grep "com.axiomatics"

This command will also return the versions of the Attribute Connectors currently in use.

Preparation

Before proceeding, ensure there are no uncommitted changes. You must either commit or discard them. For backup purposes, push your local changes to your remote repository. If you are not using APD in conjunction with a Git repository, you can skip this step and proceed directly to the Manual update section.

Important

If you have customized APD by modifying or creating files inside the buildSrc/ directory, you must transfer these changes or customizations to build.gradle or to a file outside the buildSrc/ directory before continuing. Refer to the Project structure section for assistance, or contact Axiomatics support for further help.

Update procedure

There are two ways of updating APD. Manual update by copying files and the Git way. Choose which one is suitable for you.

Terminology

• New clone: A clone of the latest APD in a new directory.

• Your APD repository: Your APD repository that is being upgraded.

Manual

1. Download the latest version of APD from GitHub into a new folder.

   This directory becomes the new clone.

2. Delete the buildSrc/ folder in your APD repository.

3. Copy the buildSrc/ folder from the new clone into your APD repository.

Git

If you are familiar with Git and comfortable resolving potential conflicts, merge the latest origin/main into your current branch using one of the following commands:

git pull

or

git fetch origin && git merge origin/main

If you encounter conflicts, use the table below as a guide for resolution:

File or directory	Instructions
buildSrc/	Keep the origin's version.
/settings.gradle	Keep your rootProject.name line, but otherwise keep the origin's version.
/deployment.yaml	Keep your changes.
/build.gradle	Keep your changes.
Other	Keep your changes for any conflicts found in src/authorizationDomain, src/test, the Dockerfile, and related files or directories.

Version-specific steps

You must perform the following steps only if you are upgrading APD from version 1.0 to 1.1 after completing the update procedure above.

1. Changes in build.gradle:

   • within the plugins {...} configuration block, change the plugin ID to:

     id 'axiomatics-policy-devops'

   • within the alfa {...} configuration block, you can control Visual tracing, a feature introduced in version 1.1 that is enabled by default (read the Visual tracing section for details). Since this feature is used for debugging and policy visualization, it may be unnecessary on a CI build server. If you wish to disable it, set the following:

     withVisualTrace false

2. Only if you followed the manual update procedure:

   1. Delete the gradle/ folder in your APD repository.
   2. Copy the gradle/ folder from the new clone into your APD repository.
   3. Copy the gradlew and gradlew.bat files from the new clone into your APD repository.
   4. Open the settings.gradle file in the new clone and replace the default rootProject.name with the one in your APD repository.
   5. Copy the edited settings.gradle file from the new clone into your APD repository.
   6. Copy the README.md file from the new clone into your APD repository, or delete it and create your own instead.

Axiomatics Decision Service (ADS) version

APD 1.1 now uses ADS 2 as the default engine, which is a change from previous APD versions that utilized ADS 1.

APD is designed to support both ADS versions, but they cannot be run concurrently because the format of the shared deployment.yaml file is incompatible. ADS 1 uses Dropwizard configuration, while ADS 2 uses Spring Boot. You have the option to either remain on ADS 1 or prepare for the ADS 2 deployment and then switch to the ADS 2 specific tasks.

The table below provides an overview of the corresponding tasks for each version:

Task	Description	ADS 1	ADS 2
Run ADS	APD assembles the components in a temporary directory and starts the ADS service.	runAdsV1	runAds
Stage build context	APD assembles the components in a known location for use by your pipeline (to build an image, etc.).	dockerPrepare	installDeploymentDist
Build image	APD builds a Docker image for pushing to your registry.	buildAdsDockerImage	Stage the build context and use your own tool to build an image if needed.

For further details, read the Migrating from ADS 1.x to 2.x section of the ADS documentation. Pay attention to the following changes:

• how environment variables are defined using Spring notation within deployment.yaml and logback configuration
• the removal of /asm-pdp endpoint. Note that the /asm-pdp and /authorize endpoints are not compatible as they implement different versions of the JSON Profile of XACML 3.0 (versions 1.0 and 1.1, respectively)
• a new software license. Contact Axiomatics support if you haven't received your ADS 2 software license yet.

tip

APD includes sample policies, attribute connectors, and tests. Since the sample use case has changed in this new version and is incompatible with the previous one, you should ensure that the src directory only contains your project files. If you wish to run the sample use case but lack your own policies, attribute connectors, and tests, you can copy the sample files from your new clone directory.

Air-gapped environments

If you have an air-gapped APD installation, the air-gapped library bundle must also be updated. Please request the necessary bundle from support@axiomatics.com and then perform the upgrade by installing it according to the provided instructions.

Verification and conclusion

Execute the following to ensure that APD is functional after the update/upgrade:

Windows

gradlew test

Linux

./gradlew test

You may also check the installed version using the appropriate command. Read the Version check section for details.

If all verification steps are successful, create a commit to conclude the procedure.