Skip to content

Commit 91e5914

Browse files
GuimoveGuimove
committed
docs: add AWS cluster preflight checks documentation
1 parent 55b944a commit 91e5914

2 files changed

Lines changed: 169 additions & 0 deletions

File tree

‎docs/configuration/integrations/kubernetes/eks/preflight-checks.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: "AWS Cluster Preflight Checks"
3+
description: "Understand the automatic prerequisite validation checks that run before AWS EKS cluster creation"
4+
---
5+
6+
Before deploying a new AWS EKS cluster, Qovery automatically runs prerequisite validation checks to ensure your AWS environment is properly configured. If any check fails, deployment is blocked and a clear report shows what needs to be fixed.
7+
8+
<Info>
9+
Preflight checks run automatically when you create or deploy an AWS EKS cluster. No additional configuration is required.
10+
</Info>
11+
12+
## Checks Performed
13+
14+
### Quota Checks (All Modes)
15+
16+
Qovery verifies that your AWS account has sufficient resource quotas in the target region:
17+
18+
| Resource | Default AWS Limit | Required by Qovery |
19+
|----------|-------------------|---------------------|
20+
| EKS clusters per region | 100 | 1 per cluster |
21+
| Elastic IPs | 5 | 3-6 depending on NAT Gateway configuration |
22+
| VPCs per region | 5 | 1 per cluster |
23+
| NAT Gateways per AZ | Per-AZ limit | 1 per AZ used |
24+
25+
<Info>
26+
Qovery attempts to query your actual quota limits via the [AWS Service Quotas API](https://docs.aws.amazon.com/servicequotas/latest/userguide/intro.html). If the `servicequotas:GetServiceQuota` permission is not granted, Qovery falls back to AWS default limits and displays a **WARN** in the report. To get accurate quota checks, add the following permission to your IAM policy:
27+
28+
```json
29+
{
30+
"Effect": "Allow",
31+
"Action": "servicequotas:GetServiceQuota",
32+
"Resource": "*"
33+
}
34+
```
35+
</Info>
36+
37+
### Availability Zone Checks (All Modes)
38+
39+
The target region must have a minimum of **3 Availability Zones**. This is required to ensure high availability for EKS workloads.
40+
41+
### VPC Configuration Checks (Custom VPC Mode Only)
42+
43+
When using the **Deploy on my existing VPC** option, Qovery validates your VPC setup:
44+
45+
- **VPC exists** and has `enable_dns_hostnames = true`
46+
- **All 15 required subnets exist** (5 subnet types x 3 Availability Zones)
47+
- **Required tags** are present on subnets:
48+
49+
| Subnet Type | Required Tag | Value |
50+
|-------------|-------------|-------|
51+
| All subnets | `kubernetes.io/cluster/qovery-{cluster_id}` | `shared` |
52+
| Public subnets | `kubernetes.io/role/elb` | `1` |
53+
| Private subnets | `kubernetes.io/role/internal-elb` | `` (empty string) |
54+
| Private subnets | `karpenter.sh/discovery` | `{cluster_name}` |
55+
56+
### IAM Checks (Managed and Custom VPC Modes)
57+
58+
Qovery verifies that:
59+
60+
- AWS credentials are valid
61+
- Basic permissions are present to create and manage cluster resources
62+
63+
## Reading the Preflight Report
64+
65+
After checks complete, Qovery displays a summary report in the deployment logs:
66+
67+
```
68+
========================================================================
69+
AWS Deployment Preflight Report
70+
========================================================================
71+
[PASS] EKS cluster quota ........................ 3/100 clusters
72+
[PASS] Elastic IP quota ......................... 2/5 allocated
73+
[FAIL] VPC subnet tags
74+
-> Missing tag 'kubernetes.io/role/elb' on subnet-abc123
75+
-> Fix: Add tag 'kubernetes.io/role/elb=1' to public subnets
76+
[WARN] IAM permissions .......................... Could not fully verify
77+
------------------------------------------------------------------------
78+
Result: 1 FAILED | 1 WARNING | 2 PASSED
79+
Deployment BLOCKED - fix FAILED checks before retrying
80+
========================================================================
81+
```
82+
83+
Each check is reported with one of three statuses:
84+
85+
| Status | Meaning |
86+
|--------|---------|
87+
| **PASS** | Check succeeded, no action needed |
88+
| **WARN** | Potential issue detected but deployment is not blocked |
89+
| **FAIL** | Check failed, deployment is blocked until resolved |
90+
91+
<Warning>
92+
If any check has a **FAIL** status, deployment will not proceed. You must fix the reported issues and retry.
93+
</Warning>
94+
95+
## Common Issues and Fixes
96+
97+
<AccordionGroup>
98+
<Accordion title="Elastic IP quota exceeded">
99+
**Symptom**: `[FAIL] Elastic IP quota` in the preflight report.
100+
101+
**Fix**: Request a quota increase through the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/). Navigate to **Amazon EC2 > Elastic IPs** and request an increase. Qovery requires 3-6 Elastic IPs depending on your NAT Gateway configuration.
102+
</Accordion>
103+
104+
<Accordion title="Missing subnet tags">
105+
**Symptom**: `[FAIL] VPC subnet tags` with details about missing tags.
106+
107+
**Fix**: Add the required Kubernetes tags to your subnets. For Custom VPC setups, ensure:
108+
- All subnets have `kubernetes.io/cluster/qovery-{cluster_id} = shared`
109+
- Public subnets have `kubernetes.io/role/elb = 1`
110+
- Private subnets have `kubernetes.io/role/internal-elb = ""`
111+
- Private subnets have `karpenter.sh/discovery = {cluster_name}`
112+
113+
You can add tags in the AWS Console under **VPC > Subnets > Tags**, or via the AWS CLI:
114+
```bash
115+
aws ec2 create-tags --resources subnet-abc123 \
116+
--tags Key=kubernetes.io/role/elb,Value=1
117+
```
118+
</Accordion>
119+
120+
<Accordion title="VPC DNS hostnames disabled">
121+
**Symptom**: `[FAIL] VPC DNS hostnames` in the preflight report.
122+
123+
**Fix**: Enable DNS hostnames on your VPC. In the AWS Console, go to **VPC > Your VPC > Actions > Edit VPC settings** and enable **DNS hostnames**. Or via the AWS CLI:
124+
```bash
125+
aws ec2 modify-vpc-attribute --vpc-id vpc-abc123 \
126+
--enable-dns-hostnames '{"Value": true}'
127+
```
128+
</Accordion>
129+
130+
<Accordion title="Insufficient Availability Zones">
131+
**Symptom**: `[FAIL] Availability Zones` indicating fewer than 3 AZs.
132+
133+
**Fix**: Choose a different AWS region that has at least 3 Availability Zones. Most standard AWS regions (e.g., `us-east-1`, `eu-west-1`, `ap-southeast-1`) meet this requirement. Some smaller or newer regions may not.
134+
</Accordion>
135+
136+
<Accordion title="Quota limits showing as WARN (default limits)">
137+
**Symptom**: `[WARN] EKS cluster quota access` (or Elastic IP / VPC quota access) with message "Could not query real quota, using default limit".
138+
139+
**Cause**: Your IAM policy does not include the `servicequotas:GetServiceQuota` permission. Qovery falls back to AWS default limits which may not reflect your actual account quotas.
140+
141+
**Fix**: Add the `servicequotas:GetServiceQuota` permission to your IAM policy:
142+
```json
143+
{
144+
"Effect": "Allow",
145+
"Action": "servicequotas:GetServiceQuota",
146+
"Resource": "*"
147+
}
148+
```
149+
This is optional — preflight checks still work without it, but quota comparisons will use AWS default limits instead of your actual limits.
150+
</Accordion>
151+
152+
<Accordion title="VPC quota exceeded">
153+
**Symptom**: `[FAIL] VPC quota` in the preflight report.
154+
155+
**Fix**: Either delete unused VPCs in the target region or request a quota increase via the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/) under **Amazon VPC > VPCs per Region**.
156+
</Accordion>
157+
</AccordionGroup>
158+
159+
## Quick Reference
160+
161+
| Issue | Fix |
162+
|---|---|
163+
| Quota limits using defaults (WARN) | Add `servicequotas:GetServiceQuota` permission to your IAM policy (optional) |
164+
| Elastic IP quota exceeded | Request quota increase via AWS Service Quotas console |
165+
| Missing subnet tags | Add required Kubernetes tags to your subnets (see Custom VPC docs) |
166+
| VPC DNS hostnames disabled | Enable `enable_dns_hostnames` on your VPC |
167+
| Insufficient AZs | Choose a region with at least 3 Availability Zones |
168+

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,7 @@
212212
"pages": [
213213
"configuration/integrations/kubernetes/eks/overview",
214214
"configuration/integrations/kubernetes/eks/managed",
215+
"configuration/integrations/kubernetes/eks/preflight-checks",
215216
"configuration/integrations/kubernetes/eks/eks-anywhere"
216217
]
217218
},

0 commit comments

Comments
 (0)