菜单
Use when understanding how Edgion works internally — Controller/Gateway/Center/Ctl architecture, gRPC sync, resource processing flow, or adding a new plugin/resource/connector.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Conventions shared by the in-repo binaries (edgion-controller, edgion-gateway, edgion-cli) — project overview, command line / directory / config-path conventions, Core layering conventions, resource system.
KubernetesCenter implementation — K8s Reflector watching, leader election, HA mode, ResourceController lifecycle, status writeback.
ConfigCenter subsystem — ConfCenter trait abstraction, FileSystemCenter and KubernetesCenter implementations, unified Workqueue + ResourceProcessor pipeline.
edgion-controller control plane architecture — overall design, startup/shutdown, Admin API, ConfigCenter, Workqueue, ResourceProcessor, Requeue, CacheServer, ACME service.
Route matching overview — multi-stage pipeline (Listener→Domain→Path→DeepMatch), per-listener isolation, registration flow, atomic swap.
TLS subsystem overview — TLS Store, SNI matching, certificate management, BoringSSL/OpenSSL backend selection.
| name | architecture |
| description | Use when understanding how Edgion works internally — Controller/Gateway/Center/Ctl architecture, gRPC sync, resource processing flow, or adding a new plugin/resource/connector. |
Edgion is a Kubernetes Gateway built on Pingora, using a Controller–Gateway split architecture.
Edgion is a single-Crate, three-binary project. Controller decides, Gateway executes, Ctl operates.
flowchart TD
User["User / K8s API"] --> Controller
Traffic["Client traffic"] --> Gateway
subgraph Controller["edgion-controller (control plane)"]
CC["ConfCenter (File/K8s)"] --> WQ["Workqueue (per-kind)"]
WQ --> RP["ResourceProcessor\n(validate/preparse/parse)"]
RP --> SC["ServerCache"]
CrossRef["Cross-resource dependencies\nSecretRefManager\nServiceRefManager\nCrossNamespaceRefManager\nRequeueChain"]
CtrlServices["Admin API (:12101)\nConfigSyncServer (:12151)\nACME Service (optional, Leader only)"]
end
SC -- "gRPC Watch/List" --> SyncClient
subgraph Gateway["edgion-gateway (data plane)"]
SyncClient["ConfigSyncClient"] --> ClientCache["ClientCache"] --> ConfHandler["ConfHandler"]
PingoraServer["Pingora Server"]
ConnFilter["ConnectionFilter (StreamPlugins)"]
ProxyHttp["ProxyHttp (HTTP/gRPC)\nroute match + plugins\nupstream_peer + LB\nlogging (AccessLog + Metrics)"]
StreamRoutes["TCP/TLS/UDP Routes"]
PingoraServer --- ConnFilter
PingoraServer --- ProxyHttp
PingoraServer --- StreamRoutes
TLS["TLS subsystem\nDownstream TLS (client → gateway)\nUpstream TLS (gateway → backend mTLS)"]
GwServices["Admin API (:12001 default)\nProbe (:12000)\nMetrics (:12090)"]
end
subgraph CLI["edgion-cli (CLI tool)"]
CliOps["apply/delete/get/reload\n3 targets: center/server/client"]
end
CLI -- "HTTP API" --> Controller
| What you want to learn | Start here |
|---|---|
| Project at a glance, code organization, conventions shared by the in-repo binaries | 00-common/ |
| How the Controller processes resources internally | 01-controller/ |
| Controller authentication & authorization (admin login, cli tokens, RBAC, 401/403 debugging) | 01-controller/11-authentication-authorization.md |
| How the Gateway processes requests | 02-gateway/ |
| How Controller and Gateway sync | 03-controller-gateway-link/ |
| edgion-cli commands and target modes | 04-ctl/ |
| The full processing chain for a specific resource | 05-resources/ |
| Troubleshoot route mismatch | 02-gateway/03-routes/ |
| Troubleshoot TLS certificate issues | 02-gateway/04-tls/ |
| Troubleshoot gRPC sync issues | 03-controller-gateway-link/00-overview.md |
| Develop a new resource type | 01-controller/09-add-new-resource/ |
| Develop an HTTP plugin | 02-gateway/12-edgion-plugin-dev.md |
| Develop a Stream plugin | 02-gateway/13-stream-plugin-dev.md |
| Develop a LinkSys connector | 02-gateway/14-link-sys-dev.md |
| Implement a ConfHandler | 02-gateway/11-conf-handler-guidelines.md |
| Implement update_status | 01-controller/10-status-management.md |
Foundational conventions shared by the in-repo binaries: project overview, command line / directory / config-path conventions, crate layering, and the resource system (define_resources! macro).
Internal architecture of the control plane, broken down by module:
| Module | Keywords |
|---|---|
| Overall architecture | ConfMgr facade, ProcessorRegistry |
| Startup / shutdown | Leader election, HA mode, event-driven main loop |
| Admin API | port :12101, CRUD, health/ready |
| ConfigCenter | ConfCenter trait, FileSystem / Kubernetes implementations |
| Workqueue | deduplication, delayed (coalesced) requeue, dirty requeue |
| ResourceProcessor | 11-step processing pipeline, 20 Handler kinds |
| Requeue | cross-resource linkage, TriggerChain cycle detection |
| CacheServer | ServerCache + EventStore, gRPC data source |
| ACME | Let's Encrypt automated certificates, Leader only |
| Adding a new resource | workflow + 4 template categories (route-like / controller-only / plugin-like / cluster-scoped) |
| Status management | update_status implementation conventions, known pitfalls |
| Authentication & authorization | token-only admin authn (Istio-style bearer), cli token RBAC, Role/Verb/CenterPolicy, middleware onion, default Center policy |
Internal architecture of the data plane, broken down by subsystem:
| Subsystem | Keywords |
|---|---|
| Overall architecture | dual-runtime model (Tokio + Pingora) |
| Startup / shutdown | 14-step startup sequence, two-phase Pingora integration |
| Pingora lifecycle | 7-phase ProxyHttp callbacks, ConnectionFilter |
| Routes | multi-stage matching pipeline, separate engines for HTTP/gRPC/TCP/TLS/UDP |
| TLS | downstream/upstream TLS, SNI matching, BoringSSL/OpenSSL |
| Plugin system | 4-phase execution, 28 HTTP plugins, conditional execution |
| Load balancing | RoundRobin/EWMA/LeastConn/ConsistentHash/Weighted |
| Backends | Service/EndpointSlice discovery, health checks |
| Observability | AccessLog (zero-copy JSON), Prometheus Metrics |
| LinkSys | ES/Redis/Etcd/Webhook/File external integrations |
| Runtime store | Gateway/Route configuration, ArcSwap atomic swap |
| ConfHandler development | full_set/partial_update conventions, incremental update constraints |
| HTTP plugin development | EdgionPlugin phase selection, runtime wiring, ExtensionRef |
| Stream plugin development | ConnectionFilter / TlsRoute two phases |
| LinkSys development | external system connector development, LinkSysStore bridging |
The ConfigSync protocol (GetServerInfo / List / Watch / WatchServerMeta), the Controller-side ConfigSyncServer and the Gateway-side ConfigSyncClient implementation.
CLI tool: 3 target modes (center/server/client), apply/delete/get/reload subcommands.
Common processing flow + features, special handling, and cross-resource links for all 20 resources. For resource Schema (field definitions, default values) see 02-features/03-resources/ (numbered to align, complementary responsibilities).
| Category | Resources |
|---|---|
| Core configuration | Gateway, GatewayClass, EdgionGatewayConfig |
| Routes | HTTPRoute, GRPCRoute, TCPRoute, TLSRoute, UDPRoute |
| Security / policy | EdgionTls, Secret, ReferenceGrant, BackendTLSPolicy |
| Plugins / extensions | EdgionPlugins, EdgionStreamPlugins, EdgionConfigData |
| Backends / services | Service, EndpointSlice |
| Automation | EdgionAcme |
| Infrastructure | LinkSys |
Gateway API v1.5.0 supported scope, conformance tests, Edgion extension points, intentional deviations.