IParameter.grantRead() omits ssm:GetParametersByPath (silent failure for confd-style readers)

[so0k]

IParameter.grantRead() grants four actions (src/aws/storage/parameter.ts:256):

ssm:DescribeParameters
ssm:GetParameters
ssm:GetParameter
ssm:GetParameterHistory

This matches aws-cdk exactly, so this is a parity issue rather than a regression — but it cost me a full e2e cycle to find, and the failure mode is bad enough that it seems worth raising.

What happened

An L3 writes config to Parameter Store for a confd daemon baked into an AMI. confd reads with GetParametersByPath. Granting with parameter.grantRead(instance) produced:

AccessDeniedException: User: arn:aws:sts::…:assumed-role/…/i-0da8ca22b804061ad is not
authorized to perform: ssm:GetParametersByPath on resource:
arn:aws:ssm:us-east-1:…:parameter/e2e-cobvrl/atlantis-yaml/contents
because no identity-based policy allows the ssm:GetParametersByPath action

The instance booted, passed health checks, and registered with SSM Session Manager. But no config file was ever rendered, so the app exited on a missing config, the reverse proxy never started, and git-sync never cloned. Nothing surfaced as an error at the infrastructure layer — terraform apply reported success and every resource existed. The only symptom was a service that would not start, and the cause was four levels away in an IAM policy.

Notably the parameters I granted by hand-written PolicyStatement (with GetParameters + GetParametersByPath, mirroring the Terraform module being ported) worked fine in the same boot. Only the ones using grantRead() failed, which made it look like a Parameter Store problem rather than an IAM one.

Why this is not simply "add it to grantRead"

GetParametersByPath authorizes against the ARN of the path being queried, not the individual parameters returned. So a per-parameter grant is only meaningful when the caller queries that exact path — which is my case (confd queries each key's full path), but would not be for a caller doing a genuine recursive walk of /prefix. Silently widening grantRead() would grant something whose semantics don't quite match the resource it's attached to.

So this may be better as an explicit, separately-named capability than as a change to grantRead.

Options

1. Add GetParametersByPath to grantRead() — simplest, diverges from aws-cdk, and slightly overloads the ARN semantics above.
2. Add a dedicated method, e.g. grantGetByPath(grantee) on IParameter, and/or a hierarchy-level helper that grants on a path prefix ARN (…:parameter/prefix + /prefix/*). This models the action correctly and keeps grantRead at CDK parity.
3. Leave the behaviour and document it on grantRead() — cheap, and would have saved me the debugging round.

I'd lean toward (2) plus (3), but happy to be told otherwise.

Current workaround

role.addToPrincipalPolicy(new aws.iam.PolicyStatement({
  actions: ["ssm:GetParametersByPath"],
  resources: parameters.map((p) => p.parameterArn),
}));

Observed on terraconstructs@0.2.12.

[so0k]

Verified the aws-cdk parity claim against source rather than memory — checked out tree at v2.261.0 (commit f3c62b67e560b749f74d34eb975aac3b84007436).

**packages/aws-cdk-lib/aws-ssm/lib/parameter.ts:202-216**, in the abstract ParameterBase` that every concrete and imported parameter class extends:

public grantRead(grantee: iam.IGrantable): iam.Grant {
  if (this.encryptionKey) {
    this.encryptionKey.grantDecrypt(grantee);
  }
  return iam.Grant.addToPrincipal({
    grantee,
    actions: [
      'ssm:DescribeParameters',
      'ssm:GetParameters',
      'ssm:GetParameter',
      'ssm:GetParameterHistory',
    ],
    resourceArns: [this.parameterArn],
  });
}

So TerraConstructs matches upstream exactly, including resourceArns: [this.parameterArn] — a single exact parameter ARN, never a hierarchy-scoped one with a trailing /*.

Three further findings that bear on which option to pick:

1. ssm:GetParametersByPath appears nowhere in aws-cdk's aws-ssm module. A repo-wide grep finds it only in an AwsCustomResource integ test's hand-written policy and in SDK mocks for CDK's internal cross-region SSM reader Lambda — never emitted by any grant helper.
2. There is no hierarchy/path-prefix grant anywhere in aws-cdk-lib. No grantReadByPath, no parameter-path construct; searches for ByPath, hierarchy, ParameterPath in the module return nothing, and the module README only documents param.grantRead(role) on a single parameter.
3. There is no comment, TODO or docstring explaining the omission. The only documentation is the factual interface doc (Grants read (DescribeParameter, GetParameters, GetParameter, GetParameterHistory) permissions...). Nothing states a rationale.

Point 3 is the one I'd weight: the omission reads as never-implemented rather than deliberately excluded, so "we match CDK" is a weaker argument for keeping it than it first appears. That said, the ARN-semantics concern in the issue body stands on its own merits regardless of what upstream does, so I still lean toward a separately-named method over widening grantRead.