Assign security groups to a pod - Elastic Container Instance

Security groups act as virtual firewalls for pods running as Elastic Container Instances (ECI) in Container Service for Kubernetes (ACK). They use Stateful Packet Inspection (SPI) and packet filtering to control inbound and outbound traffic at the pod level. You can use security groups to define security domains in the cloud.

Applies to: ACK clusters with Virtual Node (Virtual Kubelet) enabled

Before you begin

Before assigning security groups, make sure you have:

An ACK cluster with the Virtual Node component (Virtual Kubelet) installed
At least one security group created in the same virtual private cloud (VPC) as your cluster. To create one, see Create a security group
Virtual Kubelet v2.0.0.90-15deb126e-aliyun or later, if you need cluster-level configuration changes to apply without restarting pods (hot update). To check your version and upgrade if needed, see the Virtual Kubelet release notes

Limitations

Review these constraints before you proceed:

Constraint	Detail
Membership required	Each elastic container instance must belong to a security group.
Immutability	Security groups cannot be changed on a running pod. To move a pod to a different security group, create an identical pod in that security group.
Pod-level limit	A pod can belong to up to five security groups.
Same VPC	All security groups assigned to a pod must be in the same VPC.
Same type	All security groups assigned to a pod must be of the same type — either all basic security groups or all advanced security groups.
Annotation timing	The `k8s.aliyun.com/eci-security-group` annotation only takes effect when a pod is created. Adding or modifying the annotation on an existing pod has no effect.

Security group types

ECI supports two security group types:

Type	Description	Recommended when
Basic security group	Standard security group with rule-based traffic control	General workloads
Advanced security group	Higher instance capacity, simplified rule management	Large-scale ECI deployments requiring high operational efficiency

All instances in a security group are mutually trusted and protected under the same security group rules. Security group rules control access to or from the Internet or internal network for the elastic container instances in the security group.

For a detailed comparison, see Basic security groups and advanced security groups.

Assign a security group at the cluster level

By default, all ECI-based pods in an ACK cluster use the security group specified in the eci-profile ConfigMap. To change the default security group for all pods in the cluster, edit this ConfigMap.

Open the eci-profile ConfigMap for editing:

kubectl edit configmap eci-profile -n kube-system

Update securityGroupId in the data section with your security group ID. Only one security group ID is supported at the cluster level.

data:
  enableClusterIp: "true"
  enableHybridMode: "false"
  enablePrivateZone: "false"
  resourceGroupId: ""
  securityGroupId: sg-2ze0b9o8pjjzts4h****  # Specify a single security group ID.
  selectors: ""
  vSwitchIds: vsw-2zeet2ksvw7f14ryz****,vsw-2ze94pjtfuj9vaymf****
  vpcId: vpc-2zeghwzptn5zii0w7****

Save the file. If Virtual Kubelet is v2.0.0.90-15deb126e-aliyun or later, the change takes effect immediately without restarting existing pods.

Assign security groups to a specific pod

To override the cluster-level default for individual pods, add the k8s.aliyun.com/eci-security-group annotation to the pod spec. This is useful when specific workloads require stricter or more permissive network policies.

Important

Add annotations in spec.template.metadata for Deployments — not in the top-level metadata. Annotations only take effect at pod creation time.

The following example assigns two security groups to all pods created by the test Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: test
  labels:
    app: test
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      name: nginx-test
      labels:
        app: nginx
        alibabacloud.com/eci: "true"
      annotations:
        k8s.aliyun.com/eci-security-group: "sg-bp1dktddjsg5nktv****,sg-2ze0b9o8pjjzts4h****"  # Up to 5 IDs, comma-separated.
    spec:
      containers:
      - name: nginx
        image: registry.cn-shanghai.aliyuncs.com/eci_open/nginx:1.14.2
        ports:
        - containerPort: 80

Add a security group rule

Security group rules control which traffic can reach your pods. Common use cases:

Enable cross-security-group communication: Add a security group rule to allow traffic from a service outside the pod's security group.
Block malicious sources: Add a security group rule to block access from sources when attacks are detected.

To add a rule, see Add a security group rule.

What's next

Overview of security groups — Learn how security groups work and how rules are evaluated
Basic security groups and advanced security groups — Compare the two types to choose the right one for your workload