Skip to content

Latest commit

 

History

History
688 lines (423 loc) · 26 KB

API.md

File metadata and controls

688 lines (423 loc) · 26 KB
Raw

PRs Welcome GitHub npm (scoped) PyPI Nuget Sonatype Nexus (Releases) GitHub Workflow Status (branch) GitHub release (latest SemVer) Gitpod ready-to-code

CDK SSM Parameters cross-region

Store, read and lookup AWS SSM Parameters cross-region

Currently, only supports StringParameter except simple name. Implements aws_ssm.IParameter and can be used as aws_ssm.StringParameter replacement.

Install

TypeScript

npm install @pepperize/cdk-ssm-parameters-cross-region

or

yarn add @pepperize/cdk-ssm-parameters-cross-region

Python

pip install pepperize.cdk-ssm-parameters-cross-region

C# / .Net

dotnet add package Pepperize.CDK.SsmParametersCrossRegion

Java

<dependency>
  <groupId>com.pepperize</groupId>
  <artifactId>cdk-ssm-parameters-cross-region</artifactId>
  <version>${cdkSsmParametersCrossRegion.version}</version>
</dependency>

Usage

Store AWS SSM Parameter cross-region

new StringParameter(scope, "PutParameter", {
  region: "eu-central-1",
  parameterName: "/path/name/example",
  stringValue: "Say hello from another region",
});

See StringParameter

Read AWS SSM Parameter cross-region

StringParameter.fromStringParameterName(scope, "GetParameter", "eu-central-1", "/path/name/example");

See StringParameter.fromStringParameterName

Lookup AWS SSM Parameter cross-region

StringParameter.valueFromLookup(scope, "eu-central-1", "/path/name/example");

See StringParameter.valueFromLookup

API Reference

Constructs

StringParameter

  • Implements: aws-cdk-lib.aws_ssm.IStringParameter, aws-cdk-lib.aws_ssm.IParameter

Initializers 

import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

