Use custom parameters in Cloud Assistant commands - Elastic Compute Service

Cloud Assistant lets you use custom parameters or built-in environment parameters to customize command content, similar to using template variables. For more convenient and secure management, you can also combine Cloud Assistant commands with the parameter store of CloudOps Orchestration Service (OOS). This topic describes how to use these different types of parameters.

Prerequisites

The instance must be in the Running state.
The Cloud Assistant Agent must be installed on the instance. The Cloud Assistant Agent version must be one of the following versions or later. For more information, see Install the Cloud Assistant Agent.
- Linux: 2.2.3.309
- Windows: 2.1.3.309

Usage notes

Using custom parameters when running Cloud Assistant commands by calling an API
When you call the RunCommand or InvokeCommand operation to run a Cloud Assistant command, you must set the EnableParameter parameter to true to enable custom parameters. Then, you can define the custom parameters in the CommandContent parameter using the {{}} format. The following limits apply to custom parameters:
- Spaces and line feeds before and after a parameter name within {{}} are ignored.
- You can specify a maximum of 20 custom parameters.
- Custom parameter names must be a case-insensitive combination of a-zA-Z0-9-_.
- The acs:: prefix is reserved for built-in parameters and cannot be used for custom parameters. For more information about supported built-in environment parameters, see Built-in environment parameters.
- A single parameter name cannot exceed 64 bytes in length.
Using custom parameters in the Cloud Assistant console
The Cloud Assistant console supports only built-in environment parameters. For more information about the supported built-in environment parameters, see Built-in environment parameters.

Use custom parameters

Using custom parameters in Cloud Assistant commands provides greater flexibility for your scripts and improves command reusability. For example, if you have a scheduled script on a Linux instance, you can use a custom parameter to flexibly set the execution frequency.

Java

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.teaopenapi.models.Config;

import java.util.Collections;
import java.util.List;


public class EcsService {

    /**
     * Get AccessKeyId and AccessKeySecret from environment variables.
     */
    private static final String ACCESS_KEY_ID = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static final String ACCESS_KEY_SECRET = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args_) throws Exception {
        // Region ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(ACCESS_KEY_ID)
                .setAccessKeySecret(ACCESS_KEY_SECRET)
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        List<String> instanceIds = Collections.singletonList("i-bp1h23xufsi8XXXXXXXX");
        // The content of the command to run. Replace /path/to/your/script.sh with the script to run.
        String commandContent = "#!/bin/bash\n " +
                "(crontab -l 2>/dev/null; echo \"{{cron}} /path/to/your/script.sh\") | crontab -";
        // Command execution timeout period.
        long commandTimeOut = 60;
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // Enable the custom parameter feature.
        request.setEnableParameter(true);
        // Set the value of the custom parameter cron.
        request.setParameters(Collections.singletonMap("cron", "0 2 * * *"));
        request.setCommandContent(commandContent);
        request.setInstanceId(instanceIds);
        request.setTimeout(commandTimeOut);
        ecsClient.runCommand(request);
    }
}

Python

import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # Region ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # The ID of the ECS instance on which to run the command.
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # The content of the command to run. /path/to/your/script.sh is the script to run.
    command_content = "#!/bin/bash\n (crontab -l 2>/dev/null; echo \"{{cron}} /path/to/your/script.sh\") | crontab -"
    # The command execution timeout period in seconds.
    command_timeout = 60
    # The Shell command for Linux instances: RunShellScript.
    command_type = "RunShellScript"

    # Run the command.
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # Enable the custom parameter feature.
    request.enable_parameter = True
    # Set the value of the custom parameter.
    request.parameters = {"cron": "0 2 * * *"}
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

Use OOS parameters

OOS provides a parameter store that supports standard and encrypted parameters. Using the OOS parameter store with Cloud Assistant commands, you can manage custom parameters more conveniently and securely. Before you can use the OOS parameter store, you must activate the OOS service. For more information, see What is CloudOps Orchestration Service?

Use standard parameters

If your command does not involve sensitive data, you can use standard parameters. This section provides an example of how to use a standard parameter from the OOS parameter store in a Cloud Assistant command to add a new user to a Linux instance.

Create a standard parameter in the OOS parameter store. For more information, see Standard parameters.
The following example shows how to add a standard parameter named username with the value user01. You can change the value as needed.
Name
Example value
Parameter Name
username
Parameter Type
String
Value
user01

Call an API to run the Cloud Assistant command.

You can use a Resource Access Management (RAM) user to run a Cloud Assistant command to create a new user on a Linux instance. The command content is adduser {{oos:username}}. In this command, {{oos:username}} specifies the new username, which is defined by the standard parameter `username` in the OOS parameter store.

Note

You must grant the RAM user the required permissions to run Cloud Assistant commands that contain OOS standard parameters. For more information about the access policy, see Use OOS standard parameters in commands.

Java

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.ecs20140526.models.RunCommandResponse;
import com.aliyun.teaopenapi.models.Config;

import java.util.Arrays;
import java.util.List;

public class EcsService {
    public static void main(String[] args_) throws Exception {
        // Region ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // Enable the custom parameter feature.
        request.setEnableParameter(true);
        // The content of the command to run.
        String commandContent = "adduser {{oos:username}}";
        request.setCommandContent(commandContent);
        List<String> instanceIds = Arrays.asList("i-bp1h23xufsi8XXXXXXXX");
        request.setInstanceId(instanceIds);
        // Command execution timeout period.
        request.setTimeout(60L);
        RunCommandResponse response = ecsClient.runCommand(request);
        System.out.println(new Gson().toJson(response.getBody()));
    }
}

Python

import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # Region ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # The ID of the ECS instance on which to run the command.
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # The content of the command to run.
    command_content = "adduser {{oos:username}}"
    # The command execution timeout period in seconds.
    command_timeout = 60
    # The Shell command for Linux instances: RunShellScript.
    command_type = "RunShellScript"

    # Run the command.
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # Enable the custom parameter feature.
    request.enable_parameter = True
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

Use encrypted parameters

If your parameters involve sensitive data, such as passwords, you can use encrypted parameters. To use encrypted parameters, you must first activate Key Management Service (KMS). For more information, see What is Key Management Service?

Create an encrypted parameter and a standard parameter in the OOS parameter store. For more information, see Encrypted parameters and Standard parameters.

The following example shows how to create a username parameter username and a password parameter password in the OOS parameter store.

Add a standard parameter named username with the value user01. You can change the value as needed.
Name
Example value
Parameter Name
username
Parameter Type
String
Value
user01

Add an encrypted parameter named password with the value MyPassword01. You can change the value as needed.

Name	Example value
Parameter Name	password
KMS Key ID	Default Service CMK Note The example value is a free service key generated by KMS. Select a key as needed.
Value	MyPassword01 Note This password is for demonstration purposes only. Do not use it in a production environment.

Attach a RAM role to the target ECS instance.
1. Create a RAM role. For more information, see Create a RAM role for a trusted Alibaba Cloud service.
  The following table shows an example configuration.
  Name
  Example
  Principal Type
  Select Cloud Service.
  Principal Name
  Elastic Compute Service / ECS.
  Click OK. Set Role Name to AxtParametersRamRole.
2. Create an access policy for the RAM role. For more information, see Create a custom policy.
  Example access policy
  Set the Policy Name to AxtParametersRamPolicy. The policy content is shown below. This policy grants permissions to call the GetSecretValue, GetParameters, GetSecretParameters, GetParameter, and GetSecretParameter API operations for KMS and OOS.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "kms:GetSecretValue",
                "oos:GetParameters",
                "oos:GetSecretParameters",
                "oos:GetParameter",
                "oos:GetSecretParameter"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. Grant permissions to the RAM role (AxtParametersRamRole) by attaching the policy (AxtParametersRamPolicy). For more information, see Grant permissions to a RAM role.
4. Attach the RAM role (AxtParametersRamRole) to the target ECS instance. For more information, see Create a RAM role and attach it to an ECS instance.

Call an API to run the Cloud Assistant command.

You can use a RAM user to run a Cloud Assistant command that changes a user password on a Linux instance. The command content is as follows:

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

In this command, {{oos-secret:password}} specifies the new password, which is defined by the encrypted parameter password in the OOS parameter store. {{oos:username}} specifies the username, which is defined by the standard parameter username in the OOS parameter store.

Note

You must grant the RAM user the required permissions to run Cloud Assistant commands that contain OOS encrypted parameters. For more information about the access policy, see Use OOS encrypted parameters in commands.

