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
2 changes: 1 addition & 1 deletion .github/scripts/check-registry-dependencies.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
import sys
from pathlib import Path

PROVIDERS = ("zookeeper", "etcd", "nacos", "apollo", "eureka", "kubernetes")
PROVIDERS = ("zookeeper", "nacos", "apollo", "eureka", "kubernetes")
COMPATIBILITY_PROVIDERS = set(PROVIDERS) - {"apollo"}
LEAN_MODULES = (
"shenyu-registry/shenyu-registry-api",
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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. |
| Dynamic configuration | Admin persists plugins, selectors, rules, metadata, and authentication data. WebSocket sync is the default; HTTP long polling, ZooKeeper, and Nacos are available; etcd sync and registry use [plugin-store-etcd](docs/plugin-store-etcd.md). 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. |

Expand Down
5 changes: 5 additions & 0 deletions RELEASE-NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

### API Changes

- The planned etcd cutover transfers the complete integration to plugin-store
while preserving the `etcd` type and keyspace (#7597). Merge requires the
released deprecation cycle, receiving validation, compatible publication and
rollback announcement. See [the migration guide](docs/plugin-store-etcd.md).

- WASM loaders support opt-in startup execution deadlines and per-instance linear-memory
ceilings. Defaults remain disabled. Timed execution owns bounded workers, propagates
interruption and replaces interrupted instances after physical exit. See
Expand Down
141 changes: 141 additions & 0 deletions docs/plugin-store-etcd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
<!--
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.
-->
# etcd plugin-store migration

The entire etcd stack is transferred as one unit to `apache/shenyu-plugin-store`:
`shenyu-infra-etcd`, `shenyu-admin-listener-etcd`, `shenyu-sync-data-etcd`,
`shenyu-registry-etcd`, and `shenyu-spring-boot-starter-sync-data-etcd`.
Infrastructure is etcd-specific; no retained core module imports it.

## Release gates

The main removal PR can enter code review, but must not merge until dev-list consensus is recorded, an
advance deprecation notice has shipped in a core release, the full released
deprecation cycle is complete, receiving builds and real-server/full-deployment
tests pass, external artifacts are published, and a rollback window is announced.
The deprecation release retains the in-tree integration; this branch prepares a
later cutover. No removal release is scheduled. Source changes and local snapshots
do not complete these release gates.
The store currently uses `2.7.1-SNAPSHOT` and compiles against ShenYu `2.7.2-SNAPSHOT`;
select the announced compatible store release when deploying. Do not publish the
same group/artifact/version from both repositories. Retain the last in-tree release
and its configuration during the rollback window; the release announcement must
specify that window before the cutover is merged.

## Dependency selection

Admin needs `org.apache.shenyu:shenyu-admin-listener-etcd`; gateway needs
`org.apache.shenyu:shenyu-spring-boot-starter-sync-data-etcd`. Applications using etcd
instance registration, SDK discovery, or Admin etcd discovery additionally need
`org.apache.shenyu:shenyu-registry-etcd`. Use the **store** version for all five
external modules and the **core** version for retained ShenYu APIs.
Gateway registration also requires the retained core
`shenyu-spring-boot-starter-registry`; exclude its bundled providers and add the
external `shenyu-registry-etcd`. The receiving gateway example POM shows this selection.
The infrastructure and jetcd dependencies are transitive. For binary distributions,
resolve the complete runtime dependency closure into `lib/`, remove superseded etcd
JARs, and include the extension's LICENSE/NOTICE information in the custom package.
Adding only the starter JAR without its dependencies is insufficient.

The `etcd` SPI key is unchanged. The JAR still registers
`etcd=org.apache.shenyu.registry.etcd.EtcdInstanceRegisterRepository` in
`META-INF/shenyu/org.apache.shenyu.registry.api.ShenyuInstanceRegisterRepository`.
Admin's existing `ShenyuInstanceRegisterRepositoryFactory.loadRepository` loads the
external provider without a hard-coded class or dependency in core.

## Configuration and storage contract

Admin and gateway retain `shenyu.sync.etcd.url`, with comma-separated endpoint URLs:

```yaml
shenyu:
sync:
etcd:
url: http://etcd-1:2379,http://etcd-2:2379
sessionTimeout: 30000
connectionTimeout: 30000
```

Disable the previous sync channel when selecting etcd. Admin uses
`shenyu.sync.websocket.enabled=false`; gateway must remove/disable its WebSocket
`urls` setting. Preserve the existing timeout values: the historical binding maps
`sessionTimeout` to the client's operation timeout (milliseconds) and
`connectionTimeout` to its lease TTL (seconds). This migration does not reinterpret
those values; revisit the naming/units in a separate compatible change.

Gateway instance registration keeps:

```yaml
shenyu:
register:
enabled: true
registerType: etcd
serverLists: http://etcd-1:2379,http://etcd-2:2379
props:
etcdTimeout: "3000"
etcdTTL: "5"
```

Configuration keys retain their leading slash and namespace:

| Data | Key |
| --- | --- |
| Plugin | `/<namespace>/shenyu/plugin/<pluginName>` |
| Selector | `/<namespace>/shenyu/selector/<pluginName>/<selectorId>` |
| Rule | `/<namespace>/shenyu/rule/<pluginName>/<selectorId>-<ruleId>` |
| Authentication | `/<namespace>/shenyu/auth/<appKey>` |
| Metadata | `/<namespace>/shenyu/metaData/<path>` |
| Proxy selector | `/<namespace>/shenyu/proxySelectorData/<pluginName>/<selectorId>` |
| Discovery upstream | `/<namespace>/shenyu/discoveryUpstream/<pluginName>/<selectorId>` |
| Instance | `/shenyu/register/instance/<appName>/<host>:<port>` |

JSON DTOs, enum values, discovery mode, namespace IDs and existing keyspaces stay
compatible. Instance keys remain lease-backed; after client shutdown they disappear
when their lease expires. No schema conversion or data deletion is required.

## Compatibility, licensing and verification

The transferred client remains `io.etcd:jetcd-core:0.7.3`, using the core-managed
gRPC `1.65.1`. The real-server fixture targets etcd `3.5.21`; other etcd/client
versions need validation before claiming support. Server and client are Apache-2.0:
see [etcd LICENSE](https://github.com/etcd-io/etcd/blob/v3.5.21/LICENSE) and
[jetcd LICENSE](https://github.com/etcd-io/jetcd/blob/jetcd-0.7.3/LICENSE).
The receiving extension carries the former distribution's CoreOS notice.
Historical release notes and upgrade documentation remain in main.

The store README documents unit, starter, real-server and full Admin/gateway E2E
commands. Real-server tests cover initial snapshots, namespace isolation, route
create/update/delete, server restart/watch recovery, external SPI registration,
instance update/delete/lease expiry and client shutdown. CI uses Testcontainers;
a native etcd binary is an explicit local alternative. Full deployment validation
uses the real Admin API and gateway HTTP traffic with externally supplied JARs.

## Upgrade and rollback

1. Back up Admin's database and take an etcd snapshot. Record namespace, endpoints,
timeouts, TTL, core/store versions and the deployed JAR inventory.
2. Verify compatible external artifacts and all release gates in a staging deployment.
Add the selected artifacts and their runtime dependencies before changing images.
3. Roll Admin and gateways one at a time, preserving their namespace/endpoints and
registry settings. Check initial synchronization, route updates and instance discovery.
4. Keep the previous in-tree images and configuration available for the announced window.
To roll back, restore those images/configuration and remove the external etcd JARs.
Reuse the same etcd keyspace and Admin database; do not clear either as part of rollback.

The archived compose/Kubernetes assets in `examples/etcd/legacy` belong to the last
in-tree deployment. They require the original core images; the receiving project's
new external-artifact E2E launcher is the cutover validation path.
25 changes: 0 additions & 25 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,6 @@
<netty.version>4.1.139.Final</netty.version>
<aspectjweaver.version>1.9.6</aspectjweaver.version>
<h2.version>1.4.200</h2.version>
<jetcd-core.version>0.7.3</jetcd-core.version>
<java-websocket.version>1.5.0</java-websocket.version>
<mockito.version>5.11.0</mockito.version>
<awaitility.version>4.0.3</awaitility.version>
Expand Down Expand Up @@ -535,30 +534,6 @@
<version>${jakarta.json-api.version}</version>
</dependency>

<dependency>
<groupId>io.etcd</groupId>
<artifactId>jetcd-core</artifactId>
<version>${jetcd-core.version}</version>
<exclusions>
<exclusion>
<artifactId>grpc-protobuf</artifactId>
<groupId>io.grpc</groupId>
</exclusion>
<exclusion>
<artifactId>grpc-stub</artifactId>
<groupId>io.grpc</groupId>
</exclusion>
<exclusion>
<groupId>io.grpc</groupId>
<artifactId>grpc-core</artifactId>
</exclusion>
<exclusion>
<artifactId>grpc-netty</artifactId>
<groupId>io.grpc</groupId>
</exclusion>
</exclusions>
</dependency>

<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-core</artifactId>
Expand Down
1 change: 0 additions & 1 deletion shenyu-admin-listener/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@
<modules>
<module>shenyu-admin-listener-api</module>
<module>shenyu-admin-listener-apollo</module>
<module>shenyu-admin-listener-etcd</module>
<module>shenyu-admin-listener-nacos</module>
<module>shenyu-admin-listener-zookeeper</module>
</modules>
Expand Down
56 changes: 0 additions & 56 deletions shenyu-admin-listener/shenyu-admin-listener-etcd/pom.xml

This file was deleted.

This file was deleted.

This file was deleted.

Loading
Loading