Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
110 changes: 110 additions & 0 deletions .github/workflows/eureka-provider.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

name: Eureka provider lifecycle

on:
pull_request:
paths:
- "shenyu-extension/shenyu-extension-eureka/**"
- "pom.xml"
- ".github/workflows/eureka-provider.yml"
workflow_dispatch:

jobs:
live-provider:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@v4
with:
path: store
- uses: actions/checkout@v4
with:
repository: apache/shenyu
ref: 31d90ba4022c3c49bbdd2aa507cb4e1f5fc8b87f
path: core
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "17"
cache: maven
- name: Install retained core APIs and lifecycle
working-directory: core
run: >-
./mvnw -B -ntp -pl shenyu-spring-boot-starter/shenyu-spring-boot-starter-registry -am install
-DskipTests -DskipRemoteResources=true -Djacoco.skip=true -Dmaven.javadoc.skip=true
- name: Build disposable real Eureka server
working-directory: core
run: >-
./mvnw -B -ntp -f shenyu-examples/shenyu-examples-eureka/pom.xml package
-DskipTests -DskipRemoteResources=true -Djacoco.skip=true -Dmaven.javadoc.skip=true -Ddocker.skip=true
- name: Prepare real Admin and gateway classpaths
working-directory: core
run: >-
./mvnw -B -ntp -pl shenyu-admin,shenyu-bootstrap,shenyu-spring-boot-starter/shenyu-spring-boot-starter-registry -am
install dependency:build-classpath -DskipTests -Dmdep.outputFile=target/eureka-classpath.txt -DincludeScope=runtime
-DskipRemoteResources=true -Djacoco.skip=true -Dmaven.javadoc.skip=true
- name: Start Eureka and await readiness
shell: bash
run: |
nohup java -Xms128m -Xmx384m -jar core/shenyu-examples/shenyu-examples-eureka/target/shenyu-examples-eureka.jar \
--server.port=8761 --eureka.client.register-with-eureka=false --eureka.client.fetch-registry=false \
--eureka.server.enable-self-preservation=false > eureka-server.log 2>&1 &
echo "$!" > eureka-server.pid
for attempt in $(seq 1 90); do
if curl --fail --silent http://127.0.0.1:8761/eureka/apps >/dev/null; then
exit 0
fi
sleep 1
done
cat eureka-server.log
exit 1
- name: Verify external provider and starter
working-directory: core
run: >-
./mvnw -B -ntp -f ../store/pom.xml
-pl shenyu-extension/shenyu-extension-eureka/shenyu-spring-boot-starter-registry-eureka -am
verify dependency:build-classpath apache-rat:check -Peureka-live
-Dshenyu.version=2.7.3-SNAPSHOT
-Dmdep.outputFile=target/eureka-classpath.txt -DincludeScope=runtime
-Deureka.test.url=http://127.0.0.1:8761/eureka/
-Deureka.client.refresh.interval=1
-Deureka.appinfo.initial.replicate.time=1 -Deureka.appinfo.replicate.interval=1
-DskipRemoteResources=true -Djacoco.skip=true -Dmaven.javadoc.skip=true
- name: Verify external Eureka through real Admin and gateway
run: >-
python store/shenyu-extension/shenyu-extension-eureka/e2e/run-local.py
--core core --store store --java "$JAVA_HOME/bin/java"
--eureka http://127.0.0.1:8761/eureka --output store/target/eureka-e2e
- name: Stop disposable server
if: always()
shell: bash
run: |
if [ -f eureka-server.pid ]; then
kill "$(cat eureka-server.pid)" || true
fi
- uses: actions/upload-artifact@v4
if: always()
with:
name: eureka-provider-results
retention-days: 7
path: |
eureka-server.log
store/shenyu-extension/shenyu-extension-eureka/**/target/surefire-reports/
store/shenyu-extension/shenyu-extension-eureka/**/target/failsafe-reports/
store/target/eureka-e2e/*.log
store/target/eureka-e2e/result.json

205 changes: 205 additions & 0 deletions docs/plugin-store-eureka.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# Eureka plugin-store migration

Prepared cutover for apache/shenyu#7596. The receiving extension owns
shenyu-registry-eureka and shenyu-spring-boot-starter-registry-eureka.
The main-repository removal must remain a draft until compatible artifacts are
published and the complete Admin/gateway deployment gate below passes.
Source preparation, local snapshot installation and this guide are not publication.

## Compatibility and ownership

Initial development validation used store 2.7.1-SNAPSHOT, core 2.7.2-SNAPSHOT at cutover commit cfc267c8b (base 87c22dde7),
Microsoft OpenJDK 17.0.18 and Netflix eureka-client/eureka-client-jersey3 2.0.2.
The disposable server uses ShenYu's Spring Cloud Eureka example (4.1.2).
These are development coordinates and test scope, not a released compatibility matrix.

The current Eureka lifecycle workflow pins the paired removal commit
31d90ba4022c3c49bbdd2aa507cb4e1f5fc8b87f from apache/shenyu#7960 and explicitly
builds the receiving modules with `-Dshenyu.version=2.7.3-SNAPSHOT`. Store artifact
coordinates remain 2.7.1-SNAPSHOT. The workflow installs the selected core reactor
before resolving the Admin/gateway runtime classpaths, so validation uses that
source pair rather than an older cached core snapshot. This source-pair update
does not establish a published compatibility matrix or an upstream CI pass.

The provider keeps its packages, non-singleton @Join annotation, eureka type key,
SPI resource and existing lease/registration behavior. Runtime parity testing also
corrects identity-only update comparison: changed upstream payloads produce updates;
an IP/port change removes the old URL before adding its replacement. Polling-failure
recovery remains covered.
No core factory dispatch or enum/SQL key changes are needed. It resolves through
ShenyuInstanceRegisterRepositoryFactory with an external provider JAR.
This transfer does not redesign Eureka instance identity, authentication or refresh policy.
In particular, current identity is derived by Eureka's configured instance builder;
do not treat the single-identity update test as certification for multiple replicas
using an identical default identity.

The registry adapter is independent of Spring Cloud backend service discovery.
The generic main-repository Eureka server example and Spring Cloud transport E2E
fixtures remain usable while their broader test ownership is reviewed. They are not
default Admin/bootstrap registry dependencies and do not justify retaining the in-tree
registry provider.

## Install

Use a published store version explicitly announced compatible with the selected
core release. Keep one owner per Maven group/artifact/version. The same provider
coordinates/packages cannot coexist from both repositories on a runtime classpath.

For gateway instance registration, add:

```xml
<dependency>
<groupId>org.apache.shenyu</groupId>
<artifactId>shenyu-spring-boot-starter-registry-eureka</artifactId>
<version>${store.version}</version>
</dependency>
```

The external starter retains bound-port registration and owns provider cleanup on
application-context shutdown. It explicitly excludes
the core starter's old transitive Eureka provider. It contributes its external
provider instead. Other retained compatibility providers may remain on that
starter's classpath; exclude those explicitly if building a minimal assembly.

Admin discovery and SDK deployments that already own their registration/discovery
wiring need the provider rather than the gateway starter:

```xml
<dependency>
<groupId>org.apache.shenyu</groupId>
<artifactId>shenyu-registry-eureka</artifactId>
<version>${store.version}</version>
</dependency>
```

The provider JAR isolates Jersey 3 transport, HK2 and JAX-RS classes under private
packages. This avoids the older Jersey providers found on the full Bootstrap
classpath while retaining shared ShenYu API/SPI class identity. Resolve the complete
runtime dependency closure when installing into lib/ distributions. Do not copy only the provider
JAR or replace retained core API/SPI classes with bundled duplicates.
The source remains ASF/Apache-2.0. Preserve Netflix/Jersey and resolved third-party
licenses/notices in custom binary distributions.

## Enable and verify

Gateway configuration retains its keys:

```yaml
shenyu:
register:
enabled: true
registerType: eureka
serverLists: http://eureka:8761/eureka/
props:
name: shenyu-gateway
host: gateway
```

The listener uses the actually bound server port unless props.port explicitly
overrides it. Existing SDK register-type=eureka and server-list settings retain
their current meaning; HTTP annotation registration to Admin is a separate flow.
Do not change Admin's HTTP client-registration transport to eureka merely to
enable the instance/discovery adapter.

The starter tests cover disabled-by-default wiring, external SPI construction,
configuration binding and one registration at the bound port. Unit tests retain
the source module's polling and shutdown checks. The opt-in eureka-live Maven
profile launches no fake service: it requires -Deureka.test.url pointing at a
real disposable server and verifies registration, initial discovery, an instance
update/refresh, deregistration and watch shutdown.

Example verification from a checkout with the core Maven wrapper available:

```text
cd core
./mvnw -f ../store/pom.xml -pl shenyu-extension/shenyu-extension-eureka/shenyu-spring-boot-starter-registry-eureka -am test -Dshenyu.version=2.7.3-SNAPSHOT
./mvnw -f ../store/pom.xml -pl shenyu-extension/shenyu-extension-eureka/shenyu-registry-eureka -am verify -Dshenyu.version=2.7.3-SNAPSHOT -Peureka-live -Deureka.test.url=http://127.0.0.1:8761/eureka/
```

The live profile must fail if its server URL is missing/unreachable; ordinary unit
tests do not silently substitute for it. Its CI lane builds the server and core
API artifacts from a pinned main commit, then runs the receiving provider.

## Cutover gates

1. Merge/review the receiving code and confirm published artifact ownership and
compatible core/store versions without duplicate coordinates.
2. Run the live provider lane and a complete disposable Eureka + Admin + bootstrap
environment using only the external runtime provider. Verify gateway instance
registration at its bound address, discovery, config refresh, deregistration,
healthy sibling behavior and restart/rollback. Record image/JAR digests and logs.
3. Package main Admin/bootstrap after removal and inspect dependency trees and
release licenses. Keep other registry implementations and SDK boundary tests green.
4. Publish external artifacts first, then merge the main removal in the coordinated
release and announce migration/rollback versions. Do not close #7596 before the
complete deployment and publication evidence exists.

Local evidence on 2026-10-21: seven unit/SPI/starter tests pass with Checkstyle
and RAT, and a separate real-server provider lifecycle test passes. The complete
local process E2E passes 13 checkpoints using actual Eureka, H2 Admin and bootstrap
JVMs with the external provider JAR. It verifies class origins in both server
processes, bound-port registration, discovery/proxying, endpoint refresh and old
endpoint removal, graceful gateway deregistration, gateway restart, healthy sibling
preservation and final route removal. The harness uses a stdin-controlled Spring
context for graceful shutdown on Windows as well as Linux.

The runtime source pair is core cfc267c8b and extension 8bf73dd; the tested registry
JAR SHA-256 is e5fefda48d00b17cf505549e100479b87c04a5d83ca7c0ef6c3547225fc8fc31.
The receiving repository retains the machine-readable process result under its
Eureka e2e/results directory. The CI lane is configured to repeat the live provider
and complete process tests; its configuration alone is not a passing CI result.
Docker image/container execution was not run.

Current-core local evidence on 2026-11-06: store runtime code at 0921f1a43 and
core removal commit 31d90ba40 pass seven unit/SPI/starter tests, one live provider
test and all 13 full-process checkpoints on OpenJDK 21.0.13/Linux. The selected
163-module Admin/bootstrap reactor builds with Checkstyle and RAT; its tests are
compiled but skipped. Neither default Admin nor bootstrap runtime classpath
contains the Eureka provider or Netflix Eureka dependencies before the external
closure is added. The machine-readable result and provider JAR digest are in
`shenyu-extension/shenyu-extension-eureka/e2e/results/linux-jdk21-current-core.json`.
The disposable server was compiled locally with `-Dmaven.compiler.release=`
because the available runtime lacks `ct.sym`; Java 17 source/target settings
remain unchanged. The committed workflow still uses Temurin 17. This local
process result does not replace Docker IT/E2E, upstream workflow approval or
compatible artifact publication.

To reproduce the full process harness, first install core Admin, bootstrap and the
retained registry starter with dependency:build-classpath, setting
-Dmdep.outputFile=target/eureka-classpath.txt -DincludeScope=runtime. Package the
external Eureka starter reactor with the same classpath goal and
`-Dshenyu.version=2.7.3-SNAPSHOT`. Start the real Eureka
example server, then run e2e/run-local.py with --core, --store, --java, --eureka and
--output paths. The workflow records the complete wrapper commands and retains
redacted process/class-origin logs plus result.json.

## Upgrade and rollback

Back up the Admin database, registry configuration and exact old images/JARs.
Install the complete external closure in staging, remove the in-tree provider
version, and keep the eureka key and application/instance configuration unchanged.
Confirm discovery refresh and route/instance removal after a process dies; do not
infer success from a Maven build or an HTTP registration acknowledgement alone.

For rollback, stop/drain the new processes and restore the last core distribution
that included the provider, removing the external copy. Preserve database/type
keys and Eureka applications. Clean up or expire obsolete instance records using
the deployment's existing lease/identity procedure. Do not clear the whole registry
or run two versions with identical classes in the same JVM.
1 change: 1 addition & 0 deletions shenyu-extension/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -27,5 +27,6 @@
<modules>
<module>shenyu-extension-consul</module>
<module>shenyu-extension-polaris</module>
<module>shenyu-extension-eureka</module>
</modules>
</project>
36 changes: 36 additions & 0 deletions shenyu-extension/shenyu-extension-eureka/e2e/ExternalProcess.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

import java.util.Arrays;
import org.springframework.boot.SpringApplication;
import org.springframework.context.ConfigurableApplicationContext;

/**
* A disposable process controlled over stdin, including graceful shutdown on Windows.
*/
public final class ExternalProcess {
private ExternalProcess() {
}

public static void main(final String[] args) throws Exception {
ConfigurableApplicationContext context = SpringApplication.run(Class.forName(args[0]), Arrays.copyOfRange(args, 1, args.length));
System.in.read();
context.close();
System.exit(0);
}
}

Loading