Ssm Distributor Diagnostics

AWS Systems Manager Distributor Diagnostics

When to use

Any SSM Distributor investigation — package creation, version management, installation failures, uninstallation errors, association execution, scheduling, cross-platform packages, custom packages, S3 storage, IAM permissions, or third-party package issues.

Investigation workflow

Step 1 — Collect and triage

aws ssm list-documents --document-filter-list key=DocumentType,value=Package --query 'DocumentIdentifiers[*].{Name:Name,Owner:Owner,PlatformTypes:PlatformTypes}'
aws ssm list-associations --query 'Associations[*].{AssociationId:AssociationId,Name:Name,Status:Overview.Status}'
aws ssm describe-instance-information --query 'InstanceInformationList[*].{InstanceId:InstanceId,PingStatus:PingStatus,AgentVersion:AgentVersion,PlatformType:PlatformType}'

Step 2 — Domain deep dive

aws ssm describe-document --name <package-name> --query '{Name:Name,Status:Status,DocumentVersion:DocumentVersion,PlatformTypes:PlatformTypes}'
aws ssm list-command-invocations --command-id <command-id> --details --query 'CommandInvocations[*].{InstanceId:InstanceId,Status:Status,StatusDetails:StatusDetails}'
aws ssm describe-association-executions --association-id <assoc-id> --query 'AssociationExecutions[*].{ExecutionId:ExecutionId,Status:Status,DetailedStatus:DetailedStatus}'

Step 3 — Detailed investigation

aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ssm.amazonaws.com --max-results 20
aws ssm get-command-invocation --command-id <command-id> --instance-id <instance-id> --query '{Status:Status,StandardOutputContent:StandardOutputContent,StandardErrorContent:StandardErrorContent}'
aws s3 ls s3://<bucket>/packages/<package-name>/ --recursive

Read references/guardrails.md before concluding on any SSM Distributor issue.

Tool quick reference

Gotchas: SSM Distributor

• Distributor packages are SSM Documents of type Package. They are NOT the same as regular SSM Documents (Command, Automation).
• Packages require platform-specific installers. A single package can contain installers for Windows, Linux, and macOS but each must be explicitly defined in the manifest.
• The SSM Agent must be running and have connectivity to SSM endpoints. Instances with stale PingStatus are NOT managed and cannot receive packages.
• Association-based installations run on a schedule. If the schedule is misconfigured, packages may install at unexpected times or not at all.
• Custom packages are stored in S3. The S3 bucket must be in the same region as the instances, and the SSM Agent needs s3:GetObject permission.
• Package versions are immutable once created. You cannot modify an existing version — you must create a new version.
• Third-party packages (e.g., AmazonCloudWatchAgent) are AWS-managed. You cannot modify them but can pin specific versions.

Anti-hallucination rules

1. Always cite specific package names, command IDs, association IDs, or API responses as evidence.
2. Distributor packages are SSM Documents of type Package — never confuse with Command or Automation documents.
3. Package installation requires a running SSM Agent with active PingStatus. Never assume connectivity.
4. Custom packages require S3 storage in the same region. Never suggest cross-region S3 access for packages.
5. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

12 runbooks