Skip to content

Commit fb252d2

Browse files
milldrgithub-actions[bot]
milldr
authored and
github-actions[bot]
committed
(github actions) generated latest snippets
1 parent 799e559 commit fb252d2

20 files changed

Lines changed: 1089 additions & 115 deletions

File tree

‎examples/snippets/.claude/skills/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Claude Skills
2+
3+
This directory contains skills that provide Claude with detailed guidance for specific tasks. Skills are automatically
4+
invoked based on their descriptions when relevant to your request.
5+
6+
## Available Skills
7+
8+
| Skill | Description |
9+
| ----------------------- | --------------------------------------------------------------------------------------- |
10+
| `developing-components` | Creating new Terraform components, modifying existing ones, setting up catalog defaults |
11+
| `atmos-auth` | Authenticating with AWS via Atmos, SSO login, troubleshooting permission errors |
12+
| `atmos-functions` | Wiring cross-component dependencies with `!terraform.state` or `!terraform.output` |
13+
| `debugging-atmos` | Troubleshooting Atmos errors, inspecting resolved configuration with `describe stacks` |
14+
| `account-map-migration` | Removing account-map dependencies, using static account mappings, bypass pattern |
15+
16+
## How Skills Work
17+
18+
Skills are **model-invoked** - Claude automatically decides when to use them based on:
19+
20+
1. The skill's `description` field in the YAML frontmatter
21+
2. The context of your request
22+
23+
You don't need to explicitly invoke skills. Just describe what you're trying to do and Claude will use the relevant
24+
skill if applicable.
25+
26+
## Skill Structure
27+
28+
Each skill is a directory containing a `SKILL.md` file:
29+
30+
```
31+
skills/
32+
├── skill-name/
33+
│ └── SKILL.md
34+
```
35+
36+
The `SKILL.md` file has YAML frontmatter with `name` and `description`, followed by detailed instructions in Markdown.
37+
38+
## Adding New Skills
39+
40+
1. Create a new directory under `.claude/skills/`
41+
2. Add a `SKILL.md` file with frontmatter:
42+
```yaml
43+
---
44+
name: skill-name
45+
description: >-
46+
Brief description of what this skill does and when to use it. Include trigger words that would indicate this skill
47+
is relevant.
48+
---
49+
```
50+
3. Add detailed instructions in Markdown
51+
4. Update `CLAUDE.md` to reference the new skill in the Skills table
52+
53+
## References
54+
55+
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)

