Kibotos
API referencekibotos.ctrl.v1

EgressService

This page lists the methods of EgressService in kibotos.ctrl.v1 with the messages and enums each one uses, generated from ctrl.proto and its comments. Those that several services use are on kibotos.ctrl.v1 types.

ctrl APICalled with an Operator certificate.How to call it

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.

POST/kibotos.ctrl.v1.EgressService/CreateEgressUnary
RequestCreateEgressRequest
ResponseCreateEgressResponse

GetEgress

POST/kibotos.ctrl.v1.EgressService/GetEgressUnary
RequestGetEgressRequest
ResponseGetEgressResponse

ListEgresses

POST/kibotos.ctrl.v1.EgressService/ListEgressesUnary
RequestListEgressesRequest
  • page_sizeuint32= 1

    Zero selects the server default. Values above the server maximum are rejected rather than silently changed.

  • page_tokenstring= 2

    Opaque cursor returned by the preceding page.

  • label_selectormap<string, string>= 3

    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.

ResponseListEgressesResponse

UpdateEgress

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.

POST/kibotos.ctrl.v1.EgressService/UpdateEgressUnary
RequestUpdateEgressRequest
  • egress_idstring= 2
  • expected_revisionuint64= 3

    The revision the caller observed. It is required: a mismatch is aborted and never overwrites a concurrent update. Retries preserve this value.

  • specEgressSpec= 4

    The complete replacement, password included.

  • drain_secondsoptionaluint32= 5

    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.

ResponseUpdateEgressResponse

DeleteEgress

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.

POST/kibotos.ctrl.v1.EgressService/DeleteEgressUnary
RequestDeleteEgressRequest
ResponseDeleteEgressResponse

UpdateEgressLabels

UpdateEgressLabels and UpdateEgressAnnotations follow the rules of their Workspace counterparts.

POST/kibotos.ctrl.v1.EgressService/UpdateEgressLabelsUnary
RequestUpdateEgressLabelsRequest
ResponseUpdateEgressLabelsResponse

UpdateEgressAnnotations

POST/kibotos.ctrl.v1.EgressService/UpdateEgressAnnotationsUnary
RequestUpdateEgressAnnotationsRequest
ResponseUpdateEgressAnnotationsResponse

Messages and enums

Several methods of EgressService use these messages and enums.

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.

  • One of protocol
  • udp_enabledbool= 2

    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.

  • addressstring= 1

    address is host:port, where host is an IP address or a hostname.

  • usernamestring= 2

    username and password are optional. When given, each is 1 to 255 bytes and the endpoint authenticates them with RFC 1929.

  • passwordstring= 3

    password is write-only: no read, list or response returns it, so an update must send it again.

  • tlsEgressTls= 4

    tls, when present, runs the SOCKS5 negotiation and the tunnelled traffic inside TLS.

EgressTls

EgressTls verifies the endpoint of an Egress over TLS.

  • server_namestring= 1

    server_name is the name sent as SNI and verified against the endpoint certificate. Empty selects the host of the endpoint address.

  • ca_certstring= 2

    ca_cert is PEM, at most 64 KiB. When given it replaces the system trust roots for this endpoint.

Egress

  • egress_idstring= 1
  • revisionuint64= 3

    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.

  • created_atgoogle.protobuf.Timestamp= 4
  • updated_atgoogle.protobuf.Timestamp= 5
  • annotationsmap<string, string>= 6

    labels and annotations have the same meaning, rules, and limits as on Workspace.

  • labelsmap<string, string>= 7
  • labels_revisionuint64= 8

    labels_revision is the CAS token UpdateEgressLabels expects.

  • annotations_revisionuint64= 9

    annotations_revision is the CAS token UpdateEgressAnnotations expects.

ExposureService

This page lists the methods of ExposureService in kibotos.ctrl.v1 with the messages and enums each one uses, generated from ctrl.proto and its comments. Those that several services use are on kibotos.ctrl.v1 types.

ResolverService

This page lists the methods of ResolverService in kibotos.ctrl.v1 with the messages and enums each one uses, generated from ctrl.proto and its comments. Those that several services use are on kibotos.ctrl.v1 types.

On this page

CreateEgressGetEgressListEgressesUpdateEgressDeleteEgressUpdateEgressLabelsUpdateEgressAnnotationsMessages and enumsEgressSpecSocks5EgressEgressTlsEgress