Skip to content

Add new skill to help migrate weblogic monoliths to GCP. #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
copybara-service wants to merge 1 commit into
base: main
Choose a base branch
from
+10,108 −0
Open

Add new skill to help migrate weblogic monoliths to GCP. #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
339 changes: 339 additions & 0 deletions skills/cloud/google-cloud-weblogic-migration/EVAL.txtpb
View file
Open in desktop

Large diffs are not rendered by default.

196 changes: 196 additions & 0 deletions skills/cloud/google-cloud-weblogic-migration/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,196 @@
---
name: google-cloud-weblogic-migration
description: |
Migrates legacy WebLogic applications to cloud-native serverless microservices on GCP (Spring Boot or Quarkus on Cloud Run or Cloud Functions).
Use when analyzing, decomposing, or refactoring legacy Java EE/WebLogic monoliths (EJBs, JMS, JNDI, Struts, CMP/BMP entity beans) into modern cloud microservices.
Don't use for general-purpose Java bug fixing, standard Spring Boot feature development, or non-WebLogic/non-Java EE application migrations.
---

# WebLogic Monolith to Cloud-Native Migration Skill

This skill guides the agent through migrating a legacy WebLogic monolith
application to a modern, cloud-native serverless microservice architecture on
Google Cloud Platform (GCP). It supports migrating to either Spring Boot or
Quarkus, running on GKE, Cloud Run or Cloud Functions.

## Workflow Overview

The migration process is divided into seven phases:

1. **Environment & Prerequisites Check**: Verify JDK compatibility (LTS JDK 11,
17, or 21 is required for AST parsing) and resolve environmental blockers.
2. **Analysis & Discovery**: Analyze the codebase to identify WebLogic-specific
APIs, EJB, JMS, JNDI, and configs, and discover clusters mathematically to
propose microservices boundaries.
3. **Technical Stack Alignment & Decomposition Review**: Align with the user on
target cloud modernization choices and present the customized architecture
plan as an interactive UI Artifact or markdown file for review and approval.
4. **Incremental Refactoring**: Refactor the code to remove WebLogic
dependencies and implement modern patterns.
5. **Configuration & Infrastructure Mapping**: Map WebLogic resources
(datasources, JMS, caching, file storage) to GCP services (Cloud SQL,
Pub/Sub, Memorystore, Cloud Storage).
6. **Containerization & Deployment**: Generate Dockerfiles and deployment
configurations.
7. **Verification, Audit, & Traceability**: Verify that the migration was
performed correctly, validate security gates, and establish complete
endpoint traceability in a walkthrough audit report.

--------------------------------------------------------------------------------

## Phase 0: Environment & Prerequisites Check

Before initiating the codebase analysis, verify that the environment meets the
technical prerequisites to ensure accurate static analysis.

> [!IMPORTANT] You **MUST** run a pre-flight check of the environment: 1. Verify
> that Maven is installed and accessible. 2. The AST parsing engine requires a
> compatible LTS JDK version (JDK 11, 17, or 21). The tools will automatically
> attempt to locate a compatible JDK under `/usr/lib/jvm/` or
> `/usr/local/buildtools/java/` and override `JAVA_HOME` if the default JDK is
> incompatible (e.g. JDK 26+). 3. Verify that Python dependencies are installed
> by executing: `pip install -r scripts/requirements.txt` 4. **Catastrophic
> Failure Halt**: If a compatible JDK is not found, if Maven compilation of the
> `ast_parser` project fails, or if more than 10% of the Java files yield
> `ParseError` during analysis, you **MUST STOP** and align with the user. Do
> **NOT** proceed to Phase 1 with disabled or failing AST parsing. Present the
> error to the user and ask them to resolve the environment issue (e.g.,
> installing a compatible JDK 11/17/21 or fixing Maven settings).

--------------------------------------------------------------------------------

## Phase 1: Analysis & Discovery

Scan the legacy monolith codebase iteratively to understand its structure,
identify migration blockers, and calculate optimal microservice boundaries
mathematically using the Louvain community detection engine.

> [!IMPORTANT] You **MUST** read and follow
> [decomposition_guide.md](./references/decomposition_guide.md) for instructions
> on executing multi-resolution exploration, utilizing generalization knobs,
> filtering "God Glue" shared utilities, and iterating internally until
> achieving a stable mathematical optimum.