‎examples/snippets/.claude/skills/account-map-migration/SKILL.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
name: account-map-migration
3+
description: >-
4+
Use when fixing legacy account-map component references or creating new components. Covers migration from dynamic
5+
account-map lookups to static account_map variable. Use when you see account-map remote-state references or need to
6+
set up provider configuration for a new component.
7+
---
8+
9+
# Account Map Migration
10+
11+
This repository has migrated away from the `account-map` component to use Atmos Auth for authentication. Instead of
12+
dynamically looking up account IDs via the account-map component's remote state, we use a static `account_map` variable
13+
defined in `stacks/orgs/acme/_defaults.yaml`.
14+
15+
## Why We Migrated
16+
17+
The legacy `account-map` component pattern required:
18+
19+
1. Deploying account-map component first (chicken-and-egg problem)
20+
2. Remote state lookups for every component that needed account IDs
21+
3. Complex `providers.tf` with remote-state module calls
22+
4. Cross-account state access permissions
23+
24+
The new pattern:
25+
26+
1. Static account map defined once in stack defaults
27+
2. No remote state dependencies for account lookups
28+
3. Simpler provider configuration
29+
4. Works with Atmos Auth for authentication
30+
31+
## Key Configuration
32+
33+
### Stack Defaults
34+
35+
The account map is defined in `stacks/orgs/acme/_defaults.yaml`:
36+
37+
```yaml
38+
vars:
39+
account_map_enabled: false
40+
account_map:
41+
full_account_map:
42+
acme-core-root: "111111111111"
43+
acme-core-audit: "222222222222"
44+
acme-core-auto: "333333333333"
45+
acme-plat-dev: "444444444444"
46+
acme-plat-staging: "555555555555"
47+
acme-plat-prod: "666666666666"
48+
# ... all accounts
49+
iam_role_arn_templates:
50+
terraform: "arn:aws:iam::%s:role/acme-core-gbl-auto-terraform"
51+
audit_account_account_name: "acme-core-audit"
52+
root_account_account_name: "acme-core-root"
53+
```
54+
55+
### Vendored providers.tf
56+
57+
Components use a vendored `providers.tf` from Atmos mixins that includes:
58+
59+
- `account_map_enabled` and `account_map` variables
60+
- Provider configuration that uses the static account map
61+
- Dummy `iam_roles` module for legacy compatibility
62+
63+
**Vendoring is configured in each component's `component.yaml`:**
64+
65+
```yaml
66+
# components/terraform/<component-name>/component.yaml
67+
apiVersion: atmos/v1
68+
kind: ComponentVendorConfig
69+
spec:
70+
source:
71+
uri: github.com/cloudposse-terraform-components/aws-<component>.git//src?ref={{ .Version }}
72+
version: v1.x.x
73+
included_paths:
74+
- "**/**"
75+
excluded_paths:
76+
- "providers.tf" # Exclude upstream providers.tf
77+
mixins:
78+
# Vendor the providers.tf with account-map support
79+
- uri: https://raw.githubusercontent.com/cloudposse-terraform-components/mixins/{{ .Version }}/src/mixins/provider-without-account-map.tf
80+
version: v0.3.0
81+
filename: providers.tf
82+
- uri: https://raw.githubusercontent.com/cloudposse-terraform-components/mixins/{{ .Version }}/src/mixins/account-verification.mixin.tf
83+
version: v0.3.0
84+
filename: account-verification.mixin.tf
85+
```
86+
87+
**Key points:**
88+
89+
- The upstream `providers.tf` is excluded via `excluded_paths`
90+
- The `provider-without-account-map.tf` mixin is vendored as `providers.tf`
91+
- This mixin includes the `account_map_enabled` and `account_map` variables
92+
93+
**To vendor (or re-vendor) the component:**
94+
95+
```bash
96+
atmos vendor pull -c <component-name>
97+
```
98+
99+
The vendored `providers.tf` handles all account map logic automatically. You don't need to manually add these variables
100+
to `variables.tf` - they're included in `providers.tf`.
101+
102+
## Migration Checklist
103+
104+
When migrating a component or creating a new one:
105+
106+
1. **Vendor providers.tf** - Run `atmos vendor pull -c <component-name>` to get the latest providers.tf with account map
107+
support
108+
2. **Update remote-state.tf** - If the component has a `remote-state.tf` that references account-map, update it to use
109+
the bypass pattern (see below)
110+
3. **Verify catalog** - Ensure `account_map_enabled: false` is set (inherited from `_defaults.yaml`)
111+
4. **Test** - Run `atmos terraform plan` to verify
112+
113+
### Bypass Pattern for remote-state.tf
114+
115+
If a component has a `remote-state.tf` with an account-map lookup, update it to use `bypass` and `defaults`:
116+
117+
```hcl
118+
module "account_map" {
119+
source = "cloudposse/stack-config/yaml//modules/remote-state"
120+
version = "1.8.0"
121+
122+
component = "account-map"
123+
tenant = var.account_map_enabled ? coalesce(var.account_map_tenant, module.this.tenant) : null
124+
environment = var.account_map_enabled ? var.account_map_environment : null
125+
stage = var.account_map_enabled ? var.account_map_stage : null
126+
127+
context = module.this.context
128+
129+
# When account_map is disabled, bypass remote state and use the static account_map variable
130+
bypass = !var.account_map_enabled
131+
defaults = var.account_map
132+
}
133+
```
134+
135+
**Key points:**
136+
137+
- `bypass = !var.account_map_enabled` - Skips remote state lookup when disabled
138+
- `defaults = var.account_map` - Uses the static account_map variable instead
139+
- `module.account_map.outputs` works the same regardless of bypass - returns `defaults` when bypassed
140+
141+
## Identifying Legacy References
142+
143+
Search for components still using the old pattern:
144+
145+
```bash
146+
# Find remote-state references to account-map
147+
grep -r "account-map" components/terraform/*/remote-state.tf
148+
149+
# Find components without account_map_enabled variable
150+
for dir in components/terraform/*/; do
151+
if ! grep -q "account_map_enabled" "$dir/variables.tf" 2>/dev/null; then
152+
echo "Missing: $dir"
153+
fi
154+
done
155+
```
156+
157+
## Reference Implementations
158+
159+
See these components for the current pattern:
160+
161+
- `components/terraform/vpc/` - Standard component with account_map
162+
- `components/terraform/ecr/` - Component with cross-account access
163+
164+
## New Components
165+
166+
When creating new components, the migrated pattern is automatic:
167+
168+
1. **Vendor providers.tf** - Run `atmos vendor pull -c <component-name>` to get providers.tf with account map support
169+
2. **Inherit stack defaults** - `account_map_enabled: false` is inherited from `_defaults.yaml`
170+
3. **Use Atmos functions** - Use `!terraform.state` for cross-component dependencies instead of remote-state.tf
171+
172+
See the `developing-components` skill for full component creation guidance.

