What to Know Before Upgrading to AAI 26.0.0
Article ID: 453430
Updated On:
Products
Issue/Introduction
This background article explains what's different in AAI 26.0.0 and why, so the rest of the upgrade material makes sense.
It has no action items of its own — for a concrete pre-upgrade checklist, see Pre-Upgrade Checklist for AAI 26.0.0.
New to terms like PKI or certificate authority? This article uses those terms without redefining them.
See: AAI Glossary — Terms Used in the 26.0.0 Upgrade Documentation
Environment
- AAI 24.4.x or earlier, upgrading to AAI 26.0.0 or later.
- Several sections below behave differently depending on how you run AAI, so confirm this first:
- VM / traditional installer — AAI runs directly on a host (Linux or Windows), installed and upgraded by the traditional installer/upgrader tooling.
- Kubernetes / OpenShift (Helm) — AAI runs as a set of pods deployed via Helm.
- Where a fact below applies to only one of these, it's called out explicitly. Don't assume a section's general framing tells you which environment it's about — check the callout.
Cause
Not applicable. This is background reading on what changed in AAI 26.0.0, not a resolution to a specific reported problem.
Resolution
Summary of what's changing
- A new component, the Frontend Gateway, now sits in front of AAI. Your existing port keeps working, but ports and certificates behave differently underneath. Full detail: Ports, HTTPS, and Certificates in AAI 26.0.0 (see Additional Information).
- A number of defaults and runtime behaviors changed — not bugs, but places where a habit or number you learned on 24.4.x no longer holds.
- Two existing API calls break, and a few UI behaviors change or move.
- New services join the product, and the ones you already know about (Reports, Simulation) changed substantially even though they aren't new.
- The database schema grows by seven tables, one of which will accumulate rows continuously and is worth mentioning in any space-planning conversation.
- The upgrade tool itself (VM only) needs a little care — silent-mode setup, and confirming the database migration actually completed, aren't fully automatic.
1. Networking and certificates (summary — see the dedicated article for detail)
26.0.0 introduces the Frontend Gateway as the component your browser and integrations actually talk to, and separates certificate handling into three independent systems: your gateway's own certificate
(unchanged — carried forward as-is by the upgrade, never reissued), a brand-new connector certificate authority that AAI generates automatically to validate client-certificate connectors, and AAI's own internal service-to-service mesh PKI (also fully automatic).
If you have HTTPS enabled today on a VM install, confirm your certificate has the Subject Alternative Names it needs
— the upgrade no longer mints a new certificate that could paper over a missing one
— and if you use client-certificate-authenticated connectors, every one of them stops working the moment the upgrade completes, on VM by default, because the new connector certificate authority has no relationship to your existing connector certificates.
See Ports, HTTPS, and Certificates in AAI 26.0.0 for the full explanation, and Connector/Integration Impact of Upgrading AAI to 26.0.0 if you use connectors (see Additional Information).
2. Changed defaults and runtime behavior
These aren't new features — they're changed answers to questions you may already know how to ask from 24.4.x. Carrying over a 24.4.x number, log expectation, or assumption without re-checking it against 26.0.0 is the most common way these turn into support cases.
Resource and network defaults
| Setting | 24.4.x | 26.0.0 |
|---|---|---|
| Application maximum heap | 2048 MB | 8192 MB (4×) |
| Application initial heap | 1024 MB | 2048 MB (2×) |
| Application HTTP port (internal, VM) | 8080 | 8081 — your external port is unaffected; see the ports/HTTPS article (Additional Information) |
| External HTTPS | — | Not enabled by the installer by default |
| Gateway request timeout | — | Roughly 30 minutes on VM; roughly 2 minutes on Kubernetes/OpenShift by default |
Why the gateway timeout matters: a long-running request that completed fine on VM can now time out around the 2-minute mark on a default Kubernetes/OpenShift deployment. If users report requests failing "around 2 minutes in" only after moving to containers, check this before assuming an application-side regression.
Why the memory jump matters: a host or pod that was comfortably sized for 24.4.x's defaults can be under-provisioned for 26.0.0's. On Kubernetes/OpenShift specifically, exceeding a configured pod memory limit fails differently than a normal error — the component is killed externally, so its own log often shows nothing informative. This is a known specific risk for the search/indexing service (OpenSearch), whose default memory request can exceed a pod limit that was sized before the upgrade.
The empty-string configuration trap
Several of the new services (AI Insights, MCP, the custom condition generator, and the mTLS settings for Subscription/Collector/Reports) read their TLS keystore/truststore paths from service-specific environment variables rather than a shared generic one. If you set only the generic-sounding variable, it has no effect — the service-specific variable is what's actually read. If a new service's TLS configuration silently doesn't take effect, this is the first thing to check: confirm you set the variable scoped to that specific service, not a shared or generic name.
Alerting volume drops by design
You may see meaningfully fewer alerts after upgrading. This is intentional: 26.0.0 evaluates alert conditions more precisely before publishing them, so alerts that previously fired on every cycle regardless of whether a real threshold was crossed are now suppressed unless the condition genuinely applies. A volume drop on its own is not evidence of a delivery problem — treat "I'm getting way fewer alerts since upgrading" as expected behavior to confirm, not a defect to chase, unless you can show a specific alert that should have fired and didn't.
Alert links now resolve their hostname more predictably — but check one setting on Kubernetes/OpenShift
Alert emails contain a link back into AAI. 26.0.0 resolves that link's hostname through a clear, three-way precedence (an explicit override setting, then an environment-level public route, then the server's own configured address) instead of ad hoc logic — a genuine improvement. On Kubernetes/OpenShift, the most common cause of a wrong hostname in an alert link is leaving the environment's public-route setting empty; check that first if a customer reports alert links pointing to the wrong host.
Two other behavior changes worth knowing
- The Config Tool's "Ports" tab is gone. Port settings now live in the main configuration file.
This is an intentional removal, not a missing feature
— expect "where did the Ports tab go" questions after upgrading.
The Config Tool gained an AI-services tab, a read-only view of the search/indexing (OpenSearch) configuration, and a Frontend Gateway panel in its place. - Per-user scheduler authorization now fails closed. If the collector's per-user scheduler-permission check hits any error while confirming what a given user is allowed to see, it now returns an empty result
— denying access to all schedulers for that user
— rather than failing open.
If collector-backed views appear empty specifically for non-administrator users after upgrading, check this authorization path before assuming a data problem.
3. API and UI changes
Two existing API calls break — plan to audit your automation
| Change | What breaks |
|---|---|
Logging in with an auth token changed from a GET request with the token in the URL to a POST request with a JSON body | Any automation still using the old GET form fails outright |
The job-action endpoint (PUT to a job's action path) was removed | Calls fail with an HTTP 404/405 — and note that some published API specifications still list this endpoint as present, so don't rely on a generated client or spec to tell you it's gone |
Both of these tend to get reported as "intermittent connectivity" rather than recognized as API changes, because nothing on the network side actually changed. See Pre-Upgrade Checklist for AAI 26.0.0 for the concrete audit step.
A smaller, related change: the database-connection-test call now requires an administrative caller and validates the target host, so calling it programmatically without sufficient privilege now fails where it may not have before.
One additive change, not breaking: the job-dependencies endpoint gained an optional filter parameter — existing callers that don't use it are unaffected.
A documented feature can be present but invisible in the menu
A new interactive-analytics builder page can be reached directly by URL even when its setting is left at its default (unset)
— but its navigation menu entry only appears when that same setting is explicitly turned on.
With the setting left unset, the two behave asymmetrically: the page itself works if a user knows the URL, but there's no menu entry pointing to it.
If a customer reports "the documentation mentions a feature I can't find in the menu," check whether this is the cause before assuming something is broken.
Also note that once you do change this setting, the browser needs to be reloaded before the change takes visible effect — the running page caches the old value.
Cost Model is gated by a granted capability, not a setting you flip yourself
The new Cost Model area (see What's New: Cost Model & Data Insights in AAI 26.0.0 for the feature itself, in Additional Information) is gated by an explicit capability grant rather than a simple on/off toggle.
A user who hasn't been granted that capability is redirected quietly back to the main dashboard — no error message, nothing that looks like a permissions restriction.
This reads exactly like a broken link. If someone expects to use Cost Model right after upgrading and can't reach it, confirm the capability was actually granted before troubleshooting it as a bug.
The UI framework itself did not change
If you're troubleshooting a rendering problem after upgrading, it's worth knowing that 26.0.0's web UI runs on the same core framework versions as 24.4.x
— no major version changes to the underlying UI framework, component library, or client-side data layer. A rendering regression in 26.0.0 is very rarely caused by a framework upgrade, because there mostly wasn't one.
It's more useful to look at what's genuinely new: the charting library used for the new Cost Model and AI Insights visualizations did take a major version update, and the new AI-generated-content rendering path enforces its own allow-list of which UI components it's permitted to use — an unsupported or unrecognized component there fails by design, not by accident.
4. New services join the fleet — and two existing ones changed substantially
26.0.0 adds several new backend services beyond the Frontend Gateway already covered above: a Denormalizer, an MCP (tool-calling) service, Automation AI, AI Insights, and a dedicated search/indexing engine (OpenSearch).
Two services you already know — Reports and Simulation — are not new, but both changed substantially in this release (Reports, for example, gained an asynchronous report-generation path), so don't assume "existing service" means "unchanged."
Where these run differs by environment:
- On Kubernetes/OpenShift: each of the new services (Frontend Gateway, Denormalizer, MCP, Automation AI, AI Insights) runs as its own pod, each with its own log stream and health endpoint.
The search/indexing engine (OpenSearch) runs as a dedicated, AAI-managed component in the cluster. - On VM: the same new services (Frontend Gateway, Denormalizer, MCP, Automation AI, AI Insights) also run — as installer-managed "external services" alongside the main application, each with its own log file, not as separate pods.
The search/indexing engine is the one genuine exception: on a VM install, AAI does not bundle or manage this component at all
— your configuration only holds connection details for a cluster you run and manage yourself.
This is a real architectural difference, not just a naming one, and it matters if a search/indexing problem turns out to be entirely on your own infrastructure rather than AAI's.
Each of these components writes to its own named log file (for example, distinct log files for the gateway, the denormalizer, the MCP service, Automation AI, AI Insights, the search/indexing engine, Reports, and Simulation)
— see Where Did My Logs and Configuration Go? — AAI 26.0.0 Post-Upgrade Orientation for the full list and how to find them in each environment.
Two settings can make a whole service look dead rather than misconfigured. The AI-Powered Interactive Analytics feature and the Denormalizer service are each gated by their own setting on the main AAI application (not an environment variable on the service's own pod/process).
Left at their default off state, the MCP service reports every one of its tools as unavailable, and the Denormalizer indexes nothing at all
— with no corresponding log line at all from the Denormalizer side. If either of these looks completely non-functional right after upgrading, check the relevant setting before troubleshooting the service itself as broken.
5. Database schema additions
The upgrade adds seven new tables, primarily to support the new Cost Model and AI-assisted analytics features: tables for cost centers and their hierarchy,
cost ownership records, job-to-cost-center association rules, a daily cost-allocation summary, a data-insight template table, an interactive-analytics view registry, and an AI query-data table. An existing table (used for report definitions) also gains new columns.
Worth flagging in space-planning conversations now, while it's cheap: the daily cost-allocation table accumulates one row per cost center, per scheduler, per day.
It isn't a space concern on a fresh upgrade, but it will grow continuously for as long as Cost Model is in use — raise it as a factor in any 26.0.0 storage/capacity discussion rather than waiting for it to surface as a space ticket months later.
6. The upgrade tool automates most of the migration, but not all of it
This applies to VM/traditional-installer upgrades only. On a VM install, three things about the upgrade tool are worth knowing going in, so a smooth-looking upgrade doesn't hide a problem:
- Silent/automated mode needs a bit of setup, not just a command-line flag. Running the tool with its automated-mode switch alone doesn't fully suppress prompts
— a properties file needs a specific setting made beforehand for a truly hands-off run. - The database schema change is applied by a separate generated script, not verified by the upgrade tool itself.
The tool generates the SQL that actually updates your schema, but its own "upgrade successful" result doesn't confirm that script ran to completion
— it's worth checking the schema directly rather than taking a clean upgrade report at face value. - A failed or interrupted attempt can't simply be re-run as-is. Retrying without some cleanup first will cause the tool to fail immediately on every subsequent attempt.
None of this requires action from you right now — see Pre-Upgrade Checklist for AAI 26.0.0 for the concrete steps for each of these (see Additional Information).
Additional Information
- Pre-Upgrade Checklist for AAI 26.0.0 — the concrete pre-upgrade action checklist (API audit, certificate check, configuration backup, capacity planning).
- Ports, HTTPS, and Certificates in AAI 26.0.0 — full detail on the Frontend Gateway and the three independent certificate systems behind it.
- Connector/Integration Impact of Upgrading AAI to 26.0.0 — what happens to client-certificate-authenticated connectors and how to fix them.
- Where Did My Logs and Configuration Go? — AAI 26.0.0 Post-Upgrade Orientation — the full post-upgrade log and configuration file map, including per-service log file names.
- What's New: Cost Model & Data Insights in AAI 26.0.0 — the Cost Model feature itself, beyond the gating behavior summarized above.
- 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.
Feedback
