AWS AMI Snapshot Module for Persistent Workspace State

registry/mavrickrishi/README.md

@@ -0,0 +1,14 @@
+---
+display_name: "mavrickrishi"
+description: "Modules and templates by mavrickrishi"
+github_url: "https://github.com/mavrick-1"
+status: "community"
+---
+
+# mavrickrishi
+
+This namespace contains modules and templates created by mavrickrishi.
+
+## Modules
+
+- **aws-ami-snapshot**: Create and manage AMI snapshots for Coder workspaces with restore capabilities

registry/mavrickrishi/modules/aws-ami-snapshot/README.md

@@ -0,0 +1,197 @@
+---
+display_name: AWS AMI Snapshot
+description: Create and manage AMI snapshots for Coder workspaces with restore capabilities
+icon: ../../../../.icons/aws.svg
+maintainer_github: coder
+verified: false
+tags: [aws, snapshot, ami, backup, persistence]
+---
+
+# AWS AMI Snapshot Module
+
+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.
+
+```tf
+module "ami_snapshot" {
+  source  = "registry.coder.com/mavrickrishi/aws-ami-snapshot/coder"
+  version = "1.0.0"
+
+  instance_id    = aws_instance.workspace.id
+  default_ami_id = data.aws_ami.ubuntu.id
+  template_name  = "aws-linux"
+}
+```
+
+## Features
+
+- **Automatic Snapshots**: Create AMI snapshots when workspaces are stopped
+- **User Control**: Enable/disable snapshot functionality per workspace
+- **Custom Labels**: Add custom labels to snapshots for easy identification
+- **Snapshot Selection**: Choose from available snapshots when starting workspaces
+- **Automatic Cleanup**: Optional Data Lifecycle Manager integration for automated cleanup
+- **Workspace Isolation**: Snapshots are tagged and filtered by workspace and owner
+
+## Parameters
+
+The module exposes the following parameters to workspace users:
+
+- `enable_snapshots`: Enable/disable AMI snapshot creation (default: true)
+- `snapshot_label`: Custom label for the snapshot (optional)
+- `use_previous_snapshot`: Select a previous snapshot to restore from (default: none)
+
+## Usage
+
+### Basic Usage
+
+```hcl
+module "ami_snapshot" {
+  source = "registry.coder.com/modules/aws-ami-snapshot"
+
+  instance_id     = aws_instance.workspace.id
+  default_ami_id  = data.aws_ami.ubuntu.id
+  template_name   = "aws-linux"
+}
+
+resource "aws_instance" "workspace" {
+  ami           = module.ami_snapshot.ami_id
+  instance_type = "t3.micro"
+
+  # Prevent Terraform from recreating instance when AMI changes
+  lifecycle {
+    ignore_changes = [ami]
+  }
+}
+```
+
+### With Optional Cleanup
+
+```hcl
+module "ami_snapshot" {
+  source = "registry.coder.com/modules/aws-ami-snapshot"
+
+  instance_id               = aws_instance.workspace.id
+  default_ami_id           = data.aws_ami.ubuntu.id
+  template_name            = "aws-linux"
+  enable_dlm_cleanup       = true
+  dlm_role_arn            = aws_iam_role.dlm_lifecycle_role.arn
+  snapshot_retention_count = 5
+
+  tags = {
+    Environment = "development"
+    Project     = "my-project"
+  }
+}
+```
+
+### IAM Role for DLM (Optional)
+
+If using automatic cleanup, create an IAM role for Data Lifecycle Manager:
+
+```hcl
+resource "aws_iam_role" "dlm_lifecycle_role" {
+  name = "dlm-lifecycle-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRole"
+        Effect = "Allow"
+        Principal = {
+          Service = "dlm.amazonaws.com"
+        }
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "dlm_lifecycle" {
+  role       = aws_iam_role.dlm_lifecycle_role.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSDataLifecycleManagerServiceRole"
+}
+```
+
+## Required IAM Permissions
+
+Users need the following IAM permissions for full functionality:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:CreateImage",
+        "ec2:DescribeImages",
+        "ec2:DescribeInstances",
+        "ec2:CreateTags",
+        "ec2:DescribeTags"
+      ],
+      "Resource": "*"
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dlm:CreateLifecyclePolicy",
+        "dlm:GetLifecyclePolicy",
+        "dlm:UpdateLifecyclePolicy",
+        "dlm:DeleteLifecyclePolicy"
+      ],
+      "Resource": "*",
+      "Condition": {
+        "StringEquals": {
+          "dlm:Target": "INSTANCE"
+        }
+      }
+    }
+  ]
+}
+```
+
+## How It Works
+
+1. **Snapshot Creation**: When a workspace transitions to "stop", an AMI snapshot is automatically created (if enabled)
+2. **Tagging**: Snapshots are tagged with workspace name, owner, template, and custom labels
+3. **Snapshot Retrieval**: Available snapshots are retrieved and presented as options for workspace start
+4. **AMI Selection**: The module outputs the appropriate AMI ID (default or selected snapshot)
+5. **Cleanup**: Optional DLM policies can automatically clean up old snapshots
+
+## Variables
+
+| Name                     | Description                                                  | Type        | Default | Required |
+| ------------------------ | ------------------------------------------------------------ | ----------- | ------- | -------- |
+| instance_id              | The EC2 instance ID to create snapshots from                 | string      | n/a     | yes      |
+| default_ami_id           | The default AMI ID to use when not restoring from a snapshot | string      | n/a     | yes      |
+| template_name            | The name of the Coder template using this module             | string      | n/a     | yes      |
+| test_mode                | Set to true when running tests to skip AWS API calls         | bool        | false   | no       |
+| tags                     | Additional tags to apply to snapshots                        | map(string) | {}      | no       |
+| enable_dlm_cleanup       | Enable Data Lifecycle Manager for automated snapshot cleanup | bool        | false   | no       |
+| dlm_role_arn             | ARN of the IAM role for DLM                                  | string      | ""      | no       |
+| snapshot_retention_count | Number of snapshots to retain when using DLM cleanup         | number      | 7       | no       |
+
+## Outputs
+
+| Name                | Description                                           |
+| ------------------- | ----------------------------------------------------- |
+| ami_id              | The AMI ID to use for the workspace instance          |
+| is_using_snapshot   | Whether the workspace is using a snapshot AMI         |
+| snapshot_ami_id     | The AMI ID of the created snapshot (if any)           |
+| available_snapshots | List of available snapshot AMI IDs for this workspace |
+| snapshot_info       | Detailed information about available snapshots        |
+
+## Considerations
+
+- **Cost**: AMI snapshots incur storage costs. Use cleanup policies to manage costs
+- **Time**: AMI creation takes time; workspace stop operations may take longer
+- **Permissions**: Ensure proper IAM permissions for AMI creation and management
+- **Region**: Snapshots are region-specific and cannot be used across regions
+- **Lifecycle**: Use `ignore_changes = [ami]` on EC2 instances to prevent conflicts
+
+## Examples
+
+See the updated AWS templates that use this module:
+
+- `coder/templates/aws-linux`
+- `coder/templates/aws-windows`
+- `coder/templates/aws-devcontainer`

registry/mavrickrishi/modules/aws-ami-snapshot/main.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "bun:test";
+import {
+  runTerraformApply,
+  runTerraformInit,
+  testRequiredVariables,
+} from "~test";
+
+describe("aws-ami-snapshot", async () => {
+  await runTerraformInit(import.meta.dir);
+
+  it("required variables with test mode", async () => {
+    await runTerraformApply(import.meta.dir, {
+      instance_id: "i-1234567890abcdef0",
+      default_ami_id: "ami-12345678",
+      template_name: "test-template",
+      test_mode: true,
+    });
+  });
+
+  it("missing variable: instance_id", async () => {
+    await expect(runTerraformApply(import.meta.dir, {
+      default_ami_id: "ami-12345678",
+      template_name: "test-template",
+      test_mode: true,
+    })).rejects.toThrow();
+  });
+
+  it("missing variable: default_ami_id", async () => {
+    await expect(runTerraformApply(import.meta.dir, {
+      instance_id: "i-1234567890abcdef0",
+      template_name: "test-template",
+      test_mode: true,
+    })).rejects.toThrow();
+  });
+
+  it("missing variable: template_name", async () => {
+    await expect(runTerraformApply(import.meta.dir, {
+      instance_id: "i-1234567890abcdef0",
+      default_ami_id: "ami-12345678",
+      test_mode: true,
+    })).rejects.toThrow();
+  });
+
+  it("supports optional variables", async () => {
+    await runTerraformApply(import.meta.dir, {
+      instance_id: "i-1234567890abcdef0",
+      default_ami_id: "ami-12345678",
+      template_name: "test-template",
+      test_mode: true,
+      enable_dlm_cleanup: true,
+      dlm_role_arn: "arn:aws:iam::123456789012:role/dlm-lifecycle-role",
+      snapshot_retention_count: 5,
+      tags: JSON.stringify({
+        Environment: "test",
+        Project: "coder",
+      }),
+    });
+  });
+});