@mavogel/cdk-vscode-server 0.1.1 โ†’ 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/.jsii +125 -51
  2. package/AGENTS.md +12 -0
  3. package/API.md +64 -0
  4. package/README.md +16 -0
  5. package/integ-tests/expire-assertion-logs.ts +26 -0
  6. package/integ-tests/integ.al2023.ts +11 -2
  7. package/integ-tests/integ.al2023.ts.snapshot/IntegSetupVSCodeOnAl2023DefaultTestDeployAssert74D8F645.assets.json +3 -3
  8. package/integ-tests/integ.al2023.ts.snapshot/IntegSetupVSCodeOnAl2023DefaultTestDeployAssert74D8F645.metadata.json +15 -0
  9. package/integ-tests/integ.al2023.ts.snapshot/IntegSetupVSCodeOnAl2023DefaultTestDeployAssert74D8F645.template.json +13 -2
  10. package/integ-tests/integ.al2023.ts.snapshot/IntegTestStackAl2023.assets.json +13 -13
  11. package/integ-tests/integ.al2023.ts.snapshot/IntegTestStackAl2023.metadata.json +260 -174
  12. package/integ-tests/integ.al2023.ts.snapshot/IntegTestStackAl2023.template.json +318 -189
  13. package/integ-tests/integ.al2023.ts.snapshot/integ.json +1 -1
  14. package/integ-tests/integ.al2023.ts.snapshot/manifest.json +2 -2
  15. package/integ-tests/integ.al2023.ts.snapshot/tree.json +1 -1
  16. package/integ-tests/integ.custom-domain.ts +10 -1
  17. package/integ-tests/integ.custom-domain.ts.snapshot/IntegSetupVSCodeOnCustomDomainDefaultTestDeployAssert6982D514.assets.json +3 -3
  18. package/integ-tests/integ.custom-domain.ts.snapshot/IntegSetupVSCodeOnCustomDomainDefaultTestDeployAssert6982D514.metadata.json +15 -0
  19. package/integ-tests/integ.custom-domain.ts.snapshot/IntegSetupVSCodeOnCustomDomainDefaultTestDeployAssert6982D514.template.json +13 -2
  20. package/integ-tests/integ.custom-domain.ts.snapshot/IntegTestStackCustomDomain.assets.json +13 -13
  21. package/integ-tests/integ.custom-domain.ts.snapshot/IntegTestStackCustomDomain.metadata.json +281 -194
  22. package/integ-tests/integ.custom-domain.ts.snapshot/IntegTestStackCustomDomain.template.json +358 -221
  23. package/integ-tests/integ.custom-domain.ts.snapshot/integ.json +1 -1
  24. package/integ-tests/integ.custom-domain.ts.snapshot/manifest.json +2 -2
  25. package/integ-tests/integ.custom-domain.ts.snapshot/tree.json +1 -1
  26. package/integ-tests/integ.stop-on-idle.ts +14 -2
  27. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegStopOnIdleFunctionalityDefaultTestDeployAssertEECF3FC0.assets.json +3 -3
  28. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegStopOnIdleFunctionalityDefaultTestDeployAssertEECF3FC0.metadata.json +15 -0
  29. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegStopOnIdleFunctionalityDefaultTestDeployAssertEECF3FC0.template.json +16 -5
  30. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegTestStackStopOnIdle.assets.json +17 -17
  31. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegTestStackStopOnIdle.metadata.json +310 -203
  32. package/integ-tests/integ.stop-on-idle.ts.snapshot/IntegTestStackStopOnIdle.template.json +386 -254
  33. package/integ-tests/integ.stop-on-idle.ts.snapshot/manifest.json +2 -2
  34. package/integ-tests/integ.stop-on-idle.ts.snapshot/tree.json +1 -1
  35. package/integ-tests/integ.ubuntu24.ts +11 -2
  36. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegSetupVSCodeOnUbuntuDefaultTestDeployAssertFF8DF2C5.assets.json +3 -3
  37. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegSetupVSCodeOnUbuntuDefaultTestDeployAssertFF8DF2C5.metadata.json +15 -0
  38. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegSetupVSCodeOnUbuntuDefaultTestDeployAssertFF8DF2C5.template.json +13 -2
  39. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegTestStackUbuntu24.assets.json +13 -13
  40. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegTestStackUbuntu24.metadata.json +260 -174
  41. package/integ-tests/integ.ubuntu24.ts.snapshot/IntegTestStackUbuntu24.template.json +302 -173
  42. package/integ-tests/integ.ubuntu24.ts.snapshot/integ.json +1 -1
  43. package/integ-tests/integ.ubuntu24.ts.snapshot/manifest.json +2 -2
  44. package/integ-tests/integ.ubuntu24.ts.snapshot/tree.json +1 -1
  45. package/integ-tests/integ.ubuntu26.ts +11 -2
  46. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegSetupVSCodeOnUbuntu26DefaultTestDeployAssertD888890F.assets.json +3 -3
  47. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegSetupVSCodeOnUbuntu26DefaultTestDeployAssertD888890F.metadata.json +15 -0
  48. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegSetupVSCodeOnUbuntu26DefaultTestDeployAssertD888890F.template.json +13 -2
  49. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegTestStackUbuntu26.assets.json +13 -13
  50. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegTestStackUbuntu26.metadata.json +260 -174
  51. package/integ-tests/integ.ubuntu26.ts.snapshot/IntegTestStackUbuntu26.template.json +302 -173
  52. package/integ-tests/integ.ubuntu26.ts.snapshot/integ.json +1 -1
  53. package/integ-tests/integ.ubuntu26.ts.snapshot/manifest.json +2 -2
  54. package/integ-tests/integ.ubuntu26.ts.snapshot/tree.json +1 -1
  55. package/lib/idle-monitor/idle-monitor.d.ts +14 -0
  56. package/lib/idle-monitor/idle-monitor.js +4 -2
  57. package/lib/idle-monitor-enabler/idle-monitor-enabler.d.ts +14 -0
  58. package/lib/idle-monitor-enabler/idle-monitor-enabler.js +6 -2
  59. package/lib/installer/installer.d.ts +15 -0
  60. package/lib/installer/installer.js +36 -2
  61. package/lib/log-groups.d.ts +38 -0
  62. package/lib/log-groups.js +85 -0
  63. package/lib/prefixlist-retriever/prefixlist-retriever.d.ts +15 -1
  64. package/lib/prefixlist-retriever/prefixlist-retriever.js +4 -7
  65. package/lib/secret-retriever/secret-retriever.d.ts +14 -0
  66. package/lib/secret-retriever/secret-retriever.js +8 -1
  67. package/lib/vscode-server.d.ts +22 -0
  68. package/lib/vscode-server.js +35 -3
  69. package/package.json +1 -1
package/.jsii CHANGED
@@ -9747,7 +9747,7 @@
9747
9747
  },
9748
9748
  "name": "@mavogel/cdk-vscode-server",
