Add documentation for frontend VPC configuration annotations

- Document new frontend VPC annotations: frontend-subnet-id, frontend-vpc-name, frontend-subnet-name, frontend-ipv4-range, frontend-ipv6-range
- Document backend-subnet-id annotation
- Add detailed frontend VPC configuration section explaining annotation precedence and usage
- Update backend VPC annotation examples to use correct backend-vpc-name and backend-subnet-name prefixes
- Add reference to vpc-frontend-example.yaml in examples

Author: komer3

docs/configuration/annotations.md

@@ -43,6 +43,12 @@ The keys and the values in [annotations must be strings](https://kubernetes.io/d
 | `backend-ipv4-range` | string | | The IPv4 range from VPC subnet to be applied to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-vpc-name` | string | | VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `backend-subnet-name` | string | | Subnet within VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `backend-subnet-id` | string | | Subnet ID within VPC which is connected to the NodeBalancer backend. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `frontend-subnet-id` | string | | Subnet ID for the NodeBalancer frontend VPC configuration. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `frontend-vpc-name` | string | | Frontend VPC name for the NodeBalancer frontend VPC configuration. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `frontend-subnet-name` | string | | Frontend subnet name for the NodeBalancer frontend VPC configuration. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `frontend-ipv4-range` | string | | Optional IPv4 CIDR range from the frontend subnet. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
+| `frontend-ipv6-range` | string | | Optional IPv6 CIDR range from the frontend subnet. See [Nodebalancer VPC Configuration](#nodebalancer-vpc-configuration) |
 | `reserved-ipv4` | string | | An existing Reserved IPv4 address that wil be used to initialize the NodeBalancer instance. See [LoadBalancer Configuration](loadbalancer.md#reserved-ipv4-addresses)) |
 
 ### Port Specific Configuration
@@ -135,8 +141,18 @@ metadata:
 metadata:
   annotations:
     service.beta.kubernetes.io/linode-loadbalancer-backend-ipv4-range: "10.100.0.0/30"
-    service.beta.kubernetes.io/linode-loadbalancer-vpc-name: "vpc1"
-    service.beta.kubernetes.io/linode-loadbalancer-subnet-name: "subnet1"
+    service.beta.kubernetes.io/linode-loadbalancer-backend-vpc-name: "vpc1"
+    service.beta.kubernetes.io/linode-loadbalancer-backend-subnet-name: "subnet1"
+```
+
+Frontend VPC configuration:
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-frontend-subnet-id: "169341"
+    # Optional:
+    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv4-range: "10.0.0.0/24"
+    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv6-range: "2001:db8::/64"
 ```
 
 ### Service with IPv6 Address
@@ -151,7 +167,7 @@ For more examples and detailed configuration options, see:
 - [Firewall Configuration](firewall.md)
 - [Basic Service Examples](../examples/basic.md)
 - [Advanced Configuration Examples](../examples/advanced.md)
-- [Complete Stack Example](../examples/complete-stack.md)
+- [Examples](../examples/README.md)
 
 See also:
 - [Environment Variables](environment.md)

docs/configuration/loadbalancer.md

@@ -194,10 +194,43 @@ By default, CCM uses first VPC and Subnet name configured with it to attach Node
 metadata:
   annotations:
     service.beta.kubernetes.io/linode-loadbalancer-backend-ipv4-range: "10.100.0.4/30"
-    service.beta.kubernetes.io/linode-loadbalancer-vpc-name: "vpc1"
-    service.beta.kubernetes.io/linode-loadbalancer-subnet-name: "subnet1"
+    service.beta.kubernetes.io/linode-loadbalancer-backend-vpc-name: "vpc1"
+    service.beta.kubernetes.io/linode-loadbalancer-backend-subnet-name: "subnet1"
 ```
 
+### Configuring NodeBalancer frontend with VPC
+
+NodeBalancers can optionally be configured with a VPC-based frontend address.
+
+Frontend VPC configuration supports the following annotations:
+
+1. Choose the frontend subnet:
+
+   - `service.beta.kubernetes.io/linode-loadbalancer-frontend-subnet-id` (preferred)
+   - OR `service.beta.kubernetes.io/linode-loadbalancer-frontend-vpc-name` and `service.beta.kubernetes.io/linode-loadbalancer-frontend-subnet-name`
+
+2. Optionally constrain the frontend address assignment within the subnet:
+
+   - `service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv4-range` (CIDR)
+   - `service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv6-range` (CIDR)
+
+Order of precedence:
+- If `frontend-subnet-id` is set, it is used.
+- Otherwise, `frontend-vpc-name` + `frontend-subnet-name` are used.
+- IPv4/IPv6 range annotations are optional add-ons and require one of the subnet selectors above.
+
+Example:
+```yaml
+metadata:
+  annotations:
+    service.beta.kubernetes.io/linode-loadbalancer-frontend-subnet-id: "169341"
+    # Optional:
+    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv4-range: "10.0.0.0/24"
+    # service.beta.kubernetes.io/linode-loadbalancer-frontend-ipv6-range: "2001:db8::/64"
+```
+
+For a complete working example, see `examples/vpc-frontend-example.yaml`.
+
 If CCM is started with `--nodebalancer-backend-ipv4-subnet` flag, then it will not allow provisioning of nodebalancer unless subnet specified in service annotation lie within the subnet specified using the flag. This is to prevent accidental overlap between nodebalancer backend ips and pod CIDRs.
 
 ## Advanced Configuration

docs/examples/README.md

@@ -16,6 +16,9 @@ This section provides working examples of common CCM configurations. Each exampl
    - Shared IP Load-Balancing
    - Custom Node Selection
 
+3. **Frontend VPC NodeBalancer**
+   - `examples/vpc-frontend-example.yaml`
+
 Note: To test UDP based NBs, one can use [test-server](https://github.com/rahulait/test-server) repo to run server using UDP protocol and then use the client commands in repo's readme to connect to the server.
 
 For testing these examples, see the [test script](https://github.com/linode/linode-cloud-controller-manager/blob/master/examples/test.sh).