AWS Systems ManagerManagement Stable

AWS::SSM::Parameter

Creates a Systems Manager Parameter Store parameter — a named, versioned, optionally encrypted configuration value that other services and stacks can read at runtime rather than at deploy time.

Required properties 2 of 9

Ref returns Parameter name/acme/payments/database-host

Fn::GetAtt 2 attributes

Replacement risk 1 1 property force replacement

Minimal template

Every required property, nothing else

Resources:
  DatabaseHost:
    Type: AWS::SSM::Parameter
    Properties:
      Name: /acme/payments/database-host
      Type: String
      Value: payments-db.internal.acme.example

{
  "Resources": {
    "DatabaseHost": {
      "Type": "AWS::SSM::Parameter",
      "Properties": {
        "Name": "/acme/payments/database-host",
        "Type": "String",
        "Value": "payments-db.internal.acme.example"
      }
    }
  }
}

import { StringParameter } from 'aws-cdk-lib/aws-ssm';

new StringParameter(this, 'DatabaseHost', {
  parameterName: '/acme/payments/database-host',
  stringValue: 'payments-db.internal.acme.example',
});

from aws_cdk import aws_ssm as ssm

ssm.StringParameter(
    self,
    "DatabaseHost",
    parameter_name="/acme/payments/database-host",
    string_value="payments-db.internal.acme.example",
)

Omitting Name is legal and lets CloudFormation generate one, but a generated parameter name is unreadable and cannot be referenced from outside the stack. Name your parameters.

Overview #

A Parameter Store parameter is the cheapest way to publish a value that other things read at runtime. It is not a secret store, not a configuration management system, and not a database — it is a named, versioned string with an IAM policy on it, and most of its value comes from being exactly that little.

The distinction that matters when writing templates is when the value is read. A stack parameter is resolved at deploy time and baked into the resources it configures. A Parameter Store parameter is resolved whenever the reader chooses to read it, which may be every request. Changing a stack parameter needs a deployment; changing a Parameter Store value does not.

Remarks

Parameter Store sits in an awkward spot between three other services, and choosing wrongly is the most common mistake around it.

Against Secrets Manager: Parameter Store has no rotation, no cross-region replication, and no built-in integration with RDS or Redshift. It is also free at the Standard tier where Secrets Manager is billed per secret per month. Use Secrets Manager for anything that should rotate; use Parameter Store for everything else.

Against AppConfig: Parameter Store has no validation, no deployment strategy, and no rollback. A bad value takes effect immediately and everywhere. AppConfig exists precisely to make configuration changes gradual and reversible.

Against a stack output plus Fn::ImportValue: exported outputs are locked — you cannot change an export while another stack imports it, which turns a one-line change into a three-deployment dance. Parameter Store has no such coupling, at the cost of losing the dependency tracking that made the lock useful.

Reading a parameter from a template #

Three mechanisms, with different resolution times and different failure modes.

# Resolved once, at deploy time. CloudFormation validates that the parameter
# exists before the stack starts, so a typo fails immediately and cleanly.
Parameters:
  DatabaseHost:
    Type: AWS::SSM::Parameter::Value<String>
    Default: /acme/payments/database-host

Resources:
  Service:
    Type: AWS::ECS::TaskDefinition
    Properties:
      ContainerDefinitions:
        - Name: api
          Environment:
            - Name: DB_HOST
              Value: !Ref DatabaseHost   # the value, not the parameter name

# Resolved at deploy time, inline, with no template parameter needed.
# Supports a version pin; without one you get the latest value.
Resources:
  Service:
    Type: AWS::ECS::TaskDefinition
    Properties:
      ContainerDefinitions:
        - Name: api
          Environment:
            - Name: DB_HOST
              Value: '{{resolve:ssm:/acme/payments/database-host:4}}'

// Resolved by the application, every time it chooses to. The only option
// where changing the parameter takes effect without a deployment.
import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm';

const ssm = new SSMClient({});
const { Parameter } = await ssm.send(
  new GetParameterCommand({ Name: '/acme/payments/database-host' }),
);

Hierarchies #

Parameter names are paths, and the path is the access-control boundary.

/acme/payments/production/database-host → ssm:GetParametersByPath on /acme/payments/productionone policy statement covers the whole environment

A convention that works: /{org}/{system}/{environment}/{key}. It makes GetParametersByPath return exactly one environment’s configuration, and it makes an IAM policy per environment a single resource ARN with a wildcard suffix.

Properties

Expand a row for the full reference; nested types open in place