‎examples/snippets/.claude/skills/atmos-auth/SKILL.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
name: atmos-auth
3+
description: >-
4+
Use when authenticating with AWS via Atmos. Covers ATMOS_PROFILE setup, SSO login, and how Atmos automatically assumes
5+
the correct identity per stack. Use for authentication setup, SSO login issues, and permission errors.
6+
---
7+
8+
# Atmos Auth
9+
10+
Atmos Auth handles AWS authentication automatically based on your profile and the target stack.
11+
12+
## Quick Start
13+
14+
```bash
15+
# Set your profile (required for all atmos commands)
16+
# Use your assigned profile: devops, developers, or managers
17+
export ATMOS_PROFILE=<your-profile>
18+
19+
# Authenticate via SSO provider (preferred - triggers browser SSO)
20+
atmos auth login --provider acme-sso
21+
22+
# Alternative: authenticate by specifying any identity (also triggers browser SSO)
23+
atmos auth login --identity core-auto/terraform
24+
25+
# Run commands - Atmos auto-selects the correct identity per stack
26+
atmos terraform plan vpc -s plat-use2-dev
27+
```
28+
29+
## How It Works
30+
31+
1. **Set your profile**: `export ATMOS_PROFILE=<profile-name>` (or prefix each command)
32+
2. **Authenticate when needed**: Atmos authenticates per-stack automatically. If credentials are expired, it will
33+
launch the IDP to sign in, or you can manually trigger SSO login.
34+
3. **Run commands**: Atmos automatically assumes the correct identity for each stack based on the stack name.
35+
36+
When you run `atmos terraform plan <component> -s <stack>`, Atmos:
37+
38+
1. Renders all stack config, then determines the default identity for the stack
39+
2. If there's a single default identity (e.g., `plat-dev/terraform`), it's selected automatically
40+
3. Looks up that identity name in your profile to get the actual credentials
41+
4. Assumes the configured Permission Set in the target account
42+
5. Runs the Terraform command with those credentials
43+
44+
## Identity Configuration
45+
46+
Each stack defines its default identity in its `_defaults.yaml` file:
47+
48+
```yaml
49+
# stacks/orgs/acme/plat/dev/_defaults.yaml
50+
auth:
51+
identities:
52+
plat-dev/terraform:
53+
default: true
54+
```
55+
56+
The identity name (`plat-dev/terraform`) is resolved by your profile to determine the actual AWS credentials to use.
57+
58+
## Profiles
59+
60+
Profiles are defined in `profiles/<profile-name>/atmos.yaml`. Each maps identities to Permission Sets:
61+
62+
| Profile | Core Accounts | Platform Dev/Sandbox | Platform Staging/Prod |
63+
| ------------ | -------------------- | -------------------- | --------------------- |
64+
| `devops` | TerraformApplyAccess | TerraformApplyAccess | TerraformApplyAccess |
65+
| `developers` | TerraformStateAccess | TerraformApplyAccess | TerraformPlanAccess |
66+
| `managers` | TerraformStateAccess | TerraformPlanAccess | TerraformPlanAccess |
67+
68+
**Permission Set capabilities:**
69+
70+
- `TerraformApplyAccess` - Full plan and apply
71+
- `TerraformPlanAccess` - Plan only (no apply)
72+
- `TerraformStateAccess` - Read state only (for cross-account references)
73+
74+
## Identity Naming Convention
75+
76+
Identities follow the pattern: `<tenant>-<stage>/terraform`
77+
78+
Examples:
79+
80+
- `plat-dev/terraform` - Platform dev account
81+
- `core-auto/terraform` - Core automation account
82+
- `plat-prod/terraform` - Platform production account
83+
84+
## Special Cases
85+
86+
**superadmin profile**: IAM user with MFA for breakglass access. Avoid unless SSO is unavailable.
87+
88+
**github-plan profile**: OIDC-based authentication for CI/CD plan operations. Uses planner roles with read-only access.
89+
90+
**github-apply profile**: OIDC-based authentication for CI/CD apply operations. Uses terraform roles with full access.
91+
Only used from main branch after PR merge.
92+
93+
## Troubleshooting
94+
95+
If authentication fails:
96+
97+
1. Verify `ATMOS_PROFILE` is set: `echo $ATMOS_PROFILE`
98+
2. Re-authenticate: `atmos auth login --provider acme-sso` (or `--identity core-auto/terraform`)
99+
3. Check you have the required Permission Set in AWS IAM Identity Center
100+
4. Verify the identity exists in `profiles/$ATMOS_PROFILE/atmos.yaml`
101+
102+
## Debugging Authentication Issues
103+
104+
For authentication-specific debugging:
105+
106+
```bash
107+
# Enable debug logging to see auth flow
108+
ATMOS_LOGS_LEVEL=debug atmos terraform plan <component> -s <stack>
109+
```
110+
111+
Look for:
112+
113+
- Identity resolution (`<tenant>-<stage>/terraform`)
114+
- SSO token retrieval
115+
- Role assumption errors
116+
117+
For general Atmos debugging (configuration, variables, stack resolution), see the `debugging-atmos` skill.

0 commit comments

Comments
 (0)