Configure Service topology

By default, the backend endpoints for a Kubernetes Service are spread across all nodes in a cluster. This can cause connectivity issues or inefficient performance for traffic that crosses between different groups of nodes. Service topology allows you to restrict traffic to applications on edge nodes, ensuring they are only accessed by nodes within the same node pool or by the local node. This topic explains the Service topology feature and shows you how to configure it.

Background

In edge computing scenarios, edge nodes are often grouped by geographic location or other logical attributes like CPU architecture, Internet service provider (ISP), or cloud service provider. These groups of nodes are typically isolated from each other. This isolation means they might lack network connectivity, share no resources, use heterogeneous resources, or run independent applications.

How Service topology works

To solve these problems, Container Service for Kubernetes (ACK) Edge adds an endpoint topology management feature to the native Service, which allows you to restrict the access scope of backend Endpoints for a Service through simple configurations. For example, an application on an edge node can be accessed only by nodes in the same node pool or only by the local node. The implementation principle is shown in the following figure.

Service1 is associated with two backend Pod instances: Pod 2 and Pod 3. The annotation: "openyurt.io/topologyKeys: kubernetes.io/zone" sets the topological scope for Service1 to the node pool.
Pod 2 is on node 2 and Pod 3 is on node 4. These nodes belong to two different node pools, node pool A and node pool B, respectively.
Because Pod 1 and Pod 3 are not in the same node pool, when Pod 1 accesses Service1, traffic is routed only to Pod 2. Access to Pod 3 is restricted.

Usage notes

For versions earlier than v1.26.3-aliyun.1: To enable Service topology, you must apply the Service topology annotation when you create the Service. If you add the annotation after the Service is created, the feature does not take effect. In this case, you must delete and recreate the Service.
For v1.26.3-aliyun.1 and later: You can modify the Service topology annotation after the Service is created. The changes take effect immediately.

Annotations

You can configure Service topology by adding an annotation to a standard Kubernetes Service. The following table describes the available annotations.

Annotation key	Annotation value	Description
openyurt.io/topologyKeys	kubernetes.io/hostname	Restricts Service access to the local node only.
openyurt.io/topologyKeys	kubernetes.io/zone or openyurt.io/nodepool	Restricts Service access to nodes within the same node pool. If your ACK Edge cluster version is 1.18 or later, we recommend that you use openyurt.io/nodepool.
-	-	No topology restrictions are applied to the Service.

You can configure Service topology using the console or the CLI.

Console

To create a Service that is accessible only by nodes within the same node pool, add an annotation to the Service. For example, set Name to openyurt.io/topologyKeys and Value to kubernetes.io/zone. For more information about how to create a Service, see Service management.

CLI

To create a Service that uses a node pool as its topology domain, use the following YAML example.

apiVersion: v1
kind: Service
metadata:
  annotations:
    openyurt.io/topologyKeys: kubernetes.io/zone
  name: my-service-nodepool
  namespace: default
spec:
  ports:
  - port: 80
    protocol: TCP
    targetPort: 8080
  selector:
    app: nginx
  sessionAffinity: None
  type: ClusterIP