Kubernetes Services Watch Events

asyncapi: 2.6.0
info:
  title: Kubernetes Services Watch Events
  description: >-
    The Kubernetes Services watch API provides streaming event notifications
    for networking resources including Services, Ingresses, EndpointSlices,
    NetworkPolicies, and Gateway API resources. Clients subscribe to resource
    watch streams and receive ADDED, MODIFIED, DELETED, and BOOKMARK events
    as networking configuration changes in the cluster. These streams are
    used by ingress controllers, load balancer operators, service mesh
    components, and observability tools to maintain synchronized state.
  version: v1.32.0
  contact:
    name: Kubernetes Community
    url: https://kubernetes.io/community/
externalDocs:
  description: Kubernetes API Concepts - Watch
  url: https://kubernetes.io/docs/reference/using-api/api-concepts/
servers:
  kubernetesApiServer:
    url: 'https://kubernetes.default.svc'
    protocol: https
    description: In-cluster Kubernetes API server for watch streaming.
    security:
      - bearerAuth: []
      - clientCertificate: []
channels:
  /api/v1/namespaces/{namespace}/services:
    description: >-
      Watch stream for Service objects in a namespace. Service changes include
      creation of new services, updates to port mappings or selectors, type
      changes (e.g. ClusterIP to LoadBalancer), and deletions.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedServices
      summary: Watch Services in a namespace
      description: >-
        Streams WatchEvent messages for all Service changes in the specified
        namespace. Used by load balancer controllers to track service creation
        and updates, and by kube-proxy to sync iptables/ipvs rules.
      message:
        $ref: '#/components/messages/ServiceWatchEvent'
  /api/v1/services:
    description: >-
      Watch stream for all Service objects across all namespaces in the
      cluster. Used for cluster-wide service discovery and monitoring.
    subscribe:
      operationId: watchAllServices
      summary: Watch all Services cluster-wide
      description: >-
        Streams WatchEvent messages for Service changes across all namespaces.
        Useful for external DNS controllers and global load balancer
        controllers that manage cluster-wide service exposure.
      message:
        $ref: '#/components/messages/ServiceWatchEvent'
  /apis/networking.k8s.io/v1/namespaces/{namespace}/ingresses:
    description: >-
      Watch stream for Ingress objects in a namespace. Ingress changes include
      new routing rules, TLS configuration updates, and load balancer
      status updates from the ingress controller.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedIngresses
      summary: Watch Ingresses in a namespace
      description: >-
        Streams WatchEvent messages for Ingress changes in the specified
        namespace. Ingress controllers watch this stream to reconfigure
        their proxies when routing rules are added or modified.
      message:
        $ref: '#/components/messages/IngressWatchEvent'
  /apis/discovery.k8s.io/v1/namespaces/{namespace}/endpointslices:
    description: >-
      Watch stream for EndpointSlice objects in a namespace. EndpointSlice
      changes reflect pod readiness transitions, pod scheduling, and pod
      termination as pods backing a Service change state.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedEndpointSlices
      summary: Watch EndpointSlices in a namespace
      description: >-
        Streams WatchEvent messages for EndpointSlice changes. kube-proxy
        and service mesh sidecars watch this stream to keep their endpoint
        routing tables synchronized with the current set of ready pods.
      message:
        $ref: '#/components/messages/EndpointSliceWatchEvent'
  /apis/networking.k8s.io/v1/namespaces/{namespace}/networkpolicies:
    description: >-
      Watch stream for NetworkPolicy objects in a namespace. Network policy
      changes are monitored by CNI plugins to update their eBPF or iptables
      rules enforcing pod-level traffic restrictions.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedNetworkPolicies
      summary: Watch NetworkPolicies in a namespace
      description: >-
        Streams WatchEvent messages for NetworkPolicy changes in the specified
        namespace. CNI plugin agents watch this stream to enforce the latest
        traffic rules for pods without requiring restarts.
      message:
        $ref: '#/components/messages/NetworkPolicyWatchEvent'
  /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/gateways:
    description: >-
      Watch stream for Gateway objects in a namespace. Gateway changes include
      new listener configurations, TLS certificate updates, and status
      updates from the gateway controller.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedGateways
      summary: Watch Gateways in a namespace
      description: >-
        Streams WatchEvent messages for Gateway resources. Gateway controllers
        watch this stream to provision or update the underlying load balancer
        or proxy infrastructure.
      message:
        $ref: '#/components/messages/GatewayWatchEvent'
  /apis/gateway.networking.k8s.io/v1/namespaces/{namespace}/httproutes:
    description: >-
      Watch stream for HTTPRoute objects in a namespace. HTTPRoute changes
      reflect updates to routing rules, backend weights, and match conditions
      used by gateway controllers.
    parameters:
      namespace:
        $ref: '#/components/parameters/Namespace'
    subscribe:
      operationId: watchNamespacedHTTPRoutes
      summary: Watch HTTPRoutes in a namespace
      description: >-
        Streams WatchEvent messages for HTTPRoute resources. Gateway controllers
        watch this stream to update proxy routing configuration whenever
        application teams modify traffic routing rules.
      message:
        $ref: '#/components/messages/HTTPRouteWatchEvent'
