The most recent patch for this version is 26.2.1.  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:

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

The output shows the APD version, for example:

\--- com.axiomatics.alfa.test:axiomatics-policy-devops-bundle:26.2.1

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 to 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.

Files of APD and your files​

An update replaces the files that belong to APD and keeps your files. Both update procedures below follow this table. In the Project structure, the files that belong to APD are marked with ⛔.

File or directoryBelongs toWhen you update
buildSrc/, gradle/, gradlew, gradlew.bat, AGENTS.md, extra/APDTake the new version of APD.
settings.gradleAPD, except rootProject.nameTake the new version of APD, and keep your rootProject.name.
build.gradle, deployment.yaml, Dockerfile, src/extra/YouKeep your version. Compare it with the new version of APD, and take over the changes that the version-specific steps or the release notes require.
src/authorizationDomain/, src/test/, license/, README.md, CODEOWNERS, gradle.properties, AGENTS.local.mdYouKeep your version.

An update can bring new sample files in src/authorizationDomain/ and src/test/. If you have replaced the samples with your own policies and tests, delete the new sample files.

Update procedure​

You can update APD manually by copying files, or with Git. You can also let an AI coding agent do the update, see Update with an AI coding agent.

:::tip Terminology

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

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

:::

  1. Clone the latest version of APD from GitHub into a new directory, outside your APD repository:

    git clone https://github.com/axiomatics/axiomatics-policy-devops apd-new

    This directory becomes the new clone.

  2. In your APD repository, delete buildSrc/, gradle/, gradlew, gradlew.bat, AGENTS.md and extra/. Copy them from the new clone into your APD repository.

  3. Copy settings.gradle from the new clone into your APD repository, and set rootProject.name back to the name of your project.

  4. Compare build.gradle, deployment.yaml, Dockerfile and src/extra/ with the versions in the new clone. Take over the changes that the version-specific steps or the release notes require.

  5. Keep all your other files.

Version-specific steps​

After completing the update procedure above, perform the steps for the version you are updating from.

From APD 26.1 to 26.2​

Check the remotes in alfa { repositories { } } of your build.gradle:

  • Every remote needs domainName. A remote without it fails the build.
  • Set project inside each remote. alfa { project 'x' } and alfa { namespace 'x' } still work with a warning, and are removed in APD 27.1.
  • environment is optional. Without it, the tasks of a remote are named after its project and domain name. Keep it if you connect to several Authorization Hubs, or if your scripts use the current task names.
  • Authorization Hub must be version 26.2 or later, and a hub { } remote must use oidcCredentials { }.
  • Read the client secret from an environment variable instead of writing it in build.gradle.

See Authorization Hub integration for an example.

Then check your CI/CD pipelines:

  • Use DomainPushTo{environment}, DomainPullFrom{environment} and DomainPromoteFrom{source}To{target} instead of pushTo{environment}, pullFrom{environment} and promoteFrom{source}To{target}. The old names only exist for adm { } remotes, print a warning, and are removed in APD 27.1.
  • DictionaryPushTo{environment} and AllPushTo{environment} now fail when Authorization Hub rejects an attribute.

If your project has attribute connectors in the legacy format, the build prints a notice at the end. See Upgrade legacy attribute connectors.

From APD 1.0 or earlier​

Make the following 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

Upgrade legacy attribute connectors​

From APD 26.2, the task upgradeAuthzDomain converts attribute connectors in the legacy format to the new YAML configuration format. A legacy connector has a className and an XML configurationString, either inline or in a separate <name>.configurationString.* file. The task upgrades the HTTP, SQL, LDAP and Table attribute connectors and the JSON, XML and JWT parsers. In the upgraded connectors, attributes are referenced by their key in attributes.yaml.

When your project has connectors that can be upgraded, every successful build ends with a notice like this:

----------------------------------------------------------------------
The following Axiomatics attribute connectors can be upgraded to the new YAML configuration format:
  - ...
To run the upgrade, commit all files and run the Gradle task upgradeAuthzDomain, for example: ./gradlew upgradeAuthzDomain
----------------------------------------------------------------------

Run ./gradlew checkAuthzDomainUpgrade to print the same list on demand. It does not change any files.

