Use custom parameters in Cloud Assistant commands - Elastic Compute Service

Define custom parameters in Cloud Assistant commands using the {{parameter}} format, or integrate with the CloudOps Orchestration Service (OOS) parameter store for centralized and encrypted parameter management.

Prerequisites

Instance is in the Running state.
Cloud Assistant Agent is installed on the instance. Minimum version:
- Linux: 2.2.3.309
- Windows: 2.1.3.309

Usage notes

Cloud Assistant supports two types of custom parameters. For supported built-in environment parameters, see Built-in environment parameters.

Standard custom parameters: Define parameters in the {{parameter}} format and assign values manually. Useful for dynamic values or reusing a value across a command.
Built-in environment parameters: Cloud Assistant auto-replaces these with instance-specific values at execution time. No manual assignment needed.

To use custom parameters via API, call RunCommand or InvokeCommand with EnableParameter=true, and define parameters in CommandContent using the {{}} format. The following limits apply:
- For standard custom parameters: Names are case-insensitive and can contain letters, digits, hyphens (-), and underscores (_). Maximum length: 64 bytes.
- For built-in environment parameters: The acs:: prefix is reserved. Do not use it for standard custom parameters.
- Spaces and line feeds around a parameter name within {{}} are ignored.
- Maximum 20 custom parameters per command (standard + built-in combined).

Use custom parameters

The following example uses a custom parameter to dynamically set the execution frequency of a scheduled script on a Linux instance.

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 (OOS) provides a parameter store for standard and encrypted parameters. To use OOS parameters in Cloud Assistant commands, activate OOS and grant the oos:GetParameter and oos:GetParameters permissions.

Use standard parameters

Use standard parameters when your command does not involve sensitive data. The following example adds a user to a Linux instance with an OOS standard parameter.

Create a standard parameter in the OOS parameter store. See Standard parameters.

The following example creates a standard parameter named username with the value user01.

Name

Example value

Parameter Name

username

Parameter Type

String

Value

user01

Call an API to run the Cloud Assistant command.

Run adduser {{oos:username}} on a Linux instance, where {{oos:username}} resolves to the OOS standard parameter username.

Grant the RAM user the required permissions. 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

For sensitive data such as passwords, use encrypted parameters. Activate Key Management Service (KMS) before using encrypted parameters.

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

The following example creates a standard parameter username and an encrypted parameter password.

Add a standard parameter named username with the value user01.

Name

Example value

Parameter Name

username

Parameter Type

String

Value

user01

Add an encrypted parameter named password with the value MyPassword01.

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

Attach a RAM role to the ECS instance.
1. Create a RAM role. See Create a service RAM role.
  
  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. See Create a custom policy.
  Example access policy
  Set Policy Name to AxtParametersRamPolicy. This policy grants the GetSecretValue, GetParameters, GetSecretParameters, GetParameter, and GetSecretParameter permissions for KMS and OOS.
```
{
    "Version": "1",
    "Statement": [
        {
            "Action": [
                "kms:GetSecretValue",
                "oos:GetParameters",
                "oos:GetSecretParameters",
                "oos:GetParameter",
                "oos:GetSecretParameter"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }
    ]
}
```
3. Attach the policy (AxtParametersRamPolicy) to the RAM role (AxtParametersRamRole). See Manage permissions for a RAM role.
4. Attach the RAM role (AxtParametersRamRole) to the ECS instance. See Step 1: Create a RAM role.

Call an API to run the Cloud Assistant command.

The following example changes a user password on a Linux instance.

Grant the RAM user the required permissions. See Use OOS encrypted parameters in commands.

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

{{oos-secret:password}} resolves to the encrypted parameter password. {{oos:username}} resolves to the standard parameter username.

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

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

Built-in environment parameters are auto-replaced with instance-specific values at execution time. No manual assignment is needed.

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. When running a command on multiple instances with `{{ACS::InstanceName}}`, ensure the Cloud Assistant Agent version meets or exceeds: 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.