Pre-Upgrade Checklist for AAI 26.0.0

Products

• Automation Analytics & Intelligence

Issue/Introduction

Complete the checks and actions below before upgrading Automation Analytics and Intelligence (AAI) from version 24.4.x or earlier to 26.0.0.
Skipping any of these can result in a blocked upgrade, broken integrations after the upgrade completes, or an under-provisioned environment.

New to certificate terminology? This article uses terms like certificate authority and keystore (in item 2 below) without redefining them.
See: AAI Glossary — Terms Used in the 26.0.0 Upgrade Documentation

Environment

Environment

• AAI 24.4.x or earlier, upgrading to AAI 26.0.0 or later.
• Applies to both VM/traditional-installer deployments and Kubernetes/OpenShift deployments (via Helm).
  Several items below apply differently, or not at all, depending on which environment you use — each item states this explicitly.

Cause

Not applicable. This article is a pre-upgrade action checklist, not a resolution to a specific reported problem.

Resolution

Prerequisites

Before running any command in this article, confirm you have:

• keytool on your PATH (used in item 2). This ships with any JDK. Check with keytool -version (identical command on Linux and Windows). If it's not recognized, either add your JDK's bin directory to your PATH, or check whether your AAI installation bundles its own JDK and point to that JDK's keytool by its full path instead.
• (Kubernetes/OpenShift only) helm already configured against the correct cluster and namespace (used in item 3) — confirm with helm version.
• Your AAI installation directory (referred to as <install> throughout) and, on Kubernetes/OpenShift, your Helm release name and namespace.

Checklist

• Know which environment you're upgrading — VM/traditional installer, or Kubernetes/OpenShift via Helm. Several items below apply differently, or not at all, depending on which.
• Audit your automation and integrations for two removed/changed REST calls (item 1).
• If you use client-certificate authentication for any connector or integration, plan for a same-window certificate regeneration step after the upgrade completes (environment-dependent — item 4).
• VM only: if you have HTTPS enabled today, confirm your certificate includes the Subject Alternative Names (SANs) it needs (item 2). This does not apply on Kubernetes/OpenShift.
• Back up your configuration before starting — a configuration directory (VM) or your Helm values (Kubernetes/OpenShift); see item 3.
• Confirm your host (or container memory limits) can accommodate a significantly larger default memory footprint (item 5).
• If you call testDbConnection programmatically, confirm the caller has administrative rights and the target host is one you expect to be allowed (item 1).
• If you plan to use the new Cost Model capability, know what "not granted" looks like so it isn't mistaken for a bug (item 6).
• VM only, silent/automated upgrades and Oracle databases: pre-set the required entries in your upgrade properties file before starting the upgrade tool (items 7–9).

1. Audit your automation for breaking API changes

Two existing REST calls change behavior in 26.0.0, and both tend to get mis-diagnosed as "intermittent connectivity" or "something changed in the network" rather than recognized as API changes — because nothing on the network actually changed.

Call	What changed	What you'll see if you don't update first
Login with an auth token	Was a GET with the token in the URL; is now a POST with a JSON body	Any automation still using the old GET form breaks outright after the upgrade
Job action endpoint (PUT .../action)	Removed entirely	Calls fail with 404/405 — easy to misdiagnose as an intermittent integration failure rather than a removed endpoint

Action: before your upgrade window, search your own automation, scripts, and integrations for any use of the token-based login call or the job-action endpoint, and update them ahead of time. Don't rely on a generated API client or spec to tell you whether the job-action endpoint still exists — confirm directly against a running 26.0.0 system if you have access to one, since published specs can lag behind what the server actually accepts.

A related, smaller change: testDbConnection now requires an administrative caller, and validates the target host against an allow-list. If any of your tooling calls this programmatically, confirm it runs with sufficient privilege and that the hosts it targets are ones you expect to be permitted — otherwise expect a new "host is not an allowed database host" error where none existed before.

2. If you use HTTPS today: confirm your certificate has the SANs it needs

This item applies to VM/traditional-installer upgrades only. If you run AAI on Kubernetes/OpenShift via Helm, this check does not apply to you — skip to the note at the end of this section.

If your VM installation has HTTPS enabled, the upgrade carries your existing certificate forward exactly as-is — same file, same private key, same content. It is not used to sign a new certificate, and it does not need to be a certificate authority.
There is no certificate-authority requirement to satisfy before upgrading, regardless of which prior version you're upgrading from.

What you do need to check beforehand: confirm your current certificate includes the Subject Alternative Names (SANs) it needs — the hostnames and/or IP addresses your users and integrations actually use to reach it.
This matters more after this upgrade than it used to: earlier upgrade behavior minted a brand-new certificate that could paper over a missing SAN on the original.
Now your original certificate is served exactly as it is, so a missing SAN becomes a visible browser warning or connection failure after the upgrade, rather than something the upgrade quietly covers for you.

