This is an automated email from the ASF dual-hosted git repository.
Aias00 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shenyu.git
The following commit(s) were added to refs/heads/master by this push:
new 6e4cb4cd98 docs(apollo): announce staged plugin-store migration (#7627)
6e4cb4cd98 is described below
commit 6e4cb4cd98dc7464131a9a2e27ce4fe3d295bf5f
Author: redyyang <[email protected]>
AuthorDate: Thu Oct 15 12:58:25 2026 +0800
docs(apollo): announce staged plugin-store migration (#7627)
---
README.md | 2 +-
RELEASE-NOTES.md | 8 ++
docs/plugin-store-apollo.md | 210 ++++++++++++++++++++++++++++++++++++++++++++
shenyu-registry/README.md | 2 +-
4 files changed, 220 insertions(+), 2 deletions(-)
diff --git a/README.md b/README.md
index aa217f08d2..44efde0696 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ Apache ShenYu is a Java-based gateway for service proxying,
protocol conversion,
| Registration and discovery | Client SDKs register service addresses and API
metadata with Admin. Registry integrations support discovery; an optional
Kubernetes controller reconciles Ingress and Endpoints resources. |
| Security and traffic control | WAF, signing, authentication plugins, load
balancing, rate limiting, and fault tolerance through Resilience4j and
Sentinel; deprecated Hystrix remains available as an external plugin (see
[plugin-store-hystrix](docs/plugin-store-hystrix.md)). |
| Caching and transformation | In-memory or Redis-backed response caching, URL
rewriting, redirection, and request/response transformation. |
-| Dynamic configuration | Admin persists plugins, selectors, rules, metadata,
and authentication data. WebSocket sync is the default; HTTP long polling,
ZooKeeper, Nacos, etcd, and Apollo are available. Consul sync is available as
an external extension (see [plugin-store-consul](docs/plugin-store-consul.md)).
Gateway replicas apply updates to their local caches. |
+| Dynamic configuration | Admin persists plugins, selectors, rules, metadata,
and authentication data. WebSocket sync is the default; HTTP long polling,
ZooKeeper, Nacos, and etcd are available. Apollo remains available during its
deprecation release and is planned to move to an external extension (see
[Apollo migration](docs/plugin-store-apollo.md)). Consul sync is available as
an external extension (see [plugin-store-consul](docs/plugin-store-consul.md)).
Gateway replicas apply updates [...]
| Observability | Metrics and logging plugins, including Kafka and
Elasticsearch destinations; email and DingTalk alerts from Admin. |
| AI and MCP | AI proxy, prompt processing, token limits, sensitive-word
filtering, AI request/response transformation, and an MCP server plugin with
SSE and Streamable HTTP. |
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 65a7892c91..fb14b1835e 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -2,6 +2,14 @@
### API Changes
+- Apollo's in-tree registry, sync adapter, Admin listener and sync starter are
+ deprecated for transfer to plugin-store (#7599). All four remain available in
+ the release carrying this notice. Removal requires dev-list consensus, a full
+ released deprecation cycle, compatible external artifact publication and an
+ announced rollback window; no removal release is scheduled. See the
+ [migration guide](docs/plugin-store-apollo.md). Existing `apollo` type names,
+ keys and `ApolloPathConstants` remain compatibility contracts.
+
- `MemorySafeLRUMap` is deprecated since 2.7.2. The class, public constructors,
serialization identifier and existing behavior are retained for downstream
source and binary compatibility. No removal release is scheduled; a future
diff --git a/docs/plugin-store-apollo.md b/docs/plugin-store-apollo.md
new file mode 100644
index 0000000000..1c6bd65bae
--- /dev/null
+++ b/docs/plugin-store-apollo.md
@@ -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.
diff --git a/shenyu-registry/README.md b/shenyu-registry/README.md
index d91f0f8ef0..66ea84e1b5 100644
--- a/shenyu-registry/README.md
+++ b/shenyu-registry/README.md
@@ -40,7 +40,7 @@ runtime classpath, using the same ShenYu version as the
application:
| `zookeeper` | `shenyu-registry-zookeeper` |
| `etcd` | `shenyu-registry-etcd` |
| `nacos` | `shenyu-registry-nacos` |
-| `apollo` | `shenyu-registry-apollo` |
+| `apollo` | `shenyu-registry-apollo`; in-tree deprecation and planned
external ownership: [migration guide](../docs/plugin-store-apollo.md) |
| `eureka` | `shenyu-registry-eureka` |
| `kubernetes` | `shenyu-registry-kubernetes` |