--------------------------------------------------------------------------------

## Phase 2: Technical Stack Alignment & Decomposition Review

Align with the user on target cloud modernization choices, then present the
customized architecture plan as an interactive UI Artifact (if supported by the
environment) or a standard markdown file for their review and approval.

> [!IMPORTANT] You **MUST** read and follow
> [migration_plan_guide.md](./references/migration_plan_guide.md) for: 1.
> Conducting dynamic, context-relevant technical stack alignment with the user
> (adding custom questions for unique discovered blockers and omitting
> irrelevant ones). 2. Generating the customized `wls-migration-plan.md`
> artifact once and only once after all discovery and alignment are complete. 3.
> Managing the interactive human feedback and refinement loop (overwriting
> `wls-migration-plan.md` and stopping tool execution upon reviewer comments
> until explicitly approved).

--------------------------------------------------------------------------------

## Phase 3: Incremental Refactoring

Refactor the legacy codebase incrementally, service by service or module by
module, based on the approved migration plan.

> [!IMPORTANT] **Autonomy & Continuity**: Once the user approves Phase 2, you
> MUST proceed autonomously through the entire refactoring phase. Do NOT stop to
> ask for permission between services or files. Continuously refactor all
> services until Phase 3 is fully complete, unless a critical architectural
> ambiguity blocks your progress.

> [!IMPORTANT] **Java Version Policy**: ALWAYS target LTS Java versions (Java
> 17, Java 21, or Java 25). Do NOT use unreleased or experimental versions (e.g.
> Java 26).

> [!IMPORTANT] You **MUST** read and follow
> [refactoring_guide.md](./references/refactoring_guide.md) for detailed
> procedural steps on: * Initializing target workspace modules
> (`wls_migration/`). * Executing automated bulk refactoring via OpenRewrite and
> understanding its strict manual limitations. * Replacing JNDI lookups and
> migrating EJBs (Session beans and MDBs). * Aligning security constraints with
> legacy monolith maps and configuring token validation. * Decoupling
> presentation tiers (JSP/Struts to Angular/React SPAs and REST controllers). *
> Modernizing cloud-unfriendly patterns (File I/O, Batch, JavaMail, RMI, JMX). *
> Porting test suites and verifying compilation and functional equivalence.

> [!TIP] Use the following specialized reference guides for target code
> transformation patterns: *
> [refactoring_spring.md](./references/refactoring_spring.md) *
> [refactoring_quarkus.md](./references/refactoring_quarkus.md) *
> [web_modernization.md](./references/web_modernization.md) *
> [distributed_transactions.md](./references/distributed_transactions.md) *
> [legacy_remoting_and_jca.md](./references/legacy_remoting_and_jca.md) (for T3,
> RMI, CORBA, and JCA `.rar` adapters) *
> [sql_dialect_migration.md](./references/sql_dialect_migration.md) (for
> Oracle/PointBase SQL to ANSI SQL/PostgreSQL/MySQL) *
> [weblogic_specific_apis.md](./references/weblogic_specific_apis.md) (for
> custom security SPIs, JMX MBeans, Work Managers, and XML StAX) *
> [classloading_and_packaging.md](./references/classloading_and_packaging.md)
> (for EAR restructuring, `APP-INF/lib`, and `<library-ref>`) *
> [example_advanced_jms_migration.md](./assets/example_advanced_jms_migration.md)
> (for Unit-of-Order, Selectors, DLQs, and Messaging Bridges) *
> [example_soap_webservices_migration.md](./assets/example_soap_webservices_migration.md)
> (for SOAP, JAX-WS, CXF, and WS-Security) *
> [example_caching_and_clustering.md](./assets/example_caching_and_clustering.md)
> (for SFSBs, Coherence, and HTTP session replication to Redis) *
> [example_scheduling_and_timers.md](./assets/example_scheduling_and_timers.md)
> (for EJB timers, Quartz, and Cloud Scheduler/Jobs) *
> [example_observability_migration.md](./assets/example_observability_migration.md)
> (for structured JSON logging and OpenTelemetry tracing) *
> [example_servlet_filter_migration.md](./assets/example_servlet_filter_migration.md)
> (for filters, listeners, and `web.xml` / `weblogic.xml`) * View code templates
> in the `assets/` directory following the pattern `example_*.md`.

