Namespace Amazon.CDK.AWS.SSM

AWS Systems Manager Construct Library

This module is part of the AWS Cloud Development Kit project.

Using existing SSM Parameters in your CDK app

You can reference existing SSM Parameter Store values that you want to use in your CDK app by using ssm.StringParameter.fromStringParameterAttributes:

var parameterVersion = Token.AsNumber(new Dictionary<string, string> { { "Ref", "MyParameter" } });

// Retrieve the latest value of the non-secret parameter
// with name "/My/String/Parameter".
var stringValue = StringParameter.FromStringParameterAttributes(this, "MyValue", new StringParameterAttributes {
    ParameterName = "/My/Public/Parameter"
}).StringValue;
var stringValueVersionFromToken = StringParameter.FromStringParameterAttributes(this, "MyValueVersionFromToken", new StringParameterAttributes {
    ParameterName = "/My/Public/Parameter",
    // parameter version from token
    Version = parameterVersion
}).StringValue;

// Retrieve a specific version of the secret (SecureString) parameter.
// 'version' is always required.
var secretValue = StringParameter.FromSecureStringParameterAttributes(this, "MySecureValue", new SecureStringParameterAttributes {
    ParameterName = "/My/Secret/Parameter",
    Version = 5
});
var secretValueVersionFromToken = StringParameter.FromSecureStringParameterAttributes(this, "MySecureValueVersionFromToken", new SecureStringParameterAttributes {
    ParameterName = "/My/Secret/Parameter",
    // parameter version from token
    Version = parameterVersion
});

You can also reference an existing SSM Parameter Store value that matches an AWS specific parameter type:

StringParameter.ValueForTypedStringParameterV2(this, "/My/Public/Parameter", ParameterValueType.AWS_EC2_IMAGE_ID);

To do the same for a SSM Parameter Store value that is stored as a list:

StringListParameter.ValueForTypedListParameter(this, "/My/Public/Parameter", ParameterValueType.AWS_EC2_IMAGE_ID);

Lookup existing parameters

You can also use an existing parameter by looking up the parameter from the AWS environment. This method uses AWS API calls to lookup the value from SSM during synthesis.

var stringValue = StringParameter.ValueFromLookup(this, "/My/Public/Parameter");

When using valueFromLookup an initial value of 'dummy-value-for-${parameterName}' (dummy-value-for-/My/Public/Parameter in the above example) is returned prior to the lookup being performed. This can lead to errors if you are using this value in places that require a certain format. For example if you have stored the ARN for a SNS topic in a SSM Parameter which you want to lookup and provide to Topic.fromTopicArn()

var arnLookup = StringParameter.ValueFromLookup(this, "/my/topic/arn");
Topic.FromTopicArn(this, "Topic", arnLookup);

Initially arnLookup will be equal to dummy-value-for-/my/topic/arn which will cause Topic.fromTopicArn to throw an error indicating that the value is not in arn format.

For these use cases you need to handle the dummy-value in your code. For example:

var arnLookup = StringParameter.ValueFromLookup(this, "/my/topic/arn");
string arnLookupValue;
if (arnLookup.Includes("dummy-value"))
{
    arnLookupValue = FormatArn(new ArnComponents {
        Service = "sns",
        Resource = "topic",
        ResourceName = arnLookup
    });
}
else
{
    arnLookupValue = arnLookup;
}

Topic.FromTopicArn(this, "Topic", arnLookupValue);

Alternatively, if the property supports tokens you can convert the parameter value into a token to be resolved after the lookup has been completed.

var arnLookup = StringParameter.ValueFromLookup(this, "/my/role/arn");
Role.FromRoleArn(this, "role", Lazy.String(new Dictionary<string, produce> { { "produce", () => arnLookup } }));

cross-account SSM Parameters sharing

AWS Systems Manager (SSM) Parameter Store supports cross-account sharing of parameters using the AWS Resource Access Manager (AWS RAM) service. In a multi-account environment, this feature enables accounts (referred to as "consuming accounts") to access and retrieve parameter values that are shared by other accounts (referred to as "sharing accounts"). To reference and use a shared SSM parameter in a consuming account, the fromStringParameterArn() method can be employed.

The fromStringParameterArn() method provides a way for consuming accounts to create an instance of the StringParameter class from the Amazon Resource Name (ARN) of a shared SSM parameter. This allows the consuming account to retrieve and utilize the parameter value, even though the parameter itself is owned and managed by a different sharing account.

var sharingParameterArn = "arn:aws:ssm:us-east-1:1234567890:parameter/dummyName";
var sharedParam = StringParameter.FromStringParameterArn(this, "SharedParam", sharingParameterArn);

Things to note:

In summary, the process involves three main steps:

