All Products
Search
Document Center

Elastic Compute Service:Use OOS Parameter Store in Cloud Assistant commands

Last Updated:Dec 25, 2023

You can use custom parameters in Cloud Assistant commands to write scripts and improve the reusability of commands. CloudOps Orchestration Service (OOS) provides the Parameter Store feature that allows you to configure common parameters and encryption parameters. You can use the Parameter Store feature of OOS in Cloud Assistant commands to manage custom parameters.

Prerequisites

  • The Elastic Compute Service (ECS) instance on which you want to run Cloud Assistant commands meets the following requirements:

    • The instance is in the Running (Running) state.

    • Cloud Assistant Agent is installed on the instance. For more information, see Install Cloud Assistant Agent.

  • OOS is activated. For more information, see Introduction to OOS.

  • Key Management Service (KMS) is activated if you want to use encryption parameters. For more information, see What is Key Management Service?

Background information

You can use {{parameterName}} to indicate a custom parameter in Cloud Assistant commands. For example, you can run the adduser {{username}} command to add a username to a Linux instance. In the command, username indicates a custom parameter. You can specify its value in the Parameters value in a request to the RunCommand or InvokeCommand operation.

You can reference parameters in OOS Parameter Store for flexible use. Parameters in Parameter Store are classified into common parameters and encryption parameters. Cloud Assistant uses {{oos:}} to define common parameters and {{oos-secret:}} to define encryption parameters.

Use common parameters in Cloud Assistant commands

If you run a Cloud Assistant command as a Resource Access Management (RAM) user, attach a policy to grant required permissions to the RAM user. For more information, see Create custom policies and Grant permissions to a RAM user. The RAM user must be granted the permissions to call API operations related to Cloud Assistant and related to OOS Parameter Store to run Cloud Assistant commands with common parameters. Sample policy:

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DescribeInstances",
                "ecs:DescribeTagKeys",
                "ecs:DescribeTags",
                "ecs:CreateCommand",
                "ecs:DescribeCommands",
                "ecs:InvokeCommand",
                "ecs:RunCommand",
                "ecs:DeleteCommand",
                "ecs:DescribeInvocations",
                "ecs:DescribeInvocationResults",
                "ecs:StopInvocation",
                "ecs:DescribeCloudAssistantStatus",
                "ecs:InstallCloudAssistant",
                "oos:GetParameters",
                "oos:GetParameter"
            ],
            "Resource": "*"
        }
    ],
    "Version": "1"
}

If your command does not involve sensitive data, you can use common parameters. This section describes how to use common parameters of OOS Parameter Store in a Cloud Assistant command. In the example, a user is added to a Linux instance.

  1. Create common parameters by using OOS Parameter Store. For more information, see Common parameters.

    The following table provides an example on how to add username as a common parameter. The value of username is set to user01. You can specify the value based on your business requirements.

    Parameter

    Example

    Parameter Name

    username

    Parameter Type

    String

    Value

    user01

  2. Use ECS SDK for Java to call the RunCommand operation to run a Cloud Assistant command.

    The following code provides an example on how to create a user for a Linux instance by running a Cloud Assistant command. The command content is adduser {{oos:username}}. In this command, {{oos:username}} indicates that the username is specified by the username parameter.

    import com.aliyuncs.DefaultAcsClient;
    import com.aliyuncs.IAcsClient;
    import com.aliyuncs.ecs.model.v20140526.RunCommandRequest;
    import com.aliyuncs.ecs.model.v20140526.RunCommandResponse;
    import com.aliyuncs.exceptions.ClientException;
    import com.aliyuncs.exceptions.ServerException;
    import com.aliyuncs.profile.DefaultProfile;
    import com.google.gson.Gson;
    
    import java.util.ArrayList;
    import java.util.List;
    
    public class AddUserName {
        public static void main(String[] args) {
            // Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime. 
            // If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code provides an example on how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use Security Token Service (STS) tokens, which provide higher security. 
            DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            IAcsClient client = new DefaultAcsClient(profile);
    
            RunCommandRequest request = new RunCommandRequest();
            // Specify the region ID of the instance. 
            request.setRegionId("cn-hangzhou");
            // Specify the language of the Cloud Assistant command. In this example, shell is used. 
            request.setType("RunShellScript");
            // Specify the Cloud Assistant command. In this example, the specified command is used to add a user to a Linux instance, and the username of the user is specified by the username common parameter from OOS Parameter Store. 
            request.setCommandContent("adduser {{oos:username}}");
    
            List<String> instanceIdList = new ArrayList<String>();
            // Specify the ID of the instance on which to run the Cloud Assistant command. 
            instanceIdList.add("i-bp1dktddjsg7oh11****");
            request.setInstanceIds(instanceIdList);
            // Configure the Cloud Assistant command to support custom parameters. 
            request.setEnableParameter(true);
    
            try {
                RunCommandResponse response = client.getAcsResponse(request);
                System.out.println(new Gson().toJson(response));
            } catch (ServerException e) {
                e.printStackTrace();
            } catch (ClientException e) {
                System.out.println("ErrCode:" + e.getErrCode());
                System.out.println("ErrMsg:" + e.getErrMsg());
                System.out.println("RequestId:" + e.getRequestId());
            }
        }
    }

    The following response is returned:

    {
        "requestId": "67D1BD1A-0D08-42C3-AFD9-A3397CD67CD1",
        "commandId": "c-hz01hkgs19i****",
        "invokeId": "t-hz01hkgs19s****"
    }
  3. Check the output of the Cloud Assistant command.

    You can log on to the ECS instance to check whether the Cloud Assistant command has taken effect. Perform the following steps to check whether user01 is added to the Linux instance:

    1. Log on to the ECS instance.

      For more information, see Connect to a Linux instance by using a password or key.

    2. Run the following command to check whether user01 is added:

      cat /etc/passwd |grep user01

      The following command output indicates that user01 is added.新增user01

