Skip to content

Commit d94a8ed

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

2 files changed

Lines changed: 149 additions & 0 deletions

File tree

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

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
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+
### Availability Zone Checks (All Modes)
26+
27+
The target region must have a minimum of **3 Availability Zones**. This is required to ensure high availability for EKS workloads.
28+
29+
### VPC Configuration Checks (Custom VPC Mode Only)
30+
31+
When using the **Deploy on my existing VPC** option, Qovery validates your VPC setup:
32+
33+
- **VPC exists** and has `enable_dns_hostnames = true`
34+
- **All 15 required subnets exist** (5 subnet types x 3 Availability Zones)
35+
- **Required tags** are present on subnets:
36+
37+
| Subnet Type | Required Tag | Value |
38+
|-------------|-------------|-------|
39+
| All subnets | `kubernetes.io/cluster/qovery-{cluster_id}` | `shared` |
40+
| Public subnets | `kubernetes.io/role/elb` | `1` |
41+
| Private subnets | `kubernetes.io/role/internal-elb` | `` (empty string) |
42+
| Private subnets | `karpenter.sh/discovery` | `{cluster_name}` |
43+
44+
### IAM Checks (Managed and Custom VPC Modes)
45+
46+
Qovery verifies that:
47+
48+
- AWS credentials are valid
49+
- Basic permissions are present to create and manage cluster resources
50+
51+
## Reading the Preflight Report
52+
53+
After checks complete, Qovery displays a summary report in the deployment logs:
54+
55+
```
56+
========================================================================
57+
AWS Deployment Preflight Report
58+
========================================================================
59+
[PASS] EKS cluster quota ........................ 3/100 clusters
60+
[PASS] Elastic IP quota ......................... 2/5 allocated
61+
[FAIL] VPC subnet tags
62+
-> Missing tag 'kubernetes.io/role/elb' on subnet-abc123
63+
-> Fix: Add tag 'kubernetes.io/role/elb=1' to public subnets
64+
[WARN] IAM permissions .......................... Could not fully verify
65+
------------------------------------------------------------------------
66+
Result: 1 FAILED | 1 WARNING | 2 PASSED
67+
Deployment BLOCKED - fix FAILED checks before retrying
68+
========================================================================
69+
```
70+
71+
Each check is reported with one of three statuses:
72+
73+
| Status | Meaning |
74+
|--------|---------|
75+
| **PASS** | Check succeeded, no action needed |
76+
| **WARN** | Potential issue detected but deployment is not blocked |
77+
| **FAIL** | Check failed, deployment is blocked until resolved |
78+
79+
<Warning>
80+
If any check has a **FAIL** status, deployment will not proceed. You must fix the reported issues and retry.
81+
</Warning>
82+
83+
## Common Issues and Fixes
84+
85+
<AccordionGroup>
86+
<Accordion title="Elastic IP quota exceeded">
87+
**Symptom**: `[FAIL] Elastic IP quota` in the preflight report.
88+
89+
**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.
90+
</Accordion>
91+
92+
<Accordion title="Missing subnet tags">
93+
**Symptom**: `[FAIL] VPC subnet tags` with details about missing tags.
94+
95+
**Fix**: Add the required Kubernetes tags to your subnets. For Custom VPC setups, ensure:
96+
- All subnets have `kubernetes.io/cluster/qovery-{cluster_id} = shared`
97+
- Public subnets have `kubernetes.io/role/elb = 1`
98+
- Private subnets have `kubernetes.io/role/internal-elb = ""`
99+
- Private subnets have `karpenter.sh/discovery = {cluster_name}`
100+
101+
You can add tags in the AWS Console under **VPC > Subnets > Tags**, or via the AWS CLI:
102+
```bash
103+
aws ec2 create-tags --resources subnet-abc123 \
104+
--tags Key=kubernetes.io/role/elb,Value=1
105+
```
106+
</Accordion>
107+
108+
<Accordion title="VPC DNS hostnames disabled">
109+
**Symptom**: `[FAIL] VPC DNS hostnames` in the preflight report.
110+
111+
**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:
112+
```bash
113+
aws ec2 modify-vpc-attribute --vpc-id vpc-abc123 \
114+
--enable-dns-hostnames '{"Value": true}'
115+
```
116+
</Accordion>
117+
118+
<Accordion title="Insufficient Availability Zones">
119+
**Symptom**: `[FAIL] Availability Zones` indicating fewer than 3 AZs.
120+
121+
**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.
122+
</Accordion>
123+
124+
<Accordion title="VPC quota exceeded">
125+
**Symptom**: `[FAIL] VPC quota` in the preflight report.
126+
127+
**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**.
128+
</Accordion>
129+
</AccordionGroup>
130+
131+
## Quick Reference
132+
133+
| Issue | Fix |
134+
|---|---|
135+
| Elastic IP quota exceeded | Request quota increase via AWS Service Quotas console |
136+
| Missing subnet tags | Add required Kubernetes tags to your subnets (see Custom VPC docs) |
137+
| VPC DNS hostnames disabled | Enable `enable_dns_hostnames` on your VPC |
138+
| Insufficient AZs | Choose a region with at least 3 Availability Zones |
139+
140+
## API Endpoint
141+
142+
You can run preflight checks programmatically via the Qovery API before creating a cluster:
143+
144+
```
145+
POST /organization/{organizationId}/cluster/preflightChecks
146+
```
147+
148+
See the [API Reference](/api-reference/overview) for authentication details and request/response formats.

‎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)