--------------------------------------------------------------------------------

## Phase 4: Configuration & Infrastructure Mapping

Map WebLogic infrastructure resources, descriptors, and services to native GCP
managed services.

> [!IMPORTANT] You **MUST** read and follow
> [gcp_mapping.md](./references/gcp_mapping.md) for detailed configuration steps
> and code snippets for mapping: * WebLogic Datasources to GCP Cloud SQL or
> AlloyDB (including dialect updates and SQL query conversions). * Plaintext
> secrets and credentials to GCP Secret Manager and environment variables. *
> WebLogic JMS Queues and Topics to GCP Pub/Sub Topics and Subscriptions. * File
> storage and caching to Google Cloud Storage (GCS), Filestore, Parallelstore,
> and Cloud Memorystore (Redis).

--------------------------------------------------------------------------------

## Phase 5: Containerization & Deployment

Prepare the refactored microservices for serverless container execution and
automated CI/CD pipelines.

> [!IMPORTANT] You **MUST** read and follow
> [deployment_guide.md](./references/deployment_guide.md) and
> [example_containerization.md](./assets/example_containerization.md) for
> detailed instructions on: * Authoring multi-stage framework-optimized
> Dockerfiles (including Quarkus native builds). * Generating Google Cloud Build
> configurations (`cloudbuild.yaml`). * Authoring Terraform manifests
> (`main.tf`, `variables.tf`) or declarative `gcloud` deployment commands for
> Cloud Run and Cloud Functions. * Documenting operational setup, Secret Manager
> variables, and JWT/security configurations in module READMEs.

--------------------------------------------------------------------------------

## Phase 6: Verification, Audit, & Traceability

Verify that the migration was performed correctly, validate security gates, and
establish complete endpoint traceability.

> [!IMPORTANT] You **MUST** read and follow
> [verification_guide.md](./references/verification_guide.md) for detailed
> instructions on: * Constructing the comprehensive Before/After Endpoint
> Traceability Matrix. * Executing local integration assertions and security
> access verification gates on secured vs. public routes. * Generating the
> mandatory `walkthrough.md` audit report artifact (`RequestFeedback: true` and
> `UserFacing: true`) documenting structural comparisons, refactoring
> deviations, compilation/test suite logs, and security warnings.

177 changes: 177 additions & 0 deletions .../cloud/google-cloud-weblogic-migration/assets/example_advanced_jms_migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
# Advanced WebLogic JMS & Messaging Modernization Guide

This guide provides concrete transformation recipes for modernizing advanced
WebLogic JMS features (Unit-of-Order, Message Selectors, Poison Messages/Dead
Letter Queues, and Messaging Bridges) when migrating to Google Cloud Pub/Sub in
Spring Boot and Quarkus microservices.

--------------------------------------------------------------------------------

## 1. JMS Unit-of-Order (UOO) to GCP Pub/Sub Ordering Keys

In legacy WebLogic JMS, setting a `UnitOfOrder` message property guarantees that
all messages sharing the same order name are delivered sequentially by a single
consumer instance.

### Before: Legacy WebLogic JMS Unit-of-Order

```java
// Legacy WebLogic JMS Unit-of-Order
import weblogic.jms.extensions.WLMessageProducer;
import javax.jms.*;

public class OrderDispatcher {
public void sendOrderedTransaction(Session session, MessageProducer producer, String accountId, String payload) throws JMSException {
TextMessage msg = session.createTextMessage(payload);
// Set WebLogic specific Unit-of-Order property
msg.setStringProperty("JMS_BEA_UnitOfOrder", accountId);
producer.send(msg);
}
}
```

### After: Google Cloud Pub/Sub Ordering Keys

In Google Cloud Pub/Sub, message ordering is guaranteed within a topic by
setting an **Ordering Key** on published messages and enabling message ordering
on the subscription.

#### Spring Boot (Spring Cloud GCP Pub/Sub)

```java
import com.google.cloud.spring.pubsub.core.PubSubTemplate;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class OrderDispatcher {
@Autowired
private PubSubTemplate pubSubTemplate;

public void sendOrderedTransaction(String accountId, String payload) {
// Publish message with Ordering Key set to accountId
pubSubTemplate.publish("account-transactions-topic", payload, Collections.emptyMap(), accountId);
}
}
```

