Amazon EC2 Systems Manager
用户指南
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

使用 Systems Manager 参数

此部分介绍如何组织、创建和标记参数。

将参数组织成层次结构

以平面列表的形式管理几十个或数百个参数十分耗时且容易出错。而且为任务确定正确参数也很难。这意味着,您可能意外地使用了错误的参数,或者您可能创建多个使用相同配置数据的参数。

您可以使用参数层次结构来帮助组织和管理参数。一个层次结构是一个参数名称,包括您使用正斜杠定义的路径。下面是一个示例,它在名称中使用三个层次结构级别来标识以下内容:

/环境/计算机类型/应用程序/数据

/Dev/DBServer/MySQL/db-string13

您可以创建具有最多五个级别的层次结构。我们建议您创建反映环境中现有层次结构的层次结构,如以下示例所示:

  • 您的持续开发和集成环境 (CI/CD 工作流)

    /Dev/DBServer/MySQL/db-string
    /Staging/DBServer/MySQL/db-string
    /Prod/DBServer/MySQL/db-string
  • 您的使用容器的应用程序

    /MyApp/.NET/Libaries/git-password
  • 您的业务组织

    /Finance/Accountants/UserList
    /Finance/Analysts/UserList
    /HR/Employees/EU/UserList

参数层次结构规范了创建参数的方式,而且使得随时间的推移管理参数更为容易。参数层次结构还可帮助您为配置任务确定正确参数。这可帮助您避免使用相同的配置数据创建多个参数。

您可以创建一个层次结构,允许您在不同的环境中共享参数,如以下示例所示,这些示例在开发和暂存环境中使用密码。

/DevTest/MyApp/database/db_password

然后您可以为生产环境创建一个唯一密码,如以下示例所示:

/prod/MyApp/database/db_password

您无需指定参数层次结构。您可以在第一级创建参数。它们叫做参数。考虑到向后兼容性,在发布层次结构之前在 Parameter Store 中创建的所有参数都是根参数。系统将以下两个参数视为根参数。

/parameter-name

parameter-name

有关如何使用参数层次结构的示例,请参阅使用层次结构管理参数

查询层次结构中的参数

使用层次结构的另一个好处是,能够通过使用 GetParametersByPath API 操作查询层次结构中的所有参数。例如,如果您从 AWS CLI 执行以下命令,系统将返回 IIS 级别中的所有参数。

aws ssm get-parameters-by-path --path /Dev/Web/IIS

要查看层次结构中解密的 SecureString 参数,请指定路径和 --with-decryption 参数,如以下示例所示。

aws ssm get-parameters-by-path --path /Prod/ERP/SAP --with-decryption

使用层次结构限制 IAM 权限

通过对 Parameter Store API 操作使用层次结构和 AWS Identity and Access Management (IAM) 策略,您可以提供或限制对层次结构的一个级别中所有参数的访问权限。以下示例策略允许用户或组仅访问层次结构的 Oracle 级别中的参数对应的 DescribeParameter API 操作。

