diff --git a/examples/devcontainer/README.md b/examples/devcontainer/README.md index 5aa79be4ea..21cc45923c 100644 --- a/examples/devcontainer/README.md +++ b/examples/devcontainer/README.md @@ -73,26 +73,6 @@ devcontainers: forwardPorts: [9000, 9001] ``` -## Supported Fields - -- ✅ `name` - Container display name -- ✅ `image` - Pre-built container image -- ✅ `build` - Build configuration (dockerfile, context, args) -- ✅ `workspaceFolder` - Working directory inside container -- ✅ `workspaceMount` - Primary workspace volume mount -- ✅ `mounts` - Additional volume mounts -- ✅ **`forwardPorts`** - Port forwarding (critical for dev workflows) -- ✅ **`portsAttributes`** - Port metadata (labels, protocols) -- ✅ `containerEnv` - Environment variables -- ✅ `runArgs` - Additional docker/podman arguments -- ✅ `remoteUser` - User to run as - -## Unsupported Fields (Ignored) - -- ❌ `features` - Use Dockerfile instead -- ❌ `customizations` - Use VS Code extension instead -- ❌ `postCreateCommand` / lifecycle scripts - Use Dockerfile ENTRYPOINT/CMD - ## Port Forwarding Examples ### Simple Port Mapping @@ -150,12 +130,3 @@ atmos devcontainer remove # Show configuration atmos devcontainer config ``` - -## Container Naming - -Containers are named: `atmos-devcontainer-{name}-{instance}` - -Examples: -- `atmos-devcontainer-default-default` -- `atmos-devcontainer-terraform-alice` -- `atmos-devcontainer-python-bob` diff --git a/lychee.toml b/lychee.toml index 05aee6505e..9c80fd4470 100644 --- a/lychee.toml +++ b/lychee.toml @@ -34,6 +34,8 @@ exclude = [ "example\\.com", "cpco\\.io", "cloudposse\\.com.*utm_", + # Private GitHub org (not accessible to CI) + "github\\.com/cloudposse-corp", "slack\\.cloudposse\\.com", "wttr\\.in", # GNU.org (rate limits and connection resets) diff --git a/website/blog/2025-12-05-geodesic-production-ready-devcontainer.mdx b/website/blog/2025-12-05-geodesic-production-ready-devcontainer.mdx index d12cb4c801..23f16ca403 100644 --- a/website/blog/2025-12-05-geodesic-production-ready-devcontainer.mdx +++ b/website/blog/2025-12-05-geodesic-production-ready-devcontainer.mdx @@ -127,9 +127,8 @@ Make it even easier with shell aliases in your `atmos.yaml`: ```yaml # atmos.yaml -cli: - aliases: - shell: "devcontainer shell geodesic" +aliases: + shell: "devcontainer shell geodesic" ``` Now you can just type: @@ -221,42 +220,6 @@ devcontainer: Each project gets the right tool versions automatically. -## Real-World Workflows - -### Onboarding a New Team Member - -**Old way:** -1. Install Homebrew -2. Install Docker -3. Install Terraform (with tfenv or version manager) -4. Install kubectl -5. Install AWS CLI -6. Configure AWS credentials -7. Install Helm -8. Install Helmfile -9. Install jq, yq, and other tools -10. Debug version conflicts -11. Maybe productive by end of day? - -**New way with Geodesic:** -```bash -brew install atmos -cd team-infrastructure -atmos devcontainer shell geodesic -# Productive in 2 minutes -``` - -### Working on Multiple Projects - -**Old way:** -- Project A uses one set of tool versions -- Project B uses different tool versions -- Use version managers (tfenv, etc.) to switch constantly -- Hope you remember to switch before running commands - -**New way with Geodesic:** -Each project defines its Geodesic version in `atmos.yaml`, and you automatically get the right tools when you launch the devcontainer for that project. - ## Integration with Atmos Auth Geodesic works seamlessly with Atmos's identity injection feature: diff --git a/website/blog/2025-12-05-native-devcontainer-support.mdx b/website/blog/2025-12-05-native-devcontainer-support.mdx index 608edc523c..a2a5a5d2c2 100644 --- a/website/blog/2025-12-05-native-devcontainer-support.mdx +++ b/website/blog/2025-12-05-native-devcontainer-support.mdx @@ -6,6 +6,9 @@ tags: [feature] date: 2025-12-05 release: v1.201.0 --- +import EmbedExample from '@site/src/components/EmbedExample' +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; Running Atmos and managing cloud infrastructure inevitably means depending on dozens of tools—Terraform, kubectl, Helmfile, AWS CLI, and many more. But here's the problem every platform team faces: **"It works on my machine."** @@ -106,33 +109,32 @@ Each instance is an independent container with its own state, perfect for runnin ## Configuration in atmos.yaml -Define devcontainers alongside your stack and component configuration: +Devcontainers are configured under the top-level `devcontainer` key in `atmos.yaml`. You can define them inline or import existing `devcontainer.json` files — both approaches are fully supported. ```yaml # atmos.yaml -components: - devcontainer: - geodesic: - spec: - name: "Geodesic DevOps Toolbox" - image: "cloudposse/geodesic:latest" - workspaceFolder: "/workspace" - workspaceMount: "type=bind,source=${PWD},target=/workspace" - forwardPorts: - - 8080 - containerEnv: - ATMOS_BASE_PATH: "/workspace" - remoteUser: "root" - - terraform: - spec: - name: "Terraform Development" - image: "hashicorp/terraform:1.10" - workspaceFolder: "/workspace" - forwardPorts: - - 3000 - mounts: - - "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly" +devcontainer: + geodesic: + spec: + name: "Geodesic DevOps Toolbox" + image: "cloudposse/geodesic:latest" + workspaceFolder: "/workspace" + workspaceMount: "type=bind,source=${PWD},target=/workspace" + forwardPorts: + - 8080 + containerEnv: + ATMOS_BASE_PATH: "/workspace" + remoteUser: "root" + + terraform: + spec: + name: "Terraform Development" + image: "hashicorp/terraform:1.10" + workspaceFolder: "/workspace" + forwardPorts: + - 3000 + mounts: + - "type=bind,source=${HOME}/.aws,target=/root/.aws,readonly" ``` ### Use Existing devcontainer.json Files @@ -141,24 +143,22 @@ Already have `.devcontainer/devcontainer.json` files? Atmos can use them directl ```yaml # atmos.yaml -components: - devcontainer: - geodesic: - spec: !include .devcontainer/devcontainer.json +devcontainer: + geodesic: + spec: !include .devcontainer/devcontainer.json ``` Or include and override specific fields: ```yaml # atmos.yaml -components: - devcontainer: - geodesic: - spec: - - !include .devcontainer/devcontainer.json - - containerEnv: - ATMOS_BASE_PATH: "/workspace" - CUSTOM_VAR: "value" +devcontainer: + geodesic: + spec: + - !include .devcontainer/devcontainer.json + - containerEnv: + ATMOS_BASE_PATH: "/workspace" + CUSTOM_VAR: "value" ``` This is the **real Atmos `!include` function**—the same powerful YAML processing you use everywhere else in Atmos. It supports deep merging, overrides, and all the template functions you know. @@ -222,9 +222,8 @@ Make it even easier with shell aliases in your `atmos.yaml`: ```yaml # atmos.yaml -cli: - aliases: - shell: "devcontainer shell" +aliases: + shell: "devcontainer shell" ``` Now you can just type: @@ -237,9 +236,8 @@ atmos shell If you have a default devcontainer you always use, you can hardcode it: ```yaml -cli: - aliases: - shell: "devcontainer shell geodesic" +aliases: + shell: "devcontainer shell geodesic" ``` ## Additional Lifecycle Commands @@ -289,11 +287,10 @@ Works with both Docker and Podman, with automatic runtime detection. No vendor l ```yaml # Per-devcontainer runtime selection -components: - devcontainer: - geodesic: - settings: - runtime: docker # or podman, or omit for auto-detect +devcontainer: + geodesic: + settings: + runtime: docker # or podman, or omit for auto-detect ``` ### 6. Identity Injection @@ -333,16 +330,13 @@ Development containers are incredibly valuable across different domains: - No conflicts between different project requirements - Onboarding new team members in minutes instead of hours -### Data Engineering -- Jupyter notebooks with pre-installed libraries -- Data processing tools (Spark, Airflow, etc.) -- Database clients and connectors - Development containers are **equally valuable—if not more valuable—for DevOps** than traditional software development. Infrastructure teams juggle more tools, more versions, and more environmental complexity than most application developers. ## Comparison with Traditional Approaches -### Before: Manual Environment Setup + + + ```bash # Install Terraform brew install terraform @@ -367,27 +361,16 @@ brew install helmfile # Repeat when you switch projects... ``` -### After: Atmos Devcontainer + + + ```bash atmos devcontainer shell geodesic # Everything installed, versioned, ready to use ``` -### Comparison with Official devcontainer CLI - -| Feature | Official CLI | Atmos Native | -|---------|-------------|--------------| -| Installation | Separate tool | Built-in | -| Primary command | `devcontainer up` | `atmos devcontainer shell` | -| Multiple instances | No | Yes | -| Interactive selection | No | Yes | -| Shell autocomplete | Limited | Full support | -| Named configs | File-based only | Named in atmos.yaml | -| Identity injection | Manual | Coming soon | -| Rich TUI | Basic | Charm ecosystem | -| Runtime choice | Docker only | Docker or Podman | -| `!include` support | No | Yes (native Atmos) | -| Atmos integration | External | Native | + + ## Practical Subset of the Spec @@ -410,58 +393,6 @@ Atmos implements a **practical subset** of the [Development Containers specifica This approach keeps the implementation lean, maintainable, and focused on solving the actual problem: **reproducible development environments for infrastructure teams**. -## Real-World Workflows - -### Onboarding a New Team Member - -**Old way:** -1. Install Homebrew -2. Install Docker -3. Install Terraform (with tfenv or version manager) -4. Install kubectl -5. Install AWS CLI -6. Configure AWS credentials -7. Install Helm -8. Install Helmfile -9. Install jq, yq, and other tools -10. Debug version conflicts -11. Maybe productive by end of day? - -**New way:** -```bash -brew install atmos -cd team-infrastructure -atmos devcontainer shell -# Productive in 2 minutes -``` - -### Working on Multiple Projects - -**Old way:** -- Project A uses one set of tool versions -- Project B uses different tool versions -- Use version managers (tfenv, etc.) to switch constantly -- Hope you remember to switch before running commands - -**New way:** -```yaml -# project-a/atmos.yaml -components: - devcontainer: - toolbox: - spec: - image: "cloudposse/geodesic:4.3.0" # Pinned toolbox version - -# project-b/atmos.yaml -components: - devcontainer: - toolbox: - spec: - image: "cloudposse/geodesic:4.4.0" # Different toolbox version -``` - -Each project gets the right tool versions automatically. - ## Get Started Now ### 1. Upgrade Atmos @@ -473,31 +404,21 @@ brew upgrade atmos ### 2. Check Out the Examples -```bash -# Browse or clone the examples -https://github.com/cloudposse/atmos/tree/main/examples/devcontainer - -# Or try it locally -git clone https://github.com/cloudposse/atmos.git -cd atmos/examples/devcontainer -atmos devcontainer shell geodesic -``` + ### 3. Add to Your Project ```yaml # atmos.yaml -components: - devcontainer: - geodesic: - spec: - image: "cloudposse/geodesic:latest" - workspaceFolder: "/workspace" - workspaceMount: "type=bind,source=${PWD},target=/workspace" - -cli: - aliases: - shell: "devcontainer shell geodesic" +devcontainer: + geodesic: + spec: + image: "cloudposse/geodesic:latest" + workspaceFolder: "/workspace" + workspaceMount: "type=bind,source=${PWD},target=/workspace" + +aliases: + shell: "devcontainer shell geodesic" ``` ### 4. Launch Your Environment diff --git a/website/docs/cli/commands/devcontainer/devcontainer.mdx b/website/docs/cli/commands/devcontainer/devcontainer.mdx index 512de5b9c4..c452964c0b 100644 --- a/website/docs/cli/commands/devcontainer/devcontainer.mdx +++ b/website/docs/cli/commands/devcontainer/devcontainer.mdx @@ -171,20 +171,18 @@ Atmos supports both Docker and Podman as container runtimes: Devcontainers are configured in `atmos.yaml` under the `devcontainer` section: ```yaml -components: - devcontainer: - : # Choose any name for your devcontainer (e.g., geodesic, terraform, python) - settings: - runtime: podman # Optional: docker, podman, or omit for auto-detect - spec: !include devcontainer.json +devcontainer: + : # Choose any name for your devcontainer (e.g., geodesic, terraform, python) + settings: + runtime: podman # Optional: docker, podman, or omit for auto-detect + spec: !include devcontainer.json ``` **Example with `geodesic`:** ```yaml -components: - devcontainer: - geodesic: - spec: !include devcontainer.json +devcontainer: + geodesic: + spec: !include devcontainer.json ``` The `` is a user-defined identifier you choose for your devcontainer. Use it with commands like `atmos devcontainer start `.