|
| 1 | + |
| 2 | +# Gateway API Conformance Testing |
| 3 | + |
| 4 | +This directory contains conformance tests for the AWS Load Balancer Controller's Gateway API implementation. These tests validate compliance with the [Kubernetes Gateway API specification](https://gateway-api.sigs.k8s.io/concepts/conformance/). |
| 5 | + |
| 6 | +## Prerequisites |
| 7 | + |
| 8 | +- Kubernetes cluster (v1.19+) |
| 9 | +- kubectl configured to access your cluster |
| 10 | +- Gateway API CRDs installed |
| 11 | +- Go 1.21+ (for running tests locally) |
| 12 | + |
| 13 | +## Setup |
| 14 | + |
| 15 | +### 1. Install AWS Load Balancer Controller |
| 16 | + |
| 17 | +Follow the [official installation guide](https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.14/deploy/installation/) to deploy the controller to your cluster. |
| 18 | + |
| 19 | +### 2. Create a GatewayClass |
| 20 | + |
| 21 | +Create a GatewayClass resource for conformance testing: |
| 22 | + |
| 23 | +```yaml |
| 24 | +apiVersion: gateway.networking.k8s.io/v1 |
| 25 | +kind: GatewayClass |
| 26 | +metadata: |
| 27 | + name: REPLACE_WITH_GATEWAY_CLASS_NAME |
| 28 | +spec: |
| 29 | + controllerName: ingress.k8s.aws/alb |
| 30 | +``` |
| 31 | +
|
| 32 | +Apply it: |
| 33 | +```bash |
| 34 | +kubectl apply -f gatewayclass.yaml |
| 35 | +``` |
| 36 | + |
| 37 | +### 3. Configure Controller Deployment |
| 38 | + |
| 39 | +Edit the controller deployment to enable Gateway API features: |
| 40 | + |
| 41 | +```bash |
| 42 | +kubectl edit deployment -n kube-system aws-load-balancer-controller |
| 43 | +``` |
| 44 | + |
| 45 | +Ensure these arguments are present: |
| 46 | +```yaml |
| 47 | +spec: |
| 48 | + template: |
| 49 | + spec: |
| 50 | + containers: |
| 51 | + - args: |
| 52 | + - --default-target-type=ip |
| 53 | + - --feature-gates=NLBGatewayAPI=true,ALBGatewayAPI=true |
| 54 | +``` |
| 55 | +
|
| 56 | +## Running Tests |
| 57 | +
|
| 58 | +### Run a Single Test Case |
| 59 | +
|
| 60 | +Useful for debugging specific functionality: |
| 61 | +
|
| 62 | +```bash |
| 63 | +go test ./conformance -run TestConformance -v -args \ |
| 64 | +--gateway-class=REPLACE_WITH_GATEWAY_CLASS_NAME \ |
| 65 | +--run-test=HTTPRouteExactPathMatching --allow-crds-mismatch=true --cleanup-base-resources=false \ |
| 66 | +--debug=true |
| 67 | +``` |
| 68 | + |
| 69 | +**Arguments explained:** |
| 70 | +- `--gateway-class`: Name of the GatewayClass to use for testing |
| 71 | +- `--run-test`: Specific test to run (e.g., HTTPRouteExactPathMatching) |
| 72 | +- `--allow-crds-mismatch=true`: Allow CRD version mismatches between test suite and cluster |
| 73 | +- `--cleanup-base-resources=false`: Keep resources after test for debugging |
| 74 | +- `--debug=true`: Enable verbose debug logging |
| 75 | + |
| 76 | +### Run a Conformance Profile |
| 77 | + |
| 78 | +Run a complete profile (e.g., GATEWAY-HTTP) with custom configuration: |
| 79 | + |
| 80 | +```bash |
| 81 | +go test -v ./conformance \ |
| 82 | +--gateway-class=REPLACE_WITH_YOUR_GW_CLASS \ |
| 83 | +--allow-crds-mismatch=true --cleanup-base-resources=false \ |
| 84 | +--conformance-profiles=GATEWAY-HTTP \ |
| 85 | +--supported-features=Gateway,HTTPRoute \ |
| 86 | +--skip-tests=GatewaySecretInvalidReferenceGrant \ |
| 87 | +--debug=true |
| 88 | +``` |
| 89 | + |
| 90 | +**Arguments explained:** |
| 91 | +- `--conformance-profiles`: Profile to test (GATEWAY-HTTP, GATEWAY-GRPC, etc.) |
| 92 | +- `--supported-features`: Comma-separated list of features your implementation supports |
| 93 | +- `--skip-tests`: Comma-separated list of tests to skip |
| 94 | + |
| 95 | + |
| 96 | +## Exempt Features |
| 97 | + |
| 98 | +Features not yet implemented (tests will be skipped): |
| 99 | +- `GatewayStaticAddresses` |
| 100 | +- `GatewayHTTPListenerIsolation` |
| 101 | +- `HTTPRouteRequestMultipleMirrors` |
| 102 | +- `HTTPRouteRequestTimeout` |
| 103 | +- `HTTPRouteBackendTimeout` |
| 104 | +- `HTTPRouteParentRefPort` |
| 105 | +- continue updating... |
| 106 | + |
| 107 | +## Troubleshooting |
| 108 | + |
| 109 | +### CRD Version Mismatch |
| 110 | + |
| 111 | +If you see CRD version errors, use `--allow-crds-mismatch=true` or update your Gateway API CRDs: |
| 112 | +```bash |
| 113 | +kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml |
| 114 | +``` |
| 115 | + |
| 116 | +### Target Group Port Empty |
| 117 | +If you see |
| 118 | +``` |
| 119 | +"error":"TargetGroup port is empty. When using Instance targets, your service must be of type 'NodePort' or 'LoadBalancer'" |
| 120 | +``` |
| 121 | +Make sure argument `--default-target-type=ip` is added to deployment |
0 commit comments