Updraft ConfigConfiguration PreviewSince v1.2

Updraft::Config::ParameterSet

Writes every value in an Updraft::Config::Document into SSM Parameter Store under a common prefix, as one CloudFormation resource that owns the whole set and cleans up after itself.

Required properties 2 of 10

Ref returns Prefix/acme/payments/production

Fn::GetAtt 4 attributes

Replacement risk 1 1 property force replacement

Minimal template

Every required property, nothing else

Resources:
  PublishedConfig:
    Type: Updraft::Config::ParameterSet
    Properties:
      Document: !Ref AppConfig
      Prefix: /acme/payments/production

{
  "Resources": {
    "PublishedConfig": {
      "Type": "Updraft::Config::ParameterSet",
      "Properties": {
        "Document": { "Ref": "AppConfig" },
        "Prefix": "/acme/payments/production"
      }
    }
  }
}

Nested keys become path segments: {"database": {"host": "…"}} is published as /acme/payments/production/database/host.

Overview #

ParameterSet takes a whole configuration document and publishes it into SSM Parameter Store as a hierarchy. One resource owns the entire prefix: it creates parameters for new keys, updates changed ones, and deletes parameters whose keys have left the document.

That last behaviour is the reason the resource exists. Publishing configuration with one AWS::SSM::Parameter per key works until somebody removes a key from the source file and forgets to remove the resource from the template — at which point the parameter stays, stale, forever, and something is still reading it.

What gets published #

Nested objects become path segments. Scalars become String parameters. Arrays become StringList parameters.

Document

database:
  host: payments-db.internal.acme.example
  port: 5432
featureFlags:
  newCheckout: true
allowedRegions:
  - us-west-2
  - eu-west-1

Parameter Store

/acme/payments/production/database/host
    -> payments-db.internal.acme.example   (String)
/acme/payments/production/database/port
    -> 5432                                (String)
/acme/payments/production/featureFlags/newCheckout
    -> true                                (String)
/acme/payments/production/allowedRegions
    -> us-west-2,eu-west-1                 (StringList)

!Ref PublishedConfig → /acme/payments/production

!GetAtt PublishedConfig.ParameterCount → 4

Consuming the published set #

The point of publishing is that things which are not CloudFormation can read the configuration. One call returns the whole environment:

aws ssm get-parameters-by-path \
  --path /acme/payments/production \
  --recursive \
  --with-decryption

And one IAM statement authorises it:

- Effect: Allow
  Action: ssm:GetParametersByPath
  Resource: !Sub 'arn:${AWS::Partition}:ssm:${AWS::Region}:${AWS::AccountId}:parameter/acme/payments/production'

Properties

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

Document StringThe document ID to publish, from Ref on an Updraft::Config::Document. Required No interruption — updates in place
The document ID to publish, from Ref on an Updraft::Config::Document.
Type
String
Required
Yes
Update behaviour
No interruption
Example values
- doc-2f8a1c94
Prefix StringParameter Store path every published parameter hangs under. Required Replacement — CloudFormation creates a new resource and deletes the old one Create-only
Parameter Store path every published parameter hangs under.
Type
String
Required
Yes
Update behaviour
Replacement
Pattern
^/([a-zA-Z0-9_.\-]+/?)+$ Must begin with `/`. Segments may contain letters, digits, underscore, period and hyphen.
Length
1 – 1024
Example values
- /acme/payments/production
Changing the prefix replaces the whole set
A new prefix is a new resource. CloudFormation creates every parameter under the new path, then deletes every parameter under the old one — in that order, so there is no gap. But anything reading the old path at runtime breaks the moment the delete runs, and the stack will already have reported UPDATE_COMPLETE on the create half.
Migrate by running both prefixes for a release, then removing the old one, rather than by editing this property in place.
DeleteOnRemove BooleanWhether parameters that disappear from the document are deleted from Parameter Store. No interruption — updates in place
When true, this resource owns the prefix completely: removing a key from the document removes the parameter on the next update. When false, parameters are only ever created and updated, and orphans accumulate.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
true
Remarks
true is the right default because the alternative is silent drift: a key you deleted six months ago is still being read by a service that nobody realised was reading it, and the value is six months stale.
It is also the dangerous option, because it means anything written under this prefix by hand will be deleted on the next stack update. Give the resource a prefix of its own and do not share it.
Exclude Array of StringJSON Pointer prefixes to skip. Applied after Include. No interruption — updates in place
JSON Pointer prefixes to skip. Applied after Include.
Type
Array of String
Required
No
Update behaviour
No interruption
Items
0 – 50
Example values
- ["/internal","/database/password"]
Important
Exclude is not a security control. It runs on a document that has already been loaded and is already visible through the document’s own attributes. To keep a value out of the template entirely, redact it at the source with the document’s Redact property.
Include Array of StringJSON Pointer prefixes to publish. Everything is published when omitted. No interruption — updates in place
JSON Pointer prefixes to publish. Everything is published when omitted.
Type
Array of String
Required
No
Update behaviour
No interruption
Items
0 – 50
Example values
- ["/database","/featureFlags"]
KeyId StringKMS key for parameters published as SecureString. No interruption — updates in place Write-only
Only consulted for paths listed in SecurePaths. Everything else is published as String regardless.
Type
String
Required
No
Update behaviour
No interruption
Example values
- alias/acme-config
MaxParameters IntegerRefuse to publish more than this many parameters. No interruption — updates in place
A guard against a document that grew an array of ten thousand entries. The count is checked before anything is written, so the operation fails cleanly rather than half-way through.
Type
Integer
Required
No
Update behaviour
No interruption
Default
200
Range
1 – 1000
Overwrite BooleanWhether to take ownership of parameters that already exist under the prefix. No interruption — updates in place
With the default of false, a pre-existing parameter under Prefix fails the create — which is the correct behaviour when two stacks have accidentally been pointed at the same path.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
false
SecurePaths Array of StringJSON Pointer prefixes to publish as SecureString instead of String. No interruption — updates in place Write-only
JSON Pointer prefixes to publish as SecureString instead of String.
Type
Array of String
Required
No
Update behaviour
No interruption
Example values
- ["/database/password"]
The value still passes through the template
Publishing as SecureString encrypts the value at rest in Parameter Store. It does not stop the plaintext from being read out of the source document, held in the extension’s memory, and visible to anyone who can read the resolved template.
If the value is a real secret, it should not be in the source document in the first place. This property is for defence in depth on values that are sensitive but not catastrophic — internal hostnames, account identifiers, non-production credentials.
Tier StringTier applied to every parameter in the set. No interruption — updates in place
Applied uniformly. A document with one 6 KB value and forty small ones either promotes all forty to Advanced, or fails on the one. Split such documents rather than paying for the whole set.
Type
String
Required
No
Update behaviour
No interruption
Default
Standard
Allowed values
- Standard
- Advanced
- Intelligent-Tiering

