EgressService
本页列出 kibotos.ctrl.v1 中 EgressService 的方法及每个方法用到的消息与枚举，由 ctrl.proto 及其注释生成，注释保持英文。多个服务共用的消息与枚举见 kibotos.ctrl.v1 类型。
EgressService owns caller-owned egress endpoints. A PUBLIC_INTERNET policy lists Egresses in NetworkPolicy.egresses, and a new TCP connection whose destination one entry covers leaves through that entry's Egress instead of leaving directly. One Egress may be referenced by many Workspaces. Every write carries a command ID.
CreateEgress
CreateEgress stores a new Egress at revision 1. An endpoint written as an IP address in a fixed special-purpose range, or a hostname that resolves into one when the server resolves it once, is invalid_argument. That check only reports a mistake early: the endpoint is checked again on every dial.
/kibotos.ctrl.v1.EgressService/CreateEgress一元调用CreateEgressRequestPersisted in the same transaction as the create command, with the rules and limits of Workspace.labels and Workspace.annotations. Both are included in idempotency.
CreateEgressResponseGetEgress
/kibotos.ctrl.v1.EgressService/GetEgress一元调用ListEgresses
/kibotos.ctrl.v1.EgressService/ListEgresses一元调用ListEgressesRequestZero selects the server default. Values above the server maximum are rejected rather than silently changed.
Opaque cursor returned by the preceding page.
When non-empty, return only Egresses that carry every entry as a label with exactly that value. Keys and values must satisfy the label rules. A page token is only valid with the selector it was issued for.
ListEgressesResponseUpdateEgress
UpdateEgress replaces the whole spec, password included, under the same endpoint checks as CreateEgress. expected_revision must equal the current revision or the call is aborted and nothing changes. Equal content is idempotent and keeps the revision; different content increments it. The call returns once the change is stored, without waiting for running Workspaces: each one that references this Egress then switches its new connections to the new revision, which its network_policy_status.egresses entry for this Egress reports as applied_revision. Updating an Egress never changes the revision of a policy that references it.
/kibotos.ctrl.v1.EgressService/UpdateEgress一元调用UpdateEgressRequestThe revision the caller observed. It is required: a mismatch is aborted and never overwrites a concurrent update. Retries preserve this value.
The complete replacement, password included.
drain_seconds is how long connections already established through the previous revision keep running before they are closed: 0 to 3600, absent selects 600, and 0 closes them when the new revision takes over. It is a parameter of this call and is not stored with the Egress. Connections an earlier update left draining keep their own deadline. Retries preserve this value.
UpdateEgressResponseDeleteEgress
DeleteEgress deletes an Egress that no policy of a non-deleted Workspace references; while one does, it is failed_precondition. Connections still draining through the Egress are closed at once. A deleted Egress is not_found to every read and every reference.
/kibotos.ctrl.v1.EgressService/DeleteEgress一元调用DeleteEgressRequestDeleteEgressResponseUpdateEgressLabels
UpdateEgressLabels and UpdateEgressAnnotations follow the rules of their Workspace counterparts.
/kibotos.ctrl.v1.EgressService/UpdateEgressLabels一元调用UpdateEgressLabelsRequestThe labels_revision the caller observed. Retries preserve this value.
The complete replacement; empty clears every label.
UpdateEgressLabelsResponseUpdateEgressAnnotations
/kibotos.ctrl.v1.EgressService/UpdateEgressAnnotations一元调用UpdateEgressAnnotationsRequestThe annotations_revision the caller observed. Retries preserve this value.
The complete replacement; empty clears every annotation.
UpdateEgressAnnotationsResponse消息与枚举
EgressService 的多个方法用到以下消息与枚举。
EgressSpec
EgressSpec is the content of an Egress. Exactly one protocol branch is selected, and it carries the endpoint, its credentials and its TLS settings; a create or update without one is invalid_argument. Reads return the selected branch.
protocol中的一个udp_enabled lets a policy that references this Egress send the queries of a udp Resolver through it; SOCKS5 carries them with UDP ASSOCIATE. It is off by default. Even when the endpoint uses TLS, the UDP datagrams are not protected by it: they travel in clear text to the relay address the endpoint answers. Turning it off while a policy of a non-deleted Workspace sends a udp Resolver through this Egress is failed_precondition.
Socks5Egress
Socks5Egress is a SOCKS5 endpoint (RFC 1928). Each forwarded connection is requested with CONNECT to the address the guest dialed.
address is host:port, where host is an IP address or a hostname.
username and password are optional. When given, each is 1 to 255 bytes and the endpoint authenticates them with RFC 1929.
password is write-only: no read, list or response returns it, so an update must send it again.
EgressTls
EgressTls verifies the endpoint of an Egress over TLS.
server_name is the name sent as SNI and verified against the endpoint certificate. Empty selects the host of the endpoint address.
ca_cert is PEM, at most 64 KiB. When given it replaces the system trust roots for this endpoint.
Egress
revision is assigned by the server: it is 1 at creation and increases by one each time the spec changes. It is independent of the revision of every policy that references this Egress.
labels and annotations have the same meaning, rules, and limits as on Workspace.
labels_revision is the CAS token UpdateEgressLabels expects.
annotations_revision is the CAS token UpdateEgressAnnotations expects.