This cross-account sharing mechanism allows for centralized management and distribution of configuration data (stored as SSM parameters) across multiple AWS accounts within an organization or between different organizations.

Read Working with shared parameters for more details.

Creating new SSM Parameters in your CDK app

You can create either ssm.StringParameter or ssm.StringListParameters in a CDK app. These are public (not secret) values. Parameters of type SecureString cannot be created directly from a CDK application; if you want to provision secrets automatically, use Secrets Manager Secrets (see the aws-cdk-lib/aws-secretsmanager package).

new StringParameter(this, "Parameter", new StringParameterProps {
    AllowedPattern = ".*",
    Description = "The value Foo",
    ParameterName = "FooParameter",
    StringValue = "Foo",
    Tier = ParameterTier.ADVANCED
});

// Grant read access to some Role
IRole role;
// Create a new SSM Parameter holding a String
var param = new StringParameter(this, "StringParameter", new StringParameterProps {
    // description: 'Some user-friendly description',
    // name: 'ParameterName',
    StringValue = "Initial parameter value"
});
param.GrantRead(role);

// Create a new SSM Parameter holding a StringList
var listParameter = new StringListParameter(this, "StringListParameter", new StringListParameterProps {
    // description: 'Some user-friendly description',
    // name: 'ParameterName',
    StringListValue = new [] { "Initial parameter value A", "Initial parameter value B" }
});

When specifying an allowedPattern, the values provided as string literals are validated against the pattern and an exception is raised if a value provided does not comply.

Using Tokens in parameter name

When using CDK Tokens in parameter name, you need to explicitly set the simpleName property. Setting simpleName to an incorrect boolean value may result in unexpected behaviours, such as having duplicate '/' in the parameter ARN or missing a '/' in the parameter ARN.

simpleName is used to indicates whether the parameter name is a simple name. A parameter name without any '/' is considered a simple name, thus you should set simpleName to true. If the parameter name includes '/', set simpleName to false.

using Amazon.CDK.AWS.Lambda;

IFunction func;


var simpleParameter = new StringParameter(this, "StringParameter", new StringParameterProps {
    // the parameter name doesn't contain any '/'
    ParameterName = "parameter",
    StringValue = "SOME_VALUE",
    SimpleName = true
});
var nonSimpleParameter = new StringParameter(this, "StringParameter", new StringParameterProps {
    // the parameter name contains '/'
    ParameterName = $"/{func.functionName}/my/app/param",
    StringValue = "SOME_VALUE",
    SimpleName = false
});

Classes

