Proton Diagnostics

AWS Proton Diagnostics

When to use

Any AWS Proton investigation where the console alone is insufficient — template management, environment provisioning, service deployment, pipeline troubleshooting, component management, template sync, Git integration, or IAM permission issues.

Investigation workflow

Step 1 — Collect and triage

aws proton list-environments --query 'environments[*].{Name:name,Status:deploymentStatus,Template:templateName}'
version: "1.0.0"
last_updated: "2025-04-12"
aws proton list-services --query 'services[*].{Name:name,Status:status,Template:templateName}'
version: "1.0.0"
last_updated: "2025-04-12"
aws proton list-environment-templates
aws proton list-service-templates
aws proton get-environment --name <env-name>
aws proton get-service --name <service-name>

Step 2 — Domain deep dive

aws proton get-environment --name <env-name> --query '{Status:deploymentStatus,StatusMessage:deploymentStatusMessage}'
aws proton list-environment-template-versions --template-name <template-name>
aws proton list-service-template-versions --template-name <template-name>
aws proton get-service-instance --name <instance-name> --service-name <service-name>
aws proton list-service-pipeline-outputs --service-name <service-name>

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=proton.amazonaws.com --max-results 20
aws proton list-environment-outputs --environment-name <env-name>
aws proton get-template-sync-status --template-name <template-name> --template-type ENVIRONMENT
aws codestar-connections list-connections
aws codepipeline get-pipeline-state --name <pipeline-name>

Read references/guardrails.md before concluding on any AWS Proton issue.

Tool quick reference

Gotchas: AWS Proton

• Proton uses templates to define infrastructure — environment templates define shared resources, service templates define per-service resources. Templates are versioned and must be published before use.
• Template versions must be in PUBLISHED status to be used — DRAFT versions cannot be deployed. Registration and publishing are separate steps.
• Environment provisioning uses CloudFormation or Terraform — the provisioning engine is determined by the template. CloudFormation is AWS-managed; Terraform requires self-managed provisioning.
• Service pipelines are optional — not all service templates include pipelines. Pipeline configuration is part of the service template.
• Components are customer-managed infrastructure attached to services — they allow extending service instances without modifying templates.
• Template sync connects templates to Git repositories — changes pushed to the repo automatically create new template versions. Requires CodeStar connection.
• Proton IAM roles: service role (for Proton operations), pipeline role (for CI/CD), and component role (for component provisioning) are separate.
• Environment outputs are passed to service templates as inputs — if environment outputs change, dependent services may need redeployment.
• Self-managed provisioning (Terraform) requires external provisioning infrastructure — Proton sends provisioning requests but doesn't execute Terraform directly.
• Template bundles must follow the Proton schema format — incorrect schema, missing manifests, or invalid Jinja/HCL templates cause registration failures.
• Drift detection identifies differences between desired and actual state — but does not auto-remediate. Manual intervention is required.
• CodeStar connections must be in AVAILABLE status — PENDING connections require manual authorization in the console.

Anti-hallucination rules

1. Always cite specific template versions, deployment statuses, or API responses as evidence. Never guess at Proton configurations.
2. Proton does NOT execute Terraform directly for self-managed provisioning. Never suggest Proton runs terraform apply.
3. Template versions must be PUBLISHED before deployment. Never suggest deploying DRAFT versions.
4. CodeStar connections require manual authorization. Never suggest they auto-activate.
5. Components are customer-managed, not Proton-managed. Never suggest Proton auto-provisions components.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

20 runbooks