Upgrade by rebuilding, not migrating: stand up Pega Infinity 25 on Kubernetes with Helm, import your 8.7 application stack as a ruleset archive rather than restoring database backups, remediate deprecated rules against the new schema, then cut over only after parallel-run validation. The reason is structural: Pega 25 treats the container as the deployment unit and the database as disposable state, so an in-place 8.7 patch-style upgrade has no valid target. Direct database restore into Pega 25 is unsupported and silently corrupts system rulesets.
Architecture shift: why container-based changes the upgrade model
In Pega 8.7, the application server was a long-lived, hand-patched server. You deployed a WAR file, tuned JVM flags on the host, kept logs on local disk, and relied on the database as the source of truth for everything, including rules. The upgrade path was a patch install plus a rules schema update, run in place.
Pega 25 inverts the dependency. The application runs from an immutable image built and versioned by Pega, orchestrated by Kubernetes. Configuration that used to live in server files now lives in Kubernetes Secrets, ConfigMaps, and environment variables. The database holds your application data and rules, but the schema version is tied to the image tag, so mixing an old database with a new image is invalid.
The practical consequence is that your upgrade project is a platform migration plus an application upgrade running in parallel. Treating it as only one or the other is the most common cause of blown schedules. The platform work (cluster, ingress, secrets, storage classes) is largely independent of Pega and can start weeks before the application work.
Pega ships deployment artifacts as Helm charts and container images through its registry, and the official upgrade guidance centers on deploying the target version fresh, then importing the application. Confirm the exact chart versions and import tooling against Pega's current release notes for your licensed edition before you commit a build pipeline.
What actually moves: rules, data, and the pieces that do not port
Think of the 8.7 system as three layers. The rules layer is your application logic: flows, data pages, decision tables, section rules. The data layer is case data, work history, and reference tables. The platform layer is everything Pega shipped: system rulesets, node configuration, and security infrastructure.
Only the rules layer and the data layer move by design. The platform layer is replaced wholesale by the new image. Anything you customized inside Pega's system rulesets, or patched into server files, has no destination in the new architecture and must be re-implemented through supported extension points.
A ruleset archive exported from 8.7 is not guaranteed to import cleanly. Rules that reference removed APIs, deprecated UI frameworks, or old authentication schemes will fail validation. Budget remediation effort per rule type: low for declarative rules, high for activities and custom Java steps that touch internals.
The counterintuitive detail: a clean import is a warning sign, not a success signal. If every rule imports without a single validation message, you are likely missing checks that only surface at runtime, such as data page behavior under the new session model. Review the import log for skipped rules as carefully as for failures.
Quantified context: effort, versions, and thresholds
You cannot responsibly plan this upgrade without sizing the gap. The distance from 8.7 to 25 spans multiple major releases, and each one carries its own deprecation set. Pega's release cadence and support windows define how long you can stay on 8.7 while you migrate, so check the current end-of-support date for your exact 8.7 patch level first. That date sets your hard deadline.
Size your rulebase before estimating. Export a count of custom rules by type, and count custom Java steps and activities separately; those two categories dominate remediation time. A rulebase with heavy activity use will take proportionally longer than one built on declarative and data-page patterns.
Environment count matters more than application size in the early phase. Each environment needs its own namespace, secrets, ingress, and database, and each one must be validated before the next is promoted. Teams routinely underestimate this because the application itself is unchanged between environments.
Use the comparison table below to decide how much parallel infrastructure you run during the transition.
| Approach | Cutover risk | Cost profile | Rollback speed | Best fit |
|---|---|---|---|---|
| Big-bang cutover, single parallel environment | High | Lowest infrastructure spend | Slow; requires rebuilding 8.7 | Small rulebase, tolerant users |
| Phased by application or channel | Medium | Moderate | Fast per phase | Multiple applications sharing a platform |
| Blue-green with full parallel stack | Low | Highest; double run cost | Minutes; flip ingress back | Regulated or revenue-critical systems |
| Shadow traffic on 25 before cutover | Low | Moderate plus tooling | Fast | High-volume case processing |
Run the blue-green option only for the windows you need; keeping two full stacks for months is where budgets break.
Timeline: a realistic sequence
The table below is a sequence, not a promise of duration. Durations depend on rulebase size and your team's Kubernetes familiarity, so use it to order work and identify dependencies.
| Phase | Core work | Exit criterion |
|---|---|---|
| 1. Discovery | Inventory custom rules, integrations, and server-side customizations | Signed list of remediation items |
| 2. Platform build | Provision cluster, ingress, secrets, storage, database per environment | A stock Pega 25 image runs and passes health checks |
| 3. Rulebase export | Export application stack as archives from 8.7 | Export completes with documented warnings |
| 4. Import and remediate | Import into 25, fix validation errors, rebuild integrations | Clean import log and green smoke tests |
| 5. Data migration | Move case and reference data through supported utilities | Row counts and checksums reconcile |
| 6. Parallel run | Run 8.7 and 25 side by side on representative cases | Outputs match within agreed tolerance |
| 7. Cutover | Switch ingress, freeze 8.7 writes, monitor | Rollback window closes cleanly |
Start platform build during discovery, not after. The two tracks do not conflict, and starting them in series adds weeks for no benefit.
Misconceptions and red flags
The most expensive misconception is that you can restore an 8.7 database backup into a Pega 25 environment and run the upgrade tooling against it. The schema expectations differ, and the result is a system that starts but misbehaves in ways that are hard to trace. Use supported export and import paths for rules, and supported utilities for data.
The second is that containerization makes the application stateless end to end. Session state, scheduled jobs, and agent processing still need deliberate configuration in a multi-pod deployment. If you scale replicas without addressing job scheduling, you will run duplicate background work.
Watch for these red-flag conditions before you schedule cutover:
Any customization patched directly into Pega system rulesets or shipped files. Activities or Java steps that call undocumented internal APIs. Authentication or SSO configuration tied to server-level files rather than supported identity providers. Integrations using connectors or protocols that were deprecated between 8.7 and 25. Reports or extracts that read directly from Pega system tables. Scheduled jobs that assume a single node without coordination.
Each of these converts a configuration task into a development task. Find them in discovery, not in the week before cutover.
Practical actions: the step sequence
Execute in this order, and gate each step on its exit criterion so failures surface early.
Confirm licensing and support dates. Verify your license covers the target version and note the end-of-support date for your current 8.7 patch level. This date is your deadline, not a suggestion. Inventory the rulebase. Export counts of custom rules by type, listing activities, custom Java steps, and integrations separately. This inventory drives the estimate. Build the target platform. Provision a Kubernetes cluster with ingress, a supported database, persistent storage, and a secrets store. Deploy the stock Pega 25 image and confirm health checks pass before importing anything. Export from 8.7 using supported tooling. Produce the application archive and record every warning in the export log. Resolve export warnings where possible; document the rest. Import into the new environment and remediate. Work through validation errors by category, starting with authentication and integration rules, which block smoke testing. Rebuild server-level customizations through supported extension points. Migrate data through supported utilities. Reconcile row counts and checksums against the source before declaring the migration complete. Run parallel validation. Process a representative set of cases in both systems and compare outputs against agreed tolerances. Define the tolerance before you start, or the comparison has no endpoint. Cut over with a rollback window. Freeze writes to 8.7, switch ingress to the new environment, and keep the old stack available until the rollback window closes.
Reconcile two thresholds explicitly. The support end date for 8.7 sets when you must finish. The parallel-run tolerance sets when you may finish. If the first arrives before the second is met, cut scope to the highest-value applications rather than cutting validation.
Limitations and what this guide cannot tell you
Version-specific details change with every Pega release, including chart names, image tags, import tooling behavior, and deprecation lists. This guide describes the stable shape of the migration, not the exact commands for your edition. Confirm all version-specific steps against Pega's official documentation and release notes for the precise version you deploy.
Exact effort and cost depend on your rulebase, your team's Kubernetes experience, and your environment count. No article can supply those numbers for your organization, and any that claims to is guessing. Size from your own inventory.
Container platforms also shift operational responsibility onto your team: patching the cluster, managing ingress certificates, and monitoring the database become your job in ways they were not on a managed application server. Budget for that ongoing work, not just the migration project.
This article is general educational information about software migration planning, not a technical specification, legal opinion, or guarantee of outcomes. Validate every step against the vendor's current official documentation and engage qualified platform and Pega-certified professionals for your specific environment before executing a production cutover.