Endpoint Lifecycle

This section specifies the lifecycle of Cilium endpoints.

Every endpoint in Cilium is in one of the following states:

  • restoring: The endpoint was started before Cilium started, and Cilium is restoring its networking configuration.
  • waiting-for-identity: Cilium is allocating a unique identity for the endpoint.
  • waiting-to-regenerate: The endpoint received an identity and is waiting for its networking configuration to be (re)generated.
  • regenerating: The endpoint’s networking configuration is being (re)generated. This includes programming eBPF for that endpoint.
  • ready: The endpoint’s networking configuration has been successfully (re)generated.
  • disconnecting: The endpoint is being deleted.
  • disconnected: The endpoint has been deleted.

../../_images/cilium-endpoint-lifecycle.png

The state of an endpoint can be queried using the cilium endpoint list and cilium endpoint get CLI commands.

While an endpoint is running, it transitions between the waiting-for-identity, waiting-to-regenerate, regenerating, and ready states. A transition into the waiting-for-identity state indicates that the endpoint changed its identity. A transition into the waiting-to-regenerate or regenerating state indicates that the policy to be enforced on the endpoint has changed because of a change in identity, policy, or configuration.

An endpoint transitions into the disconnecting state when it is being deleted, regardless of its current state.

Init Identity

In some situations, Cilium can’t determine the labels of an endpoint immediately when the endpoint is created, and therefore can’t allocate an identity for the endpoint at that point. Until the endpoint’s labels are known, Cilium temporarily associates a special single label reserved:init to the endpoint. When the endpoint’s labels become known, Cilium then replaces that special label with the endpoint’s labels and allocates a proper identity to the endpoint.

This may occur during endpoint creation in the following cases: * Running Cilium with docker via libnetwork * With Kubernetes when the Kubernetes API server is not available * In etcd or consul mode when the corresponding kvstore is not available

To allow traffic to/from endpoints while they are initializing, you can create policy rules that select the reserved:init label, and/or rules that allow traffic to/from the special init entity.

For instance, writing a rule that allows all initializing endpoints to receive connections from the host and to perform DNS queries may be done as follows:

k8s YAML

JSON

  1. apiVersion: "cilium.io/v2"
  2. kind: CiliumNetworkPolicy
  3. metadata:
  4.   name: init
  5. specs:
  6.   - endpointSelector:
  7.       matchLabels:
  8.         "reserved:init": ""
  9.     ingress:
  10.     - fromEntities:
  11.       - host
  12.     egress:
  13.     - toEntities:
  14.       - all
  15.       toPorts:
  16.       - ports:
  17.         - port: "53"
  18.           protocol: UDP
  1. [{
  2.   "labels": [{"key": "name", "value": "init"}],
  3.   "endpointSelector": {"matchLabels":{"reserved:init":""}},
  4.   "ingress": [{
  5.     "fromEntities": ["host"]
  6.   }],
  7.   "egress": [{
  8.     "toEntities": ["all"],
  9.     "toPorts": [
  10.       {"ports":[ {"port": "53", "protocol": "UDP"}]}
  11.     ]
  12.   }]
  13. }]

Likewise, writing a rule that allows an endpoint to receive DNS queries from initializing endpoints may be done as follows:

k8s YAML

JSON

  1. apiVersion: "cilium.io/v2"
  2. kind: CiliumNetworkPolicy
  3. metadata:
  4.   name: "from-init"
  5. spec:
  6.   endpointSelector:
  7.     matchLabels:
  8.       app: myService
  9.   ingress:
  10.     - fromEntities:
  11.       - init
  12.     - toPorts:
  13.       - ports:
  14.         - port: "53"
  15.           protocol: UDP
  1. [{
  2.   "labels": [{"key": "name", "value": "from-init"}],
  3.   "endpointSelector": {"matchLabels":{"app":"myService"}},
  4.   "ingress": [{
  5.     "fromEntities": ["init"],
  6.     "toPorts": [
  7.       {"ports":[ {"port": "53", "protocol": "UDP"}]}
  8.     ]
  9.   }]
  10. }]

If any ingress (resp. egress) policy rules selects the reserved:init label, all ingress (resp. egress) traffic to (resp. from) initializing endpoints that is not explicitly allowed by those rules will be dropped. Otherwise, if the policy enforcement mode is never or default, all ingress (resp. egress) traffic is allowed to (resp. from) initializing endpoints. Otherwise, all ingress (resp. egress) traffic is dropped.