Skip to content

Commit 72602d3

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #3425 from geoffcline/gdc-revise-sg
Revise page on security groups
2 parents 276c693 + 3900e42 commit 72602d3

File tree

3 files changed

+181
-17
lines changed

3 files changed

+181
-17
lines changed

‎docs/deploy/security_groups.md‎

Lines changed: 59 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,74 @@
1-
# Security groups
1+
# Security Groups for Load Balancers
22

3-
The AWS Load Balancer Controller classifies security groups into two categories: frontend and backend.
3+
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**.
4+
5+
- **Frontend Security Groups:** Determine the clients that can access the load balancers.
6+
- **Backend Security Groups:** Permit the load balancer to connect to targets, such as EC2 instances or ENIs.
47

58
## Frontend Security Groups
69

7-
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`.
10+
Frontend security groups control access to load balancers by specifying which clients can connect to them.
11+
12+
Use cases for Frontent Security Groups include:
13+
14+
* Placing the load balancer behind another service, such as [AWS Web Application Firewall](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html) or [AWS CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html).
15+
* Blocking the IP address range (CIDR) of a region.
16+
* Configuring the Load Balancer for private or internal use, by specifying internal CIDRs and Security Groups.
17+
18+
In the default configuration, the LBC automatically creates one security group per load balancer, allowing traffic from `inbound-cidrs` to `listen-ports`.
19+
20+
### Configuration
21+
22+
Apply custom frontend security groups with an annotation. This disables automatic generation of frontend security groups.
23+
24+
- For Ingress resources, use the [`alb.ingress.kubernetes.io/security-groups`](../guide/ingress/annotations.md#security-groups) annotation.
25+
- For Service resources, use the [`service.beta.kubernetes.io/aws-load-balancer-security-groups`](../guide/service/annotations.md#security-groups) annotation.
26+
- The annotation must be set to one or more security group IDs or security group names.
27+
828

929
## Backend Security Groups
1030

11-
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.
31+
Backend Security Groups control 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.
32+
33+
- Backend security groups permit traffic from AWS Load Balancers to their targets.
34+
- 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.
35+
- When configuring security group rules at the ENI/Instance level, use the Security Group ID of the backend security group. Avoid using the IP addresses of a specific AWS Load Balancer, these IPs are dynamic and the security group rules aren't updated automatically.
36+
37+
### Configuration
38+
39+
**Enable or Disable:** Use `--enable-backend-security-group` (default `true`) to enable/disable the shared backend security group.
40+
41+
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.
42+
43+
**Specification:** Use `--backend-security-group` to pass in a security group ID to use as a custom shared backend security group.
44+
45+
If `--backend-security-group` is left empty, a security group with the following attributes will be created:
46+
47+
```yaml
48+
name: k8s-traffic-<cluster_name>-<hash_of_cluster_name>
49+
tags:
50+
elbv2.k8s.aws/cluster: <cluster_name>
51+
elbv2.k8s.aws/resource: backend-sg
52+
```
53+
1254
13-
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 -
55+
### Coordination of Frontend and Backend Security Groups
1456
15-
```
16-
name: k8s-traffic-<cluster_name>-<hash_of_cluster_name>
17-
tags:
18-
elbv2.k8s.aws/cluster: <cluster_name>
19-
elbv2.k8s.aws/resource: backend-sg
20-
```
2157
22-
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.
58+
- 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.
59+
- If the frontend security groups are manually specified, the LBC will not **by default** add any rules to the backend security group.
2360
24-
### Management of Backend Security Group Rules
61+
#### Enable Autogeneration of Backend Security Group Rules
2562
26-
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.
63+
- If using custom frontend security groups, the LBC can be configured to automatically manage backend security group rules.
64+
- To enable managing backend security group rules, apply an additional annotation to Ingress and Service resources.
65+
- For Ingress resources, set the `alb.ingress.kubernetes.io/manage-backend-security-group-rules` annotation to `true`.
66+
- For Service resources, set the `service.beta.kubernetes.io/aws-load-balancer-manage-backend-security-group-rules` annotation to `true`.
67+
- 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.
68+
- These annotations are ignored when using auto-generated frontend security groups.
2769

28-
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.
70+
### Port Range Restrictions
2971

30-
### Port Range Restrictions for Backend Security Group Rules
72+
From version v2.3.0 onwards, the controller restricts port ranges in the backend security group rules by default. This improves the security of the default configuration. The LBC should generate the necessary rules to permit traffic, based on the Service and Ingress resources.
3173

32-
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.
74+
If needed, set the controller flag `--disable-restricted-sg-rules` to `true` to permit traffic to all ports. This may be appropriate for backwards compatability, or troubleshooting.

‎docs/guide/use_cases/frontend_sg/index.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Restrict Access with Frontend Security Groups
3+
---
4+
5+
Frontend security groups limit client/internet traffic with a load balancer. This improves security by preventing unauthorized access to cluster services, and blocking unexpected outbound connections. Both [AWS Network Load Balancers (NLBs) and Application Load Balancers (ALBs)](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/load-balancer-types.html) support frontend security groups. Learn more about how the Load Balancer Controller uses [Frontend and Backend Security Groups](../../../deploy/security_groups.md).
6+
7+
## Solution Overview
8+
9+
Load balancers expose cluster workloads to a wider network. Creating a frontend security group limits access to these workloads (service or ingress resources). More specifically, a security group acts as a virtual firewall to control incoming and outgoing traffic. Inbound rules control the incoming traffic to your load balancer, and outbound rules control the outgoing traffic from your load balancer.
10+
11+
Security groups are particularly suited for defining what access other AWS resources (services, EC2 instances) have to your cluster. For example, if you have an existing security group including EC2 instances, you can permit only that security group to access a service.
12+
13+
In this example, you will restrict access to a cluster service. You will create a new security group for the frontend of a load balancer, and add an inbound rule permitting traffic. The rule may limit traffic to a specific port, CIDR, or existing security group.
14+
15+
## Prerequisites
16+
17+
- [Kubernetes Cluster Version 1.22+](https://docs.aws.amazon.com/cli/latest/reference/eks/describe-cluster.html)
18+
- [AWS Load Balancer Controller v2.6.0+](../../../deploy/installation/)
19+
- [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
20+
21+
## Configure
22+
23+
### 1. Find the VPC ID of your cluster
24+
25+
```sh
26+
$ aws eks describe-cluster --name <cluster-name> --query "cluster.resourcesVpcConfig.vpcId" --output text
27+
28+
vpc-0101XXXXa356
29+
```
30+
31+
Ensure you have the right cluster name, AWS region, and the AWS CLI is configured.
32+
33+
### 2. Create a security group using the VPC ID
34+
35+
```sh
36+
$ aws ec2 create-security-group --group-name <sg-name> --description <description> --vpc-id <vpc-id>
37+
38+
{
39+
"GroupId": "sg-0406XXXX645c"
40+
}
41+
```
42+
43+
Note the security group ID. This will be the frontend security group for the load balancer.
44+
45+
### 3. Create your ingress rules
46+
47+
Load balancers generally serve as an entrypoint for clients to access your cluster. This makes ingress rules especially important.
48+
49+
For example, this rule permits all traffic on port 443:
50+
51+
```sh
52+
aws ec2 authorize-security-group-ingress --group-id <sg-id> --protocol all --port 443 --cidr 0.0.0.0/0
53+
```
54+
55+
Learn more about how to [create an ingress rule with the AWS CLI.](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/authorize-security-group-ingress.html)
56+
57+
### 4. Determine your egress rules (optional)
58+
59+
By default, all outbound traffic is allowed. Further, security groups are stateful, and responses to an allowed connection will also be permitted.
60+
61+
Learn how to [create an egress rule with the AWS CLI.](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/authorize-security-group-egress.html)
62+
63+
### 5. Add the security group annotation to your Ingress or Service
64+
65+
For [Ingress resources](../../../guide/ingress/annotations.md), add the following annotation:
66+
67+
```yaml
68+
apiVersion: networking.k8s.io/v1
69+
kind: Ingress
70+
metadata:
71+
name: frontend
72+
annotations:
73+
alb.ingress.kubernetes.io/security-groups: <sg-id>
74+
```
75+
76+
For [Service resources](../../../guide/service/annotations.md#annotations), add the following annotation:
77+
78+
```yaml
79+
apiVersion: v1
80+
kind: Service
81+
metadata:
82+
name: frontend
83+
annotations:
84+
service.beta.kubernetes.io/aws-load-balancer-security-groups: <sg-id>
85+
spec:
86+
type: LoadBalancer
87+
loadBalancerClass: service.k8s.aws/nlb
88+
```
89+
90+
For Ingress resources, the associated Application Load Balancer will be updated. For Service resources, the associated Network Load Balancer will be updated.
91+
92+
### 6. List your load balancers and verify the security groups are attached
93+
94+
```sh
95+
$ aws elbv2 describe-load-balancers
96+
97+
{
98+
"LoadBalancers": [
99+
{
100+
"LoadBalancerArn": "arn:aws:elasticloadbalancing:us-east-1:1853XXXX5115:loadbalancer/net/k8s-default-frontend-ae3743b818/3ad6d16fb75ff688",
101+
<...>
102+
"SecurityGroups": [
103+
"sg-0406XXXX645c",
104+
"sg-0873XXXX2bef"
105+
],
106+
"IpAddressType": "ipv4"
107+
}
108+
]
109+
}
110+
```
111+
112+
If you don't see the security groups, verify:
113+
114+
- The Load Balancer Controller is properly installed.
115+
- The controller has proper IAM permissions to modify load balancers. Look at the logs of the controller pods for IAM errors.
116+
117+
### 7. Clean up (Optional)
118+
119+
Removing the annotations from Service/Ingress resources will revert to the default frontend ecurity groups.
120+
121+
Load balancers may be costly. Delete Ingress and Service resources to deprovision the load balancers. If the load balancers are deleted from the console, they may be recreated by the controller.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ nav:
3434
- Use Cases:
3535
- NLB TLS Termination: guide/use_cases/nlb_tls_termination/index.md
3636
- Externally Managed Load Balancer: guide/use_cases/self_managed_lb/index.md
37+
- Frontend Security Groups: guide/use_cases/frontend_sg/index.md
3738
- Examples:
3839
- EchoServer: examples/echo_server.md
3940
- gRPCServer: examples/grpc_server.md

0 commit comments

Comments
 (0)