new StringParameter(scope: Construct, id: string, props: StringParameterProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props StringParameterProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
grantRead Grants read (DescribeParameter, GetParameter, GetParameterHistory) permissions on the SSM Parameter.
grantWrite Grants write (PutParameter) permissions on the SSM Parameter.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
grantRead 
public grantRead(grantee: IGrantable): Grant

Grants read (DescribeParameter, GetParameter, GetParameterHistory) permissions on the SSM Parameter.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
grantWrite 
public grantWrite(grantee: IGrantable): Grant

Grants write (PutParameter) permissions on the SSM Parameter.

granteeRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable

Static Functions

Name Description
isConstruct Checks if x is a construct.
isResource Check whether the given construct is a Resource.
fromStringParameterAttributes Imports an external string parameter with name and optional version.
fromStringParameterName Imports an external string parameter by name and region.
valueFromLookup Reads the value of an SSM parameter during synthesis through an environmental context provider.
isConstruct 
import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

StringParameter.isConstruct(x: any)

Checks if x is a construct.

xRequired
  • Type: any

Any object.

isResource 
import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

StringParameter.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromStringParameterAttributes 
import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

StringParameter.fromStringParameterAttributes(scope: Construct, id: string, attrs: StringParameterAttributes)

Imports an external string parameter with name and optional version.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
attrsRequired
fromStringParameterName 
import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

StringParameter.fromStringParameterName(scope: Construct, id: string, region: string, parameterName: string)

Imports an external string parameter by name and region.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
regionRequired
  • Type: string
parameterNameRequired
  • Type: string
valueFromLookup 
import { StringParameter } from '@pepperize/cdk-ssm-parameters-cross-region'

StringParameter.valueFromLookup(scope: Construct, region: string, parameterName: string)

Reads the value of an SSM parameter during synthesis through an environmental context provider.

Requires that the stack this scope is defined in will have explicit account information. Otherwise, it will fail during synthesis.

scopeRequired
  • Type: constructs.Construct
regionRequired
  • Type: string
parameterNameRequired
  • Type: string

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
parameterArn string The ARN of the SSM Parameter resource.
parameterName string The name of the SSM Parameter resource.
parameterType string The type of the SSM Parameter resource.
stringValue string The parameter value.
tags aws-cdk-lib.TagManager No description.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

parameterArnRequired 
public readonly parameterArn: string;
  • Type: string

The ARN of the SSM Parameter resource.

parameterNameRequired 
public readonly parameterName: string;
  • Type: string

The name of the SSM Parameter resource.

parameterTypeRequired 
public readonly parameterType: string;
  • Type: string

The type of the SSM Parameter resource.

stringValueRequired 
public readonly stringValue: string;
  • Type: string

The parameter value.

Value must not nest another parameter. Do not use {{}} in the value.

tagsRequired 
public readonly tags: TagManager;
  • Type: aws-cdk-lib.TagManager

Structs

StringParameterAttributes

Initializer 

import { StringParameterAttributes } from '@pepperize/cdk-ssm-parameters-cross-region'

const stringParameterAttributes: StringParameterAttributes = { ... }

Properties

Name Type Description
parameterName string The name of the parameter store value.
simpleName boolean Indicates of the parameter name is a simple name (i.e. does not include "/" separators).
type aws-cdk-lib.aws_ssm.ParameterType The type of the string parameter.
version number The version number of the value you wish to retrieve.
region string The region to retrieve the parameter from.
parameterNameRequired 
public readonly parameterName: string;
  • Type: string

The name of the parameter store value.

This value can be a token or a concrete string. If it is a concrete string and includes "/" it must also be prefixed with a "/" (fully-qualified).

simpleNameOptional 
public readonly simpleName: boolean;
  • Type: boolean
  • Default: auto-detect based on parameterName

Indicates of the parameter name is a simple name (i.e. does not include "/" separators).

This is only required only if parameterName is a token, which means we are unable to detect if the name is simple or "path-like" for the purpose of rendering SSM parameter ARNs.

If parameterName is not specified, simpleName must be true (or undefined) since the name generated by AWS CloudFormation is always a simple name.

typeOptional 
public readonly type: ParameterType;
  • Type: aws-cdk-lib.aws_ssm.ParameterType
  • Default: ParameterType.STRING

The type of the string parameter.

versionOptional 
public readonly version: number;
  • Type: number
  • Default: The latest version will be retrieved.

The version number of the value you wish to retrieve.

regionRequired 
public readonly region: string;
  • Type: string

The region to retrieve the parameter from.

See AWS.SSM.region for more information.

StringParameterProps

Properties needed to create a String SSM parameter.

Initializer 

import { StringParameterProps } from '@pepperize/cdk-ssm-parameters-cross-region'

const stringParameterProps: StringParameterProps = { ... }

Properties

Name Type Description
parameterName string The name of the parameter.
region string The region to create the parameter in.
stringValue string The value of the parameter.
allowedPattern string A regular expression used to validate the parameter value.
dataType aws-cdk-lib.aws_ssm.ParameterDataType The data type of the parameter, such as text or aws:ec2:image.
description string Information about the parameter that you want to add to the system.
removalPolicy aws-cdk-lib.RemovalPolicy Whether to retain or delete the parameter on CloudFormation delete event.
tier aws-cdk-lib.aws_ssm.ParameterTier The tier of the string parameter.
parameterNameRequired 
public readonly parameterName: string;
  • Type: string
  • Default: a name will be generated by CloudFormation

The name of the parameter.

It may not be a

regionRequired 
public readonly region: string;
  • Type: string

The region to create the parameter in.

See AWS.SSM.region for more information.

stringValueRequired 
public readonly stringValue: string;
  • Type: string

The value of the parameter.

It may not reference another parameter and {{}} cannot be used in the value.

allowedPatternOptional 
public readonly allowedPattern: string;
  • Type: string
  • Default: undefined, no validation is performed

A regular expression used to validate the parameter value.

dataTypeOptional 
public readonly dataType: ParameterDataType;
  • Type: aws-cdk-lib.aws_ssm.ParameterDataType
  • Default: undefined

The data type of the parameter, such as text or aws:ec2:image.

descriptionOptional 
public readonly description: string;
  • Type: string
  • Default: undefined

Information about the parameter that you want to add to the system.

removalPolicyOptional 
public readonly removalPolicy: RemovalPolicy;
  • Type: aws-cdk-lib.RemovalPolicy
  • Default: DESTROY

Whether to retain or delete the parameter on CloudFormation delete event.

tierOptional 
public readonly tier: ParameterTier;
  • Type: aws-cdk-lib.aws_ssm.ParameterTier
  • Default: undefined

The tier of the string parameter.