components:
  securitySchemes:
    bearerAuth:
      type: httpApiKey
      name: Authorization
      in: header
      description: Kubernetes service account or user bearer token.
    clientCertificate:
      type: X509
      description: Client TLS certificate signed by the cluster CA.
  parameters:
    Namespace:
      description: Namespace name to scope the watch stream.
      schema:
        type: string
  messages:
    ServiceWatchEvent:
      name: ServiceWatchEvent
      title: Service Watch Event
      summary: Change event for a Kubernetes Service resource
      description: >-
        A watch event delivered when a Service is created, modified, or deleted
        in the cluster. The object field contains the current state of the
        Service, including its type, port mappings, selector, and load balancer
        status.
      payload:
        $ref: '#/components/schemas/WatchEvent'
    IngressWatchEvent:
      name: IngressWatchEvent
      title: Ingress Watch Event
      summary: Change event for a Kubernetes Ingress resource
      description: >-
        A watch event delivered when an Ingress is created, its routing rules
        are modified, or the ingress controller updates its load balancer
        status.
      payload:
        $ref: '#/components/schemas/WatchEvent'
    EndpointSliceWatchEvent:
      name: EndpointSliceWatchEvent
      title: EndpointSlice Watch Event
      summary: Change event for a Kubernetes EndpointSlice resource
      description: >-
        A watch event delivered when an EndpointSlice is created, when pod
        readiness changes, when pods are added or removed from a Service's
        selector, or when topology hints are updated.
      payload:
        $ref: '#/components/schemas/WatchEvent'
    NetworkPolicyWatchEvent:
      name: NetworkPolicyWatchEvent
      title: NetworkPolicy Watch Event
      summary: Change event for a Kubernetes NetworkPolicy resource
      description: >-
        A watch event delivered when a NetworkPolicy is created, its ingress
        or egress rules are modified, or the policy is deleted. CNI plugins
        consume these events to enforce the current network segmentation rules.
      payload:
        $ref: '#/components/schemas/WatchEvent'
    GatewayWatchEvent:
      name: GatewayWatchEvent
      title: Gateway Watch Event
      summary: Change event for a Gateway API Gateway resource
      description: >-
        A watch event delivered when a Gateway is created, listener
        configurations change, TLS certificates are updated, or the gateway
        controller updates the assigned addresses in the status.
      payload:
        $ref: '#/components/schemas/WatchEvent'
    HTTPRouteWatchEvent:
      name: HTTPRouteWatchEvent
      title: HTTPRoute Watch Event
      summary: Change event for a Gateway API HTTPRoute resource
      description: >-
        A watch event delivered when an HTTPRoute is created, routing rules
        are modified, backend references change, or the gateway controller
        updates the route's accepted status.
      payload:
        $ref: '#/components/schemas/WatchEvent'
  schemas:
    WatchEvent:
      type: object
      required:
        - type
        - object
      description: >-
        A watch event representing a state change to a Kubernetes networking
        resource. The type indicates the change nature and the object contains
        the full resource state after the change.
      properties:
        type:
          type: string
          enum:
            - ADDED
            - MODIFIED
            - DELETED
            - BOOKMARK
            - ERROR
          description: >-
            Type of change. ADDED on resource creation, MODIFIED on any
            spec/status/metadata update, DELETED on removal. BOOKMARK
            provides a resourceVersion checkpoint for resuming watches.
            ERROR indicates a problem with the watch stream.
        object:
          type: object
          description: >-
            The Kubernetes resource at the time of the event. For BOOKMARK
            events only metadata.resourceVersion is populated. For ERROR
            events this is a Status object.
          properties:
            apiVersion:
              type: string
              description: API version of the resource.
            kind:
              type: string
              description: Kind of the resource (e.g. Service, Ingress, EndpointSlice).
            metadata:
              type: object
              description: Object metadata including name, namespace, and resourceVersion.
              properties:
                name:
                  type: string
                  description: Name of the resource.
                namespace:
                  type: string
                  description: Namespace of the resource.
                uid:
                  type: string
                  description: Unique identifier of the resource.
                resourceVersion:
                  type: string
                  description: Resource version for resuming watch streams.
                generation:
                  type: integer
                  description: Generation of the resource spec.
                creationTimestamp:
                  type: string
                  format: date-time
                  description: Creation timestamp.
                deletionTimestamp:
                  type: string
                  format: date-time
                  description: Deletion timestamp when graceful deletion is pending.
                labels:
                  type: object
                  additionalProperties:
                    type: string
                  description: Resource labels.
                annotations:
                  type: object
                  additionalProperties:
                    type: string
                  description: Resource annotations.