Use encryption parameters in Cloud Assistant commands

If you run a Cloud Assistant command as a RAM user, attach a policy to grant required permissions to the RAM user. For more information, see Create custom policies and Grant permissions to a RAM user. The RAM user must be granted the permissions to call API operations related to Cloud Assistant, API operations related to OOS Parameter Store, and KMS API operations to run Cloud Assistant commands with encryption parameters. Sample policy:

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecs:DescribeInstances",
                "ecs:DescribeTagKeys",
                "ecs:DescribeTags",
                "ecs:CreateCommand",
                "ecs:DescribeCommands",
                "ecs:InvokeCommand",
                "ecs:RunCommand",
                "ecs:DeleteCommand",
                "ecs:DescribeInvocations",
                "ecs:DescribeInvocationResults",
                "ecs:StopInvocation",
                "ecs:DescribeCloudAssistantStatus",
                "ecs:InstallCloudAssistant",
                "oos:GetParameters",
                "oos:GetSecretParameters",
                "oos:GetParameter",
                "oos:GetSecretParameter",
                "kms:GetSecretValue"
            ],
            "Resource": "*"
        }
    ],
    "Version": "1"
}

If your command involves sensitive data such as server passwords and database passwords, we recommend that you use encryption parameters to improve the security of your command. This section describes how to use encryption parameters from OOS Parameter Store in a Cloud Assistant command. In the example, the password of a user for a Linux instance is changed.

Note