Copy
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:*" ], "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/*" }, { "Effect": "Deny", "Action": [ "ssm:GetParametersByPath" ], "Condition": { "StringEquals": { "ssm:Recursive": [ "true" ] } }, "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/Dev/ERP/Oracle/*" }, { "Effect": "Deny", "Action": [ "ssm:PutParameter" ], "Condition": { "StringEquals": { "ssm:Overwrite": [ "false" ] } }, "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/*" } ] }

创建 Systems Manager 参数

您可以使用 AWS CLI、AWS Tools for Windows PowerShell 或 Amazon EC2 控制台创建参数,如此部分中所述。

当您创建参数时,需要指定以下信息:

  • 名称:(必填) 指定用于识别您的参数的名称。请注意以下有关 Systems Manager 参数名称的要求和限制:

    • 参数名称区分大小写。

    • 在您的 AWS 账户中,参数名称必须是唯一的。例如,Systems Manager 将以下两个参数视为不同的参数:

      • /CMH/TestParam1

      • /TestParam1

      以下示例也是唯一的:

      • /CMH/TestParam1/Logpath1

      • /CMH/TestParam1

      以下示例不是唯一的:

      • /TestParam1

      • TestParam1

    • 参数名称不得以“aws”或“ssm”(不区分大小写) 作为前缀。例如,awsTestParameter、SSM-testparameter 或 /aws/testparam1 将失败并引发异常。

    • 参数名称只能包含下列符号和字母:

      a-zA-Z0-9_.-/

    • 参数名称不能包含空格。

    • 如果指定参数层次结构,则层次结构可以具有最多五个级别的深度。可以在该层次结构的任何级别定义参数。以下两个例子都是有效的:

      /Level-1/Level-2/Level-3/Level-4/Level-5/parameter-name

      /Level-1/parameter-name

      尝试创建以下参数将失败并引发 HierarchyLevelLimitExceededException 异常:

      /Level-1/Level-2/Level-3/Level-4/Level-5/Level-6/parameter-name

  • 数据类型:(必填) 指定数据类型,以定义系统使用参数的方式。Parameter Store 当前支持以下数据类型:StringStringListSecureString

    注意

    StringList 中的项目必须用逗号 (,) 分隔。不能使用其他标点符号或特殊字符对列表中的项目进行转义。如果您有需要逗号的参数值,则使用 String 数据类型。

  • 描述 (可选,但建议):键入描述,以帮助您识别参数及其预期用途。

  • :(必填) 您的参数值。

  • 密钥 IDKey ID仅适用于使用 SecureString 数据类型的参数。Key ID 可以是自动分配给您的 AWS 账户的默认 AWS Key Management Service (AWS KMS) 密钥,也可以是自定义密钥。请注意以下几点:

    • 要使用默认 AWS KMS 密钥,请选择 SecureString 类型数据,而且在创建参数时不要指定 Key ID。系统会自动用您的默认 KMS 密钥填充 Key ID

    • 要使用自定义 KMS 密钥,请选择带有 Key ID 参数的 SecureString 数据类型。

注意

您可以使用句点 "." 或下划线 "_" 来分组类似参数。例如,您可以按照如下所示对参数进行分组:prod.db.string 和 prod.domain.password。

创建参数后,您可以在 SSM 文档、命令或脚本中使用以下语法指定该参数 (括号之间没有空格):

{{ssm:parameter_name}} 或 {{ ssm:parameter_name }}

注意

Systems Manager 参数的名称不得以“ssm”或“aws”作为前缀,但是当您在 SSM 文档或命令中指定参数时,语法中就会包括“ssm”,如以下示例所示。

有效:{{ssm:addUsers}}

无效:{{ssm:ssmAddUsers}}。

使用 AWS CLI 创建 Systems Manager 参数

使用以下过程创建一个使用 StringStringList 数据类型的参数。使用 AWS CLI 创建 SecureString 参数的过程在本主题的稍后部分介绍。

注意

参数只在创建它的区域可用。

使用 AWS CLI 创建 StringStringList 参数

  1. 打开 AWS CLI 并运行以下命令指定您的凭证和区域。您必须在 Amazon EC2 中具有管理员权限,或者您必须在 AWS Identity and Access Management (IAM) 中被授予相应权限。

    Copy
    aws configure

    系统将提示您指定以下内容。

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  2. 执行以下命令创建一个参数。

    Copy
    aws ssm put-parameter --name "a_name" --value "a value, or a comma-separated list of values" --type String or StringList

    如果成功,则命令没有输出。

    下面是使用 StringList 数据类型的示例。

    Copy
    aws ssm put-parameter --name /IAD/ERP/Oracle/addUsers --value "Milana,Mariana,Mark,Miguel" --type StringList

    注意

    StringList 中的项目必须用逗号 (,) 分隔。不能使用其他标点符号或特殊字符对列表中的项目进行转义。如果您有需要逗号的参数值,则使用 String 数据类型。

  3. 执行以下命令验证参数的详细信息。

    Copy
    aws ssm get-parameters --name "the name you specified"

    下面是使用前面示例中指定的名称的示例。

    Copy
    aws ssm get-parameters --name "/IAD/ERP/Oracle/addUsers"

使用 AWS CLI 创建 SecureString 参数

  1. 打开 AWS CLI 并运行以下命令指定您的凭证和区域。您必须在 Amazon Elastic Compute Cloud (Amazon EC2) 中具有管理员权限,或者您必须在 IAM 中被授予相应权限。有关更多信息,请参阅 Systems Manager 先决条件

    Copy
    aws configure

    系统将提示您指定以下内容。

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  2. 执行以下命令创建一个参数。

    Copy
    aws ssm put-parameter --name "a_name" --value "a value" --type SecureString --key-id "a custom KMS key ID"

    注意

    要使用分配给您的账户的默认 AWS KMS 密钥,请从命令中删除 key-id 参数。

    下面是对密码和自定义 AWS KMS 密钥使用模糊名称 (elixir3131) 的示例。

    Copy
    aws ssm put-parameter --name /Finance/Payroll/elixir3131 --value "P@sSwW)rd" --type SecureString --key-id arn:aws:kms:us-east-1:123456789012:key/1a2b3c4d-1a2b-1a2b-1a2b-1a2b3c4d5e
  3. 执行以下命令验证参数的详细信息。

    Copy
    aws ssm get-parameters --name "the name you specified" --with-decryption

    注意

    如果您不指定 with-decryption 参数,或者如果您指定no-with-decryption 参数,命令会返回加密的 GUID。

有关使用 AWS CLI 创建参数的更多信息,请参阅在命令中创建和使用参数 (AWS CLI)

使用 AWS Tools for Windows 创建 Systems Manager 参数

使用以下过程创建一个使用 StringStringList 数据类型的参数。使用 AWS Tools for Windows 创建 SecureString 参数的过程在本主题的稍后部分介绍。

注意

参数只在创建它的区域可用。

使用 AWS Tools for Windows 创建 StringStringList 参数

  1. 打开 AWS Tools for Windows PowerShell 并执行以下命令指定您的凭证。您必须在 Amazon EC2 中具有管理员权限,或者您必须在 IAM 中被授予相应权限。有关更多信息,请参阅 Systems Manager 先决条件

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. 执行以下命令为 PowerShell 会话设置区域。该示例使用 us-east-2 区域。

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. 执行以下命令创建一个参数。

    Copy
    Write-SSMParameter -Name "a name" -Value "a value, or a comma-separated list of values" -Type "String or StringList"

    如果成功,则命令没有输出。

    注意

    StringList 中的项目必须用逗号 (,) 分隔。不能使用其他标点符号或特殊字符对列表中的项目进行转义。如果您有需要逗号的参数值,则使用 String 数据类型。

    下面是使用 String 数据类型的示例。

    Copy
    Write-SSMParameter -Name "/IAD/Web/SQL/IPaddress" -Value "99.99.99.999" -Type "String"
  4. 执行以下命令验证参数的详细信息。

    Copy
    (Get-SSMParameterValue -Name "the name you specified").Parameters

使用 AWS Tools for Windows 创建 SecureString 参数

  1. 打开 AWS Tools for Windows PowerShell 并执行以下命令指定您的凭证。您必须在 Amazon EC2 中具有管理员权限,或者您必须在 IAM 中被授予相应权限。有关更多信息,请参阅 Systems Manager 先决条件

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. 执行以下命令为 PowerShell 会话设置区域。该示例使用 us-east-2 区域。

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. 执行以下命令创建一个参数。

    Copy
    Write-SSMParameter -Name "a name" -Value "a value" -Type "SecureString" -KeyId "a custom KMS key ID"

    如果成功,则命令没有输出。

    注意

    要使用分配给您的账户的默认 AWS KMS 密钥,请从命令中删除 -KeyId 参数。

    下面是对密码和用户默认 KMS 密钥使用模糊名称 (elixir3131) 的示例。

    Copy
    Write-SSMParameter -Name "/Finance/Payroll/elixir3131" -Value "P@sSwW)rd" -Type "SecureString"
  4. 执行以下命令验证参数的详细信息。

    Copy
    (Get-SSMParameterValue -Name "the name you specified" –WithDecryption $true).Parameters

使用 Amazon EC2 控制台创建 Systems Manager 参数

执行以下过程,使用 Amazon EC2 控制台创建 Systems Manager 参数。

注意

参数只在创建它的区域可用。

使用 EC2 控制台创建参数

  1. 打开 Amazon EC2 控制台,展开导航窗格中的 Systems Manager Shared Resources,然后选择 Parameter Store

  2. 选择创建参数

  3. 对于 Name,键入层次结构和参数名称。例如,键入 /Test/helloWorld

  4. Description 框中,键入用于将此参数标识为测试参数的描述。

  5. 对于 Type,选择 StringString ListSecure String

  6. Value 框中,键入一个值。例如,键入 MyFirstParameter。如果您选择 Secure String,则在您键入时值会被掩蔽。

  7. 选择创建参数。在系统创建参数后,选择 Close

  8. 在参数列表中,选择您刚创建的参数。验证 Description 选项卡上的详细信息。如果您创建了 SecureString 参数,请选择 Show 查看未加密值。

标记 Systems Manager 参数

使用 AddTagsToResource API 向资源 (例如 Amazon EC2 实例、Systems Manager 维护时段和 Systems Manager 参数) 添加标签。标签用于对参数进行组织。例如,可以为特定环境、部门或用户和组标记参数。在标记参数之后,可以通过创建一个指定用户可访问的标签的 IAM 策略来限制对该参数的访问权限。有关使用标签限制对参数的访问权限的更多信息,请参阅使用标签控制对参数的访问权限

有关提供 Systems Manager 的区域的信息,请参阅区域

使用 AWS CLI 标记参数

  1. 打开 AWS CLI 并运行以下命令指定您的凭证和区域。您必须在 Amazon EC2 中具有管理员权限,或者您必须在 IAM 中被授予相应权限。有关更多信息,请参阅 Systems Manager 先决条件

    Copy
    aws configure

    系统将提示您指定以下内容。

    Copy
    AWS Access Key ID [None]: key_name AWS Secret Access Key [None]: key_name Default region name [None]: region Default output format [None]: ENTER
  2. 执行以下命令列出您可以标记的参数。

    Copy
    aws ssm describe-parameters

    记下您想标记的参数的名称。

  3. 执行以下命令标记一个参数。

    Copy
    aws ssm add-tags-to-resource --resource-type "Parameter" --resource-id "the parameter name" --tags "Key=a key, for example Environment,Value=a value, for example TEST"

    如果成功,则命令没有输出。

  4. 执行以下命令验证参数标签。

    Copy
    aws ssm list-tags-for-resource --resource-type "Parameter" --resource-id "the parameter name"

使用 AWS Tools for Windows 标记参数

  1. 打开 AWS Tools for Windows PowerShell 并执行以下命令指定您的凭证。您必须在 Amazon EC2 中具有管理员权限,或者您必须在 IAM 中被授予相应权限。有关更多信息,请参阅 Systems Manager 先决条件

    Copy
    Set-AWSCredentials –AccessKey key_name –SecretKey key_name
  2. 执行以下命令为 PowerShell 会话设置区域。该示例使用 us-east-2 区域。目前在以下区域提供 Systems Manager。

    Copy
    Set-DefaultAWSRegion -Region us-east-2
  3. 执行以下命令列出您可以标记的参数。

    Copy
    Get-SSMParameterList
  4. 执行以下命令标记一个参数。

    Copy
    $tag1 = New-Object Amazon.SimpleSystemsManagement.Model.Tag $tag1.Key = "Environment" $tag1.Value = "TEST" Add-SSMResourceTag -ResourceType "Parameter" -ResourceId "the parameter name" -Tag $tag1

    如果成功,则命令没有输出。

  5. 执行以下命令验证参数标签。

    Copy
    Get-SSMResourceTag -ResourceType "Parameter" -ResourceId "the parameter name"