Type StringThe parameter's value type, which fixes how the value is stored and returned. Required No interruption — updates in place
String stores a single value. StringList stores a comma-separated list that Systems Manager splits on read. SecureString stores a value encrypted with a KMS key.
Type
String
Required
Yes
Update behaviour
No interruption
Allowed values
- String
- StringList
- SecureString
Example values
- String
CloudFormation cannot create SecureString parameters
SecureString is a valid value for the underlying API but not for CloudFormation. A stack that specifies it fails at create time, because the plaintext would have to pass through the template.
Create secure parameters out of band and reference them with a dynamic reference ({{resolve:ssm-secure:/name:version}}), or store the secret in Secrets Manager instead.
Value StringThe parameter value. Changing it creates a new version rather than mutating the old one. Required No interruption — updates in place
For StringList, supply a comma-separated string — readers receive it split into a list. Commas cannot be escaped, so a list member containing a comma is not representable.
Type
String
Required
Yes
Update behaviour
No interruption
Length
1 – 4096
Example values
- payments-db.internal.acme.example
Remarks
Parameter Store is versioned. Every update creates a new version and the previous ones remain readable by explicit version reference (/name:3). Standard-tier parameters keep the 100 most recent versions; older ones are pruned automatically, which means a long-lived parameter under frequent CloudFormation churn will eventually lose its early history.
AllowedPattern StringRegular expression that Systems Manager enforces against the value on write. No interruption — updates in place
Validation happens in Systems Manager, not in CloudFormation. A value that fails the pattern surfaces as a ParameterPatternMismatchException in the stack event rather than as a template validation error.
Type
String
Required
No
Update behaviour
No interruption
Length
0 – 1024
Example values
- ^\d+$
DataType StringTells Systems Manager to validate the value as a particular kind of identifier. No interruption — updates in place
aws:ec2:image makes Systems Manager check that the value is a real, accessible AMI ID before accepting the write, and re-check it periodically. It is the difference between finding out about a deregistered AMI at parameter-write time and finding out during an Auto Scaling event.
Type
String
Required
No
Update behaviour
No interruption
Default
text
Allowed values
- text
- aws:ec2:image
- aws:ssm:integration
Description StringFree-text description shown in the console and returned by DescribeParameters. No interruption — updates in place
Free-text description shown in the console and returned by DescribeParameters.
Type
String
Required
No
Update behaviour
No interruption
Length
0 – 1024
Name StringThe fully qualified parameter name, including its hierarchy path. Replacement — CloudFormation creates a new resource and deletes the old one Create-only
Leading / puts the parameter in a hierarchy, which is what makes GetParametersByPath and path-scoped IAM policies work. A name without a leading slash is a flat top-level parameter and cannot be retrieved by path.
Type
String
Required
No
Update behaviour
Replacement
Pattern
^[a-zA-Z0-9_.\-/]+$ Letters, digits, underscore, period, hyphen and forward slash.
Length
1 – 2048
Example values
- /acme/payments/database-host
Important
Renaming a parameter replaces it: CloudFormation creates the new name, then deletes the old one. Anything reading the old name at runtime — a Lambda function, an agent, another account — breaks at the delete step, not at the create step, so the failure surfaces after the stack reports success.
aws reserved prefixes
Names beginning with aws or ssm (case-insensitive) are reserved. The API rejects them with a validation error that names neither prefix, so the cause is not obvious from the stack event.
Policies StringA JSON array of parameter policies — expiration, expiration notification, and no-change notification. No interruption — updates in place
Supplied as a JSON string, not as a template object, so it must be escaped or written with a block scalar in YAML. Requires the Advanced tier; supplying policies on a Standard parameter fails the stack.
Type
String
Required
No
Update behaviour
No interruption
Example values
- [{"Type":"Expiration","Version":"1.0","Attributes":{"Timestamp":"2027-01-01T00:00:00.000Z"}}]
Note
Expiration deletes the parameter. It does not notify the stack that owns it, so CloudFormation’s view of the resource silently diverges from reality and the next stack update fails on a missing resource.
Tags JSONKey/value tags, supplied as a JSON object rather than the usual list of Key/Value pairs. No interruption — updates in place
This is one of the few resource types whose Tags property is a plain object ({"Team": "payments"}) rather than a list of {"Key": …, "Value": …} objects. Copying a Tags block from another resource type into this one will not validate.
Type
JSON
Required
No
Update behaviour
No interruption
Example values
- {"Team": "payments", "Environment": "production"}
Tier StringStorage tier, which sets the size limit, policy support, and whether the parameter is billed. No interruption — updates in place
Standard is free, caps the value at 4 KB, and supports no policies. Advanced raises the cap to 8 KB, enables parameter policies, and is billed per parameter per month. Intelligent-Tiering starts a parameter as Standard and promotes it to Advanced automatically the first time it exceeds a Standard limit.
Type
String
Required
No
Update behaviour
No interruption
Default
Standard
Allowed values
- Standard
- Advanced
- Intelligent-Tiering
Warning
Promotion from Standard to Advanced is one-way. Once a parameter is Advanced you cannot downgrade it in place, and it keeps accruing charges until it is deleted and recreated. Setting Intelligent-Tiering on a parameter that is close to 4 KB is a decision to start paying, taken by whoever next edits the value.

