change: mark server-info plugin as deprecated

[LiteSun]

Description

mark server-info plugin as deprecated and update docs

mailing list: https://lists.apache.org/thread/nrwqo1gbc0z4z48fkb8dd4rn0trnfnz9

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

[shreemaan-abhishek]

@LiteSun please link the mailing list conversation in the pull request for reference on why it is being deprecated.

[LiteSun]

@LiteSun please link the mailing list conversation in the pull request for reference on why it is being deprecated.

done

[AlinsRan]

This is a change, not a feature, it modifies the default behavior.

[bzp2010]

Block it for now until I have some free time to look at it more closely. Please don't merge it. 🫡

[bzp2010]

There is a lack of transparency about several things:

1. You mentioned

These frequent etcd writes may lead to performance degradation or even startup failures if etcd is not properly provisioned.

How to quantitatively assess the performance impact on etcd?

What specific parts are not configured correctly? I think it needs to be clearly stated how it should be done correctly. I think this might help users who are unable to upgrade and need to use the plugin.

2. You mentioned

which is not a suitable use case for etcd and can lead to unnecessary system stress

APISIX does not register itself with external service discovery systems in any way, how does one know how to detect if an APISIX instance is alive or not, no one knows on which IP APISIX is running.

What are the alternatives? What alternative features will be introduced to compensate for the "issues" of the current removal, and if not, you need to explicitly mention "no" and welcome discussion on this.

3. The deprecation process starts with the next release (i.e. 3.13.0), which is fine. But in your plan it will be removed at 3.14.0, which is too soon, and the process requires more releases. Need to be more robust about these features that may have a larger sphere of influence.

An example is 553ac42. We introduced a new event broadcasting mechanism as the new default in 3.8.0, but the old implementation was not removed, the Users can switch it at any time via the configuration file. It remains in the code base for now.

We need to add more background information in the email thread and in this issue, and while this deprecation may not be a "discussion", it still needs to be transparent.

[LiteSun]

How to quantitatively assess the performance impact on etcd?

What specific parts are not configured correctly? I think it needs to be clearly stated how it should be done correctly. I think this might help users who are unable to upgrade and need to use the plugin.

When does the issue occur:

When APISIX is deployed in traditional mode, restarting APISIX triggers the server-info plugin to write data to etcd. If too many APISIX instances write to etcd at the same time, it may cause etcd to become unavailable. This can prevent APISIX from starting properly, which in turn affects the data plane (DP) and its ability to handle traffic.

Recommended approach:

If you need to continue using the server-info plugin, before APISIX begins handling production traffic, refer to the etcd example hardware configurations to test and determine how much etcd hardware resources are required for the number of APISIX instances you’re running. This ensures APISIX can start up reliably.

---

What are the alternatives?

There is currently no perfect alternative. If you still need the information provided by the server-info plugin, you might consider developing a new plugin to store this data in a different backend such as Redis or MySQL. Alternatively, you can continue using the server-info plugin with caution, making sure that sufficient etcd hardware resources are provisioned.

---

But in your plan it will be removed at 3.14.0, which is too soon

If you feel the removal is too soon, we can postpone it by two additional release cycles to give users more time to adjust and discuss.

Here’s the updated deprecation schedule:

• 3.13.0 – Deprecation begins:

  • Marked as deprecated
  • Documentation updated
  • Warning logs emitted

• 3.14.0 – Grace period:

  • No functional changes
  • Gives developers time to adapt

• 3.15.0 – Extended grace period:

  • Continued support
  • More time for migration and community feedback

• 3.16.0 – Final removal:

  • The feature will be completely removed from this version onward

Considering the uncertainty in APISIX's release cycle, this functionality will be officially deprecated no later than 6 months after the release of version 3.13.0.