Working with shared parameters - Amazon Systems Manager
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with shared parameters

Sharing advanced parameters simplifies configuration data management in a multi-account environment. You can centrally store and manage your parameters and share them with other Amazon Web Services accounts that need to reference them.

Parameter Store integrates with Amazon Resource Access Manager (Amazon RAM) to enable advanced parameter sharing. Amazon RAM is a service that enables you to share resources with other Amazon Web Services accounts or through Amazon Organizations.

With Amazon RAM, you share resources that you own by creating a resource share. A resource share specifies the resources to share, permissions to grant, and the consumers with whom to share. Consumers can include:

  • Specific Amazon Web Services accounts inside or outside of its organization in Amazon Organizations

  • An organizational unit inside its organization in Amazon Organizations

  • Its entire organization in Amazon Organizations

For more information about Amazon RAM, see the Amazon RAM User Guide.

This topic explains how to share parameters that you own, and how to use parameters that are shared with you.

Prerequisites for sharing parameters

The following prerequisites must be met before you can share parameters from your account:

  • To share a parameter, you must own it in your Amazon Web Services account. You can't share a parameter that has been shared with you.

  • To share a parameter, it must be in the advanced parameter tier. For information about parameter tiers, see Managing parameter tiers. For information about changing an existing standard parameter to an advanced parameter, see Changing a standard parameter to an advanced parameter.

  • To share a SecureString parameter, it must be encrypted with a customer managed key, and you must share the key separately through Amazon Key Management Service. Amazon managed keys cannot be shared. Parameters encrypted with the default Amazon managed key can be updated to use a customer managed key instead. For Amazon KMS key definitions, see Amazon KMS concepts in the Amazon Key Management Service Developer Guide.

  • To share a parameter with your organization or an organizational unit in Amazon Organizations, you must enable sharing with Amazon Organizations. For more information, see Enable Sharing with Amazon Organizations in the Amazon RAM User Guide.

Sharing a parameter

To share a parameter, you must add it to a resource share. A resource share is an Amazon RAM resource that lets you share your resources across Amazon Web Services accounts. A resource share specifies the resources to share, and the consumers with whom they are shared.

When you share a parameter that you own with other Amazon Web Services accounts, you can choose from two Amazon managed permissions to grant the consumers. For more information, see Permissions sets for sharing parameters.

If you are part of an organization in Amazon Organizations and sharing within your organization is enabled, you can grant consumers in your organization access from the Amazon RAM console to the shared parameter. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared parameter after accepting the invitation.

You can share a parameter that you own using the Amazon RAM console, or the Amazon CLI.

Note

While you can share a parameter using the Systems Manager PutResourcePolicy API operation, we recommend using Amazon Resource Access Manager (Amazon RAM) instead. This is because using PutResourcePolicy requires the extra step of promoting the parameter to a standard Resource Share using the Amazon RAM PromoteResourceShareCreatedFromPolicy API operation. Otherwise, the parameter won't be returned by the Systems Manager DescribeParameters API operation using the --shared option.

To share a parameter that you own using the Amazon RAM console

See Creating a Resource Share in the Amazon RAM User Guide.

To share a parameter that you own using the Amazon CLI

Use the create-resource-share command to add parameters to a new resource share.

Use the associate-resource-share command to add parameters to an existing resource share.

The following example creates a new resource share to share parameters with consumers in an organization and in an individual account.

aws ram create-resource-share \ --name "MyParameter" \ --resource-arns "arn:aws:ssm:us-east-2:123456789012:parameter/MyParameter" \ --principals "arn:aws:organizations::123456789012:ou/o-63bEXAMPLE/ou-46xi-rEXAMPLE" "987654321098"

Stop sharing a shared parameter

When you stop sharing a shared parameter, the consumer account can no longer access the parameter.

To stop sharing a parameter that you own, you must remove it from the resource share. You can do this using the Systems Manager console, Amazon RAM console, or the Amazon CLI.