Java

import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.RunCommandRequest;
import com.aliyun.ecs20140526.models.RunCommandResponse;
import com.aliyun.teaopenapi.models.Config;
import com.google.gson.Gson;

import java.util.Arrays;
import java.util.List;

public class EcsService {
    public static void main(String[] args_) throws Exception {
        // Region ID
        String regionId = "cn-hangzhou";
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setRegionId(regionId);
        Client ecsClient = new Client(config);
        RunCommandRequest request = new RunCommandRequest();
        request.setRegionId(regionId);
        request.setType("RunShellScript");
        // Enable the custom parameter feature.
        request.setEnableParameter(true);
        // The content of the command to run.
        String commandContent = "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin";
        request.setCommandContent(commandContent);
        List<String> instanceIds = Arrays.asList("i-bp1h23xufsi8XXXXXXXX");
        request.setInstanceId(instanceIds);
        // Command execution timeout period.
        request.setTimeout(60L);
        RunCommandResponse response = ecsClient.runCommand(request);
        System.out.println(new Gson().toJson(response.getBody()));
    }
}

Python

import json
import os

from alibabacloud_ecs20140526 import models as ecs_20140526_models
from alibabacloud_ecs20140526.client import Client as Ecs20140526Client
from alibabacloud_tea_openapi import models as open_api_models

ACCESS_KEY_ID = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
ACCESS_KEY_SECRET = os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")


def get_ecs_client(region_id):
    config = open_api_models.Config(
        access_key_id=ACCESS_KEY_ID,
        access_key_secret=ACCESS_KEY_SECRET,
        region_id=region_id
    )
    return Ecs20140526Client(config)


def main():
    # Region ID
    region_id = "cn-hangzhou"
    client = get_ecs_client(region_id)
    # The ID of the ECS instance on which to run the command.
    instance_ids = ["i-bp1h23xufsi8XXXXXXXX"]
    # The content of the command to run.
    command_content = "echo '{{oos-secret:password}}' | passwd '{{oos:username}}' --stdin"
    # The command execution timeout period in seconds.
    command_timeout = 60
    # The Shell command for Linux instances: RunShellScript.
    command_type = "RunShellScript"

    # Run the command.
    request = ecs_20140526_models.RunCommandRequest()
    request.region_id = region_id
    request.type = command_type
    # Enable the custom parameter feature.
    request.enable_parameter = True
    request.command_content = command_content
    request.instance_id = instance_ids
    request.timeout = command_timeout
    response = client.run_command(request)
    print("execute_command result:", json.dumps(response.to_map()['body']))


if __name__ == "__main__":
    main()

Built-in environment parameters

You can use built-in environment parameters in the same way as custom parameters. When you run a command, you do not need to manually assign values to these parameters. Cloud Assistant automatically replaces these parameters with their corresponding values during execution.

Built-in environment parameter	Description
{{ACS::RegionId}}	The region ID.
{{ACS::AccountId}}	The UID of the Alibaba Cloud account.
{{ACS::InstanceId}}	The instance ID. If you run a command on multiple instances and want to specify `{{ACS::InstanceId}}` as a built-in environment parameter, make sure that the Cloud Assistant Agent version is not earlier than the following versions: Linux: 2.2.3.309 Windows: 2.1.3.309
{{ACS::InstanceName}}	The instance name. If you run a command on multiple instances and want to specify `{{ACS::InstanceName}}` as a built-in environment parameter, make sure that the Cloud Assistant Agent version is not earlier than the following versions: Linux: 2.2.3.344 Windows: 2.1.3.344
{{ACS::InvokeId}}	The command execution ID. If you want to specify `{{ACS::InvokeId}}` as a built-in environment parameter, make sure that the Cloud Assistant Agent version is not earlier than the following versions: Linux: 2.2.3.309 Windows: 2.1.3.309
{{ACS::CommandId}}	The command ID. If you call the RunCommand operation to run a command and want to specify `{{ACS::CommandId}}` as a built-in environment parameter, make sure that the Cloud Assistant Agent version is not earlier than the following versions: Linux: 2.2.3.309 Windows: 2.1.3.309

Name	Example value
Parameter Name	username
Parameter Type	String
Value	user01

Name	Example
Principal Type	Select Cloud Service.
Principal Name	Elastic Compute Service / ECS.