diff --git a/README.md b/README.md index aa217f08d238..44efde0696d4 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 to their local caches. | | 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 65a7892c9142..fb14b1835e1b 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 000000000000..1c6bd65baeb2 --- /dev/null +++ b/docs/plugin-store-apollo.md @@ -0,0 +1,210 @@ + +# 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 + + org.apache.shenyu + shenyu-admin-listener-apollo + ${store.version} + +``` + +Gateway data synchronization needs: + +```xml + + org.apache.shenyu + shenyu-spring-boot-starter-sync-data-apollo + ${store.version} + +``` + +Applications using Apollo instance registration or SDK instance discovery additionally need: + +```xml + + org.apache.shenyu + shenyu-registry-apollo + ${store.version} + +``` + +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 | `.plugin.` | +| Selector | `.selector..` | +| Rule | `.rule...` | +| Authentication | `.auth.` | +| Metadata | `.meta.` | +| Proxy selector | `.proxy.selector..` | +| Discovery upstream | `.discovery..` | +| Instance | `/shenyu/register/instance//:` | + +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 d91f0f8ef0e5..66ea84e1b5c2 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` |