To stop sharing a parameter that you own using the Amazon RAM console

See Update a resource share in Amazon RAM in the Amazon RAM User Guide.

To stop sharing a parameter that you own using the Amazon CLI

Use the disassociate-resource-share command.

Identifying shared parameters

Owners and consumers can identify shared parameters using the Amazon CLI.

To identify shared parameters using the Amazon CLI

To identify shared parameters using the Amazon CLI, you can choose from the Systems Manager describe-parameters command and the Amazon RAM list-resources command.

When you use the --shared option with describe-parameters, the command returns the parameters that are shared with you.

The following is an example:

aws ssm describe-parameters --shared

Accessing shared parameters

Consumers can access shared parameters using the Amazon command line tools, and Amazon SDKs. For consumer accounts, parameters shared with that account aren't included in the My parameters page.

CLI Example: Accessing shared parameter details using the Amazon CLI

To access shared parameter details using the Amazon CLI, you can use the get-parameter or get-parameters commands. You must specify the full parameter ARN as the --name in order to retrieve the parameter from another account.

The following is an example.

aws ssm get-parameter \ --name arn:aws:ssm:us-east-2:123456789012:parameter/MySharedParameter
Supported and unsupported integrations for shared parameters

Currently, you can use shared parameters in the following integration scenarios:

The following scenarios and integrated services do not currently support the use of shared parameters:

Permissions sets for sharing parameters

Your consumer accounts receive read-only access to you shared parameters. The consumer can't update or delete the parameter. The consumer can't share the parameter with a third account. You can choose from two Amazon managed permission sets to grant this read-only access:

AWSRAMDefaultPermissionSSMParameterReadOnly

Allowed actions: DescribeParameters, GetParameter, GetParameters

AWSRAMPermissionSSMParameterReadOnlyWithHistory

Allowed actions: DescribeParameters, GetParameter, GetParameters, GetParameterHistory

Maximum throughput for shared parameters

Systems Manager limits the maximum throughput (transactions per second) for the GetParameter and GetParameters. operations. Throughput is enforced at the individual account level. Therefore, each account that consumes a shared parameter can use its maximum allowed throughput without being affected by other accounts. For more information about maximum throughput for parameters, see the following topics:

Pricing for shared parameters

Cross-account sharing is only available in the advanced parameter tier. For advanced parameters, charges are incurred at the current price for the storage and API usage for each advanced parameter. The owning account is charged for storage of the advanced parameter. Any consuming account that makes an API call to a shared advanced parameter is charged for the parameter usage.

For example, if Account A creates an advanced parameter, MyAdvancedParameter, that account is charged USD 0.05 per month to store the parameter.

Account A then shares MyAdvancedParameter with Account B and Account C. During a month, the three accounts make calls to MyAdvancedParameter. The following table illustrates the charges they would incur for the number of calls each makes.

Note

The charges in the following table are for illustration only. To verify current pricing, see Amazon Systems Manager Pricing for Parameter Store.

Account Number of calls Charges
Account A (owning account) 10,000 calls
  • One month advanced parameter storage: USD 0.05

  • 10,000 calls to MyAdvancedParameter: USD 0.05

  • Total: USD 0.10

Account B (consuming account) 20,000 calls
  • 20,000 calls to MyAdvancedParameter: USD 0.10

  • Total: USD 0.10

Account C (consuming account) 30,000 calls
  • 30,000 calls to MyAdvancedParameter: USD 0.15

  • Total: USD 0.15

Cross-account access for closed Amazon Web Services accounts

If the Amazon Web Services account that owns a shared parameter is closed, all consuming accounts lose access to the shared parameter. If the owning account is reopened within 90 days after the account is closed, consuming accounts regain access to the previously shared parameters. For more information about reopening an account during the Post-Closure Period, see Accessing your Amazon Web Services account after you close it in the Amazon Account Management Reference Guide.