[arnaud-dezandee]

Description

The Session Manager tunnel always used the AWS managed AWS-StartPortForwardingSession document because the name was hard-coded. Some organizations control which SSM documents can be used and when updates are adopted, so they need to point Packer at their own document.

This PR adds an ssm_document option to the amazon-ebs, amazon-ebssurrogate, amazon-ebsvolume and amazon-instance builders:

source "amazon-ebs" "image" {
  # ...
  communicator         = "ssh"
  ssh_interface        = "session_manager"
  ssh_username         = "someuser"
  iam_instance_profile = "SomeInstanceProfileName"

  ssm_document = "MyPortForwardingDocument"
}

Changes:

• New ssm_document field in RunConfig, in both common/ (SDK v2) and builder/common/ (SDK v1).
• StepCreateSSMTunnel and ssm.Session pass the document name to StartSession. If it's empty, they fall back to AWS-StartPortForwardingSession, so existing behavior doesn't change.
• Setting ssm_document without ssh_interface = "session_manager" returns a configuration error.
• As the issue asks, the custom document must accept the same portNumber / localPortNumber parameters as the AWS managed one. Custom parameters are out of scope (see System Manager Document Provisioner #417).
• Unit tests for config validation and for the StartSessionInput document name.
• Regenerated the HCL2 specs and docs, and documented the option in the Session Manager Connections section.

Testing: go build ./..., go vet, go test ./... and make plugin-check pass locally. I haven't run it end to end against AWS with a custom document yet; I'm happy to do that or help with it if maintainers want.

Resolved Issues

Closes #421

Rollback Plan

If a change needs to be reverted, we will roll out an update to the code within 7 days.

Changes to Security Controls

No. Users can choose which SSM document starts the tunnel, but the credentials still need ssm:StartSession permission on that document, so IAM controls are unchanged.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The focused change preserves default behavior, consistently wires the option through all four builders, and includes validation and selection tests with no identified blockers.

No open issues 🎉

4 files not reviewed

• builder/ebs/builder.hcl2spec.go: Generated file
• builder/ebssurrogate/builder.hcl2spec.go: Generated file
• builder/ebsvolume/builder.hcl2spec.go: Generated file
• builder/instance/builder.hcl2spec.go: Generated file

What changed in this PR

Adds custom Session Manager document selection to four Amazon builders, addressing #421 while preserving the existing AWS-managed default.

Changes:

• Passes ssm_document through configuration and tunnel creation in both AWS SDK implementations.
• Adds configuration validation and document-selection tests.
• Updates HCL2 schemas and documentation; custom parameters remain out of scope.

File	Description
docs-partials/​common/​RunConfig-not-required.mdx	Documents the SDK v2 option.
docs-partials/​builders/​aws-session-manager.mdx	Explains document compatibility and permissions.
docs-partials/​builder/​common/​RunConfig-not-required.mdx	Documents the SDK v1 option.
common/​step_create_ssm_tunnel.go	Forwards the document name.
common/​ssm/​session.go	Selects the custom or default document.
common/​ssm/​session_test.go	Tests document selection.
common/​run_config.go	Adds and validates the option.
common/​run_config_test.go	Tests configuration validation.
builder/​instance/​builder.hcl2spec.go	Exposes the HCL2 option.
builder/​instance/​builder.go	Passes configuration to the tunnel.
builder/​ebsvolume/​builder.hcl2spec.go	Exposes the HCL2 option.
builder/​ebsvolume/​builder.go	Passes configuration to the tunnel.
builder/​ebssurrogate/​builder.hcl2spec.go	Exposes the HCL2 option.
builder/​ebssurrogate/​builder.go	Passes configuration to the tunnel.
builder/​ebs/​builder.hcl2spec.go	Exposes the HCL2 option.
builder/​ebs/​builder.go	Passes configuration to the tunnel.
builder/​common/​step_create_ssm_tunnel.go	Forwards the document name.
builder/​common/​ssm/​session.go	Selects the custom or default document.
builder/​common/​ssm/​session_test.go	Tests document selection.
builder/​common/​run_config.go	Adds and validates the option.
builder/​common/​run_config_test.go	Tests configuration validation.
.web-docs/​components/​builder/​instance/​README.md	Updates instance builder documentation.
.web-docs/​components/​builder/​ebsvolume/​README.md	Updates volume builder documentation.
.web-docs/​components/​builder/​ebssurrogate/​README.md	Updates surrogate builder documentation.
.web-docs/​components/​builder/​ebs/​README.md	Updates EBS builder documentation.

_{Review effort: Balanced}

[taru-garg-2000]

Hi @arnaud-dezandee,

Thanks for the PR, it looks good to me, we should be good to merge it after testing it a bit 🚀

Cheers!

[hariom-hashicorp]

Hi @arnaud-dezandee

Thanks for this PR! I tested the PR end-to-end and confirmed the ssm_document feature works as expected.
CloudTrail verifies that default behavior uses AWS-StartPortForwardingSession, while custom config uses CustomPortForwardingDocument.
Validation, backward compatibility, and build results all look good from my testing.

I also noticed merge conflicts that may need to be resolved before merging:

• builder/common/run_config_test.go
• common/run_config_test.go

[arnaud-dezandee]

Hi @hariom-hashicorp, thank you for the quick review!
Fixed the merge conflicts