Property	Type	Required	Update	Description
Document	`String`	Yes	None	The document ID to publish, from Ref on an Updraft::Config::Document.
Prefix	`String`	Yes	Replacement	Parameter Store path every published parameter hangs under.
DeleteOnRemove	`Boolean`	No	None	Whether parameters that disappear from the document are deleted from Parameter Store.
Exclude	`Array of String`	No	None	JSON Pointer prefixes to skip. Applied after Include.
Include	`Array of String`	No	None	JSON Pointer prefixes to publish. Everything is published when omitted.
KeyId	`String`	No	None	KMS key for parameters published as SecureString.
MaxParameters	`Integer`	No	None	Refuse to publish more than this many parameters.
Overwrite	`Boolean`	No	None	Whether to take ownership of parameters that already exist under the prefix.
SecurePaths	`Array of String`	No	None	JSON Pointer prefixes to publish as SecureString instead of String.
Tier	`String`	No	None	Tier applied to every parameter in the set.

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: Updraft::Config::ParameterSet
Properties:
  Document: doc-2f8a1c94
  Prefix: /acme/payments/production

{
  "Type": "Updraft::Config::ParameterSet",
  "Properties": {
    "Document": "doc-2f8a1c94",
    "Prefix": "/acme/payments/production"
  }
}

Every property, three levels deep:

Type: Updraft::Config::ParameterSet
Properties:
  DeleteOnRemove: true
  Document: doc-2f8a1c94
  Exclude:
  - String
  Include:
  - String
  KeyId: alias/acme-config
  MaxParameters: 200
  Overwrite: false
  Prefix: /acme/payments/production
  SecurePaths:
  - String
  Tier: Standard

{
  "Type": "Updraft::Config::ParameterSet",
  "Properties": {
    "DeleteOnRemove": true,
    "Document": "doc-2f8a1c94",
    "Exclude": [
      "String"
    ],
    "Include": [
      "String"
    ],
    "KeyId": "alias/acme-config",
    "MaxParameters": 200,
    "Overwrite": false,
    "Prefix": "/acme/payments/production",
    "SecurePaths": [
      "String"
    ],
    "Tier": "Standard"
  }
}

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 prefix the set was published under.

!Ref MyResource → /acme/payments/production

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
Checksum	`String`	SHA-256 of the published set, for asserting that two environments received identical configuration.	`4f2a9c1e8b7d6a5f3e2c1b0a9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e`
DeletedCount	`Integer`	Parameters removed on the last update because their keys left the document.	`2`
ParameterCount	`Integer`	Number of parameters written on the last successful operation.	`23`
ParameterNames	`Array`	Full names of every published parameter, sorted.	`["/acme/payments/production/database/host"]`

Required permissions

For the principal running the stack operation

create

ssm:PutParameter
ssm:GetParametersByPath
ssm:AddTagsToResource
kms:Encrypt

read

ssm:GetParametersByPath
ssm:ListTagsForResource

update

ssm:PutParameter
ssm:DeleteParameters
ssm:GetParametersByPath
kms:Encrypt

delete

ssm:DeleteParameters
ssm:GetParametersByPath

list

ssm:DescribeParameters

{
  "Statement": [
    {
      "Action": [
        "kms:Encrypt",
        "ssm:AddTagsToResource",
        "ssm:DeleteParameters",
        "ssm:DescribeParameters",
        "ssm:GetParametersByPath",
        "ssm:ListTagsForResource",
        "ssm:PutParameter"
      ],
      "Effect": "Allow",
      "Resource": "*",
      "Sid": "ManageResource"
    }
  ],
  "Version": "2012-10-17"
}

Statement:
- Action:
  - kms:Encrypt
  - ssm:AddTagsToResource
  - ssm:DeleteParameters
  - ssm:DescribeParameters
  - ssm:GetParametersByPath
  - ssm:ListTagsForResource
  - ssm:PutParameter
  Effect: Allow
  Resource: '*'
  Sid: ManageResource
Version: '2012-10-17'

Minimal template

Overview #

What gets published #

Consuming the published set #

Properties

Return values

Fn::GetAtt attributes

Required permissions

Related types

`Fn::GetAtt` attributes