Before you perform the following operations, make sure that a user is added to the instance. For information about how to add users to Linux instances, see the "Use common parameters in Cloud Assistant commands" section of this topic.

  1. Create encryption parameters and common parameters by using OSS Parameter Store. For more information, see Manage encryption parameters and Common parameters.

    The following tables provide examples of creating a username parameter and a password parameter in OOS Parameter Store.

    • Add username as a common parameter in OOS Parameter Store and set the value of username to user01. You can specify the value based on your business requirements.

      Parameter

      Example

      Parameter Name

      username

      Parameter Type

      String

      Value

      user01

    • Add password as an encryption parameter in OOS Parameter Store and set the value of password to MyPassword01. You can specify the value based on your business requirements.

      Parameter

      Example

      Parameter Name

      password

      KMS Key ID

      Default Service CMK

      Value

      MyPassword01

      Note

      The password used in this example is for reference only. Do not use it in the online environment.

  2. Bind a RAM role to the ECS instance.

    1. Create a RAM role. For more information, see Create a RAM role for a trusted Alibaba Cloud service.

      The following table describes the parameters that you need to configure.

      Parameter

      Example

      Select Trusted Entity

      Select Alibaba Cloud Service.

      Role Type

      Select Normal Service Role.

      Role Name

      AxtParametersRamRole

      Select Trusted Service

      Select Elastic Compute Service from the drop-down list.

    2. Create a policy for the RAM role. For more information, see Create custom policies.

      In this example, a policy named AxtParametersRamPolicy is created. The policy grants permissions to call the following KMS and OOS API operations: GetSecretValue, GetParameters, GetSecretParameters, GetParameter, and GetSecretParameter. Sample policy:

      {
          "Version": "1",
          "Statement": [
              {
                  "Action": [
                      "kms:GetSecretValue"
                  ],
                  "Resource": "*",
                  "Effect": "Allow"
              },
              {
                  "Action": [
                      "oos:GetParameters",
                      "oos:GetSecretParameters",
                      "oos:GetParameter",
                      "oos:GetSecretParameter"
                  ],
                  "Effect": "Allow",
                  "Resource": "*"
              }
          ]
      }
    3. Attach the AxtParametersRamPolicy policy to the AxtParametersRamRole role. For more information, see Grant permissions to a RAM role.

    4. Bind the AxtParametersRamRole role to the ECS instance. For more information, see Attach an instance RAM role to an ECS instance.

  3. Use ECS SDK for Java to call the RunCommand operation to run a Cloud Assistant command.

    The following example demonstrates how to change the password of a user for a Linux instance by running a Cloud Assistant command. Sample command:

     "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin"

    In the preceding command, {{oos-secret:password}} indicates that the new password is specified by the password encryption parameter from OOS Parameter Store and {{oos:username}} indicates that the username is specified by the username common parameter from OOS Parameter Store.

    import com.aliyuncs.DefaultAcsClient;
    import com.aliyuncs.IAcsClient;
    import com.aliyuncs.ecs.model.v20140526.RunCommandRequest;
    import com.aliyuncs.ecs.model.v20140526.RunCommandResponse;
    import com.aliyuncs.exceptions.ClientException;
    import com.aliyuncs.exceptions.ServerException;
    import com.aliyuncs.profile.DefaultProfile;
    import com.google.gson.Gson;
    
    import java.util.ArrayList;
    import java.util.List;
    
    public class ChangePassword {
        public static void main(String[] args) {
            // Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured in the code runtime. 
            // If the project code is leaked, the AccessKey pair may be leaked and security issues may occur on all resources of your account. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. We recommend that you use STS tokens, which provide higher security. 
            DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            IAcsClient client = new DefaultAcsClient(profile);
    
            RunCommandRequest request = new RunCommandRequest();
            // Specify the region ID of the instance. 
            request.setRegionId("cn-hangzhou");
            // Specify the language of the Cloud Assistant command. In this example, shell is used. 
            request.setType("RunShellScript");
            // Specify the content of the Cloud Assistant command. In this example, the specified command is used to change the password of a specified user for the Linux instance, and the username is specified by the username parameter and the password is specified by the password parameter. 
            request.setCommandContent(
                    "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin");
    
            List<String> instanceIdList = new ArrayList<String>();
            instanceIdList.add("i-bp1dktddjsg7oh11****");
            request.setInstanceIds(instanceIdList);
            request.setEnableParameter(true);
    
            try {
                RunCommandResponse response = client.getAcsResponse(request);
                System.out.println(new Gson().toJson(response));
            } catch (ServerException e) {
                e.printStackTrace();
            } catch (ClientException e) {
                System.out.println("ErrCode:" + e.getErrCode());
                System.out.println("ErrMsg:" + e.getErrMsg());
                System.out.println("RequestId:" + e.getRequestId());
            }
        }
    
    }

    The following response is returned:

    {
        "requestId": "C73D7B90-6503-4DB4-844C-9412AC55ECC5",
        "commandId": "c-hz01hnyd4e8****",
        "invokeId": "t-hz01hnyd4ed****"
    }
  4. Check the output of the Cloud Assistant command.

    You can log on to the ECS instance by using the new password to check whether the Cloud Assistant command has taken effect. For more information, see Connect to a Linux instance by using a password or key.