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
8 changes: 6 additions & 2 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ jobs:
CORE_API_DIR="${RUNNER_TEMP}/shenyu-core-api"
git init "${CORE_API_DIR}"
git -C "${CORE_API_DIR}" remote add origin https://github.com/apache/shenyu.git
git -C "${CORE_API_DIR}" fetch --depth 1 origin 91bd8d0c18fae8a1b297a3a752ab3282643bc7f9
git -C "${CORE_API_DIR}" fetch --depth 1 origin 971354fef10260e46e09ed951e0bff4d9b5e4040
git -C "${CORE_API_DIR}" checkout --detach FETCH_HEAD
"${CORE_API_DIR}/mvnw" -B -ntp -f "${CORE_API_DIR}/pom.xml" -pl shenyu-plugin/shenyu-plugin-logging/shenyu-plugin-logging-common,shenyu-web,shenyu-admin-listener/shenyu-admin-listener-api,shenyu-registry/shenyu-registry-api,shenyu-plugin/shenyu-plugin-global,shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-divide,shenyu-plugin/shenyu-plugin-uri,shenyu-plugin/shenyu-plugin-httpclient,shenyu-plugin/shenyu-plugin-response -am install -DskipTests -Dmaven.javadoc.skip=true -Drat.skip=true -Djacoco.skip=true -DskipRemoteResources=true
"${CORE_API_DIR}/mvnw" -B -ntp -f "${CORE_API_DIR}/pom.xml" -pl shenyu-sync-data-center/shenyu-sync-data-api,shenyu-registry/shenyu-registry-core,shenyu-plugin/shenyu-plugin-logging/shenyu-plugin-logging-common,shenyu-web,shenyu-admin-listener/shenyu-admin-listener-api,shenyu-registry/shenyu-registry-api,shenyu-plugin/shenyu-plugin-global,shenyu-plugin/shenyu-plugin-proxy/shenyu-plugin-divide,shenyu-plugin/shenyu-plugin-uri,shenyu-plugin/shenyu-plugin-httpclient,shenyu-plugin/shenyu-plugin-response -am install -DskipTests -Dmaven.javadoc.skip=true -Drat.skip=true -Djacoco.skip=true -DskipRemoteResources=true
- name: Prepare original-suite core APIs
run: |
CORE_API_DIR="${RUNNER_TEMP}/shenyu-core-api"
Expand All @@ -62,6 +62,10 @@ jobs:
bash script/plugin-store/prepare-core-artifacts.sh "${CORE_API_DIR}"
- name: Build, test, check style, and verify licenses
run: mvn -B -ntp clean verify -Dapi.version=1.44
- name: Verify the complete external Apollo stack
run: |
mvn -B -ntp -pl shenyu-extension/shenyu-extension-apollo/shenyu-admin-listener-apollo,shenyu-extension/shenyu-extension-apollo/shenyu-sync-data-apollo,shenyu-extension/shenyu-extension-apollo/shenyu-registry-apollo,shenyu-extension/shenyu-extension-apollo/shenyu-spring-boot-starter-sync-data-apollo -am clean verify -Dapi.version=1.44
python3 script/plugin-store/check-apollo-packaging.py
- name: Compile preserved original test and example assets
run: mvn -B -ntp -Pintegration-tests,e2e,examples test-compile -DskipTests -Dapi.version=1.44
- name: Verify store-owned SQL installation
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -266,3 +266,7 @@ starter plus gateway plus backend end-to-end fixture is not included in this cha
In order of registration, More access companies are welcome to register at [https://github.com/apache/shenyu/issues/68](https://github.com/apache/shenyu/issues/68) (For open source users only) .

All Users : [Known Users](https://shenyu.apache.org/community/user-registration)

### Apollo integration

The [Apollo extension](shenyu-extension/shenyu-extension-apollo/README.md) builds its listener, sync adapter, registry and starter together. See [staged migration](docs/plugin-store-apollo.md) for the one-release deprecation and publication contract.
210 changes: 210 additions & 0 deletions docs/plugin-store-apollo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,210 @@
<!--
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.
-->
# Apollo plugin-store migration

## Status and deprecation cycle

Apollo is currently an optional, supported in-tree integration. Issue [#7599](https://github.com/apache/shenyu/issues/7599)
proposes transferring its registry, data-sync, Admin listener and gateway starter to
[plugin-store](https://github.com/apache/shenyu-plugin-store), extending [#7306](https://github.com/apache/shenyu/issues/7306).
This guide is the advance deprecation notice: the in-tree modules remain available
for the release carrying this notice. No removal release has been selected.
The separate removal PR is a draft and must not be merged in that deprecation release.

| Stage | Required action |
| --- | --- |
| Agreement | Obtain and link the dev-list decision approving Apollo externalization. |
| Deprecation release | Ship this notice and migration guide in a core release while retaining all four in-tree modules. Record that released version publicly. |
| Receiving parity | Build/test all four modules together in plugin-store, verify external SPI loading and unchanged sync/registry configuration. |
| Publication | Announce compatible core/store versions, publish external artifacts before cutover, and reserve one publisher per Maven group/artifact/version. |
| Later core release | After the deprecation release has shipped, merge the separate removal, update the release inventory, and announce the rollback window. |

Do not treat creating PRs, merging documentation, or producing local snapshot JARs
as completing the dev-list decision, a released deprecation cycle, or artifact publication.
Keep the issue open until all stages and their release evidence are complete.

## Artifact ownership and installation

The receiving `shenyu-extension-apollo` reactor owns these artifacts together:

- `shenyu-admin-listener-apollo`
- `shenyu-sync-data-apollo`
- `shenyu-registry-apollo`
- `shenyu-spring-boot-starter-sync-data-apollo`

The preparation branch uses store `2.7.1-SNAPSHOT` against core `2.7.2-SNAPSHOT`.
These are development coordinates, not an announced release compatibility matrix.
For deployment, select the published store release declared compatible with your core release.
Use the core version for retained APIs and the store version for **all four** Apollo artifacts.
Keep exactly one provider version on each runtime classpath; the in-tree and external
implementations retain identical packages and must not coexist.

Admin needs:

```xml
<dependency>
<groupId>org.apache.shenyu</groupId>
<artifactId>shenyu-admin-listener-apollo</artifactId>
<version>${store.version}</version>
</dependency>
```

Gateway data synchronization needs:

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

Applications using Apollo instance registration or SDK instance discovery additionally need:

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

Gateway registration also requires the retained core `shenyu-spring-boot-starter-registry`;
SDK discovery requires the appropriate SDK starter. Apollo was never included in the
compatibility registry starter, so it remains an explicit provider dependency.
For binary distributions, resolve the complete runtime dependency closure into `lib/`,
replace old Apollo JARs, and retain the extension's licensing information and dependency notices.

Shading continues to package Apollo client dependencies, but excludes retained ShenYu
API artifacts and sibling extension modules. API classes come from the application's core artifacts, preserving
class identity for external SPI loading. The published POM retains runtime dependencies.

## Enable Admin and gateway synchronization

Admin keeps its existing property prefix and portal publishing settings:

```yaml
shenyu:
sync:
websocket:
enabled: false
apollo:
appId: shenyu
meta: http://apollo-config-service:8080
portalUrl: http://apollo-portal:8070
env: DEV
clusterName: default
namespace: application
token: ${APOLLO_OPENAPI_TOKEN}
operatorUser: apollo
```

Gateway keeps the same reading settings; remove or disable the previous sync channel:

```yaml
shenyu:
namespace: 649330b6-c2d7-4edc-be8e-8a54df9eb385
sync:
websocket:
urls: false
apollo:
appId: shenyu
meta: http://apollo-config-service:8080
env: DEV
clusterName: default
namespace: application
accessKey: ${APOLLO_ACCESS_KEY:}
```

The portal OpenAPI token and config-service access key serve different APIs.
Ensure the publishing app, environment, cluster and Apollo namespace match the reader.
The preserved reader calls Apollo `ConfigService.getAppConfig()`, so the example uses
`application`. This migration does not add arbitrary namespace selection.
The ShenYu namespace ID is a separate tenant prefix inside Apollo item keys.
The Apollo client sets JVM-wide app/meta/cluster properties; preserve the existing
process-level configuration when using sync and registry together.

## Registry and SPI contract

The external JAR continues to publish:

```text
META-INF/shenyu/org.apache.shenyu.registry.api.ShenyuInstanceRegisterRepository
apollo=org.apache.shenyu.registry.apollo.ApolloInstanceRegisterRepository
```

`ShenyuInstanceRegisterRepositoryFactory.loadRepository("apollo")` resolves that
resource without any factory or core runtime change, and preserves the non-singleton provider.
Registry configuration remains:

```yaml
shenyu:
register:
enabled: true
registerType: apollo
serverLists: http://apollo-config-service:8080
props:
appId: shenyu
portalUrl: http://apollo-portal:8070
token: ${APOLLO_OPENAPI_TOKEN}
env: DEV
clusterName: default
namespace: application
```

SDK discovery uses the same `apollo` type and registry settings via its existing SDK
configuration; it does not replace backend HTTP annotation/API registration.
Instance registration writes persistent portal items and publishes the namespace.
Existing shutdown removes listeners; it does not deregister persistent instance items.
Preserve that behavior during migration and apply your existing instance-removal procedure.

## Stored keys and shared compatibility shim

| Data | Existing Apollo item key |
| --- | --- |
| Plugin | `<shenyuNamespace>.plugin.<pluginName>` |
| Selector | `<shenyuNamespace>.selector.<pluginName>.<selectorId>` |
| Rule | `<shenyuNamespace>.rule.<pluginName>.<selectorId>.<ruleId>` |
| Authentication | `<shenyuNamespace>.auth.<appKey>` |
| Metadata | `<shenyuNamespace>.meta.<metadataId>` |
| Proxy selector | `<shenyuNamespace>.proxy.selector.<pluginName>.<selectorId>` |
| Discovery upstream | `<shenyuNamespace>.discovery.<pluginName>.<selectorId>` |
| Instance | `/shenyu/register/instance/<appName>/<host>:<port>` |

The existing `.list` index items under each category/group are retained alongside the data keys.
JSON DTOs, key prefixes, namespace IDs and the `apollo` type remain unchanged.
`org.apache.shenyu.common.constant.ApolloPathConstants` stays in core as a small
constants/path compatibility shim with no Apollo SDK dependency. Do not duplicate that
class in store JARs or migrate/delete existing keyspaces as part of this transfer.

The client versions remain `apollo-client`, `apollo-openapi` and `apollo-core` `2.1.0`.
Source and the Apollo clients are Apache-2.0; preserve licenses when assembling custom packages.
Existing unit tests, real Apollo `DefaultConfig` listener filtering tests and starter
configuration tests move with their modules. Those tests do not claim a full live Apollo
portal/config-service deployment; validate your staging deployment before production cutover.

## Upgrade and rollback

1. After publication and release gates pass, back up the Admin database and Apollo
application/namespace configuration, recording exact core/store versions and deployed JARs.
2. Verify the external artifacts in staging using unchanged namespace, endpoints, tokens,
keys and registry properties. Check initial sync, create/update/delete and instance updates.
3. Roll Admin and gateways with complete external dependency closures, then confirm
subsequent changes propagate and existing instance discovery still works.
4. Retain the last in-tree release for the announced rollback window. To roll back,
restore its images/JARs and configuration and remove the external Apollo versions.
Reuse the same Admin database and Apollo keyspace; do not clear either during rollback.
28 changes: 28 additions & 0 deletions examples/apollo/admin/application.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# 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.

shenyu:
sync:
apollo:
appId: shenyu
meta: http://apollo-config-service:8080
env: DEV
clusterName: default
namespace: application
portalUrl: http://apollo-portal:8070
token: ${APOLLO_OPENAPI_TOKEN}
operatorUser: apollo
websocket:
enabled: false
26 changes: 26 additions & 0 deletions examples/apollo/gateway/application.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# 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.

shenyu:
sync:
apollo:
appId: shenyu
meta: http://apollo-config-service:8080
env: DEV
clusterName: default
namespace: application
accessKey: ${APOLLO_ACCESS_KEY:}
websocket:
urls: false
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# 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.

# apollo:
# meta: http://localhost:8080
# appId: shenyu
# portalUrl: http://localhost:8070
# env: dev
# clusterName: test
# namespace: application
# token: 0fff5645fc74ee5e0d63a6389433c8c8afc0beea31eed0279ecc1c8961d12da9
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 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.

# apollo:
# appId: shenyu
# meta: http://localhost:8080
# env: dev
# clusterName: test
# namespace: application
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 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.

# apollo:
# appId: shenyu
# meta: http://localhost:8080
# env: dev
# clusterName: test
# namespace: application
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 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.

# apollo:
# appId: shenyu
# meta: http://localhost:8080
# env: dev
# clusterName: test
# namespace: application
Loading