Cilium Endpoint

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://cilium.io/schemas/endpoint.json",
  "title": "Cilium Endpoint",
  "description": "A Cilium-managed network endpoint representing a Kubernetes pod or container with associated security identity, IP addressing, and policy enforcement state.",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Numeric endpoint ID assigned by the Cilium agent.",
      "minimum": 1
    },
    "spec": {
      "$ref": "#/$defs/EndpointSpec"
    },
    "status": {
      "$ref": "#/$defs/EndpointStatus"
    }
  },
  "$defs": {
    "EndpointSpec": {
      "type": "object",
      "description": "Desired configuration for a Cilium endpoint.",
      "properties": {
        "addressing": {
          "$ref": "#/$defs/AddressPair"
        },
        "containerID": {
          "type": "string",
          "description": "Container runtime identifier for this endpoint.",
          "minLength": 1
        },
        "containerName": {
          "type": "string",
          "description": "Container name as reported by the container runtime."
        },
        "k8sNamespace": {
          "type": "string",
          "description": "Kubernetes namespace in which the pod runs."
        },
        "k8sPodName": {
          "type": "string",
          "description": "Kubernetes pod name associated with this endpoint."
        },
        "k8sUID": {
          "type": "string",
          "description": "Kubernetes pod UID uniquely identifying the pod object."
        },
        "labels": {
          "type": "array",
          "description": "Security labels associated with this endpoint in key=value format.",
          "items": {
            "type": "string",
            "pattern": "^[^=]+=.*$"
          }
        },
        "datapath-configuration": {
          "$ref": "#/$defs/DatapathConfiguration"
        }
      }
    },
    "AddressPair": {
      "type": "object",
      "description": "IPv4 and IPv6 address pair assigned to an endpoint.",
      "properties": {
        "ipv4": {
          "type": "string",
          "description": "IPv4 address assigned to the endpoint.",
          "format": "ipv4"
        },
        "ipv4-expiry-time": {
          "type": "string",
          "description": "Expiry time for the IPv4 address lease.",
          "format": "date-time"
        },
        "ipv6": {
          "type": "string",
          "description": "IPv6 address assigned to the endpoint.",
          "format": "ipv6"
        },
        "ipv6-expiry-time": {
          "type": "string",
          "description": "Expiry time for the IPv6 address lease.",
          "format": "date-time"
        }
      }
    },
    "DatapathConfiguration": {
      "type": "object",
      "description": "BPF datapath-specific configuration for an endpoint.",
      "properties": {
        "disable-sip-verification": {
          "type": "boolean",
          "description": "Disable source IP verification for this endpoint."
        },
        "external-ipam": {
          "type": "boolean",
          "description": "Whether IP addressing is managed by an external IPAM provider."
        },
        "install-endpoint-route": {
          "type": "boolean",
          "description": "Whether to install a per-endpoint host route."
        },
        "require-arp-passthrough": {
          "type": "boolean",
          "description": "Whether ARP passthrough is required for this endpoint."
        },
        "require-egress-prog": {
          "type": "boolean",
          "description": "Whether an egress BPF program is required."
        },
        "require-routing": {
          "type": "boolean",
          "description": "Whether routing is required for this endpoint."
        }
      }
    },
    "EndpointStatus": {
      "type": "object",
      "description": "Current observed state of a Cilium endpoint.",
      "properties": {
        "state": {
          "type": "string",
          "description": "Current lifecycle state of the endpoint.",
          "enum": [
            "waiting-for-identity",
            "not-ready",
            "waiting-to-regenerate",
            "regenerating",
            "restoring",
            "ready",
            "disconnecting",
            "disconnected",
            "invalid"
          ]
        },
        "identity": {
          "$ref": "#/$defs/Identity"
        },
        "networking": {
          "$ref": "#/$defs/EndpointNetworking"
        },
        "policy": {
          "$ref": "#/$defs/EndpointPolicyStatus"
        },
        "health": {
          "$ref": "#/$defs/EndpointHealth"
        },
        "controllers": {
          "type": "array",
          "description": "Status of background controllers managing this endpoint.",
          "items": {
            "$ref": "#/$defs/ControllerStatus"
          }
        },
        "log": {
          "type": "array",
          "description": "Recent status change log entries for this endpoint.",
          "items": {
            "$ref": "#/$defs/EndpointStatusChange"
          },
          "maxItems": 100
        }
      }
    },
    "Identity": {
      "type": "object",
      "description": "Cilium security identity derived from a workload's label set.",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "Unique numeric security identity ID.",
          "minimum": 1
        },
        "labels": {
          "type": "array",
          "description": "Labels that define this security identity.",
          "items": {
            "type": "string"
          }
        },
        "labelsSHA256": {
          "type": "string",
          "description": "SHA256 hash of the serialized label set for change detection.",
          "pattern": "^[0-9a-f]{64}$"
        }
      }
    },
    "EndpointNetworking": {
      "type": "object",
      "description": "Network addressing and routing information for an endpoint.",
      "properties": {
        "addressing": {
          "type": "array",
          "description": "IP addresses assigned to this endpoint.",
          "items": {
            "$ref": "#/$defs/AddressPair"
          }
        },
        "node": {
          "type": "string",
          "description": "IP address of the Kubernetes node hosting this endpoint."
        },
        "interface-index": {
          "type": "integer",
          "description": "Linux network interface index for this endpoint's veth."
        },
        "interface-name": {
          "type": "string",
          "description": "Linux network interface name for this endpoint's veth device."
        }
      }
    },
    "EndpointPolicyStatus": {
      "type": "object",
      "description": "Policy enforcement status for ingress and egress traffic.",
      "properties": {
        "spec": {
          "$ref": "#/$defs/EndpointPolicy"
        },
        "realized": {
          "$ref": "#/$defs/EndpointPolicy"
        },
        "proxy-statistics": {
          "type": "array",
          "description": "Statistics from L7 proxy enforcement.",
          "items": {
            "$ref": "#/$defs/ProxyStatistics"
          }
        }
      }
    },
    "EndpointPolicy": {
      "type": "object",
      "description": "The set of policy rules applied to an endpoint.",
      "properties": {
        "allowed-egress-identities": {
          "type": "array",
          "description": "Numeric identity IDs that egress traffic from this endpoint may reach.",
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "allowed-ingress-identities": {
          "type": "array",
          "description": "Numeric identity IDs permitted to send traffic to this endpoint.",
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "denied-egress-identities": {
          "type": "array",
          "description": "Numeric identity IDs explicitly denied for egress.",
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "denied-ingress-identities": {
          "type": "array",
          "description": "Numeric identity IDs explicitly denied for ingress.",
          "items": {
            "type": "integer",
            "format": "int64"
          }
        },
        "cidr-policy": {
          "type": "object",
          "description": "CIDR-based policy configuration.",
          "properties": {
            "egress": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/CIDRRule"
              },
              "description": "CIDR rules for egress traffic."
            },
            "ingress": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/CIDRRule"
              },
              "description": "CIDR rules for ingress traffic."
            }
          }
        },
        "id": {
          "type": "integer",
          "format": "int64",
          "description": "Policy revision number when these rules were last computed."
        }
      }
    },
    "CIDRRule": {
      "type": "object",
      "description": "A CIDR-based policy rule.",
      "required": ["cidr"],
      "properties": {
        "cidr": {
          "type": "string",
          "description": "CIDR block this rule applies to.",
          "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}/[0-9]{1,2}$|^[0-9a-fA-F:]+/[0-9]{1,3}$"
        },
        "except": {
          "type": "array",
          "description": "CIDR blocks to exclude from this rule.",
          "items": {
            "type": "string"
          }
        },
        "derived-from-rules": {
          "type": "array",
          "description": "Policy rule labels from which this CIDR rule was derived.",
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "ProxyStatistics": {
      "type": "object",
      "description": "L7 proxy traffic statistics for an endpoint port.",
      "properties": {
        "location": {
          "type": "string",
          "description": "Location of the proxy (ingress or egress).",
          "enum": ["Ingress", "Egress"]
        },
        "port": {
          "type": "integer",
          "description": "Port number being proxied."
        },
        "protocol": {
          "type": "string",
          "description": "Application protocol being proxied (HTTP, Kafka, DNS, etc.)."
        },
        "statistics": {
          "type": "object",
          "description": "Traffic statistics counters.",
          "properties": {
            "requests": {
              "$ref": "#/$defs/TrafficStatistics"
            },
            "responses": {
              "$ref": "#/$defs/TrafficStatistics"
            }
          }
        }
      }
    },
    "TrafficStatistics": {
      "type": "object",
      "description": "Traffic counters for a direction.",
      "properties": {
        "received": {
          "type": "integer",
          "format": "int64",
          "description": "Number of requests or responses received."
        },
        "sent": {
          "type": "integer",
          "format": "int64",
          "description": "Number of requests or responses sent."
        },
        "forwarded": {
          "type": "integer",
          "format": "int64",
          "description": "Number of requests or responses forwarded."
        },
        "denied": {
          "type": "integer",
          "format": "int64",
          "description": "Number of requests or responses denied by policy."
        },
        "error": {
          "type": "integer",
          "format": "int64",
          "description": "Number of requests or responses that encountered errors."
        }
      }
    },
    "EndpointHealth": {
      "type": "object",
      "description": "Health status of an endpoint's BPF programs and policy.",
      "properties": {
        "bpf": {
          "type": "string",
          "description": "Health status of BPF programs for this endpoint.",
          "enum": ["OK", "Warning", "Failure", "Disabled", "Pending"]
        },
        "connected": {
          "type": "boolean",
          "description": "Whether the endpoint's network interface is connected."
        },
        "overallHealth": {
          "type": "string",
          "description": "Overall health status of the endpoint.",
          "enum": ["OK", "Warning", "Failure", "Disabled", "Pending"]
        },
        "policy": {
          "type": "string",
          "description": "Health status of policy enforcement for this endpoint.",
          "enum": ["OK", "Warning", "Failure", "Disabled", "Pending"]
        }
      }
    },
    "ControllerStatus": {
      "type": "object",
      "description": "Status of a background controller managing endpoint reconciliation.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Controller name."
        },
        "configuration": {
          "type": "object",
          "description": "Controller configuration settings."
        },
        "status": {
          "type": "object",
          "description": "Current controller run status.",
          "properties": {
            "consecutiveFailureCount": {
              "type": "integer",
              "description": "Number of consecutive failed runs.",
              "minimum": 0
            },
            "failureCount": {
              "type": "integer",
              "description": "Total number of failed runs.",
              "minimum": 0
            },
            "lastFailureTimestamp": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp of the most recent failure."
            },
            "lastSuccessTimestamp": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp of the most recent successful run."
            },
            "successCount": {
              "type": "integer",
              "description": "Total number of successful runs.",
              "minimum": 0
            }
          }
        },
        "uuid": {
          "type": "string",
          "description": "Unique identifier for this controller instance."
        }
      }
    },
    "EndpointStatusChange": {
      "type": "object",
      "description": "A single status change entry in the endpoint log.",
      "properties": {
        "code": {
          "type": "string",
          "description": "Status change result code.",
          "enum": ["ok", "failed"]
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of the status change event."
        },
        "state": {
          "type": "string",
          "description": "Endpoint state after this change.",
          "enum": [
            "waiting-for-identity",
            "not-ready",
            "waiting-to-regenerate",
            "regenerating",
            "restoring",
            "ready",
            "disconnecting",
            "disconnected",
            "invalid"
          ]
        },
        "timestamp": {
          "type": "string",
          "description": "ISO 8601 timestamp when this status change occurred."
        }
      }
    }
  }
}