revise

docs/deploy/security_groups.md

@@ -1,32 +1,68 @@
-# Security groups
+# Security Groups for Load Balancers
 
-The AWS Load Balancer Controller classifies security groups into two categories: frontend and backend.
+Use security groups to limit client connections to your load balancers, and restrict connections with nodes. The AWS Load Balancer Controller (LBC) defines two classifications of security groups: **frontend** and **backend**.
+
+- **Frontend Security Groups:** Determine the clients that can access the load balancers.
+- **Backend Security Groups:** Permit the load balancer to connect to targets, such as EC2 instances or ENIs.
 
 ## Frontend Security Groups
 
-Frontend security groups control which clients can access the load balancers. The frontend security groups can be configured with the `alb.ingress.kubernetes.io/security-groups` annotation on Ingress resources or `service.beta.kubernetes.io/aws-load-balancer-security-groups` annotation on Service resources. If the annotations are not specified, the LBC will create one security group per load balancer, allowing traffic from `inbound-cidrs` to `listen-ports`.
+Frontend security groups govern access to load balancers by specifying which clients can connect to them.
+
+In the default configuration, the LBC automatically creates one security group per load balancer, allowing traffic from `inbound-cidrs` to `listen-ports`.
+
+### Manually Specify Frontend Security Groups
+
+The frontend security groups may be manually specified with an annotation. This disables automatic generation of frontend security groups. 
+
+- For Ingress resources, use the [`alb.ingress.kubernetes.io/security-groups`](../guide/ingress/annotations.md#security-groups) annotation.
+- For Service resources, use the [`service.beta.kubernetes.io/aws-load-balancer-security-groups`](../guide/service/annotations.md#security-groups) annotation.
+- The annotation must be set to one or more security group IDs.
+
 
 ## Backend Security Groups
 
-A single shared backend security group controls the traffic between load balancers and their target EC2 instances or ENIs. This security group is attached to the load balancers and is used as the traffic source in the ENI/Instance security group rules. The backend security group is shared between multiple load balancers.
+Backend Security Groups serve as the control mechanism for traffic between AWS Load Balancers and their target EC2 instances or ENIs. For example, backend security groups can restrict the ports load balancers may access on nodes.
+
+- Backend security groups permit traffic from AWS Load Balancers to their targets. 
+- LBC uses a single, shared backend security group, attaching it to each load balancer and using as the traffic source in the security group rules it adds to targets.
+- When configuring security group rules at the ENI/Instance level, use the Security Group ID of the backend security group.
+
+### Configuration
+
+**Enable or Disable:** Use `--enable-backend-security-group` (default `true`) to enable/disable the shared backend security group.
+
+You can turn off the shared backend security group feature by setting it to `false`. However, if you have a high number of Ingress resources with frontend security groups auto-generated by the controller, you might run into security group rule limits on the instance/ENI security groups.
+
+**Specification:** Use `--backend-security-group` to pass in a security group ID to use as a shared backend security group. 
+
+If `--backend-security-group` is left empty, a security group with the following attributes will be created:
+
+  ```yaml
+  name: k8s-traffic-<cluster_name>-<hash_of_cluster_name>
+  tags: 
+      elbv2.k8s.aws/cluster: <cluster_name>
+      elbv2.k8s.aws/resource: backend-sg
+  ```
+
 
-The controller flag `--enable-backend-security-group` (default `true`) is used to enable/disable the shared backend security group. The flag `--backend-security-group` (default empty) is used to pass in the security group to use as a shared backend security group. If it is empty, the LBC will auto-generate a security group with the following name and tags -
+### Coordination of Frontend and Backend Security Groups
 
-```
-name: k8s-traffic-<cluster_name>-<hash_of_cluster_name>
-tags: 
-    elbv2.k8s.aws/cluster: <cluster_name>
-    elbv2.k8s.aws/resource: backend-sg
-```
 
-You can turn off the shared backend security group feature by setting `--enable-backend-security-group` to `false`. However, if you have a high number of Ingress resources with frontend security groups auto-generated by the controller, you might run into security group rule limits on the instance/ENI security groups.
+- If the LBC auto-creates the frontend security group for a load balancer, it automatically adds the security group rules to allow traffic from the load balancer to the backend instances/ENIs.
+- If the frontend security groups are manually specified, the LBC will not **by default** add any rules to the backend security group.
 
-### Management of Backend Security Group Rules
+#### Enable Management of Backend Security Group Rules
 
-When the LBC auto-creates the frontend security group for a load balancer, it automatically adds the security group rules to allow traffic from the load balancer to the backend instances/ENIs.
+- If using manually specified frontend security groups, the LBC can be configured to automatically manage backend security group rules.
+- To enable managing backend security group rules, apply an additional annotation to Ingress and Service resources.
+  - For Ingress resources, set the `alb.ingress.kubernetes.io/manage-backend-security-group-rules` annotation to `true`.
+  - For Service resources, set the `service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules` annotation to `true`.
+- If management of backend security group rules is enabled with an annotation on a Service or Ingress, then `--enable-backend-security-group` must be set to true.
+- These annotations are ignored when using auto-generated frontend security groups. 
 
-When the frontend security group is specified via the `alb.ingress.kubernetes.io/security-groups` annotation on Ingress resources or `service.beta.kubernetes.io/aws-load-balancer-security-groups` annotation on Service resources, the controller will not by default add any security group rules to the backend instances/ENIs. The automatic management of instance/ENI security group can be controlled via the additional annotation `alb.ingress.kubernetes.io/manage-backend-security-group-rules` on Ingress resources or `service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules` on Service resources. When these annotations are set to true the security group rules are automatically managed by the controller. These annotations get ignored in the case of auto-generated security groups. `--enable-backend-security-group` needs to be true if either `alb.ingress.kubernetes.io/manage-backend-security-group-rules` or `service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules` are specified, otherwise it is an error.
+### Port Range Restrictions
 
-### Port Range Restrictions for Backend Security Group Rules
+From version v2.3.0 onwards, the controller restricts port ranges in the backend security group rules by default.
 
-As of version v2.3.0, the controller will by default restrict the backend security group rules to specific port ranges. You can set the controller flag `--disable-restricted-sg-rules` to `true` to get the backend security group rules to allow traffic to ALL ports.
+If needed, set the controller flag `--disable-restricted-sg-rules` to `true` to permit traffic to all ports.