Check this yourself before your upgrade window:

Linux:

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> \
  | grep -A5 -i "SubjectAlternativeName"

Windows (Command Prompt — findstr can't show extra context lines; use the PowerShell form below if you need the full block):

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> ^
  | findstr /i "SubjectAlternativeName"

Windows (PowerShell — shows the surrounding lines, closer to the Linux output):

keytool -list -v -keystore <your-keystore-file>.p12 -storetype PKCS12 -storepass <your-keystore-password> `
  | Select-String -Pattern "SubjectAlternativeName" -Context 0,5

Example output (what you want to see):

SubjectAlternativeName [
  DNSName: myaai.example.com
  IPAddress: 10.20.30.40
]

How to read it: you should see an entry for every hostname (DNSName) and/or IP address (IPAddress) your users or integrations use to reach this install.
If the block is missing entirely, or is missing an address you rely on, get an updated certificate from whoever manages your organization's certificates before your upgrade window
— this isn't something the upgrade can fix for you afterward without a new certificate. Full background on the certificate model behind this check is in the ports/HTTPS/certificates article (see Additional Information).

On Kubernetes/OpenShift: this check doesn't apply — the gateway's own certificate isn't touched by this upgrade path at all. Verify your external TLS independently
— check whether your Route/Ingress uses the cluster's router wildcard certificate or a TLS secret you supplied, rather than looking for anything on the Frontend Gateway itself.

3. Back up your configuration before starting

On a VM install: the upgrade process merges your existing configuration into the new format automatically, adding any new settings it needs without overwriting values you've already set. On a successful upgrade, it then deletes its own backup copies of the pre-upgrade configuration file as a cleanup step.

Action: before starting, copy both of your configuration directories somewhere safe — there are two, and both hold settings you may have customized.

Linux:

cp -r <install>/configuration <install>/configuration.pre-upgrade-backup
cp -r <install>/jboss/standalone/configuration <install>/jboss-standalone-configuration.pre-upgrade-backup

Windows (PowerShell):

Copy-Item -Recurse "<install>\configuration" "<install>\configuration.pre-upgrade-backup"
Copy-Item -Recurse "<install>\jboss\standalone\configuration" "<install>\jboss-standalone-configuration.pre-upgrade-backup"

Don't rely on the upgrade's own internal backup surviving afterward — by design, it won't be there once the upgrade reports success, so it's not something you can go back and grab after the fact if you later want to compare before/after values.

On Kubernetes/OpenShift: there is no on-disk configuration directory to back up in the way a VM has one — configuration files inside a running pod are reset from the container image on every pod start, so editing or copying them directly is not a reliable before-image. The actual source of truth for your settings in this environment is your Helm release configuration.

Action: export it before upgrading:

helm get values <your-release-name> -n <your-namespace> > pre-upgrade-values.yaml

That file is what you'd compare against afterward, or use to help reconstruct your settings if something needs to be rolled back.

4. Plan for a same-window certificate step if you use client-certificate connectors

This applies whenever your connectors present a client certificate directly to the Frontend Gateway
— always true on a VM install. On Kubernetes/OpenShift, this is not the default: the gateway's own TLS ships disabled, and the Route/Ingress in front of it defaults to edge termination (or no TLS at all), so client certificates never reach the gateway out of the box.
If your cluster runs that default configuration, this item doesn't apply to you. It only applies if someone has deliberately switched the Route/Ingress to passthrough mode and enabled the gateway's own TLS
— confirm that's actually your setup before planning around this.

Where it applies: every client-certificate-authenticated connector will stop working the moment the upgrade completes, because after the upgrade the gateway validates connectors against a brand-new,
dedicated connector certificate authority it generates automatically — one that has no relationship to your existing connector certificates.
(Your gateway's own certificate is not reissued by this upgrade and is not the cause of this.)

Action: treat regenerating and redeploying each affected connector's certificate as part of the same maintenance window, not a follow-up task
— plan for integrations to be unavailable between the upgrade finishing and this step completing. See the connector-impact article for the exact steps (Additional Information).

5. Capacity-plan for a larger default memory footprint

The default JVM memory settings for the main application jump significantly in 26.0.0.

Setting	24.4.x default	26.0.0 default
Maximum heap (-Xmx)	2048m	8192m (4×)
Initial heap (-Xms)	1024m	2048m (2×)

A host that was appropriately sized for 24.4.x's defaults may be under-provisioned for 26.0.0's.

1. Action (VM): before upgrading, confirm available host memory comfortably covers the new default, and compare against your actual configured JVM flags
   — don't assume the table above matches your install exactly; check your own configuration first.
   • Linux: free -h
   • Windows (PowerShell): Get-CimInstance Win32_OperatingSystem | Select-Object TotalVisibleMemorySize,FreePhysicalMemory (values are in KB), or check the Performance tab in Task Manager
2. Action (Kubernetes/OpenShift): check your configured pod memory limits against the new defaults, per component — a limit that was sized against 24.4.x's smaller default can now be smaller than what the component tries to request.
   This fails differently than a normal error: the component is killed externally for exceeding its memory limit, so the failure often won't show anything informative in that component's own log.
   This is a known specific risk for your search/indexing component, where a default heap request of 8192m against a pod memory limit of, for example, 4GiB will reliably get it killed for exceeding its limit
   — check that component's pod memory limit first if you're on Kubernetes/OpenShift.

6. Know what changes immediately after a successful upgrade (informational)

A few things change the moment the upgrade completes that aren't broken, but can look that way if you don't expect them:

• The certificate-management screen you may have used before is gone. Port and TLS settings now live in a configuration file instead of a UI tab.
  If you're used to managing ports through that screen, expect to ask "where did that go"
  — it's an intentional removal, not a missing feature.
• A new cost-tracking feature area may be present but inaccessible. It's gated by an explicit capability grant. Without that grant, navigating to it simply redirects you back to the main dashboard with no error message
  — which reads like a broken link rather than a permissions restriction. If you were expecting to use this feature immediately after upgrading, confirm the capability was granted rather than assuming something broke.

7. If upgrading in silent/automated mode, or on an Oracle database: pre-set required upgrade properties first

This item applies to VM/traditional-installer upgrades only. There is no Helm/Kubernetes equivalent — this is specific to the standalone upgrade tool (upgrade.sh on Linux, upgrade.bat on Windows).

The upgrade tool reads a properties file before it runs. Two situations require you to create or edit that file before starting the upgrade, not just pass a command-line flag:

• Silent/automated mode: the automated-mode command-line switch alone does not fully suppress prompts. You must also set the automation property to true in the properties file beforehand.
• Oracle databases: two device-name properties, for the table and index tablespaces, must be set in the properties file beforehand. If they're left unset, the values are carried through literally,
  unresolved, into the generated database-upgrade script later (see item 8) instead of being filled in — which then causes that script to fail outright when you try to run it.

Action: before starting the upgrade, create or edit the upgrade properties file in the upgrade bundle's properties directory and set:

• The automation property to true, if you're running in silent/automated mode.
• (Oracle only) the table-tablespace and index-tablespace device-name properties, set to the tablespace names your schema's tables and indexes actually use today. Find your current values with:

  SELECT DISTINCT tablespace_name FROM dba_tables WHERE owner = '<your schema owner>';
  SELECT DISTINCT tablespace_name FROM dba_indexes WHERE owner = '<your schema owner>';

Consult your product documentation for the exact property names and file location for your version. Setting these correctly beforehand avoids a partially-failed silent run and avoids needing to hand-correct the generated database script in item 8.

8. After the upgrade reports success, manually verify the database schema migration actually completed

The upgrade includes a generated SQL script that performs the real database schema changes (new tables, columns, and default rows). Depending on your installation mode, running this script may be a separate manual step.

Action: after the upgrade finishes, before considering it complete, confirm the new schema objects exist. For example, check for the new cost-tracking and data-insight tables your target database should now have.

9. If a first upgrade attempt fails or is interrupted: reset your upgrade properties before retrying

Simply re-running the upgrade tool after a failed or interrupted first attempt is not safe. The properties file the tool reads picks up leftover state from the failed attempt (resume-related keys the tool wrote during that run),
which causes the tool to treat the next run as a resume of the broken attempt rather than a fresh run — and it crashes immediately, before doing anything useful, on every subsequent attempt while that state remains.

Action: before retrying, reset the upgrade properties file to a clean, minimal state — only the automation property (if applicable) and the existing-installation-directory property should remain — then re-run the upgrade as a fresh attempt.

Additional Information

• What to Know Before Upgrading to AAI 26.0.0 — background on the architectural changes behind these action items.
• Ports, HTTPS, and Certificates in AAI 26.0.0 — broader background on the certificate-authority requirement in item 2 and the rest of the port/TLS changes in 26.0.0.
• Connector/Integration Impact of Upgrading AAI to 26.0.0 — the full certificate-regeneration procedure for item 4.
• AAI Glossary — Terms Used in the 26.0.0 Upgrade Documentation — plain-language definitions of PKI, certificate, and other terms used across this article set.
• To speak with a customer representative or a Support Engineer see Contact Support. Scroll to the bottom of the page and click on the respective region.