AlexStocks commented on code in PR #1042:
URL: https://github.com/apache/dubbo-go-pixiu/pull/1042#discussion_r4093514209
##########
docs/developer/xds-operations.md:
##########
@@ -0,0 +1,144 @@
+# xDS Operations Guide
+
+Pixiu Admin publishes gateway listeners and clusters through Envoy xDS v3. It
+supports the project-specific `TypedExtensionConfig` transport and standard
+CDS/EDS ingestion for Istio-compatible control planes.
+
+## Resource support matrix
+
+`Supported` means the repository maintains the complete Admin-to-Pixiu path.
+`Experimental` means conversion and protocol handling exist, but production
+environment coverage is still limited. Registering a gRPC service alone does
+not make its resource type supported.
+
+| Resource path | Status | Boundary |
+| --- | --- | --- |
+| ExtensionConfig listener | Supported | Pixiu-specific aggregate over Delta
ECDS. |
+| ExtensionConfig cluster | Supported | Pixiu-specific aggregate over Delta
ECDS. |
+| Standard CDS | Experimental | EDS-type clusters through standard ADS. |
+| Standard EDS | Experimental | Socket-address endpoints for referenced CDS
resources. |
+| Standard LDS | Unsupported | Listener conversion is outside the base scope. |
+| Standard RDS/SDS/RTDS | Unsupported | Services may be registered, but no
resources are published or applied. |
+| `ads_config` bootstrap | Unsupported | Use `lds_config`/`cds_config` with
the documented API types. |
+
+## Admin configuration
+
+Configure the management server in the Admin YAML:
+
+```yaml
+xds:
+ listen_port: 18000
+ node_id: gateway-a
+```
+
+`listen_port` defaults to `18000`; `node_id` defaults to `test-id`. The Pixiu
+client node ID must exactly match the Admin node ID because the snapshot cache
+is keyed by that value.
+
+Admin loads listeners and clusters, validates a complete candidate snapshot,
+and publishes it only after all conversions succeed. Its etcd prefix watch
+then rebuilds on create, update, and delete events. A failed candidate does not
+replace the last-good snapshot or advance its version.
+
+## Diagnostics
+
+After obtaining an Admin JWT, query:
+
+```shell
+curl -H "token: ${TOKEN}" http://127.0.0.1:8081/config/api/xds/status
+```
+
+The `data` object contains:
+
+| Field | Meaning |
+| --- | --- |
+| `node_id` | Snapshot cache key expected from clients. |
+| `listen_port` | Effective xDS gRPC listen port. |
+| `listening` | Whether the xDS gRPC socket is currently bound. |
+| `listen_error`, `listen_error_at` | Latest listener startup or serving error
and its time. |
+| `snapshot_version` | Last successfully published version. |
+| `listener_count`, `cluster_count` | Resources in the last-good snapshot. |
+| `last_updated_at` | Time the last-good snapshot was published. |
+| `last_attempt_at` | Time of the latest successful or failed publication
attempt. |
+| `last_error`, `last_error_at` | Latest rejected candidate and its time. |
+| `ready` | The xDS listener is bound and at least one snapshot has been
published. |
+| `degraded` | Listener startup/serving or the latest snapshot candidate
failed. |
+| `resource_support` | Explicit support status for each xDS path. |
+
+An empty `snapshot_version` means no candidate has been published. A response
+with both `ready: true` and `degraded: true` means the listener is available
and
+clients can continue using the last-good version while the operator fixes the
+newer configuration.
+
+## Client correctness
+
+- Delta ExtensionConfig responses are applied before ACK. Decode or runtime
+ application failures produce a NACK with `ErrorDetail`.
+- Empty Delta responses are no-ops. An explicitly delivered empty aggregate
+ removes the corresponding xDS-owned resources.
+- Reconnect requests include only versions that were successfully applied.
+- Static listeners and clusters cannot be overwritten or deleted by xDS.
+- Standard ADS uses one stream for CDS and referenced EDS resources. Standard
+ LDS conversion is not currently supported. Non-EDS CDS resources are logged
+ and skipped; invalid fields in a selected EDS cluster still produce a NACK.
+
+## Compatibility notes
+
+- Listener construction is fail-closed. A bad network or HTTP filter prevents
Review Comment:
[P2] 这里的兼容性说明和当前代码行为不一致。`CreateDefaultListenerManager` 在静态 listener
创建失败时只是记录错误并跳过该 listener（测试也固化为
`TestCreateDefaultListenerManagerSkipsInvalidStaticListener`），网关进程仍会继续启动；这段文字容易让运维以为坏的静态
listener 会阻止整个启动。建议把静态 listener 的行为明确写成“该 listener 不会进入 active
set，进程继续启动”，或者如果期望真的是启动失败，就让代码返回初始化错误。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
