Skip to content

Commit b18ad04

Browse files
MAVRICK-1MAVRICK-1
committed
added the required files
1 parent 0a3c9b0 commit b18ad04

File tree

8 files changed

+577
-7
lines changed

8 files changed

+577
-7
lines changed

‎demo-script.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# AWS AMI Snapshot Demo Script
2+
3+
## Video Demonstration Outline
4+
5+
### 1. Introduction (30 seconds)
6+
- Show the problem: "Coder workspaces lose state when stopped"
7+
- Introduce solution: "AMI snapshots for persistent workspace state"
8+
9+
### 2. Code Structure Overview (1 minute)
10+
- Navigate to `registry/coder/modules/aws-ami-snapshot/`
11+
- Show the single `main.tf` file structure
12+
- Highlight key components:
13+
- User parameters (enable_snapshots, snapshot_label, use_previous_snapshot)
14+
- AMI snapshot creation logic
15+
- Dynamic AMI selection
16+
17+
### 3. Template Integration (1 minute)
18+
- Show updated AWS templates:
19+
- `registry/coder/templates/aws-linux/main.tf`
20+
- `registry/coder/templates/aws-windows/main.tf`
21+
- `registry/coder/templates/aws-devcontainer/main.tf`
22+
- Point out the module integration and AMI ID usage
23+
24+
### 4. Live Validation (2 minutes)
25+
- Run `terraform validate` to show it works
26+
- Run `terraform plan` to show AWS integration
27+
- Show the user parameters that would appear in Coder UI
28+
29+
### 5. Feature Walkthrough (2 minutes)
30+
- Demonstrate user workflow:
31+
1. User creates workspace (uses default AMI)
32+
2. User works and customizes environment
33+
3. User stops workspace (snapshot created automatically)
34+
4. User starts workspace again (can choose to restore from snapshot)
35+
5. User sees their previous state restored
36+
37+
### 6. Advanced Features (1 minute)
38+
- Show optional cleanup configuration
39+
- Explain IAM permissions needed
40+
- Show tagging and organization features
41+
42+
## Demo Commands to Run
43+
44+
```bash
45+
# Navigate to the module
46+
cd registry/coder/modules/aws-ami-snapshot/
47+
48+
# Show the structure
49+
ls -la
50+
51+
# Show the main configuration
52+
head -50 main.tf
53+
54+
# Show template integration
55+
grep -A 10 -B 2 "ami_snapshot" ../../../templates/aws-*/main.tf
56+
57+
# Validate the configuration
58+
terraform init
59+
terraform validate
60+
61+
# Show it works with AWS
62+
terraform plan
63+
```
64+
65+
## Key Points to Emphasize
66+
67+
1. **Seamless Integration**: Module works with existing templates
68+
2. **User Control**: Users can enable/disable and label snapshots
69+
3. **Smart Selection**: Automatically chooses between default AMI and snapshots
70+
4. **Cost Management**: Optional cleanup policies prevent runaway costs
71+
5. **Production Ready**: Proper error handling and AWS best practices

