Skip to content

Commit c5fb2cf

Browse files
nyerglernyergler
authored
Update EKS module, examples (#119)
* Pin provider versions in EKS modules * Bump dependency chart versions * Use curly-brace substitution * Set K8s image pull secret * Remove vestigial record_log_bucket * Saner default for bucket name handling in EKS * Make certificate ARN optional for eks-helm module * Tidy up complete example documentation Additionally, use the module from the repository in the example, rather than the latest from Github. * Add K8s addons, access entries configuration * Update default versions for example Redis, Postgres * Update eks-addons to reflect module version changes * Additional improvements from testing: - Do not rely on expansion for database, redis URLs - Attach IAM role for pulling the image - Increase default instance type to t3.medium
1 parent 973b803 commit c5fb2cf

File tree

25 files changed

+568
-259
lines changed

25 files changed

+568
-259
lines changed

‎.claude/settings.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
{
22
"permissions": {
33
"allow": [
4-
"Bash(helm dependency list:*)"
4+
"Bash(helm dependency list:*)",
5+
"Bash(terraform-docs markdown table:*)"
56
]
67
}
78
}

‎helm/charts/polytomic/Chart.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ type: application
1515
# This is the chart version. This version number should be incremented each time you make changes
1616
# to the chart and its templates, including the app version.
1717
# Versions are expected to follow Semantic Versioning (https://semver.org/)
18-
version: 1.0.0
18+
version: 1.0.2
1919

2020
# This is the version number of the application being deployed. This version number should be
2121
# incremented each time you make changes to the application. Versions are not expected to

‎helm/charts/polytomic/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Polytomic helm chart for kubernetes
44

5-
![Version: 1.0.0](https://img.shields.io/badge/Version-1.0.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square)
5+
![Version: 1.0.2](https://img.shields.io/badge/Version-1.0.2-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: latest](https://img.shields.io/badge/AppVersion-latest-informational?style=flat-square)
66

77
## Installing the Chart
88

‎helm/charts/polytomic/templates/_helpers.tpl‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,8 +223,9 @@ Build PostgreSQL connection URL
223223
{{- else if .Values.externalPostgresql.ssl -}}
224224
{{- $sslMode = "require" -}}
225225
{{- end -}}
226-
{{- printf "postgres://%s:${DATABASE_PASSWORD}@%s:%s/%s?sslmode=%s"
226+
{{- printf "postgres://%s:%s@%s:%s/%s?sslmode=%s"
227227
(include "polytomic.postgresql.username" .)
228+
.Values.externalPostgresql.password
228229
(include "polytomic.postgresql.host" .)
229230
(include "polytomic.postgresql.port" .)
230231
(include "polytomic.postgresql.database" .)
@@ -301,11 +302,13 @@ Build Redis connection URL
301302
{{- $password = .Values.externalRedis.password -}}
302303
{{- if $password -}}
303304
{{- if .Values.externalRedis.ssl -}}
304-
{{- printf "rediss://:${REDIS_PASSWORD}@%s:%s"
305+
{{- printf "rediss://:%s@%s:%s"
306+
$password
305307
(include "polytomic.redis.host" .)
306308
(include "polytomic.redis.port" .) -}}
307309
{{- else -}}
308-
{{- printf "redis://:${REDIS_PASSWORD}@%s:%s"
310+
{{- printf "redis://:%s@%s:%s"
311+
$password
309312
(include "polytomic.redis.host" .)
310313
(include "polytomic.redis.port" .) -}}
311314
{{- end -}}
@@ -350,6 +353,10 @@ SINGLE_PLAYER: {{ .Values.polytomic.auth.single_player | quote }}
350353
AWS_REGION: {{ .Values.polytomic.s3.region | quote }}
351354
AWS_ACCESS_KEY_ID: {{ .Values.polytomic.s3.access_key_id | quote }}
352355
AWS_SECRET_ACCESS_KEY: {{ .Values.polytomic.s3.secret_access_key | quote }}
356+
RECORD_LOG_BUCKET: {{ .Values.polytomic.s3.operational_bucket | trimPrefix "s3://" | quote }}
357+
RECORD_LOG_REGION: {{ .Values.polytomic.s3.region | quote }}
358+
EXECUTION_LOG_BUCKET: {{ .Values.polytomic.s3.operational_bucket | trimPrefix "s3://" | quote }}
359+
EXECUTION_LOG_REGION: {{ .Values.polytomic.s3.region | quote }}
353360
KUBERNETES: "true"
354361
KUBERNETES_NAMESPACE: {{ .Release.Namespace | quote }}
355362
KUBERNETES_IMAGE: {{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}

‎terraform/examples/eks-complete/README.md‎

Lines changed: 210 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,230 @@
1-
# Polytomic EKS Module
1+
# Polytomic EKS Complete Example
22

3+
This example demonstrates a complete production-ready Polytomic deployment on
4+
AWS EKS using all three EKS Terraform modules.
35

4-
This module has two stages:
5-
- cluster install
6-
- app install
6+
## What This Example Includes
77

8+
A two-stage deployment that creates:
89

9-
The cluster module must be applied before running the app module.
10+
**Stage 1: Infrastructure (cluster/)**
1011

12+
- EKS cluster with managed node groups
13+
- VPC with public/private subnets across 3 AZs
14+
- RDS PostgreSQL Multi-AZ database
15+
- ElastiCache Redis cluster
16+
- EFS filesystem for shared storage
17+
- S3 bucket for operations and logs
1118

12-
## Cluster Install
19+
**Stage 2: Application (app/)**
20+
21+
- AWS Load Balancer Controller
22+
- EFS CSI Driver
23+
- IAM roles (IRSA) for service accounts
24+
- Polytomic Helm chart deployment
25+
26+
## Documentation
27+
28+
**For complete deployment instructions, see [EKS Deployment Guide](../../modules/eks/INSTALL.md)**
29+
30+
The comprehensive guide includes:
31+
32+
- Architecture diagrams
33+
- Detailed prerequisites
34+
- Step-by-step deployment instructions
35+
- Configuration reference
36+
- Troubleshooting scenarios
37+
38+
## Example-Specific Notes
39+
40+
This example differs from the comprehensive guide in that it:
41+
42+
**Does NOT manage DNS or TLS certificates**
43+
44+
- You must manually create CNAME records pointing to the ALB
45+
- TLS can be handled externally (CloudFlare, CloudFront) or by providing an ACM certificate ARN
46+
- See step 3d in the Quick Start below for TLS options
47+
48+
**Uses simplified configuration**
49+
50+
- Minimal viable settings for testing
51+
- Defaults to HTTP (port 80) without certificate
52+
- Suitable for proof-of-concept deployments
53+
54+
## Quick Start
55+
56+
### Prerequisites
57+
58+
Before starting, ensure you have:
59+
60+
- AWS CLI configured with appropriate credentials
61+
- Terraform v1.0+
62+
- kubectl and helm installed
63+
- Polytomic license credentials (deployment name and key)
64+
- Google OAuth credentials (or other auth method configured)
65+
66+
### Step 1: Deploy Infrastructure
67+
68+
```bash
69+
cd cluster
70+
71+
# Edit main.tf and configure the locals block
72+
# See INSTALL.md for detailed configuration options
1373

14-
```sh
15-
cd cluster
1674
terraform init
75+
terraform apply
1776
```
1877

78+
**Deployment time**: ~15-20 minutes
79+
80+
**Note**: The EKS module automatically configures node IAM roles with ECR read permissions, so pods can pull from private ECR repositories without needing imagePullSecrets.
81+
82+
### Step 2: Deploy Application
1983

20-
Fill in the `locals` block at the top with the desired values.
84+
```bash
85+
cd ../app
2186

22-
```sh
87+
# Edit main.tf and configure:
88+
# - Polytomic deployment credentials
89+
# - Domain name and authentication settings
90+
# - Optional: certificate_arn if using ACM
91+
92+
terraform init
2393
terraform apply
2494
```
2595

26-
## App Install
96+
**Deployment time**: ~5-10 minutes
2797

28-
```sh
29-
cd app
30-
terraform init
98+
### Step 3: Configure DNS
99+
100+
```bash
101+
# Get ALB hostname
102+
kubectl get ingress -n polytomic polytomic -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
103+
104+
# Create CNAME record pointing your domain to the ALB hostname
105+
# Example using Route53:
106+
HOSTED_ZONE_ID="Z1234567890ABC"
107+
DOMAIN_NAME="app.polytomic-local.com"
108+
ALB_HOSTNAME=$(kubectl get ingress -n polytomic polytomic -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
109+
110+
aws route53 change-resource-record-sets \
111+
--hosted-zone-id $HOSTED_ZONE_ID \
112+
--change-batch "{
113+
\"Changes\": [{
114+
\"Action\": \"UPSERT\",
115+
\"ResourceRecordSet\": {
116+
\"Name\": \"$DOMAIN_NAME\",
117+
\"Type\": \"CNAME\",
118+
\"TTL\": 300,
119+
\"ResourceRecords\": [{\"Value\": \"$ALB_HOSTNAME\"}]
120+
}
121+
}]
122+
}"
123+
```
124+
125+
### Step 4: Access Application
126+
127+
```bash
128+
# Verify pods are running
129+
kubectl get pods -n polytomic
130+
131+
# Access the application at your configured domain
132+
# HTTP by default; HTTPS if certificate_arn was provided
133+
```
134+
135+
## TLS Configuration Options
136+
137+
This example does not manage TLS certificates by default. Choose one of these options:
138+
139+
### Option 1: External TLS Termination (Recommended)
140+
141+
Use CloudFlare, CloudFront, or another CDN to handle TLS:
142+
143+
- The ALB serves HTTP on port 80
144+
- Your CDN terminates TLS and forwards to ALB
145+
- No ACM certificate needed
146+
147+
### Option 2: ACM Certificate
148+
149+
If you have an ACM certificate in the same AWS account/region:
150+
151+
```hcl
152+
# In app/main.tf, add to eks_helm module:
153+
module "eks_helm" {
154+
# ... existing config ...
155+
certificate_arn = "arn:aws:acm:us-east-2:123456789:certificate/your-cert-id"
156+
}
157+
```
158+
159+
### Option 3: Manual Certificate Creation
160+
161+
Uncomment the certificate resources at the bottom of [app/main.tf](app/main.tf), then:
162+
163+
```bash
164+
cd app
31165
terraform apply
166+
terraform output certificate_arn
167+
168+
# Get validation records
169+
aws acm describe-certificate --certificate-arn <arn> | \
170+
jq -r '.Certificate.DomainValidationOptions[0].ResourceRecord'
171+
```
172+
173+
Add the CNAME validation record to your DNS provider, then the certificate will be issued.
174+
175+
## Configuration Files
176+
177+
**cluster/main.tf** - Infrastructure configuration
178+
179+
- EKS cluster settings (node size, count)
180+
- Database configuration (RDS instance class, storage)
181+
- Redis configuration (instance type, cluster size)
182+
- VPC and networking
183+
184+
**app/main.tf** - Application configuration
185+
186+
- Polytomic deployment credentials
187+
- Domain and authentication settings
188+
- Helm chart values
189+
- Optional ACM certificate
190+
191+
See [INSTALL.md](../../modules/eks/INSTALL.md) for detailed configuration options.
192+
193+
## Cleanup
194+
195+
Destroy resources in reverse order:
196+
197+
```bash
198+
cd app && terraform destroy
199+
cd ../cluster && terraform destroy
32200
```
33201

34-
Obtain the ingress loadbalancer name to create a CNAME record in your DNS.
202+
**Warning**: This permanently deletes all data. Ensure you have backups.
203+
204+
## Troubleshooting
205+
206+
For common issues, see the [Troubleshooting section in INSTALL.md](../../modules/eks/INSTALL.md#troubleshooting).
207+
208+
Quick diagnostics:
209+
210+
```bash
211+
# Check pod status
212+
kubectl get pods -n polytomic
213+
214+
# View pod logs
215+
kubectl logs -n polytomic -l app.kubernetes.io/component=web --tail=50
216+
217+
# Check ALB controller
218+
kubectl logs -n kube-system -l app.kubernetes.io/name=aws-load-balancer-controller
219+
220+
# If seeing ImagePullBackOff errors, verify the node IAM role has ECR permissions
221+
kubectl describe pod -n polytomic <pod-name> | grep -A 5 "Events:"
35222
```
36-
aws eks update-kubeconfig --name ${YOUR LOCAL.PREFIX VALUE}-cluster --region ${YOUR LOCAL.REGION VALUE}
37-
kubectl get ingress -n polytomic
38-
```
223+
224+
## Additional Resources
225+
226+
- [EKS Deployment Guide (INSTALL.md)](../../modules/eks/INSTALL.md) - Complete deployment documentation
227+
- [eks Module README](../../modules/eks/README.md) - Module reference
228+
- [eks-addons Module README](../../modules/eks-addons/README.md)
229+
- [eks-helm Module README](../../modules/eks-helm/README.md)
230+
- [Helm Chart Documentation](../../../helm/charts/polytomic/README.md)

0 commit comments

Comments
 (0)