Repository navigation
Add claude-3p-on-bedrock use case: Claude Code and Cowork on Bedrock via the Claude apps gateway - #117
Conversation
…via the Claude apps gateway Deploys Anthropic's Claude apps gateway on ECS Fargate (ARM64) in the platform VPC, so Claude Code and Claude Desktop/Cowork use Amazon Bedrock in the customer's account. - Entra ID sign-in (direct OIDC); models per team via Entra App Roles, enforced on the server - Internal ALB only; customer DNS (CNAME) by default, Route 53 optional - gateway.yaml rendered into the task definition and written by an init container, so config changes need no image rebuild; the image is built from the pinned release after GPG and sha256 verification - Setup wizard (setup.py), verify.py, example platform.yaml, docs (README, docs/walkthrough.md, docs/changes.md) and tests
…o proxy
Optional agentcore_tools block: the Claude apps gateway delivers the
platform's AgentCore Gateway (web search and other targets) to Claude Code
(cli) and Cowork (desktop) as an MCP server named agentcore, for everyone
or listed teams. People sign in with Entra ID directly; the platform runs
identity.mode: direct, so there is no Cognito and no OAuth proxy.
- Gateway URL from the platform's SSM parameter at deploy time, expanded
by the gateway at boot (${AGENTCORE_GATEWAY_URL})
- verify.py checks the AgentCore Gateway's 401 and protected-resource
metadata (Entra issuer, resource = gateway URL)
- Wizard step 7 and checks; desktop_settings pass-through for Desktop
managed settings
- Docs: Entra registration for the AgentCore Gateway, changes guide,
README foundation and limitations; example platform.yaml
YAML reads an unquoted `on` as the boolean true. gateway.web_search takes the strings auto|on|off, so the example failed validation on platforms that do not coerce the boolean.
|
@Robobc ready for your review when you have a moment. The workflows from my fork probably need an Approve and run from you to start CI. Thanks! |
There was a problem hiding this comment.
Thanks @alepas, this is a substantial and careful contribution. The use case follows the repo's use-case contract (manifest.yaml with requires: [networking] and a uc- stack, build(app, ctx, config) in stack.py, a verify.py, README + walkthrough, and contract fixtures), and it comes with about 1,100 lines of tests. The infrastructure is private by default: internal ALB with TLS 1.3, ingress only from client_cidrs, tasks reachable only from the ALB, Postgres only from the tasks with rds.force_ssl, Bedrock IAM scoped to the catalog's inference-profile and foundation-model ARNs, and secrets passed by name through Secrets Manager. The Claude release is verified with GPG and sha256 before the image is built.
The points below are mostly about the setup wizard: on a re-run it can drop access policies the operator set by hand. There is also one governance gap to discuss: this use case's Bedrock role sits outside the platform's guardrailed-only and model allow-list controls. Two findings come from a manual read-only check and are labelled "not from the reviewer agent".
CI: the PR's workflows (Python Code Quality, ASH, Control Library, Docs, Contract Parity, Shell, Secret Boundary) are waiting for maintainer approval to run, because the PR comes from a fork. When they run, Secret Boundary is expected to be red because of the repo's aws-cdk CLI pin, not because of this PR. #119 fixes that.
Verdict: changes needed
Automated review by the software factory (us.openai.gpt-6-astra+us.openai.gpt-6.1-sol). It reads the diff only and never runs PR code.
| # 8 ───────────────────────────────────────────────────────────────────── | ||
| def step_write(self) -> None: | ||
| header("8. Write platform.yaml") | ||
| cfg = {"claude_version": self._claude_version(), **self.cfg} |
There was a problem hiding this comment.
major: Preserve existing security policies when rerunning the wizard
The wizard replaces the entire use-case block but preserves only an allowlist of advanced keys. step_entra reconstructs oidc without existing allowed_roles, groups_claim, or extra_auth_params, while step_teams discards settings, desktop_settings, and start_model from each team and the default policy. Rerunning setup for an unrelated change can therefore remove sign-in restrictions and managed tool-denial policies. Printing the replacement block and saving a backup does not clearly identify these security-policy removals. Preserve fields the wizard does not edit and explicitly confirm any policy deletions.
| ) | ||
| default = { | ||
| "models": self.ui.ask_list( | ||
| " models ([] = none)", pd.get("models") or ids[-1:], models_ok |
There was a problem hiding this comment.
major: Do not replace an explicitly empty default model policy
For an existing default policy with models: [], pd.get("models") or ids[-1:] substitutes the last catalog model. Accepting the wizard's defaults then grants model access to signed-in users who match no team, despite the previous explicit deny-all policy. The advertised input [] does not work either: ask_list turns it into the model ID "[]", which models_ok rejects. Distinguish an absent models key from an empty list, and support an explicit empty-list answer without falling back to a model.
| assumed_by=iam.ServicePrincipal("ecs-tasks.amazonaws.com"), | ||
| description="Claude apps gateway: Bedrock invoke on the configured models only", | ||
| ) | ||
| task_role.add_to_policy( |
There was a problem hiding this comment.
major: (not from the reviewer agent) Bedrock role sits outside the platform's guardrailed-only and allow-list controls
The platform presents "model allow-list and guardrailed-only inference enforced by IAM" (docs/home.md, docs/SECURITY_CONTROLS.md item 6b). Those controls apply to the runtime roles in stacks/runtime_stack.py: the allowed_models resources, plus the Null deny on bedrock:GuardrailIdentifier when require_guardrails is on. This task role gets InvokeModel/InvokeModelWithResponseStream on its own models catalog, and guardrail is optional. A deployment with require_guardrails: true and an allow-list would still let Claude Code/Cowork call any model in this catalog without a guardrail. The use-case context (app.py _uc_ctx) does not pass those settings, so this is partly a platform gap. Two possible fixes: have the config validator require guardrail and restrict models to the platform's allow-list when the platform turns them on. Or, at minimum, state in the README's Known limitations and in SECURITY_CONTROLS.md that this use case is outside control 6b.
| def ask_list( | ||
| self, prompt: str, default: list[str] | None = None, validate=None | ||
| ) -> list[str]: | ||
| raw = self.ask(prompt, ", ".join(default or []) or None, None) |
There was a problem hiding this comment.
minor: Allow empty optional lists during non-interactive replay
ask_list converts both an explicitly supplied empty list and an absent default into None. UI.ask treats None as a missing answer in non-interactive mode and exits. Consequently, a valid answers file containing a team with deny_tools: [] cannot be replayed: setup fails at the optional denied-tools prompt even though the empty list is a complete answer. Preserve explicit empty defaults as an empty string and let each caller's validator decide whether an empty list is permitted.
| dns: DnsConfig = Field(default_factory=DnsConfig) | ||
| # Networks developers connect FROM (VPN client pool, corporate ranges). | ||
| # The ALB admits only these on 443. Not the VPC CIDR. | ||
| client_cidrs: list[str] = Field(min_length=1) |
There was a problem hiding this comment.
minor: (not from the reviewer agent) client_cidrs accepts 0.0.0.0/0
The validator checks that each entry is IPv4, but accepts 0.0.0.0/0 or other very broad prefixes. The ALB is internal, so this is not internet exposure. It would still open the gateway to every network routed into the VPC (VPN, peered VPCs, Transit Gateway), which is broader than the "developer networks only" the security-group description promises. Consider rejecting /0, or prefixes broader than a threshold you choose, with a clear error.
…ient ranges) - Wizard re-run keeps what it does not ask about: oidc allowed_roles, groups_claim and extra_auth_params; team and default settings, desktop_settings and start_model; and every top-level key it does not own (desktop, policy_mode, spend_admin_roles, ...). Dropping an existing team now needs an explicit confirmation. - An explicit `models: []` default policy stays deny-all instead of being replaced by the last catalog model; "none" is accepted as an answer. - ask_list keeps an explicit empty default as an answer, so an answers file with `deny_tools: []` replays non-interactively. - client_cidrs refuses ranges wider than /8 (0.0.0.0/0 admitted every network routed into the VPC), in the schema and in the wizard. - Document that the use case's Bedrock role is outside the platform's allow-list and guardrailed-only controls (6b): README known limitations and SECURITY_CONTROLS.md.
|
Thanks for the review. Addressed in 0ab6232:
Each has tests (656 pass locally; ruff, contract and docs checks clean). |
There was a problem hiding this comment.
The PR adds a Claude Code/Cowork-on-Bedrock use case with Entra sign-in, per-team model policies, optional AgentCore tools, setup documentation, and configuration and deployment tests. The supplied excerpts cover documentation and tests rather than the stack and gateway implementation, so they do not establish the correctness or security of the deployed resources. No high-confidence actionable problems were identified in the provided excerpts.
Verdict: changes needed
Automated review by the software factory (us.openai.gpt-6.1-sol). It reads the diff only and never runs PR code.
| return ( | ||
| "".join(lines) | ||
| + ("\n" if lines and lines[-1].strip() else "") | ||
| + "use_cases:\n" |
There was a problem hiding this comment.
major: Appending a duplicate use_cases key discards flow-style configurations
The section matcher only recognizes block-style use_cases: or an empty {}. A valid existing manifest such as use_cases: {release-notes: {}} therefore takes this branch and gets a second top-level use_cases key. PyYAML keeps the last occurrence, so the subsequent check silently loses the existing use cases, changing the deployment contract despite the helper's promise to preserve them.
| ) | ||
| new = ( | ||
| set_nested_scalar( | ||
| new, "agents", "model_id", pick, "available in this Region" |
There was a problem hiding this comment.
minor: Regional model replacement leaves the model allow-list inconsistent
When the configured platform model is unavailable in the selected Region, the wizard replaces only agents.model_id. Existing manifests with agents.allowed_models—including the documented pinned-model configurations—still allow only the previous profile. Selecting an available regional profile consequently leaves the new model outside the allow-list, so platform validation or inference permissions fail rather than producing deployable platform settings.
… allow-list
- upsert_use_case_block no longer appends a second `use_cases:` key when the
existing one is flow style with content (`use_cases: {release-notes: {}}`,
also multi-line): it converts the section to block style and keeps every
other use case. A form it can't edit (not a mapping) is refused instead of
rewritten. `null` and `~` are treated as empty.
- When the wizard swaps the platform sample agent's model for the Region, it
also replaces that entry in agents.allowed_models (the platform requires
agents.model_id to be in it), after asking. Declining stops with
platform.yaml unchanged.
|
Second round addressed in 1b8ecb4. The five earlier findings were fixed in 0ab6232 (the new review shows them again on that commit).
Tests added for both (667 pass locally; ruff, contract, docs and gitleaks clean). |
There was a problem hiding this comment.
The PR adds a Claude Code and Cowork use case backed by an ECS-hosted Claude apps gateway, with Entra sign-in, team model policies, optional AgentCore tools, setup guidance, and tests. The supplied excerpts cover documentation and tests rather than the deployment implementation, limiting assessment of runtime security and correctness. The quick-start deployment instructions have a first-deploy dependency problem when using the supplied example configuration.
Verdict: changes needed
Automated review by the software factory (us.openai.gpt-6.1-sol). It reads the diff only and never runs PR code.
| insert_at -= 1 | ||
| return "".join(lines[:insert_at] + [block] + lines[insert_at:]) | ||
| stop = start + 1 | ||
| while stop < end and (not lines[stop].strip() or lines[stop].startswith(" ")): |
There was a problem hiding this comment.
major: Use-case replacement can leave stale policy fields in platform.yaml
The replacement stops at any line that is not indented by four spaces, including a two-space comment inside the use-case block. YAML ignores comment indentation, so a valid block can contain such a comment followed by more four-space fields. Those trailing fields survive the replacement and become part of the newly rendered block; duplicate keys such as teams or default can then silently override the wizard's new policy when loaded with yaml.safe_load. The same editing routine assumes use-case keys have exactly two spaces, so valid manifests using other indentation can also be corrupted.
| ```bash | ||
| ./scripts/deploy.sh design | ||
| ./scripts/deploy.sh doctor | ||
| NON_INTERACTIVE=1 ./scripts/deploy.sh deploy --stack "agentcore-workshop-dev-networking agentcore-workshop-dev-uc-claude-3p-on-bedrock" |
There was a problem hiding this comment.
minor: Quick-start deployment omits the gateway required by the example
The preceding manual configuration path tells readers to copy docs/platform.example.yaml, which enables agentcore_tools. That option resolves ///gateway/url from SSM at deployment time, but this command deploys only networking and the use-case stack. On a fresh account the platform gateway has not published that parameter, so following the documented quick start fails instead of creating the use case.
… gateway ordering - The wizard now finds the old use-case block through the YAML parser's source positions instead of counting spaces, so a two-space comment inside the block or a different indentation can no longer leave stale fields (duplicate teams/default keys) behind, and the new block follows the file's indentation. - agentcore_tools makes the use-case stack depend on the platform's gateway stack, because the task resolves <ssm_prefix>/gateway/url at deploy time. A deployment without that stack now fails at synth with a clear message. - README quick start: deploy auth and gateway too when agentcore_tools is on.
|
Third round addressed in 0ca7850.
674 tests pass locally; ruff, contract, docs and gitleaks clean. |
There was a problem hiding this comment.
The PR adds a Claude Code and Cowork use case backed by Bedrock, with Entra sign-in, per-team model policies, optional AgentCore tools, setup documentation, and regression tests. The deployment and authentication changes warrant careful review, but the supplied excerpts primarily cover documentation and tests rather than the implementing stack and handlers. No high-confidence defects are demonstrated in these excerpts.
Verdict: changes needed
Automated review by the software factory (us.openai.gpt-6.1-sol). It reads the diff only and never runs PR code.
| class ServiceConfig(_Strict): | ||
| desired_count: int = Field(default=2, ge=1, le=20) | ||
| cpu: Literal[256, 512, 1024, 2048, 4096] = 512 | ||
| memory_mib: int = Field(default=1024, ge=512, le=30720) |
There was a problem hiding this comment.
major: Validate Fargate memory against the selected CPU
The schema validates CPU and memory independently, allowing unsupported Fargate task sizes. For example, cpu: 256 with memory_mib: 4096 passes validation, but Fargate supports only 512, 1024, or 2048 MiB at that CPU size. Such a configuration passes the design checks and subsequently fails task-definition registration during deployment.
| ids = [model_id_from_profile(p) for p in picked] | ||
| if picked and len(ids) == len(set(ids)): | ||
| break | ||
| print( |
There was a problem hiding this comment.
minor: Stop instead of retrying invalid model selections in non-interactive mode
When an answers file selects two geographic profiles for the same model (for example, eu. and global. profiles), the generated model IDs collide and this branch retries. With --non-interactive, UI.ask returns the same default selection on every iteration, so the wizard loops forever and continuously prints warnings. Unlike the other validated prompts, this validation never exits on invalid non-interactive input.
…ooping on replay - service.cpu and service.memory_mib are validated together against the memory sizes Fargate offers for each cpu. A pair such as 256 / 4096 passed `design` and then failed when the task definition was registered. - The wizard's model catalog step uses the prompt's own validation, so an answers file that picks two profiles of the same model (eu. and global.) stops with a message under --non-interactive instead of repeating forever. Numbers outside the list are refused too: 0 selected the last profile.
|
Fourth round addressed in c3f2377.
703 tests pass locally; ruff, contract, docs and gitleaks clean. |
There was a problem hiding this comment.
The PR adds a Claude Code and Cowork on Bedrock use case, with Entra sign-in, per-team policies, optional AgentCore Gateway tools, setup documentation, and regression tests. No high-confidence problems were identified in the supplied excerpts; however, the deployment stack and runtime implementation were not included, so their IAM, networking, and runtime behavior could not be assessed directly.
Verdict: approve-worthy
Automated review by the software factory (us.openai.gpt-6.1-sol). It reads the diff only and never runs PR code.
|
Commit: Security Scan Results |
What
New use case
claude-3p-on-bedrock. It deploys Anthropic's Claude apps gateway onECS Fargate (ARM64) in the platform VPC, so Claude Code and Claude Desktop/Cowork
use Amazon Bedrock in the customer's account.
enforced on the server
the image is rebuilt only when claude_version changes, after GPG and sha256 checks
(README with known limitations, docs/walkthrough.md, docs/changes.md)
agentcore_tools): Claude Code and Cowork getthe platform's AgentCore Gateway (web search and other targets) as an MCP server,
delivered per team by the Claude apps gateway. Sign-in is Entra ID directly:
no Cognito and no OAuth proxy Lambda. The platform runs identity.mode: direct.
teams[].desktop_settings/default.desktop_settings: pass-through for anyClaude Desktop managed setting
Verified live (eu-west-1, eu-central-1)
Entra sign-in without omitResource (gateway URL registered as an App ID URI),
web search via mcp__agentcore__web-search___WebSearch; ${AGENTCORE_GATEWAY_URL}
expands in both cli and desktop blocks; verify.py checks the AgentCore Gateway's
401 + protected-resource metadata (issuer and resource)
Checks
(README tooling prerequisites, covered by the repository README)
Not verified
Fixes found while testing
(renamed, validator added)
the JWT secret no longer has a fixed name
For the reviewer (Roberto)
from the use-case layout)
PLATFORM_INTERFACE.md
trusted_proxies be filled in automatically
requiresin manifest.yaml is static, sogatewayisn't listed: onlyagentcore_tools needs it. A missing gateway fails at deploy (SSM parameter
///gateway/url) and in verify.py with a clear message. A
config-dependent
requireswould make this explicitwizard check and verify.py enforce it
config file when bootstrapUrl is set, so delivery through the gateway is the
only working path