9749
9749
  "readme": {
9750
- "markdown": "![Source](https://img.shields.io/github/stars/mavogel/cdk-vscode-server?logo=github&label=GitHub%20Stars)\n[![Build Status](https://github.com/mavogel/cdk-vscode-server/actions/workflows/build.yml/badge.svg)](https://github.com/mavogel/cdk-vscode-server/actions/workflows/build.yml)\n[![ESLint Code Formatting](https://img.shields.io/badge/code_style-eslint-brightgreen.svg)](https://eslint.org)\n[![Latest release](https://img.shields.io/github/release/mavogel/cdk-vscode-server.svg)](https://github.com/mavogel/cdk-vscode-server/releases)\n![GitHub](https://img.shields.io/github/license/mavogel/cdk-vscode-server)\n[![npm](https://img.shields.io/npm/dt/@mavogel/cdk-vscode-server?label=npm&color=orange)](https://www.npmjs.com/package/@mavogel/cdk-vscode-server)\n[![typescript](https://img.shields.io/badge/jsii-typescript-blueviolet.svg)](https://www.npmjs.com/package/@mavogel/cdk-vscode-server)\n\n# cdk-vscode-server\n\nRunning your dev IDE vscode on AWS for development and workshop purposes.\n\n> [!Note]\n> This construct is designed for workshop purposes and does not fulfill all security and authentication best practices.\n\n![EXPERIMENTAL](https://img.shields.io/badge/stability-experimantal-orange?style=for-the-badge)**<br>This is an early version of the package. The API will change while I\nwe implement new features. Therefore make sure you use an exact version in your `package.json` before it reaches 1.0.0.**\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n - [Standard](#Standard)\n - [Pre-populate with Git Repository](#pre-populate-with-git-repository)\n - [Custom Domain Configuration](#custom-domain-configuration)\n - [Auto-Stop Configuration](#auto-stop-configuration)\n - [Custom Installation Steps](#custom-installation-steps)\n- [Solution Design](#solution-design)\n- [Inspiration](#inspiration)\n\n## Features\n\n- โšก **Quick Setup**: Spin up and configure your [vscode](https://code.visualstudio.com/) server in under 10 minutes in your AWS account\n- ๐Ÿ“ **Best Practice Setup**: Set up with [projen](https://projen.io/) and a [single configuration file](./.projenrc.ts) to keep your changes centralized.\n- ๐Ÿคนโ€โ™‚๏ธ **Pre-installed packages**: Besides the [vscode](https://code.visualstudio.com/) server, other tools and software packages such as `git`, `docker`, `awscli` `nodejs` and `python` are pre-installed on the EC2 instance.\n- ๐ŸŒ **Custom Domain Support**: Use your own domain name with automatic ACM certificate creation and Route53 DNS configuration, or bring your existing certificate.\n- ๐Ÿ’ฐ **Auto-Stop**: Automatically stop EC2 instances after inactivity with Elastic IP retention - save up to 75% on costs for development environments.\n- ๐Ÿ”ง **Custom Install Steps**: Extend the standard installation with your own shell commands to install workshop-specific tools, configure environments, or run setup scripts.\n- ๐Ÿ—๏ธ **Extensibility**: Pass in properties to the construct, which start with `additional*`. They allow you to extend the configuration to your needs. There are more to come...\n\n## Usage\nActually we supported 2 modes:\n\n### Standard\nThe following steps get you started:\n\n1. Create a new `awscdk-app` via\n```bash\nnpx projen new awscdk-app-ts --package-manager=npm\n```\n3. Add `@mavogel/cdk-vscode-server` as a dependency to your project in the `.projenrc.ts` file\n4. Run `npx projen` to install it\n5. Add the following to the `src/main.ts` file:\n```ts\nimport { App, Stack, StackProps } from 'aws-cdk-lib';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as iam from 'aws-cdk-lib/aws-iam';\nimport { Construct } from 'constructs';\nimport {\n LinuxArchitectureType,\n LinuxFlavorType,\n VSCodeServer\n} from '@mavogel/cdk-vscode-server';\n\nexport class MyStack extends Stack {\n constructor(scope: Construct, id: string, props: StackProps = {}) {\n super(scope, id, props);\n\n new VSCodeServer(this, 'vscode', {\n // for example (or simply use the defaults by not setting the properties)\n instanceVolumeSize: 8,\n instanceClass: ec2.InstanceClass.M7G,\n instanceSize: ec2.InstanceSize.LARGE,\n instanceOperatingSystem: LinuxFlavorType.UBUNTU_24, // or UBUNTU_26, AMAZON_LINUX_2023\n instanceCpuArchitecture: LinuxArchitectureType.ARM,\n\n // ๐Ÿ‘‡๐Ÿฝ or if you want to give the InstanceRole more permissions\n additionalInstanceRolePolicies: [\n new iam.PolicyStatement({\n effect: iam.Effect.ALLOW,\n actions: [\n 'codebuild:*',\n ],\n resources: [\n `arn:aws:codebuild:*:${Stack.of(this).account}:*/*`,\n ],\n }),\n ]\n\n // and more... ๐Ÿ’ก\n });\n }\n}\n\nconst env = {\n account: '123456789912',\n region: 'eu-central-1',\n};\n\nconst app = new App();\nnew MyStack(app, 'vscode-server', { env });\napp.synth();\n```\n\nand deploy it\n```bash\nnpx projen build\nnpx projen deploy\n```\n\nwith the output\n```console\nโœจ Deployment time: 509.87s\n\nOutputs:\ndev.vscodedomainName6729AA39 = https://d1foo65bar4baz.cloudfront.net/?folder=/Workshop\ndev.vscodepassword64FBCA12 = foobarbaz\n```\n\nSee the [examples](./examples) folder for more inspiration.\n\n### Supported Operating Systems\n\nSet the operating system with `instanceOperatingSystem` and the CPU architecture with `instanceCpuArchitecture` (`ARM` or `AMD64`). Only Ubuntu LTS releases are supported:\n\n| `LinuxFlavorType` | OS | Notes |\n|---|---|---|\n| `UBUNTU_24` (default) | Ubuntu 24.04 LTS (noble) | Installs .NET SDK 8.0 |\n| `UBUNTU_26` | Ubuntu 26.04 LTS (resolute) | Installs .NET SDK 10.0, since 8.0 is not in the Ubuntu 26 archive |\n| `AMAZON_LINUX_2023` | Amazon Linux 2023 | Installs .NET SDK 8.0 |\n\n**Upgrading:** `UBUNTU_22` and `UBUNTU_25` were removed; only the two current Ubuntu LTS releases (24.04 and 26.04) are supported, and 25.04 was not an LTS release. If your stack uses either removed value, switch to `UBUNTU_24` or `UBUNTU_26`. Changing the operating system replaces the EC2 instance.\n\n### Pre-populate with Git Repository\n\nClone a git repository into the VS Code Server's home folder during instance setup - perfect for workshops or development environments with starter code:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n // Clone a git repository into the home folder\n repoUrl: 'https://github.com/aws-samples/my-workshop-repo.git',\n\n // Optional: customize the home folder path (default: /Workshop)\n homeFolder: '/MyWorkshop',\n\n // Optional: specify VS Code user (default: vscode-user)\n vscodeUser: 'workshop-user',\n});\n```\n\n**What happens:**\n1. During instance setup, the specified git repository is cloned into the user's home folder\n2. VS Code Server opens with the repository already loaded and ready to use\n3. Participants can start coding immediately without manual git clone steps\n\n**Use cases:**\n- Workshop environments with pre-configured starter code\n- Development environments with boilerplate projects\n- Training sessions with example applications\n- Code review sessions with pre-loaded repositories\n\n**Repository requirements:**\n- Must be publicly accessible (no authentication required)\n- HTTPS URLs only (SSH git URLs are not supported)\n- Repository will be cloned using `git clone` during instance initialization\n\nFor complete examples, see [examples/](./examples).\n\n### Custom Domain Configuration\n\nYou can configure your VS Code Server with a custom domain name instead of using the default CloudFront domain. The construct supports three different configuration options:\n\n#### Option 1: Auto-create Certificate with DNS Validation\n```ts\nnew VSCodeServer(this, 'vscode', {\n domainName: 'vscode.example.com',\n hostedZoneId: 'Z123EXAMPLE456', // optional - will auto-discover if not provided\n autoCreateCertificate: true,\n});\n```\n\nThis will:\n- Create an ACM certificate in us-east-1 (required for CloudFront)\n- Validate the certificate using DNS validation\n- Create a Route53 A record pointing to the CloudFront distribution\n- Configure the CloudFront distribution with the custom domain\n\n#### Option 2: Use Existing Certificate\n```ts\nnew VSCodeServer(this, 'vscode', {\n domainName: 'vscode.example.com',\n hostedZoneId: 'Z123EXAMPLE456',\n certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012',\n});\n```\n\n**Requirements:**\n- Certificate must be in us-east-1 region\n- Certificate must be validated and ready to use\n- Certificate must include the domain name\n\n#### Option 3: Default (No Custom Domain)\n```ts\nnew VSCodeServer(this, 'vscode', {\n // No domain configuration - uses CloudFront default domain\n});\n```\n\nFor complete examples, see [examples/custom-domain/main.ts](./examples/custom-domain/main.ts).\n\n6. Then open the domain name in your favorite browser and you'd see the following login screen:\n![vscode-server-ui-login](docs/img/vscode-server-ui-login-min.png)\n\n7. After entering the password, you are logged into VSCode and can start coding :tada:\n\n![vscode-server-ui](docs/img/vscode-server-ui-min.png)\n\n> [!Important]\n> There are issues with copy pasting into the VSCode terminal within the Firefox browser (2025-01-12)\n\n### Auto-Stop Configuration\n\nSave up to 75% on costs by automatically stopping EC2 instances when idle:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n enableAutoStop: true, // Enable auto-stop feature\n idleTimeoutMinutes: 30, // Stop after 30 minutes of no activity (default)\n idleCheckIntervalMinutes: 5, // Check for idle activity every 5 minutes (default)\n});\n```\n\n**How it works:**\n1. **Idle Detection**: Monitors CloudFront request metrics at configured intervals (default: every 5 minutes)\n2. **Auto-Stop**: Stops the EC2 instance after the configured idle timeout when no requests are detected\n3. **Static IP**: Allocates an Elastic IP to maintain a consistent public IP address across stop/start cycles\n4. **Manual Resume**: Users can manually start the instance via AWS Console or CLI when needed\n\n**Cost Savings Example:**\n- **Without auto-stop**: m7g.xlarge running 24/7 = ~$120/month\n- **With auto-stop** (8 hours/day, 5 days/week): ~$30/month\n- **Savings**: ~$90/month (75% reduction)\n\n**Additional costs:**\n- Elastic IP (allocated): ~$3.65/month\n- Lambda function (IdleMonitor): ~$0.10/month\n- EventBridge rule: Negligible\n- **Net savings**: ~$86/month per instance\n\n**Architecture Components:**\n- Elastic IP for consistent public addressing\n- EventBridge rule triggering idle monitoring at configured intervals\n- IdleMonitor Lambda function checking CloudWatch metrics for request activity\n- IdleMonitorEnabler custom resource ensuring monitoring only starts after installation completes\n- CloudWatch metrics from CloudFront distribution\n\n**Integration Testing:**\n\nThe stop-on-idle functionality includes comprehensive integration tests (`integ-tests/integ.stop-on-idle.ts`) that verify the complete workflow:\n\n1. **Phase 1 - Verify Auto-Stop**: Waits for the instance to automatically stop after the configured idle timeout\n2. **Phase 2 - Disable IdleMonitor**: Disables the EventBridge rule to prevent the instance from being stopped again during testing\n3. **Phase 3 - Start Instance**: Starts the stopped instance and waits for it to reach the running state\n4. **Phase 4 - Verify Login**: Confirms that VS Code Server is accessible through CloudFront after the instance has been restarted\n\nThis 4-phase test ensures that:\n- Idle detection works correctly based on CloudWatch metrics\n- Instance stops automatically when no activity is detected\n- Instance can be successfully restarted after being stopped\n- VS Code Server remains accessible after stop/start cycles\n- Elastic IP maintains connectivity across state changes\n\nRun integration tests with:\n```bash\nnpm run integ-test\n```\n\n### Custom Installation Steps\n\nExtend the standard VS Code Server installation with your own custom shell commands - perfect for installing workshop-specific tools, configuring development environments, or running setup scripts:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n // Add custom installation steps that run after standard setup\n customInstallSteps: [\n {\n name: 'InstallWorkshopTools',\n commands: [\n '#!/bin/bash',\n 'echo \"Installing workshop-specific tools\"',\n\n // Install additional software\n 'curl -fsSL https://get.docker.com | sh',\n 'usermod -aG docker ubuntu',\n\n // Configure environment\n 'echo \"export WORKSHOP_ENV=production\" >> /home/ubuntu/.bashrc',\n ],\n },\n {\n name: 'CloneStarterCode',\n commands: [\n '#!/bin/bash',\n 'cd /home/ubuntu',\n 'git clone https://github.com/my-org/workshop-starter.git',\n 'chown -R ubuntu:ubuntu workshop-starter',\n ],\n },\n ],\n});\n```\n\n**Key Features:**\n- **Execute After Standard Setup**: Custom steps run after VS Code Server installation completes\n- **Multiple Steps**: Add as many installation steps as needed, executed in order\n- **Full Shell Access**: Run any shell commands with root privileges\n- **Workshop-Friendly**: Pre-install tools, configure environments, or download starter code\n\n**Common Use Cases:**\n- Install additional development tools (Docker, kubectl, terraform)\n- Configure workshop-specific environments and credentials\n- Clone starter code repositories with specific permissions\n- Set up databases or services required for training\n- Download and prepare datasets or assets\n- Configure IDE extensions or settings\n\n**Supported Operating Systems:**\n- Ubuntu 24/26\n- Amazon Linux 2023\n\n**Requirements:**\n- Commands execute with root privileges during instance initialization\n- Use absolute paths or ensure proper working directory context\n- Consider idempotency if instance might be restarted\n- Commands run synchronously in the order specified\n\nFor complete examples, see [examples/custom-install-steps/main.ts](./examples/custom-install-steps/main.ts).\n\n## Solution Design\n\n<details>\n <summary>... if you're curious about click here for the details</summary>\n\n![vscode-server-solution-design](docs/img/vscode-server.drawio-min.png)\n\n</details>\n\n## Inspiration\nThis project was created based on the following inspiration\n\n- [vscode-on-ec2-for-prototyping](https://github.com/aws-samples/vscode-on-ec2-for-prototyping): as baseline, which unfortunately was outdated\n- [aws-terraform-dev-container](https://github.com/awslabs/aws-terraform-dev-container): as baseline for terraform, but unfortunately also outdated\n- [java-on-aws-workshop-ide-only.yaml](https://github.com/aws-samples/java-on-aws/blob/main/labs/unicorn-store/infrastructure/cfn/java-on-aws-workshop-ide-only.yaml): an already synthesized cloudformation stack, which used mostly python as the custom resources\n- [fleet-workshop-team-stack-self.json](https://static.us-east-1.prod.workshops.aws/public/cc4aa67e-5b7a-4df1-abf7-c42502899a25/assets/fleet-workshop-team-stack-self.json): also an already synthesized cloudformation stack, which did much more as I currently implemented here.\n- [eks-workshop-vscode-cfn.yaml](https://github.com/aws-samples/eks-workshop-v2/blob/main/lab/cfn/eks-workshop-vscode-cfn.yaml): another great baseline\n\n\n## ๐Ÿš€ Unlock the Full Potential of Your AWS Cloud Infrastructure\n\nHi, Iโ€™m Manuel, an AWS expert passionate about empowering businesses with **scalable, resilient, and cost-optimized cloud solutions**. With **MV Consulting**, I specialize in crafting **tailored AWS architectures** and **DevOps-driven workflows** that not only meet your current needs but grow with you.\n\n---\n\n### ๐ŸŒŸ Why Work With Me?\n\nโœ”๏ธ **Tailored AWS Solutions:** Every business is unique, so I design custom solutions that fit your goals and challenges.\nโœ”๏ธ **Well-Architected Designs:** From scalability to security, my solutions align with AWS Well-Architected Framework.\nโœ”๏ธ **Cloud-Native Focus:** I specialize in modern, cloud-native systems that embrace the full potential of AWS.\nโœ”๏ธ **Business-Driven Tech:** Technology should serve your business, not the other way around.\n\n---\n\n### ๐Ÿ›  What I Bring to the Table\n\n๐Ÿ”‘ **12x AWS Certifications**\nIโ€™m **AWS Certified Solutions Architect and DevOps โ€“ Professional** and hold numerous additional certifications, so you can trust Iโ€™ll bring industry best practices to your projects. Feel free to explose by [badges](https://www.credly.com/users/manuel-vogel)\n\nโš™๏ธ **Infrastructure as Code (IaC)**\nWith deep expertise in **AWS CDK** and **Terraform**, I ensure your infrastructure is automated, maintainable, and scalable.\n\n๐Ÿ“ฆ **DevOps Expertise**\nFrom CI/CD pipelines with **GitHub Actions** and **GitLab CI** to container orchestration **Kubernetes** and others, I deliver workflows that are smooth and efficient.\n\n๐ŸŒ **Hands-On Experience**\nWith over **7 years of AWS experience** and a decade in the tech world, Iโ€™ve delivered solutions for companies large and small. My open-source contributions showcase my commitment to transparency and innovation. Feel free to explore my [GitHub profile](https://github.com/mavogel)\n\n---\n\n### ๐Ÿ’ผ Letโ€™s Build Something Great Together\n\nI know that choosing the right partner is critical to your success. When you work with me, youโ€™re not just contracting an engineer โ€“ youโ€™re gaining a trusted advisor and hands-on expert who cares about your business as much as you do.\n\nโœ”๏ธ **Direct Collaboration**: No middlemen or red tape โ€“ you work with me directly.\nโœ”๏ธ **Transparent Process**: Expect open communication, clear timelines, and visible results.\nโœ”๏ธ **Real Value**: My solutions focus on delivering measurable impact for your business.\n\n\n<a href=\"https://tinyurl.com/mvc-15min\"><img alt=\"Schedule your call\" src=\"https://img.shields.io/badge/schedule%20your%20call-success.svg?style=for-the-badge\"/></a>\n\n---\n\n## ๐Ÿ™Œ Acknowledgements\n\nBig shoutout to the amazing team behind [Projen](https://github.com/projen/projen)!\nTheir groundbreaking work simplifies cloud infrastructure projects and inspires us every day. ๐Ÿ’ก\n\n## Author\n\n[Manuel Vogel](https://manuel-vogel.de/about/)\n\n[![](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/manuel-vogel)\n[![](https://img.shields.io/badge/GitHub-2b3137?style=for-the-badge&logo=github&logoColor=white)](https://github.com/mavogel)"
9750
+ "markdown": "![Source](https://img.shields.io/github/stars/mavogel/cdk-vscode-server?logo=github&label=GitHub%20Stars)\n[![Build Status](https://github.com/mavogel/cdk-vscode-server/actions/workflows/build.yml/badge.svg)](https://github.com/mavogel/cdk-vscode-server/actions/workflows/build.yml)\n[![ESLint Code Formatting](https://img.shields.io/badge/code_style-eslint-brightgreen.svg)](https://eslint.org)\n[![Latest release](https://img.shields.io/github/release/mavogel/cdk-vscode-server.svg)](https://github.com/mavogel/cdk-vscode-server/releases)\n![GitHub](https://img.shields.io/github/license/mavogel/cdk-vscode-server)\n[![npm](https://img.shields.io/npm/dt/@mavogel/cdk-vscode-server?label=npm&color=orange)](https://www.npmjs.com/package/@mavogel/cdk-vscode-server)\n[![typescript](https://img.shields.io/badge/jsii-typescript-blueviolet.svg)](https://www.npmjs.com/package/@mavogel/cdk-vscode-server)\n\n# cdk-vscode-server\n\nRunning your dev IDE vscode on AWS for development and workshop purposes.\n\n> [!Note]\n> This construct is designed for workshop purposes and does not fulfill all security and authentication best practices.\n\n![EXPERIMENTAL](https://img.shields.io/badge/stability-experimantal-orange?style=for-the-badge)**<br>This is an early version of the package. The API will change while I\nwe implement new features. Therefore make sure you use an exact version in your `package.json` before it reaches 1.0.0.**\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n - [Standard](#Standard)\n - [Pre-populate with Git Repository](#pre-populate-with-git-repository)\n - [Custom Domain Configuration](#custom-domain-configuration)\n - [Auto-Stop Configuration](#auto-stop-configuration)\n - [Custom Installation Steps](#custom-installation-steps)\n- [Solution Design](#solution-design)\n- [Inspiration](#inspiration)\n\n## Features\n\n- โšก **Quick Setup**: Spin up and configure your [vscode](https://code.visualstudio.com/) server in under 10 minutes in your AWS account\n- ๐Ÿ“ **Best Practice Setup**: Set up with [projen](https://projen.io/) and a [single configuration file](./.projenrc.ts) to keep your changes centralized.\n- ๐Ÿคนโ€โ™‚๏ธ **Pre-installed packages**: Besides the [vscode](https://code.visualstudio.com/) server, other tools and software packages such as `git`, `docker`, `awscli` `nodejs` and `python` are pre-installed on the EC2 instance.\n- ๐ŸŒ **Custom Domain Support**: Use your own domain name with automatic ACM certificate creation and Route53 DNS configuration, or bring your existing certificate.\n- ๐Ÿ’ฐ **Auto-Stop**: Automatically stop EC2 instances after inactivity with Elastic IP retention - save up to 75% on costs for development environments.\n- ๐Ÿ”ง **Custom Install Steps**: Extend the standard installation with your own shell commands to install workshop-specific tools, configure environments, or run setup scripts.\n- ๐Ÿ—๏ธ **Extensibility**: Pass in properties to the construct, which start with `additional*`. They allow you to extend the configuration to your needs. There are more to come...\n\n## Usage\nActually we supported 2 modes:\n\n### Standard\nThe following steps get you started:\n\n1. Create a new `awscdk-app` via\n```bash\nnpx projen new awscdk-app-ts --package-manager=npm\n```\n3. Add `@mavogel/cdk-vscode-server` as a dependency to your project in the `.projenrc.ts` file\n4. Run `npx projen` to install it\n5. Add the following to the `src/main.ts` file:\n```ts\nimport { App, Stack, StackProps } from 'aws-cdk-lib';\nimport * as ec2 from 'aws-cdk-lib/aws-ec2';\nimport * as iam from 'aws-cdk-lib/aws-iam';\nimport { Construct } from 'constructs';\nimport {\n LinuxArchitectureType,\n LinuxFlavorType,\n VSCodeServer\n} from '@mavogel/cdk-vscode-server';\n\nexport class MyStack extends Stack {\n constructor(scope: Construct, id: string, props: StackProps = {}) {\n super(scope, id, props);\n\n new VSCodeServer(this, 'vscode', {\n // for example (or simply use the defaults by not setting the properties)\n instanceVolumeSize: 8,\n instanceClass: ec2.InstanceClass.M7G,\n instanceSize: ec2.InstanceSize.LARGE,\n instanceOperatingSystem: LinuxFlavorType.UBUNTU_24, // or UBUNTU_26, AMAZON_LINUX_2023\n instanceCpuArchitecture: LinuxArchitectureType.ARM,\n\n // ๐Ÿ‘‡๐Ÿฝ or if you want to give the InstanceRole more permissions\n additionalInstanceRolePolicies: [\n new iam.PolicyStatement({\n effect: iam.Effect.ALLOW,\n actions: [\n 'codebuild:*',\n ],\n resources: [\n `arn:aws:codebuild:*:${Stack.of(this).account}:*/*`,\n ],\n }),\n ]\n\n // and more... ๐Ÿ’ก\n });\n }\n}\n\nconst env = {\n account: '123456789912',\n region: 'eu-central-1',\n};\n\nconst app = new App();\nnew MyStack(app, 'vscode-server', { env });\napp.synth();\n```\n\nand deploy it\n```bash\nnpx projen build\nnpx projen deploy\n```\n\nwith the output\n```console\nโœจ Deployment time: 509.87s\n\nOutputs:\ndev.vscodedomainName6729AA39 = https://d1foo65bar4baz.cloudfront.net/?folder=/Workshop\ndev.vscodepassword64FBCA12 = foobarbaz\n```\n\nSee the [examples](./examples) folder for more inspiration.\n\n### Supported Operating Systems\n\nSet the operating system with `instanceOperatingSystem` and the CPU architecture with `instanceCpuArchitecture` (`ARM` or `AMD64`). Only Ubuntu LTS releases are supported:\n\n| `LinuxFlavorType` | OS | Notes |\n|---|---|---|\n| `UBUNTU_24` (default) | Ubuntu 24.04 LTS (noble) | Installs .NET SDK 8.0 |\n| `UBUNTU_26` | Ubuntu 26.04 LTS (resolute) | Installs .NET SDK 10.0, since 8.0 is not in the Ubuntu 26 archive |\n| `AMAZON_LINUX_2023` | Amazon Linux 2023 | Installs .NET SDK 8.0 |\n\n**Upgrading:** `UBUNTU_22` and `UBUNTU_25` were removed; only the two current Ubuntu LTS releases (24.04 and 26.04) are supported, and 25.04 was not an LTS release. If your stack uses either removed value, switch to `UBUNTU_24` or `UBUNTU_26`. Changing the operating system replaces the EC2 instance.\n\n### Log Retention\n\nEvery log group the construct creates expires its logs after 5 days and is deleted together with the stack. That covers the Lambda functions, the custom resource providers and the install output (`/aws/ssm/<document>`). They are deleted after all other resources of the stack, because Lambda delivers its last logs a few seconds late and would recreate an already deleted group without retention. Change both with:\n\n```ts\nimport { RemovalPolicy } from 'aws-cdk-lib';\nimport { RetentionDays } from 'aws-cdk-lib/aws-logs';\n\nnew VSCodeServer(this, 'vscode', {\n logRetention: RetentionDays.ONE_MONTH, // default: FIVE_DAYS, INFINITE never expires the logs\n logRemovalPolicy: RemovalPolicy.RETAIN, // default: DESTROY, RETAIN keeps the logs after the stack is deleted\n});\n```\n\n**Upgrading:** the Lambda functions now log to log groups of the stack. The groups they used before (`/aws/lambda/<function name>`) are not touched and keep their old retention; delete them if you do not need the logs. If you have several `VSCodeServer` in one stack, the setting of the first one applies to the shared log group of the VPC default security group provider.\n\n### Pre-populate with Git Repository\n\nClone a git repository into the VS Code Server's home folder during instance setup - perfect for workshops or development environments with starter code:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n // Clone a git repository into the home folder\n repoUrl: 'https://github.com/aws-samples/my-workshop-repo.git',\n\n // Optional: customize the home folder path (default: /Workshop)\n homeFolder: '/MyWorkshop',\n\n // Optional: specify VS Code user (default: vscode-user)\n vscodeUser: 'workshop-user',\n});\n```\n\n**What happens:**\n1. During instance setup, the specified git repository is cloned into the user's home folder\n2. VS Code Server opens with the repository already loaded and ready to use\n3. Participants can start coding immediately without manual git clone steps\n\n**Use cases:**\n- Workshop environments with pre-configured starter code\n- Development environments with boilerplate projects\n- Training sessions with example applications\n- Code review sessions with pre-loaded repositories\n\n**Repository requirements:**\n- Must be publicly accessible (no authentication required)\n- HTTPS URLs only (SSH git URLs are not supported)\n- Repository will be cloned using `git clone` during instance initialization\n\nFor complete examples, see [examples/](./examples).\n\n### Custom Domain Configuration\n\nYou can configure your VS Code Server with a custom domain name instead of using the default CloudFront domain. The construct supports three different configuration options:\n\n#### Option 1: Auto-create Certificate with DNS Validation\n```ts\nnew VSCodeServer(this, 'vscode', {\n domainName: 'vscode.example.com',\n hostedZoneId: 'Z123EXAMPLE456', // optional - will auto-discover if not provided\n autoCreateCertificate: true,\n});\n```\n\nThis will:\n- Create an ACM certificate in us-east-1 (required for CloudFront)\n- Validate the certificate using DNS validation\n- Create a Route53 A record pointing to the CloudFront distribution\n- Configure the CloudFront distribution with the custom domain\n\n#### Option 2: Use Existing Certificate\n```ts\nnew VSCodeServer(this, 'vscode', {\n domainName: 'vscode.example.com',\n hostedZoneId: 'Z123EXAMPLE456',\n certificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012',\n});\n```\n\n**Requirements:**\n- Certificate must be in us-east-1 region\n- Certificate must be validated and ready to use\n- Certificate must include the domain name\n\n#### Option 3: Default (No Custom Domain)\n```ts\nnew VSCodeServer(this, 'vscode', {\n // No domain configuration - uses CloudFront default domain\n});\n```\n\nFor complete examples, see [examples/custom-domain/main.ts](./examples/custom-domain/main.ts).\n\n6. Then open the domain name in your favorite browser and you'd see the following login screen:\n![vscode-server-ui-login](docs/img/vscode-server-ui-login-min.png)\n\n7. After entering the password, you are logged into VSCode and can start coding :tada:\n\n![vscode-server-ui](docs/img/vscode-server-ui-min.png)\n\n> [!Important]\n> There are issues with copy pasting into the VSCode terminal within the Firefox browser (2025-01-12)\n\n### Auto-Stop Configuration\n\nSave up to 75% on costs by automatically stopping EC2 instances when idle:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n enableAutoStop: true, // Enable auto-stop feature\n idleTimeoutMinutes: 30, // Stop after 30 minutes of no activity (default)\n idleCheckIntervalMinutes: 5, // Check for idle activity every 5 minutes (default)\n});\n```\n\n**How it works:**\n1. **Idle Detection**: Monitors CloudFront request metrics at configured intervals (default: every 5 minutes)\n2. **Auto-Stop**: Stops the EC2 instance after the configured idle timeout when no requests are detected\n3. **Static IP**: Allocates an Elastic IP to maintain a consistent public IP address across stop/start cycles\n4. **Manual Resume**: Users can manually start the instance via AWS Console or CLI when needed\n\n**Cost Savings Example:**\n- **Without auto-stop**: m7g.xlarge running 24/7 = ~$120/month\n- **With auto-stop** (8 hours/day, 5 days/week): ~$30/month\n- **Savings**: ~$90/month (75% reduction)\n\n**Additional costs:**\n- Elastic IP (allocated): ~$3.65/month\n- Lambda function (IdleMonitor): ~$0.10/month\n- EventBridge rule: Negligible\n- **Net savings**: ~$86/month per instance\n\n**Architecture Components:**\n- Elastic IP for consistent public addressing\n- EventBridge rule triggering idle monitoring at configured intervals\n- IdleMonitor Lambda function checking CloudWatch metrics for request activity\n- IdleMonitorEnabler custom resource ensuring monitoring only starts after installation completes\n- CloudWatch metrics from CloudFront distribution\n\n**Integration Testing:**\n\nThe stop-on-idle functionality includes comprehensive integration tests (`integ-tests/integ.stop-on-idle.ts`) that verify the complete workflow:\n\n1. **Phase 1 - Verify Auto-Stop**: Waits for the instance to automatically stop after the configured idle timeout\n2. **Phase 2 - Disable IdleMonitor**: Disables the EventBridge rule to prevent the instance from being stopped again during testing\n3. **Phase 3 - Start Instance**: Starts the stopped instance and waits for it to reach the running state\n4. **Phase 4 - Verify Login**: Confirms that VS Code Server is accessible through CloudFront after the instance has been restarted\n\nThis 4-phase test ensures that:\n- Idle detection works correctly based on CloudWatch metrics\n- Instance stops automatically when no activity is detected\n- Instance can be successfully restarted after being stopped\n- VS Code Server remains accessible after stop/start cycles\n- Elastic IP maintains connectivity across state changes\n\nRun integration tests with:\n```bash\nnpm run integ-test\n```\n\n### Custom Installation Steps\n\nExtend the standard VS Code Server installation with your own custom shell commands - perfect for installing workshop-specific tools, configuring development environments, or running setup scripts:\n\n```ts\nnew VSCodeServer(this, 'vscode', {\n // Add custom installation steps that run after standard setup\n customInstallSteps: [\n {\n name: 'InstallWorkshopTools',\n commands: [\n '#!/bin/bash',\n 'echo \"Installing workshop-specific tools\"',\n\n // Install additional software\n 'curl -fsSL https://get.docker.com | sh',\n 'usermod -aG docker ubuntu',\n\n // Configure environment\n 'echo \"export WORKSHOP_ENV=production\" >> /home/ubuntu/.bashrc',\n ],\n },\n {\n name: 'CloneStarterCode',\n commands: [\n '#!/bin/bash',\n 'cd /home/ubuntu',\n 'git clone https://github.com/my-org/workshop-starter.git',\n 'chown -R ubuntu:ubuntu workshop-starter',\n ],\n },\n ],\n});\n```\n\n**Key Features:**\n- **Execute After Standard Setup**: Custom steps run after VS Code Server installation completes\n- **Multiple Steps**: Add as many installation steps as needed, executed in order\n- **Full Shell Access**: Run any shell commands with root privileges\n- **Workshop-Friendly**: Pre-install tools, configure environments, or download starter code\n\n**Common Use Cases:**\n- Install additional development tools (Docker, kubectl, terraform)\n- Configure workshop-specific environments and credentials\n- Clone starter code repositories with specific permissions\n- Set up databases or services required for training\n- Download and prepare datasets or assets\n- Configure IDE extensions or settings\n\n**Supported Operating Systems:**\n- Ubuntu 24/26\n- Amazon Linux 2023\n\n**Requirements:**\n- Commands execute with root privileges during instance initialization\n- Use absolute paths or ensure proper working directory context\n- Consider idempotency if instance might be restarted\n- Commands run synchronously in the order specified\n\nFor complete examples, see [examples/custom-install-steps/main.ts](./examples/custom-install-steps/main.ts).\n\n## Solution Design\n\n<details>\n <summary>... if you're curious about click here for the details</summary>\n\n![vscode-server-solution-design](docs/img/vscode-server.drawio-min.png)\n\n</details>\n\n## Inspiration\nThis project was created based on the following inspiration\n\n- [vscode-on-ec2-for-prototyping](https://github.com/aws-samples/vscode-on-ec2-for-prototyping): as baseline, which unfortunately was outdated\n- [aws-terraform-dev-container](https://github.com/awslabs/aws-terraform-dev-container): as baseline for terraform, but unfortunately also outdated\n- [java-on-aws-workshop-ide-only.yaml](https://github.com/aws-samples/java-on-aws/blob/main/labs/unicorn-store/infrastructure/cfn/java-on-aws-workshop-ide-only.yaml): an already synthesized cloudformation stack, which used mostly python as the custom resources\n- [fleet-workshop-team-stack-self.json](https://static.us-east-1.prod.workshops.aws/public/cc4aa67e-5b7a-4df1-abf7-c42502899a25/assets/fleet-workshop-team-stack-self.json): also an already synthesized cloudformation stack, which did much more as I currently implemented here.\n- [eks-workshop-vscode-cfn.yaml](https://github.com/aws-samples/eks-workshop-v2/blob/main/lab/cfn/eks-workshop-vscode-cfn.yaml): another great baseline\n\n\n## ๐Ÿš€ Unlock the Full Potential of Your AWS Cloud Infrastructure\n\nHi, Iโ€™m Manuel, an AWS expert passionate about empowering businesses with **scalable, resilient, and cost-optimized cloud solutions**. With **MV Consulting**, I specialize in crafting **tailored AWS architectures** and **DevOps-driven workflows** that not only meet your current needs but grow with you.\n\n---\n\n### ๐ŸŒŸ Why Work With Me?\n\nโœ”๏ธ **Tailored AWS Solutions:** Every business is unique, so I design custom solutions that fit your goals and challenges.\nโœ”๏ธ **Well-Architected Designs:** From scalability to security, my solutions align with AWS Well-Architected Framework.\nโœ”๏ธ **Cloud-Native Focus:** I specialize in modern, cloud-native systems that embrace the full potential of AWS.\nโœ”๏ธ **Business-Driven Tech:** Technology should serve your business, not the other way around.\n\n---\n\n### ๐Ÿ›  What I Bring to the Table\n\n๐Ÿ”‘ **12x AWS Certifications**\nIโ€™m **AWS Certified Solutions Architect and DevOps โ€“ Professional** and hold numerous additional certifications, so you can trust Iโ€™ll bring industry best practices to your projects. Feel free to explose by [badges](https://www.credly.com/users/manuel-vogel)\n\nโš™๏ธ **Infrastructure as Code (IaC)**\nWith deep expertise in **AWS CDK** and **Terraform**, I ensure your infrastructure is automated, maintainable, and scalable.\n\n๐Ÿ“ฆ **DevOps Expertise**\nFrom CI/CD pipelines with **GitHub Actions** and **GitLab CI** to container orchestration **Kubernetes** and others, I deliver workflows that are smooth and efficient.\n\n๐ŸŒ **Hands-On Experience**\nWith over **7 years of AWS experience** and a decade in the tech world, Iโ€™ve delivered solutions for companies large and small. My open-source contributions showcase my commitment to transparency and innovation. Feel free to explore my [GitHub profile](https://github.com/mavogel)\n\n---\n\n### ๐Ÿ’ผ Letโ€™s Build Something Great Together\n\nI know that choosing the right partner is critical to your success. When you work with me, youโ€™re not just contracting an engineer โ€“ youโ€™re gaining a trusted advisor and hands-on expert who cares about your business as much as you do.\n\nโœ”๏ธ **Direct Collaboration**: No middlemen or red tape โ€“ you work with me directly.\nโœ”๏ธ **Transparent Process**: Expect open communication, clear timelines, and visible results.\nโœ”๏ธ **Real Value**: My solutions focus on delivering measurable impact for your business.\n\n\n<a href=\"https://tinyurl.com/mvc-15min\"><img alt=\"Schedule your call\" src=\"https://img.shields.io/badge/schedule%20your%20call-success.svg?style=for-the-badge\"/></a>\n\n---\n\n## ๐Ÿ™Œ Acknowledgements\n\nBig shoutout to the amazing team behind [Projen](https://github.com/projen/projen)!\nTheir groundbreaking work simplifies cloud infrastructure projects and inspires us every day. ๐Ÿ’ก\n\n## Author\n\n[Manuel Vogel](https://manuel-vogel.de/about/)\n\n[![](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/manuel-vogel)\n[![](https://img.shields.io/badge/GitHub-2b3137?style=for-the-badge&logo=github&logoColor=white)](https://github.com/mavogel)"
9751
9751
  },