Property	Type	Required	Update	Description
Type	`String`	Yes	None	The parameter's value type, which fixes how the value is stored and returned.
Value	`String`	Yes	None	The parameter value. Changing it creates a new version rather than mutating the old one.
AllowedPattern	`String`	No	None	Regular expression that Systems Manager enforces against the value on write.
DataType	`String`	No	None	Tells Systems Manager to validate the value as a particular kind of identifier.
Description	`String`	No	None	Free-text description shown in the console and returned by DescribeParameters.
Name	`String`	No	Replacement	The fully qualified parameter name, including its hierarchy path.
Policies	`String`	No	None	A JSON array of parameter policies — expiration, expiration notification, and no-change notification.
Tags	`JSON`	No	None	Key/value tags, supplied as a JSON object rather than the usual list of Key/Value pairs.
Tier	`String`	No	None	Storage tier, which sets the size limit, policy support, and whether the parameter is billed.

Generated from the schema. The first pair shows only required and conditionally-required properties — a template you can paste and deploy. Property keys are ordered alphabetically here rather than required-first, because that is the order a template file conventionally uses.

Type: AWS::SSM::Parameter
Properties:
  Type: String
  Value: payments-db.internal.acme.example

{
  "Type": "AWS::SSM::Parameter",
  "Properties": {
    "Type": "String",
    "Value": "payments-db.internal.acme.example"
  }
}

Every property, three levels deep:

Type: AWS::SSM::Parameter
Properties:
  AllowedPattern: '^\d+$'
  DataType: text
  Description: String
  Name: /acme/payments/database-host
  Policies: '[{"Type":"Expiration","Version":"1.0","Attributes":{"Timestamp":"2027-01-01T00:00:00.000Z"}}]'
  Tags: '{"Team": "payments", "Environment": "production"}'
  Tier: Standard
  Type: String
  Value: payments-db.internal.acme.example

{
  "Type": "AWS::SSM::Parameter",
  "Properties": {
    "AllowedPattern": "^\\d+$",
    "DataType": "text",
    "Description": "String",
    "Name": "/acme/payments/database-host",
    "Policies": "[{\"Type\":\"Expiration\",\"Version\":\"1.0\",\"Attributes\":{\"Timestamp\":\"2027-01-01T00:00:00.000Z\"}}]",
    "Tags": "{\"Team\": \"payments\", \"Environment\": \"production\"}",
    "Tier": "Standard",
    "Type": "String",
    "Value": "payments-db.internal.acme.example"
  }
}

updates in place some interruption replacement create-only read-only write-only

Return values

What other resources can read from this one

Ref

Returns the parameter’s name — the value of Name, or the generated name if Name was omitted.

!Ref MyResource → /acme/payments/database-host

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
Type	`String`	The parameter’s type, echoed back.	`String`
Value	`String`	The parameter’s value, echoed back. Readable in the template, so treat it as public.	`payments-db.internal.acme.example`

Required permissions

For the principal running the stack operation

create

ssm:PutParameter
ssm:AddTagsToResource
ssm:GetParameters

read

ssm:GetParameters
ssm:ListTagsForResource

update

ssm:PutParameter
ssm:AddTagsToResource
ssm:RemoveTagsFromResource

delete

ssm:DeleteParameter

list

ssm:DescribeParameters

{
  "Statement": [
    {
      "Action": [
        "ssm:AddTagsToResource",
        "ssm:DeleteParameter",
        "ssm:DescribeParameters",
        "ssm:GetParameters",
        "ssm:ListTagsForResource",
        "ssm:PutParameter",
        "ssm:RemoveTagsFromResource"
      ],
      "Effect": "Allow",
      "Resource": "*",
      "Sid": "ManageResource"
    }
  ],
  "Version": "2012-10-17"
}

Statement:
- Action:
  - ssm:AddTagsToResource
  - ssm:DeleteParameter
  - ssm:DescribeParameters
  - ssm:GetParameters
  - ssm:ListTagsForResource
  - ssm:PutParameter
  - ssm:RemoveTagsFromResource
  Effect: Allow
  Resource: '*'
  Sid: ManageResource
Version: '2012-10-17'