CfnAssociation	The `AWS::SSM::Association` resource creates a State Manager association for your managed instances.
CfnAssociation.InstanceAssociationOutputLocationProperty	`InstanceAssociationOutputLocation` is a property of the AWS::SSM::Association resource that specifies an Amazon S3 bucket where you want to store the results of this association request.
CfnAssociation.S3OutputLocationProperty	`S3OutputLocation` is a property of the AWS::SSM::Association resource that specifies an Amazon S3 bucket where you want to store the results of this association request.
CfnAssociation.TargetProperty	`Target` is a property of the AWS::SSM::Association resource that specifies the targets for an SSM document in Systems Manager . You can target all instances in an AWS account by specifying the `InstanceIds` key with a value of `*` . To view a JSON and a YAML example that targets all instances, see the example "Create an association for all managed instances in an AWS account " later in this page.
CfnAssociationProps	Properties for defining a `CfnAssociation`.
CfnDocument	The `AWS::SSM::Document` resource creates a Systems Manager (SSM) document in AWS Systems Manager .
CfnDocument.AttachmentsSourceProperty	Identifying information about a document attachment, including the file name and a key-value pair that identifies the location of an attachment to a document.
CfnDocument.DocumentRequiresProperty	An SSM document required by the current document.
CfnDocumentProps	Properties for defining a `CfnDocument`.
CfnMaintenanceWindow	The `AWS::SSM::MaintenanceWindow` resource represents general information about a maintenance window for AWS Systems Manager .
CfnMaintenanceWindowProps	Properties for defining a `CfnMaintenanceWindow`.
CfnMaintenanceWindowTarget	The `AWS::SSM::MaintenanceWindowTarget` resource registers a target with a maintenance window for AWS Systems Manager .
CfnMaintenanceWindowTarget.TargetsProperty	The `Targets` property type specifies adding a target to a maintenance window target in AWS Systems Manager .
CfnMaintenanceWindowTargetProps	Properties for defining a `CfnMaintenanceWindowTarget`.
CfnMaintenanceWindowTask	The `AWS::SSM::MaintenanceWindowTask` resource defines information about a task for an AWS Systems Manager maintenance window.
CfnMaintenanceWindowTask.CloudWatchOutputConfigProperty	Configuration options for sending command output to Amazon CloudWatch Logs.
CfnMaintenanceWindowTask.LoggingInfoProperty	The `LoggingInfo` property type specifies information about the Amazon S3 bucket to write instance-level logs to.
CfnMaintenanceWindowTask.MaintenanceWindowAutomationParametersProperty	The `MaintenanceWindowAutomationParameters` property type specifies the parameters for an `AUTOMATION` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.MaintenanceWindowLambdaParametersProperty	The `MaintenanceWindowLambdaParameters` property type specifies the parameters for a `LAMBDA` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.MaintenanceWindowRunCommandParametersProperty	The `MaintenanceWindowRunCommandParameters` property type specifies the parameters for a `RUN_COMMAND` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.MaintenanceWindowStepFunctionsParametersProperty	The `MaintenanceWindowStepFunctionsParameters` property type specifies the parameters for the execution of a `STEP_FUNCTIONS` task in a Systems Manager maintenance window.
CfnMaintenanceWindowTask.NotificationConfigProperty	The `NotificationConfig` property type specifies configurations for sending notifications for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.TargetProperty	The `Target` property type specifies targets (either instances or window target IDs).
CfnMaintenanceWindowTask.TaskInvocationParametersProperty	The `TaskInvocationParameters` property type specifies the task execution parameters for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTaskProps	Properties for defining a `CfnMaintenanceWindowTask`.
CfnParameter	The `AWS::SSM::Parameter` resource creates an SSM parameter in AWS Systems Manager Parameter Store.
CfnParameterProps	Properties for defining a `CfnParameter`.
CfnPatchBaseline	The `AWS::SSM::PatchBaseline` resource defines the basic information for an AWS Systems Manager patch baseline.
CfnPatchBaseline.PatchFilterGroupProperty	The `PatchFilterGroup` property type specifies a set of patch filters for an AWS Systems Manager patch baseline, typically used for approval rules for a Systems Manager patch baseline.
CfnPatchBaseline.PatchFilterProperty	The `PatchFilter` property type defines a patch filter for an AWS Systems Manager patch baseline.
CfnPatchBaseline.PatchSourceProperty	`PatchSource` is the property type for the `Sources` resource of the AWS::SSM::PatchBaseline resource.
CfnPatchBaseline.RuleGroupProperty	The `RuleGroup` property type specifies a set of rules that define the approval rules for an AWS Systems Manager patch baseline.
CfnPatchBaseline.RuleProperty	The `Rule` property type specifies an approval rule for a Systems Manager patch baseline.
CfnPatchBaselineProps	Properties for defining a `CfnPatchBaseline`.
CfnResourceDataSync	The `AWS::SSM::ResourceDataSync` resource creates, updates, or deletes a resource data sync for AWS Systems Manager .
CfnResourceDataSync.AwsOrganizationsSourceProperty	Information about the `AwsOrganizationsSource` resource data sync source.
CfnResourceDataSync.S3DestinationProperty	Information about the target S3 bucket for the resource data sync.
CfnResourceDataSync.SyncSourceProperty	Information about the source of the data included in the resource data sync.
CfnResourceDataSyncProps	Properties for defining a `CfnResourceDataSync`.
CfnResourcePolicy	Creates or updates a Systems Manager resource policy.
CfnResourcePolicyProps	Properties for defining a `CfnResourcePolicy`.
CommonStringParameterAttributes	Common attributes for string parameters.
ListParameterAttributes	Attributes for parameters of string list type.
ParameterDataType	SSM parameter data type.
ParameterOptions	Properties needed to create a new SSM Parameter.
ParameterTier	SSM parameter tier.
ParameterType	(deprecated) SSM parameter type.
ParameterValueType	The type of CFN SSM Parameter.
SecureStringParameterAttributes	Attributes for secure string parameters.
StringListParameter	Creates a new StringList SSM Parameter.
StringListParameterProps	Properties needed to create a StringList SSM Parameter.
StringParameter	Creates a new String SSM Parameter.
StringParameterAttributes	Attributes for parameters of various types of string.
StringParameterProps	Properties needed to create a String SSM parameter.

Interfaces