9752
9752
  "repository": {
9753
9753
  "type": "git",
@@ -9775,7 +9775,7 @@
9775
9775
  "kind": "interface",
9776
9776
  "locationInModule": {
9777
9777
  "filename": "src/vscode-server.ts",
9778
- "line": 33
9778
+ "line": 45
9779
9779
  },
9780
9780
  "name": "CustomInstallStep",
9781
9781
  "properties": [
@@ -9789,7 +9789,7 @@
9789
9789
  "immutable": true,
9790
9790
  "locationInModule": {
9791
9791
  "filename": "src/vscode-server.ts",
9792
- "line": 48
9792
+ "line": 60
9793
9793
  },
9794
9794
  "name": "commands",
9795
9795
  "type": {
@@ -9811,7 +9811,7 @@
9811
9811
  "immutable": true,
9812
9812
  "locationInModule": {
9813
9813
  "filename": "src/vscode-server.ts",
9814
- "line": 40
9814
+ "line": 52
9815
9815
  },
9816
9816
  "name": "name",
9817
9817
  "type": {
@@ -9835,7 +9835,7 @@
9835
9835
  },
9836
9836
  "locationInModule": {
9837
9837
  "filename": "src/idle-monitor/idle-monitor.ts",
9838
- "line": 60
9838
+ "line": 75
9839
9839
  },
9840
9840
  "parameters": [
9841
9841
  {
@@ -9861,7 +9861,7 @@
9861
9861
  "kind": "class",
9862
9862
  "locationInModule": {
9863
9863
  "filename": "src/idle-monitor/idle-monitor.ts",
9864
- "line": 49
9864
+ "line": 64
9865
9865
  },
9866
9866
  "name": "IdleMonitor",
9867
9867
  "properties": [
@@ -9873,7 +9873,7 @@
9873
9873
  "immutable": true,
9874
9874
  "locationInModule": {
9875
9875
  "filename": "src/idle-monitor/idle-monitor.ts",
9876
- "line": 53
9876
+ "line": 68
9877
9877
  },
9878
9878
  "name": "function",
9879
9879
  "type": {
@@ -9888,7 +9888,7 @@
9888
9888
  "immutable": true,
9889
9889
  "locationInModule": {
9890
9890
  "filename": "src/idle-monitor/idle-monitor.ts",
9891
- "line": 58
9891
+ "line": 73
9892
9892
  },
9893
9893
  "name": "scheduleRule",
9894
9894
  "type": {
@@ -9909,7 +9909,7 @@
9909
9909
  "kind": "interface",
9910
9910
  "locationInModule": {
9911
9911
  "filename": "src/idle-monitor/idle-monitor.ts",
9912
- "line": 14
9912
+ "line": 16
9913
9913
  },
9914
9914
  "name": "IdleMonitorProps",
9915
9915
  "properties": [
@@ -9922,7 +9922,7 @@
9922
9922
  "immutable": true,
9923
9923
  "locationInModule": {
9924
9924
  "filename": "src/idle-monitor/idle-monitor.ts",
9925
- "line": 22
9925
+ "line": 24
9926
9926
  },
9927
9927
  "name": "distribution",
9928
9928
  "type": {
@@ -9938,7 +9938,7 @@
9938
9938
  "immutable": true,
9939
9939
  "locationInModule": {
9940
9940
  "filename": "src/idle-monitor/idle-monitor.ts",
9941
- "line": 26
9941
+ "line": 28
9942
9942
  },
9943
9943
  "name": "idleTimeoutMinutes",
9944
9944
  "type": {
@@ -9954,7 +9954,7 @@
9954
9954
  "immutable": true,
9955
9955
  "locationInModule": {
9956
9956
  "filename": "src/idle-monitor/idle-monitor.ts",
9957
- "line": 18
9957
+ "line": 20
9958
9958
  },
9959
9959
  "name": "instance",
9960
9960
  "type": {
@@ -9971,7 +9971,7 @@
9971
9971
  "immutable": true,
9972
9972
  "locationInModule": {
9973
9973
  "filename": "src/idle-monitor/idle-monitor.ts",
9974
- "line": 31
9974
+ "line": 33
9975
9975
  },
9976
9976
  "name": "checkIntervalMinutes",
9977
9977
  "optional": true,
@@ -9979,6 +9979,42 @@
9979
9979
  "primitive": "number"
9980
9980
  }
9981
9981
  },
9982
+ {
9983
+ "abstract": true,
9984
+ "docs": {
9985
+ "default": "RemovalPolicy.DESTROY",
9986
+ "stability": "experimental",
9987
+ "summary": "What happens to the log groups when the stack is deleted."
9988
+ },
9989
+ "immutable": true,
9990
+ "locationInModule": {
9991
+ "filename": "src/idle-monitor/idle-monitor.ts",
9992
+ "line": 58
9993
+ },
9994
+ "name": "logRemovalPolicy",
9995
+ "optional": true,
9996
+ "type": {
9997
+ "fqn": "aws-cdk-lib.RemovalPolicy"
9998
+ }
9999
+ },
10000
+ {
10001
+ "abstract": true,
10002
+ "docs": {
10003
+ "default": "RetentionDays.FIVE_DAYS",
10004
+ "stability": "experimental",
10005
+ "summary": "How long the logs of the monitoring Lambda function are kept."
10006
+ },
10007
+ "immutable": true,
10008
+ "locationInModule": {
10009
+ "filename": "src/idle-monitor/idle-monitor.ts",
10010
+ "line": 51
10011
+ },
10012
+ "name": "logRetention",
10013
+ "optional": true,
10014
+ "type": {
10015
+ "fqn": "aws-cdk-lib.aws_logs.RetentionDays"
10016
+ }
10017
+ },
9982
10018
  {
9983
10019
  "abstract": true,
9984
10020
  "docs": {
@@ -9990,7 +10026,7 @@
9990
10026
  "immutable": true,
9991
10027
  "locationInModule": {
9992
10028
  "filename": "src/idle-monitor/idle-monitor.ts",
9993
- "line": 43
10029
+ "line": 45
9994
10030
  },
9995
10031
  "name": "skipStatusChecks",
9996
10032
  "optional": true,
@@ -10011,7 +10047,7 @@
10011
10047
  "kind": "enum",
10012
10048
  "locationInModule": {
10013
10049
  "filename": "src/vscode-server.ts",
10014
- "line": 321
10050
+ "line": 355
10015
10051
  },
10016
10052
  "members": [
10017
10053
  {
@@ -10042,7 +10078,7 @@
10042
10078
  "kind": "enum",
10043
10079
  "locationInModule": {
10044
10080
  "filename": "src/vscode-server.ts",
10045
- "line": 301
10081
+ "line": 335
10046
10082
  },
10047
10083
  "members": [
10048
10084
  {
@@ -10084,7 +10120,7 @@
10084
10120
  },
10085
10121
  "locationInModule": {
10086
10122
  "filename": "src/vscode-server.ts",
10087
- "line": 357
10123
+ "line": 391
10088
10124
  },
10089
10125
  "parameters": [
10090
10126
  {
@@ -10111,7 +10147,7 @@
10111
10147
  "kind": "class",
10112
10148
  "locationInModule": {
10113
10149
  "filename": "src/vscode-server.ts",
10114
- "line": 336
10150
+ "line": 370
10115
10151
  },
10116
10152
  "name": "VSCodeServer",
10117
10153
  "properties": [
@@ -10123,7 +10159,7 @@
10123
10159
  "immutable": true,
10124
10160
  "locationInModule": {
10125
10161
  "filename": "src/vscode-server.ts",
10126
- "line": 340
10162
+ "line": 374
10127
10163
  },
10128
10164
  "name": "domainName",
10129
10165
  "type": {
@@ -10138,7 +10174,7 @@
10138
10174
  "immutable": true,
10139
10175
  "locationInModule": {
10140
10176
  "filename": "src/vscode-server.ts",
10141
- "line": 350
10177
+ "line": 384
10142
10178
  },
10143
10179
  "name": "instance",
10144
10180
  "type": {
@@ -10153,7 +10189,7 @@
10153
10189
  "immutable": true,
10154
10190
  "locationInModule": {
10155
10191
  "filename": "src/vscode-server.ts",
10156
- "line": 345
10192
+ "line": 379
10157
10193
  },
10158
10194
  "name": "password",
10159
10195
  "type": {
@@ -10168,7 +10204,7 @@
10168
10204
  "immutable": true,
10169
10205
  "locationInModule": {
10170
10206
  "filename": "src/vscode-server.ts",
10171
- "line": 355
10207
+ "line": 389
10172
10208
  },
10173
10209
  "name": "idleMonitor",
10174
10210
  "optional": true,
@@ -10190,7 +10226,7 @@
10190
10226
  "kind": "interface",
10191
10227
  "locationInModule": {
10192
10228
  "filename": "src/vscode-server.ts",
10193
- "line": 54
10229
+ "line": 66
10194
10230
  },
10195
10231
  "name": "VSCodeServerProps",
10196
10232
  "properties": [
@@ -10204,7 +10240,7 @@
10204
10240
  "immutable": true,
10205
10241
  "locationInModule": {
10206
10242
  "filename": "src/vscode-server.ts",
10207
- "line": 137
10243
+ "line": 149
10208
10244
  },
10209
10245
  "name": "additionalInstanceRolePolicies",
10210
10246
  "optional": true,
@@ -10227,7 +10263,7 @@
10227
10263
  "immutable": true,
10228
10264
  "locationInModule": {
10229
10265
  "filename": "src/vscode-server.ts",
10230
- "line": 144
10266
+ "line": 156
10231
10267
  },
10232
10268
  "name": "additionalTags",
10233
10269
  "optional": true,
@@ -10252,7 +10288,7 @@
10252
10288
  "immutable": true,
10253
10289
  "locationInModule": {
10254
10290
  "filename": "src/vscode-server.ts",
10255
- "line": 240
10291
+ "line": 252
10256
10292
  },
10257
10293
  "name": "assetZipS3Path",
10258
10294
  "optional": true,
@@ -10270,7 +10306,7 @@
10270
10306
  "immutable": true,
10271
10307
  "locationInModule": {
10272
10308
  "filename": "src/vscode-server.ts",
10273
- "line": 181
10309
+ "line": 193
10274
10310
  },
10275
10311
  "name": "autoCreateCertificate",
10276
10312
  "optional": true,
@@ -10290,7 +10326,7 @@
10290
10326
  "immutable": true,
10291
10327
  "locationInModule": {
10292
10328
  "filename": "src/vscode-server.ts",
10293
- "line": 251
10329
+ "line": 263
10294
10330
  },
10295
10331
  "name": "branchZipS3Path",
10296
10332
  "optional": true,
@@ -10308,7 +10344,7 @@
10308
10344
  "immutable": true,
10309
10345
  "locationInModule": {
10310
10346
  "filename": "src/vscode-server.ts",
10311
- "line": 171
10347
+ "line": 183
10312
10348
  },
10313
10349
  "name": "certificateArn",
10314
10350
  "optional": true,
@@ -10328,7 +10364,7 @@
10328
10364
  "immutable": true,
10329
10365
  "locationInModule": {
10330
10366
  "filename": "src/vscode-server.ts",
10331
- "line": 295
10367
+ "line": 307
10332
10368
  },
10333
10369
  "name": "customInstallSteps",
10334
10370
  "optional": true,
@@ -10351,7 +10387,7 @@
10351
10387
  "immutable": true,
10352
10388
  "locationInModule": {
10353
10389
  "filename": "src/vscode-server.ts",
10354
- "line": 123
10390
+ "line": 135
10355
10391
  },
10356
10392
  "name": "devServerBasePath",
10357
10393
  "optional": true,
@@ -10369,7 +10405,7 @@
10369
10405
  "immutable": true,
10370
10406
  "locationInModule": {
10371
10407
  "filename": "src/vscode-server.ts",
10372
- "line": 130
10408
+ "line": 142
10373
10409
  },
10374
10410
  "name": "devServerPort",
10375
10411
  "optional": true,
@@ -10387,7 +10423,7 @@
10387
10423
  "immutable": true,
10388
10424
  "locationInModule": {
10389
10425
  "filename": "src/vscode-server.ts",
10390
- "line": 153
10426
+ "line": 165
10391
10427
  },
10392
10428
  "name": "domainName",
10393
10429
  "optional": true,
@@ -10405,7 +10441,7 @@
10405
10441
  "immutable": true,
10406
10442
  "locationInModule": {
10407
10443
  "filename": "src/vscode-server.ts",
10408
- "line": 189
10444
+ "line": 201
10409
10445
  },
10410
10446
  "name": "enableAutoStop",
10411
10447
  "optional": true,
@@ -10425,7 +10461,7 @@
10425
10461
  "immutable": true,
10426
10462
  "locationInModule": {
10427
10463
  "filename": "src/vscode-server.ts",
10428
- "line": 262
10464
+ "line": 274
10429
10465
  },
10430
10466
  "name": "folderZipS3Path",
10431
10467
  "optional": true,
@@ -10443,7 +10479,7 @@
10443
10479
  "immutable": true,
10444
10480
  "locationInModule": {
10445
10481
  "filename": "src/vscode-server.ts",
10446
- "line": 116
10482
+ "line": 128
10447
10483
  },
10448
10484
  "name": "homeFolder",
10449
10485
  "optional": true,
@@ -10461,7 +10497,7 @@
10461
10497
  "immutable": true,
10462
10498
  "locationInModule": {
10463
10499
  "filename": "src/vscode-server.ts",
10464
- "line": 162
10500
+ "line": 174
10465
10501
  },
10466
10502
  "name": "hostedZoneId",
10467
10503
  "optional": true,
@@ -10479,7 +10515,7 @@
10479
10515
  "immutable": true,
10480
10516
  "locationInModule": {
10481
10517
  "filename": "src/vscode-server.ts",
10482
- "line": 205
10518
+ "line": 217
10483
10519
  },
10484
10520
  "name": "idleCheckIntervalMinutes",
10485
10521
  "optional": true,
@@ -10497,7 +10533,7 @@
10497
10533
  "immutable": true,
10498
10534
  "locationInModule": {
10499
10535
  "filename": "src/vscode-server.ts",
10500
- "line": 197
10536
+ "line": 209
10501
10537
  },
10502
10538
  "name": "idleTimeoutMinutes",
10503
10539
  "optional": true,
@@ -10515,7 +10551,7 @@
10515
10551
  "immutable": true,
10516
10552
  "locationInModule": {
10517
10553
  "filename": "src/vscode-server.ts",
10518
- "line": 88
10554
+ "line": 100
10519
10555
  },
10520
10556
  "name": "instanceClass",
10521
10557
  "optional": true,
@@ -10533,7 +10569,7 @@
10533
10569
  "immutable": true,
10534
10570
  "locationInModule": {
10535
10571
  "filename": "src/vscode-server.ts",
10536
- "line": 109
10572
+ "line": 121
10537
10573
  },
10538
10574
  "name": "instanceCpuArchitecture",
10539
10575
  "optional": true,
@@ -10551,7 +10587,7 @@
10551
10587
  "immutable": true,
10552
10588
  "locationInModule": {
10553
10589
  "filename": "src/vscode-server.ts",
10554
- "line": 74
10590
+ "line": 86
10555
10591
  },
10556
10592
  "name": "instanceName",
10557
10593
  "optional": true,
@@ -10569,7 +10605,7 @@
10569
10605
  "immutable": true,
10570
10606
  "locationInModule": {
10571
10607
  "filename": "src/vscode-server.ts",
10572
- "line": 102
10608
+ "line": 114
10573
10609
  },
10574
10610
  "name": "instanceOperatingSystem",
10575
10611
  "optional": true,
@@ -10587,7 +10623,7 @@
10587
10623
  "immutable": true,
10588
10624
  "locationInModule": {
10589
10625
  "filename": "src/vscode-server.ts",
10590
- "line": 95
10626
+ "line": 107
10591
10627
  },
10592
10628
  "name": "instanceSize",
10593
10629
  "optional": true,
@@ -10605,7 +10641,7 @@
10605
10641
  "immutable": true,
10606
10642
  "locationInModule": {
10607
10643
  "filename": "src/vscode-server.ts",
10608
- "line": 81
10644
+ "line": 93
10609
10645
  },
10610
10646
  "name": "instanceVolumeSize",
10611
10647
  "optional": true,
@@ -10613,6 +10649,44 @@
10613
10649
  "primitive": "number"
10614
10650
  }
10615
10651
  },
10652
+ {
10653
+ "abstract": true,
10654
+ "docs": {
10655
+ "default": "RemovalPolicy.DESTROY",
10656
+ "remarks": "Use `RemovalPolicy.RETAIN` to keep the logs.\n\nApplies to every log group the construct creates, including the install log\ngroup (SSM command output). Supports `DESTROY` and `RETAIN`.",
10657
+ "stability": "experimental",
10658
+ "summary": "What happens to the log groups the construct creates when the stack is deleted or the log group is replaced."
10659
+ },
10660
+ "immutable": true,
10661
+ "locationInModule": {
10662
+ "filename": "src/vscode-server.ts",
10663
+ "line": 329
10664
+ },
10665
+ "name": "logRemovalPolicy",
10666
+ "optional": true,
10667
+ "type": {
10668
+ "fqn": "aws-cdk-lib.RemovalPolicy"
10669
+ }
10670
+ },
10671
+ {
10672
+ "abstract": true,
10673
+ "docs": {
10674
+ "default": "RetentionDays.FIVE_DAYS",
10675
+ "remarks": "Applies to every log group the construct creates. They are deleted together\nwith the stack. Use `RetentionDays.INFINITE` to never expire the logs.",
10676
+ "stability": "experimental",
10677
+ "summary": "How long the logs of the Lambda functions, the custom resource providers and the installation (SSM command output) are kept."
10678
+ },
10679
+ "immutable": true,
10680
+ "locationInModule": {
10681
+ "filename": "src/vscode-server.ts",
10682
+ "line": 318
10683
+ },
10684
+ "name": "logRetention",
10685
+ "optional": true,
10686
+ "type": {
10687
+ "fqn": "aws-cdk-lib.aws_logs.RetentionDays"
10688
+ }
10689
+ },
10616
10690
  {
10617
10691
  "abstract": true,
10618
10692
  "docs": {
@@ -10625,7 +10699,7 @@
10625
10699
  "immutable": true,
10626
10700
  "locationInModule": {
10627
10701
  "filename": "src/vscode-server.ts",
10628
- "line": 229
10702
+ "line": 241
10629
10703
  },
10630
10704
  "name": "repoUrl",
10631
10705
  "optional": true,
@@ -10644,7 +10718,7 @@
10644
10718
  "immutable": true,
10645
10719
  "locationInModule": {
10646
10720
  "filename": "src/vscode-server.ts",
10647
- "line": 218
10721
+ "line": 230
10648
10722
  },
10649
10723
  "name": "skipStatusChecks",
10650
10724
  "optional": true,
@@ -10662,7 +10736,7 @@
10662
10736
  "immutable": true,
10663
10737
  "locationInModule": {
10664
10738
  "filename": "src/vscode-server.ts",
10665
- "line": 67
10739
+ "line": 79
10666
10740
  },
10667
10741
  "name": "vscodePassword",
10668
10742
  "optional": true,
@@ -10680,7 +10754,7 @@
10680
10754
  "immutable": true,
10681
10755
  "locationInModule": {
10682
10756
  "filename": "src/vscode-server.ts",
10683
- "line": 60
10757
+ "line": 72
10684
10758
  },
10685
10759
  "name": "vscodeUser",
10686
10760
  "optional": true,
@@ -10692,6 +10766,6 @@
10692
10766
  "symbolId": "src/vscode-server:VSCodeServerProps"
10693
10767
  }
10694
10768
  },
10695
- "version": "0.1.1",
10696
- "fingerprint": "HN6dE9640sx4E3R2OTnTPI0oOs3y0vvj+fkdYTAWj9U="
10769
+ "version": "0.1.2",
10770
+ "fingerprint": "SAdx3vSgLbYbRxjhKbHTsjutcBIu0OoX7PtiggNLhGs="
10697
10771
  }
package/AGENTS.md CHANGED
@@ -176,9 +176,21 @@ aws ssm get-parameters --names \
176
176
  - `customInstallSteps` - Array of custom shell commands that run after standard installation
177
177
  - `repoUrl` - Git repository to clone into home folder during setup
178
178
 
179
+ **Logging**:
180
+ - `logRetention` - Retention of every log group the construct creates (default: `RetentionDays.FIVE_DAYS`)
181
+ - `logRemovalPolicy` - What happens to them when the stack is deleted (default: `RemovalPolicy.DESTROY`)
182
+
179
183
  **Extensions**:
180
184
  - `additionalInstanceRolePolicies`, `additionalTags`
181
185
 
186
+ ## Log Groups
187
+
188
+ Every Lambda the construct creates must log to a log group from `createLogGroup()` (`src/log-groups.ts`), which applies the configured retention and removal policy. CDK's own default is `TWO_YEARS` and `RETAIN`, so a function without an explicit `logGroup` leaves a group that never expires or is orphaned. Where a CDK library construct creates the Lambda (`DnsValidatedCertificate`, the VPC default security group provider) use `routeFunctionLogs()`. The SSM command output group is created by SSM itself, so the installer sets its retention with `LogRetention`, which also adopts a group left by an earlier deployment.
189
+
190
+ Lambda delivers the last logs of a function (the delete-time invocation of a custom resource) a few seconds late, and recreates a log group that was just deleted, without retention. `deleteLogGroupsLast()` therefore makes every other resource of the construct wait for a no-op sentinel (`LogGroupsDeletedLast`) that waits for all log groups, so CloudFormation deletes the log groups last. Do not add a `node.addDependency()` from a construct that contains a log group to a resource that is created after the sentinel: it creates a dependency cycle (see how the idle monitor enabler waits for the installer).
191
+
192
+ The `vscode-server-log-retention` tests fail for any Lambda without a log group, with and without the feature flags of `cdk init` apps, so a new Lambda cannot slip through.
193
+
182
194
  ## JSII Constraints
183
195
 
184
196
  **Critical for JSII compatibility**: