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.
We recommend that you use common parameters to store non-sensitive data. For more information, see the "Use encryption parameters in Cloud Assistant commands" section of this topic.
We recommend that you use encryption parameters to store sensitive data, such as passwords. For more information, see the "Use encryption parameters in Cloud Assistant commands" section of this topic.
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.
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
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****" }
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:
Log on to the ECS instance.
For more information, see Connect to a Linux instance by using a password or key.
Run the following command to check whether user01 is added:
cat /etc/passwd |grep user01
The following command output indicates that user01 is added.
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.
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.
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
NoteThe password used in this example is for reference only. Do not use it in the online environment.
Bind a RAM role to the ECS instance.
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.
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
, andGetSecretParameter
. Sample policy:{ "Version": "1", "Statement": [ { "Action": [ "kms:GetSecretValue" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "oos:GetParameters", "oos:GetSecretParameters", "oos:GetParameter", "oos:GetSecretParameter" ], "Effect": "Allow", "Resource": "*" } ] }
Attach the AxtParametersRamPolicy policy to the AxtParametersRamRole role. For more information, see Grant permissions to a RAM role.
Bind the AxtParametersRamRole role to the ECS instance. For more information, see Attach an instance RAM role to an ECS instance.
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****" }
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.