CfnAssociation.IInstanceAssociationOutputLocationProperty	`InstanceAssociationOutputLocation` is a property of the AWS::SSM::Association resource that specifies an Amazon S3 bucket where you want to store the results of this association request.
CfnAssociation.IS3OutputLocationProperty	`S3OutputLocation` is a property of the AWS::SSM::Association resource that specifies an Amazon S3 bucket where you want to store the results of this association request.
CfnAssociation.ITargetProperty	`Target` is a property of the AWS::SSM::Association resource that specifies the targets for an SSM document in Systems Manager . You can target all instances in an AWS account by specifying the `InstanceIds` key with a value of `*` . To view a JSON and a YAML example that targets all instances, see the example "Create an association for all managed instances in an AWS account " later in this page.
CfnDocument.IAttachmentsSourceProperty	Identifying information about a document attachment, including the file name and a key-value pair that identifies the location of an attachment to a document.
CfnDocument.IDocumentRequiresProperty	An SSM document required by the current document.
CfnMaintenanceWindowTarget.ITargetsProperty	The `Targets` property type specifies adding a target to a maintenance window target in AWS Systems Manager .
CfnMaintenanceWindowTask.ICloudWatchOutputConfigProperty	Configuration options for sending command output to Amazon CloudWatch Logs.
CfnMaintenanceWindowTask.ILoggingInfoProperty	The `LoggingInfo` property type specifies information about the Amazon S3 bucket to write instance-level logs to.
CfnMaintenanceWindowTask.IMaintenanceWindowAutomationParametersProperty	The `MaintenanceWindowAutomationParameters` property type specifies the parameters for an `AUTOMATION` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.IMaintenanceWindowLambdaParametersProperty	The `MaintenanceWindowLambdaParameters` property type specifies the parameters for a `LAMBDA` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.IMaintenanceWindowRunCommandParametersProperty	The `MaintenanceWindowRunCommandParameters` property type specifies the parameters for a `RUN_COMMAND` task type for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.IMaintenanceWindowStepFunctionsParametersProperty	The `MaintenanceWindowStepFunctionsParameters` property type specifies the parameters for the execution of a `STEP_FUNCTIONS` task in a Systems Manager maintenance window.
CfnMaintenanceWindowTask.INotificationConfigProperty	The `NotificationConfig` property type specifies configurations for sending notifications for a maintenance window task in AWS Systems Manager .
CfnMaintenanceWindowTask.ITargetProperty	The `Target` property type specifies targets (either instances or window target IDs).
CfnMaintenanceWindowTask.ITaskInvocationParametersProperty	The `TaskInvocationParameters` property type specifies the task execution parameters for a maintenance window task in AWS Systems Manager .
CfnPatchBaseline.IPatchFilterGroupProperty	The `PatchFilterGroup` property type specifies a set of patch filters for an AWS Systems Manager patch baseline, typically used for approval rules for a Systems Manager patch baseline.
CfnPatchBaseline.IPatchFilterProperty	The `PatchFilter` property type defines a patch filter for an AWS Systems Manager patch baseline.
CfnPatchBaseline.IPatchSourceProperty	`PatchSource` is the property type for the `Sources` resource of the AWS::SSM::PatchBaseline resource.
CfnPatchBaseline.IRuleGroupProperty	The `RuleGroup` property type specifies a set of rules that define the approval rules for an AWS Systems Manager patch baseline.
CfnPatchBaseline.IRuleProperty	The `Rule` property type specifies an approval rule for a Systems Manager patch baseline.
CfnResourceDataSync.IAwsOrganizationsSourceProperty	Information about the `AwsOrganizationsSource` resource data sync source.
CfnResourceDataSync.IS3DestinationProperty	Information about the target S3 bucket for the resource data sync.
CfnResourceDataSync.ISyncSourceProperty	Information about the source of the data included in the resource data sync.
ICfnAssociationProps	Properties for defining a `CfnAssociation`.
ICfnDocumentProps	Properties for defining a `CfnDocument`.
ICfnMaintenanceWindowProps	Properties for defining a `CfnMaintenanceWindow`.
ICfnMaintenanceWindowTargetProps	Properties for defining a `CfnMaintenanceWindowTarget`.
ICfnMaintenanceWindowTaskProps	Properties for defining a `CfnMaintenanceWindowTask`.
ICfnParameterProps	Properties for defining a `CfnParameter`.
ICfnPatchBaselineProps	Properties for defining a `CfnPatchBaseline`.
ICfnResourceDataSyncProps	Properties for defining a `CfnResourceDataSync`.
ICfnResourcePolicyProps	Properties for defining a `CfnResourcePolicy`.
ICommonStringParameterAttributes	Common attributes for string parameters.
IListParameterAttributes	Attributes for parameters of string list type.
IParameter	An SSM Parameter reference.
IParameterOptions	Properties needed to create a new SSM Parameter.
ISecureStringParameterAttributes	Attributes for secure string parameters.
IStringListParameter	A StringList SSM Parameter.
IStringListParameterProps	Properties needed to create a StringList SSM Parameter.
IStringParameter	A String SSM Parameter.
IStringParameterAttributes	Attributes for parameters of various types of string.
IStringParameterProps	Properties needed to create a String SSM parameter.