Thanks for the question. This restriction is based on a core architectural principle of Apache APISIX’s decoupled deployment model: *Data Plane nodes must not write to etcd.*
For reference, this principle is reflected in the official architecture diagram: https://github.com/apache/apisix/blob/master/docs/assets/images/apisix.png This ensures a clear separation of responsibilities and avoids potential consistency or security issues. There is no compatible or recommended workaround for writing to etcd from the Data Plane. Zhiyuan Ju <juzhiy...@apache.org> 于2025年5月22日周四 14:54写道： > Hi, > > Can you guide us on how to migrate the existing implementations to align > with the new proposal? We can stop using those functions to write to ETCD, > but how can we change the implementations to make it work again? > > On Thu, May 22, 2025 at 10:24 AM Yi Sun <su...@apache.org> wrote: > > > Dear APISIX community, > > > > I would like to propose an improvement to enforce the behavior of the > > data_plane role in decoupled deployments of Apache APISIX. > > > > > > Background > > > > In decoupled deployment mode, APISIX nodes are configured with specific > > roles: > > control_plane: responsible for managing configurations and writing to > etcd. > > data_plane: responsible for handling traffic and reading configuration > > from etcd only. > > > > In this model, the Data Plane should never perform any writes to etcd. > > However, the current implementation does not strictly enforce this > > rule. As a result: > > > > Plugins or custom logic running in the Data Plane can still invoke > > core.etcd methods that perform write operations. > > > > This breaks the intended separation of responsibilities between > > Control Plane and Data Plane. > > It introduces risks of accidental or unauthorized etcd writes from > > Data Plane nodes. > > > > > > Proposal > > > > When APISIX is configured with deployment.role = data_plane, all calls > > to etcd write-related functions in core.etcd should be strictly > > forbidden. > > > > > > Affected functions: > > > > core.etcd.set > > core.etcd.atomic_set > > core.etcd.push > > core.etcd.delete > > core.etcd.rmdir > > > > > > Expected behavior: > > > > No additional configuration flag is needed. > > When the role is data_plane, any invocation of the above methods: > > Will be ignored, and return immediately (e.g., nil, "etcd write is > > forbidden in data_plane"). > > Will emit a warning log, e.g.: > > attempted etcd write via core.etcd.set is forbidden in data_plane mode > > > > > > Breaking Change Notice > > > > This change is a breaking behavioral change for users or plugins that > > currently rely on etcd write operations from Data Plane nodes. After > > this change: > > > > Any such calls will no longer take effect. > > > > Existing custom code (or community plugins) may break if they depend > > on etcd write access in Data Plane mode. > > > > This makes it essential to audit and update custom logic before > > upgrading, especially in decoupled or multi-plane deployments. > > > > > > Benefits > > > > Enforces strict role-based access rules for etcd. > > Prevents misbehavior in large-scale or security-sensitive deployments. > > Reinforces separation of concerns between Control Plane and Data Plane. > > Avoids side effects from plugin logic or custom scripts in the Data > Plane. > > > > > > Next Steps > > > > If this direction makes sense, I’m happy to contribute an > > implementation, with test coverage and documentation updates. > > > > > > Looking forward to your feedback and suggestions. > > > > > > Best regards, > > Sun Yi > > GitHub: https://github.com/LiteSun > > >