To upgrade:

  1. Commit all files. The upgrade has no undo of its own: Git is the undo. upgradeAuthzDomain refuses to run when there are uncommitted changes or untracked files, or when the project is not in a Git repository. To run it anyway, add -Dapd.allowUnsafe=true.

  2. Run the upgrade:

    ./gradlew upgradeAuthzDomain

    The task rewrites the connector files and then deletes the separate configurationString files. It lists the upgraded connectors and the next steps.

  3. Verify that everything works as before: run your tests with ./gradlew test, and/or start ADS with ./gradlew runAds.

  4. Review the changes, for example with git diff, and commit them.

The upgrade uses the attribute connector library's own conversion. It does not start the connectors, so no database, LDAP or HTTP connection is needed, and it works in air-gapped environments.

Version-specific notes for ADS​

APD uses the latest Access Decision Service (ADS) as its default engine. New APD projects are set up for the latest ADS: the Dockerfile and deployment.yaml in the project root, and startService.sh and logback-custom.xml in src/extra.

warning

ADS 1 support is deprecated and will be removed in APD version 27.1. The ADS 1 tasks runAdsV1 and buildAdsDockerImage print a warning. The ADS 1 Dockerfile and deployment.yaml are in extra/exampleAds1Configuration.

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. To use ADS 1 until then, replace the Dockerfile and deployment.yaml in the project root with the ones in extra/exampleAds1Configuration, as described in its README.md.

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

TaskDescriptionADS 1 (deprecated)ADS 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.

Switch an existing project to the current ADS image​

Updating APD does not change the Dockerfile and deployment.yaml of your project. To use the ADS setup of new projects, copy these files from the new clone into your APD repository, replacing your own:

  • Dockerfile and deployment.yaml in the project root
  • src/extra/startService.sh and src/extra/logback-custom.xml

Then run stageDeployment and build the image from build/install/deployment/ads/. Take over your own changes, if any, and note the following differences to the previous default deployment.yaml:

  • The environment variables start with ADS_:

    PreviousCurrent default
    LICENSEADS_LICENSE
    DOMAIN_CONFIGADS_DOMAIN
    ADS_USERNAMEADS_USERNAME
    PASSWORDADS_PASSWORD
    LOGLEVELADS_LOGGER_ROOT_LEVEL
    AXIOMATICS_AUDITLOGSADS_LOGGER_AUDIT_LEVEL
    AXIOMATICS_LOGLEVELnone

    New variables are ADS_PORT (default 8080), ADS_MANAGEMENT_PORT (default 8082), ADS_JDBC_MAX_POOL and ADS_DISTCACHE_*. stageDeployment lists all variables in build/install/deployment/.env.generated.

  • The default user is pdp-user with password secret (previously admin / changeme). Set your own with ADS_USERNAME and ADS_PASSWORD.

  • The health probes (/health/startup, /health/readiness, /health/liveness) are served without authentication on the separate management port 8082. Do not expose it publicly.

  • Logging uses logback-custom.xml instead of logback-json.xml.

  • ADS is installed in /opt/ads in the image, instead of /, and runs as the non-root user 10001. If you mount files into the container, such as the license, mount them below /opt/ads or set their absolute paths with ADS_LICENSE and ADS_DOMAIN.

Update with an AI coding agent​

APD projects contain an AGENTS.md file (from APD version 26.2) with instructions for AI coding agents, such as GitHub Copilot, OpenAI Codex, Cursor or Claude Code. It describes the whole update for the agent: the preparation, getting the new version, resolving conflicts with the table above, the version-specific steps, and the verification. The agent reports the result to you and asks you before it commits.

Ask the agent, for example:

Update APD to the latest version. Get the latest APD from
https://github.com/axiomatics/axiomatics-policy-devops first, then follow
the "Updating APD" section of its AGENTS.md.

Getting the new version first matters when your project is older than APD 26.2 and has no AGENTS.md yet. Review the agent's changes before you commit them.

Put your own instructions for agents, such as your team's conventions, in AGENTS.local.md in the project root. AGENTS.md is replaced when APD is updated while AGENTS.local.md is kept.

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 install it as described in Offline installation.

Verification and conclusion​

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

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.