#### Pub/Sub Subscription Configuration (Terraform / gcloud)

```hcl
resource "google_pubsub_subscription" "ordered_sub" {
name = "account-transactions-sub"
topic = google_pubsub_topic.transactions.name
enable_message_ordering = true # CRITICAL: Required for ordering keys
}
```

--------------------------------------------------------------------------------

## 2. JMS Message Selectors to Pub/Sub Subscription Filters

WebLogic JMS consumers frequently use SQL-92 message selectors (e.g.,
`priority = 'HIGH' AND region = 'US'`) to filter incoming messages at the broker
level.

### Before: Legacy WebLogic JMS Message Selector

```java
// Legacy WebLogic JMS Selector
String selector = "hospital_code = 'GENERAL' AND emergency_level >= 3";
MessageConsumer consumer = session.createConsumer(queue, selector);
```

### After: Google Cloud Pub/Sub Filter Expressions

GCP Pub/Sub supports broker-level **Subscription Filter Expressions** matching
message attributes.

#### Spring Boot Publisher (Setting Attributes)

```java
import com.google.cloud.spring.pubsub.support.GcpPubSubHeaders;
import org.springframework.messaging.support.MessageBuilder;

public void publishAlert(String hospitalCode, int emergencyLevel, String payload) {
Map<String, String> attributes = Map.of(
"hospital_code", hospitalCode,
"emergency_level", String.valueOf(emergencyLevel)
);
pubSubTemplate.publish("emergency-alerts-topic", payload, attributes);
}
```

#### Pub/Sub Subscription Filter Configuration

```hcl
resource "google_pubsub_subscription" "filtered_sub" {
name = "general-hospital-emergencies-sub"
topic = google_pubsub_topic.alerts.name

# Pub/Sub filter syntax matching SQL-92 selector logic
filter = "attributes.hospital_code = \"GENERAL\" AND attributes.emergency_level >= \"3\""
}
```

--------------------------------------------------------------------------------

## 3. Poison Messages & Dead Letter Queues (DLQ)

In WebLogic JMS, error destinations and redelivery limits prevent failing
messages (poison messages) from looping infinitely.

### After: Google Cloud Pub/Sub Dead-Letter Topics & Exponential Backoff

Configure Dead-Letter Topics (DLT) and retry policies directly on the GCP
Pub/Sub subscription:

```hcl
resource "google_pubsub_topic" "dead_letter_topic" {
name = "emergency-alerts-dlq"
}

resource "google_pubsub_subscription" "robust_sub" {
name = "emergency-alerts-sub"
topic = google_pubsub_topic.alerts.name

# Dead-Letter Policy (Poison Message Handling)
dead_letter_policy {
dead_letter_topic = google_pubsub_topic.dead_letter_topic.id
max_delivery_attempts = 5
}

# Exponential Backoff Retry Policy
retry_policy {
minimum_backoff = "10s"
maximum_backoff = "600s"
}

# Acknowledge deadline for long-running message consumers (up to 600s)
ack_deadline_seconds = 600
}
```

> [!WARNING] **Ack Deadlines & Consumer Idempotency**: If message processing
> exceeds `ack_deadline_seconds`, GCP Pub/Sub will automatically redeliver the
> message to another worker instance. All consumer logic MUST be designed to be
> completely **idempotent** (e.g., checking message deduplication IDs in Cloud
> SQL/Redis before execution) to prevent duplicate processing.

--------------------------------------------------------------------------------

## 4. WebLogic Messaging Bridges to GCP Pub/Sub Connectors

WebLogic Messaging Bridges connect external message brokers (e.g., IBM MQ, Tibco
EMS, or Apache ActiveMQ) to internal WebLogic JMS queues.

### After: Cloud-Native Bridge Strategies

In serverless containers, replace embedded WebLogic Messaging Bridges with:

1. **Google Cloud Pub/Sub Connectors**: Use managed connectors (like
Kafka-to-PubSub or MQ-to-PubSub sinks/sources in Google Cloud Dataflow).
2. **Dedicated Ingestion Worker Microservice**: If specific MQ protocols are
required, deploy a lightweight Spring Boot worker using Spring JMS
(`spring-boot-starter-activemq` or IBM MQ client) that listens to the
external broker and forwards messages asynchronously into GCP Pub/Sub
topics.
Loading