Use custom OOS and built-in parameters in Cloud Assistant commands - Elastic Compute Service

Cloud Assistant lets you use custom parameters, such as standard custom parameters and built-in environment parameters, to customize command content. This feature is similar to using template variables. For more convenient and secure management, you can also use Cloud Assistant commands with the parameter store of CloudOps Orchestration Service (OOS). This topic describes how to use these 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 a later version.
- Linux: 2.2.3.309
- Windows: 2.1.3.309

Usage notes

Custom parameters: You can define parameters using the {{parameter}} format and assign values manually. This is useful for dynamic values and for reusing a value multiple times. You can also use built-in environment parameters as custom parameters. Cloud Assistant automatically replaces built-in parameters with their corresponding values during execution. You do not need to assign values to these parameters. For more information about supported built-in environment parameters, see Built-in environment parameters.

You can use custom parameters when you run Cloud Assistant commands by calling an API.
When you call the RunCommand or InvokeCommand operation to run a Cloud Assistant command, you can enable custom parameters by specifying EnableParameter=true and define them in the CommandContent parameter using the {{}} format. The following limits apply to custom parameters:
- For standard custom parameters: Parameter names must be a case-insensitive combination of letters, digits, hyphens (-), and underscores (_). A parameter name cannot exceed 64 bytes in length.
- For built-in environment parameters: The acs:: prefix is reserved for built-in environment parameters. Do not use this prefix for your standard custom parameters.
- Spaces and line feeds before and after a parameter name within {{}} are ignored.
- The total number of custom parameters, including standard and built-in parameters, cannot exceed 20.

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 dynamically 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 {
        // The region ID.
        String regionId = "ap-southeast-1";
        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 -";
        // The 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():
    # The region ID.
    region_id = "ap-southeast-1"
    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. Replace /path/to/your/script.sh with 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

CloudOps Orchestration Service provides a parameter store that supports standard and encrypted parameters. You can use the OOS parameter store with Cloud Assistant commands to manage custom parameters more conveniently and securely. To use the OOS parameter store, you must first activate OOS and grant the oos:GetParameter and oos:GetParameters permissions.

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 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 `username` standard parameter in the OOS parameter store.

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 com.google.gson.Gson;

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

public class EcsService {
    public static void main(String[] args_) throws Exception {
        // The region ID.
        String regionId = "ap-southeast-1";
        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);
        // The 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():
    # The region ID.
    region_id = "ap-southeast-1"
    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, use encrypted parameters. To use encrypted parameters, you must first activate Key Management Service (KMS).

Create an encrypted parameter and a standard parameter in the OOS parameter store.

The following example creates a parameter named username and a parameter named 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 The example value is a free service key generated by KMS. Select a key as needed.
Value	MyPassword01 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
  Principle Type
  Select Cloud Service.
  Principle Name
  Elastic Compute Service / ECS.
  Click OK. Set Role Name to AxtParametersRamRole.
2. Create a custom 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 Manage permissions for a RAM role.
4. Attach the RAM role (AxtParametersRamRole) to the target ECS instance. For more information, see Step 1: Create a RAM role.

Call an API to run the Cloud Assistant command.

Use a RAM user to run a Cloud Assistant command that changes a user password on a Linux instance.

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

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

{{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.

The passwd --stdin command in the example applies to Red Hat-based operating systems such as CentOS and Alibaba Cloud Linux. If you use an Ubuntu or Debian system, use the echo '{{oos:username}}:{{oos-secret:password}}' | chpasswd command.

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 {
        // The region ID.
        String regionId = "ap-southeast-1";
        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);
        // The 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():
    # The region ID.
    region_id = "ap-southeast-1"
    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 as custom parameters. When you run a command, you do not need to manually assign values to these parameters. Cloud Assistant automatically replaces them with their corresponding values.

Built-in environment parameter	Description
`{{ACS::RegionId}}`	The region ID.
`{{ACS::AccountId}}`	The UID of the Alibaba Cloud account.
`{{ACS::InstanceId}}`	The instance ID.
`{{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.
`{{ACS::CommandId}}`	The command ID.

Name	Example value
Parameter Name	username
Parameter Type	String
Value	user01

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