docs: add least-privilege deployment roles and deployment guide#46
Draft
scottschreckengaust wants to merge 14 commits intomainfrom
Draft
docs: add least-privilege deployment roles and deployment guide#46scottschreckengaust wants to merge 14 commits intomainfrom
scottschreckengaust wants to merge 14 commits intomainfrom
Conversation
scottschreckengaust
changed the base branch from
main
to
feat/fargate-agent-stack
Add DEPLOYMENT_ROLES.md with least-privilege IAM policy for the CloudFormation execution role (IaCRole-ABCA), derived from analysis of all CDK constructs and handler code in the current single-stack architecture. Includes optional ECS statements when Fargate is enabled. Add DEPLOYMENT_GUIDE.md covering compute backend choices (AgentCore vs opt-in ECS Fargate via ComputeStrategy), scale-to-zero analysis, and complete AWS services inventory. Update COST_MODEL.md with scale-to-zero characteristics section, corrected baseline to ~$85-95/month, and updated references. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
scottschreckengaust
force-pushed
the
least-privilege-deployment-documentation
branch
from
f0c077f to
9babf85
Compare
scottschreckengaust
changed the base branch from
feat/fargate-agent-stack
to
main
Append new references at the bottom instead of reordering the existing list. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The original had COMPUTE.md listed twice intentionally — once for the network architecture section and once for compute billing. Restore this pattern instead of merging into one entry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Single entry with anchor link to the network architecture section instead of listing the same file twice. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Use AWS-native IAM Access Analyzer policy generation instead of third-party tooling for iterative policy tightening. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The sync-starlight.mjs script generates mirror files under docs/src/content/docs/ from source docs. These generated files were missing from prior commits, causing the CI mutation check to fail. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The PR#46 build failed because Starlight mirror files under docs/src/content/docs/ were not regenerated after editing source docs. The pre-commit hooks had no step to catch this locally. - Add `docs-sync` pre-commit hook that auto-runs sync-starlight.mjs and stages the generated mirrors when docs sources change - Strengthen AGENTS.md boundary and common-mistakes sections to explicitly warn that CI rejects stale mirrors and name the exact command to regenerate them Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ODEL - Session timeout: 8 hours → 9 hours (matches task-orchestrator.ts:173) - Concurrency limit: 2 → 3 (matches task-orchestrator.ts:163 default) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prevents local plugin state from the remember and MCP plugins from being tracked in version control. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…l notes On a fresh AWS account, `aws xray update-trace-segment-destination` fails with AccessDeniedException because X-Ray needs a CloudWatch Logs resource policy before it can write spans. Added the prerequisite `aws logs put-resource-policy` command to Quick Start Step 3. Also documented that `mise run build` requires AWS credentials with ec2:DescribeAvailabilityZones for CDK synthesis, and added common error table entries for the X-Ray, build credential, and non-TTY deploy issues. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ref to /deploy The /setup skill's Phase 3 only ran `aws xray update-trace-segment-destination` which fails with AccessDeniedException on fresh accounts. Added the prerequisite `aws logs put-resource-policy` command. Added a "Least-Privilege Deployment" section to the /deploy skill linking to DEPLOYMENT_ROLES.md with the re-bootstrap command for scoped execution policies. Updated CLAUDE.md to reference the abca-plugin and its available skills so Claude Code sessions discover the guided workflows without requiring --plugin-dir. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
scottschreckengaust
force-pushed
the
least-privilege-deployment-documentation
branch
from
903fa5f to
544cbf2
Compare
Replace the single monolithic IAM policy (which exceeded the 6,144-char IAM managed policy limit) with three validated policies: - IaCRole-ABCA-Infrastructure (CFN, IAM, VPC, DNS Firewall) - IaCRole-ABCA-Application (DDB, Lambda, APIGW, Cognito, WAF, EB, SM) - IaCRole-ABCA-Observability (Bedrock, CW, X-Ray, S3, ECR, KMS, SSM, STS) All three policies were validated against a live deployment in us-east-1 (create, update, task execution, and destroy). CloudTrail analysis found 36 additional actions beyond the initial code review, and 7 deployment iterations refined the policies. Key additions: - KMS (entirely missing from original) - lambda:InvokeFunction for AwsCustomResource - bedrock-agentcore:* (CFN handler uses internal action names) - Legacy CW Logs delivery actions for Route53 Resolver - Various Describe/List/Get actions for read-only CFN operations Updated the origin disclaimer, Resource-level permission constraints table, and ECS section to reference the Application policy. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Clarify in the ECS section that adding the ECS statement to IaCRole-ABCA-Application keeps the combined policy under the 6,144-character IAM managed policy limit (4,212 of 6,144 chars). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/design/DEPLOYMENT_ROLES.mdwith a least-privilege IAM policy for the CloudFormation execution role (IaCRole-ABCA), derived from analysis of all CDK constructs and handler code in the current single-stack architecture. Includes an optional ECS statement for when Fargate compute is enabled. Documents the trust policy, runtime role inventory, resource-level permission constraints, and iterative tightening recommendations.docs/guides/DEPLOYMENT_GUIDE.mdcovering the single-stack architecture withComputeStrategyinterface (AgentCore default, ECS Fargate opt-in), scale-to-zero analysis, and complete AWS services inventory by category.docs/design/COST_MODEL.mdwith a scale-to-zero characteristics section, corrected baseline to ~$85-95/month (matching the 7 VPC interface endpoints in the current codebase), and updated references.Context
No pre-existing IAM deployment role or operational deployment guide documentation existed. The IAM policy is a starting point -- it will be validated against a fresh AWS account deployment in
us-east-1and iteratively tightened using CloudTrail.Test plan
IaCRole-ABCApolicy against a freshmise run //cdk:deployinus-east-1🤖 Generated with Claude Code