The most recent patch for this version is 26.1.7.  Learn more  

Skip to main content

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:

*:first-child]:mt-0>
gradlew -q dependencies --configuration testCompileClasspath | findstr "com.axiomatics"
*:first-child]:mt-0 hidden>
./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, as any pending changes may be lost during the update. 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 the Update procedure below.

warning

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.

:::tip Terminology

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

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

:::

*:first-child]:mt-0>

  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.

*:first-child]:mt-0 hidden>

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 directoryInstructions
buildSrc/Keep the origin's version.
/settings.gradleKeep your rootProject.name line, but otherwise keep the origin's version.
/deployment.yamlKeep your changes.
/build.gradleKeep your changes.
OtherKeep your changes for any conflicts found in src/authorizationDomain, src/test, the Dockerfile, and related files or directories.

After resolving all conflicts using the guidance above, stage the resolved files and run git merge --continue to complete the merge.

Version-specific steps​

After completing the update procedure above, perform these additional steps only if you are upgrading from APD version 1.0 or earlier.

  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.

Version-specific notes for ADS​

While APD uses the latest Access Decision Service (ADS) as its default engine, it remains compatible with all ADS versions. However, you cannot run ADS 1 and ADS 2+ concurrently due to breaking changes in the shared deployment.yaml file. ADS 1 relies on Dropwizard configuration, whereas ADS 2 and later use Spring Boot. You must either remain on ADS 1 or prepare your Spring Boot environment before switching to ADS 2+ specific tasks.

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

TaskDescriptionADS 1ADS 2+
Run ADSAPD assembles the components in a temporary directory and starts the ADS service.runAdsV1runAds
Stage build contextAPD assembles the components in a known location for use by your pipeline (to build an image, etc.).dockerPreparestageDeployment
Build imageAPD builds a Docker image for pushing to your registry.buildAdsDockerImageStage 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:

*:first-child]:mt-0>
gradlew test
*:first-child]:mt-0 hidden>
./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.