‎registry/coder/modules/aws-ami-snapshot/README.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
display_name: AWS AMI Snapshot
3+
description: Create and manage AMI snapshots for Coder workspaces with restore capabilities
4+
icon: ../../../../.icons/aws.svg
5+
maintainer_github: coder
6+
verified: true
7+
tags: [aws, snapshot, ami, backup, persistence]
8+
---
9+
10+
# AWS AMI Snapshot Module
11+
12+
This module provides AMI-based snapshot functionality for Coder workspaces running on AWS EC2 instances. It enables users to create snapshots when workspaces are stopped and restore from previous snapshots when starting workspaces.
13+
14+
## Features
15+
16+
- **Automatic Snapshots**: Create AMI snapshots when workspaces are stopped
17+
- **User Control**: Enable/disable snapshot functionality per workspace
18+
- **Custom Labels**: Add custom labels to snapshots for easy identification
19+
- **Snapshot Selection**: Choose from available snapshots when starting workspaces
20+
- **Automatic Cleanup**: Optional Data Lifecycle Manager integration for automated cleanup
21+
- **Workspace Isolation**: Snapshots are tagged and filtered by workspace and owner
22+
23+
## Parameters
24+
25+
The module exposes the following parameters to workspace users:
26+
27+
- `enable_snapshots`: Enable/disable AMI snapshot creation (default: true)
28+
- `snapshot_label`: Custom label for the snapshot (optional)
29+
- `use_previous_snapshot`: Select a previous snapshot to restore from (default: none)
30+
31+
## Usage
32+
33+
### Basic Usage
34+
35+
```hcl
36+
module "ami_snapshot" {
37+
source = "registry.coder.com/modules/aws-ami-snapshot"
38+
39+
instance_id = aws_instance.workspace.id
40+
default_ami_id = data.aws_ami.ubuntu.id
41+
template_name = "aws-linux"
42+
}
43+
44+
resource "aws_instance" "workspace" {
45+
ami = module.ami_snapshot.ami_id
46+
instance_type = "t3.micro"
47+
48+
# Prevent Terraform from recreating instance when AMI changes
49+
lifecycle {
50+
ignore_changes = [ami]
51+
}
52+
}
53+
```
54+
55+
### With Optional Cleanup
56+
57+
```hcl
58+
module "ami_snapshot" {
59+
source = "registry.coder.com/modules/aws-ami-snapshot"
60+
61+
instance_id = aws_instance.workspace.id
62+
default_ami_id = data.aws_ami.ubuntu.id
63+
template_name = "aws-linux"
64+
enable_dlm_cleanup = true
65+
dlm_role_arn = aws_iam_role.dlm_lifecycle_role.arn
66+
snapshot_retention_count = 5
67+
68+
tags = {
69+
Environment = "development"
70+
Project = "my-project"
71+
}
72+
}
73+
```
74+
75+
### IAM Role for DLM (Optional)
76+
77+
If using automatic cleanup, create an IAM role for Data Lifecycle Manager:
78+
79+
```hcl
80+
resource "aws_iam_role" "dlm_lifecycle_role" {
81+
name = "dlm-lifecycle-role"
82+
83+
assume_role_policy = jsonencode({
84+
Version = "2012-10-17"
85+
Statement = [
86+
{
87+
Action = "sts:AssumeRole"
88+
Effect = "Allow"
89+
Principal = {
90+
Service = "dlm.amazonaws.com"
91+
}
92+
}
93+
]
94+
})
95+
}
96+
97+
resource "aws_iam_role_policy_attachment" "dlm_lifecycle" {
98+
role = aws_iam_role.dlm_lifecycle_role.name
99+
policy_arn = "arn:aws:iam::aws:policy/service-role/AWSDataLifecycleManagerServiceRole"
100+
}
101+
```
102+
103+
## Required IAM Permissions
104+
105+
Users need the following IAM permissions for full functionality:
106+
107+
```json
108+
{
109+
"Version": "2012-10-17",
110+
"Statement": [
111+
{
112+
"Effect": "Allow",
113+
"Action": [
114+
"ec2:CreateImage",
115+
"ec2:DescribeImages",
116+
"ec2:DescribeInstances",
117+
"ec2:CreateTags",
118+
"ec2:DescribeTags"
119+
],
120+
"Resource": "*"
121+
},
122+
{
123+
"Effect": "Allow",
124+
"Action": [
125+
"dlm:CreateLifecyclePolicy",
126+
"dlm:GetLifecyclePolicy",
127+
"dlm:UpdateLifecyclePolicy",
128+
"dlm:DeleteLifecyclePolicy"
129+
],
130+
"Resource": "*",
131+
"Condition": {
132+
"StringEquals": {
133+
"dlm:Target": "INSTANCE"
134+
}
135+
}
136+
}
137+
]
138+
}
139+
```
140+
141+
## How It Works
142+
143+
1. **Snapshot Creation**: When a workspace transitions to "stop", an AMI snapshot is automatically created (if enabled)
144+
2. **Tagging**: Snapshots are tagged with workspace name, owner, template, and custom labels
145+
3. **Snapshot Retrieval**: Available snapshots are retrieved and presented as options for workspace start
146+
4. **AMI Selection**: The module outputs the appropriate AMI ID (default or selected snapshot)
147+
5. **Cleanup**: Optional DLM policies can automatically clean up old snapshots
148+
149+
## Variables
150+
151+
| Name | Description | Type | Default | Required |
152+
|------|-------------|------|---------|----------|
153+
| instance_id | The EC2 instance ID to create snapshots from | string | n/a | yes |
154+
| default_ami_id | The default AMI ID to use when not restoring from a snapshot | string | n/a | yes |
155+
| template_name | The name of the Coder template using this module | string | n/a | yes |
156+
| tags | Additional tags to apply to snapshots | map(string) | {} | no |
157+
| enable_dlm_cleanup | Enable Data Lifecycle Manager for automated snapshot cleanup | bool | false | no |
158+
| dlm_role_arn | ARN of the IAM role for DLM | string | "" | no |
159+
| snapshot_retention_count | Number of snapshots to retain when using DLM cleanup | number | 7 | no |
160+
161+
## Outputs
162+
163+
| Name | Description |
164+
|------|-------------|
165+
| ami_id | The AMI ID to use for the workspace instance |
166+
| is_using_snapshot | Whether the workspace is using a snapshot AMI |
167+
| snapshot_ami_id | The AMI ID of the created snapshot (if any) |
168+
| available_snapshots | List of available snapshot AMI IDs for this workspace |
169+
| snapshot_info | Detailed information about available snapshots |
170+
171+
## Considerations
172+
173+
- **Cost**: AMI snapshots incur storage costs. Use cleanup policies to manage costs
174+
- **Time**: AMI creation takes time; workspace stop operations may take longer
175+
- **Permissions**: Ensure proper IAM permissions for AMI creation and management
176+
- **Region**: Snapshots are region-specific and cannot be used across regions
177+
- **Lifecycle**: Use `ignore_changes = [ami]` on EC2 instances to prevent conflicts
178+
179+
## Examples
180+
181+
See the updated AWS templates that use this module:
182+
- `coder/templates/aws-linux`
183+
- `coder/templates/aws-windows`
184+
- `coder/templates/aws-devcontainer`

‎registry/coder/modules/aws-ami-snapshot/main.test.ts

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { describe, expect, it } from "bun:test";
2+
import {
3+
runTerraformApply,
4+
runTerraformInit,
5+
testRequiredVariables,
6+
} from "~test";
7+
8+
describe("aws-ami-snapshot", async () => {
9+
await runTerraformInit(import.meta.dir);
10+
11+
testRequiredVariables(import.meta.dir, {
12+
instance_id: "i-1234567890abcdef0",
13+
default_ami_id: "ami-12345678",
14+
template_name: "test-template",
15+
});
16+
17+
it("supports optional variables", async () => {
18+
await testRequiredVariables(import.meta.dir, {
19+
instance_id: "i-1234567890abcdef0",
20+
default_ami_id: "ami-12345678",
21+
template_name: "test-template",
22+
enable_dlm_cleanup: true,
23+
dlm_role_arn: "arn:aws:iam::123456789012:role/dlm-lifecycle-role",
24+
snapshot_retention_count: 5,
25+
tags: {
26+
Environment: "test",
27+
Project: "coder",
28+
},
29+
});
30+
});
31+
});

0 commit comments

Comments
 (0)