You can create and run a new command simultaneously by using the immediate execution feature.

Prerequisites

  • The instances on which to run a command are in the Running (Running) state.
  • You can retain up to 100 Cloud Assistant commands within an Alibaba Cloud region. This quota may increase based on your ECS usage. For more information about how to view the quota, see Step 1: View resource quotas. If you click Run when you create a command in the Create Command panel, the command does not count against your command quota.
    Note You can also call the DescribeAccountAttributes operation with AttributeName.N set to max-axt-command-count to query the maximum number of Cloud Assistant commands that you can retain within a region.
  • You can run Cloud Assistant commands up to 5,000 times within a region per day. This quota may increase based on your ECS usage. For more information about how to view the quota, see Step 1: View resource quotas.
    Note You can also call the DescribeAccountAttributes operation with the AttributeName.N parameter set to max-axt-invocation-daily to query the maximum number of times that you can run Cloud Assistant commands within in a region per day.
  • The Cloud Assistant client is installed on the instance. For more information, see Install the Cloud Assistant client.
    If you are concerned about recurring tasks, make sure that the version of the Cloud Assistant client is not earlier than the following ones. A recurring task is a task that is scheduled to run a command at a specified interval, only once at a specified time, or on a schedule defined by a cron expression with a specified year or time zone.
    • Linux: 2.2.3.282
    • Windows: 2.1.3.282

    If the ClientNeedUpgrade error code is returned after a recurring task is executed, update the Cloud Assistant client to the latest version. For more information, see Upgrades or disable upgrades for the Cloud Assistant client.

Background information

When you use the immediate execution feature, take note of the following items:

  • A command cannot exceed 16 KB in size after it is encoded in Base64.
  • Up to 20 custom parameters can be specified in a single Cloud Assistant command.
  • You can call an API operation to run a command on up to 50 instances.
  • When you create a command, you must check whether the syntax, logic, and algorithm of the command are correct.

    For example, assume that you have created the /backup directory (mkdir /backup) on an instance. You can run the following shell commands to archive a file in this directory:

    #!/bin/bash 
    OF=/backup/my-backup-$(date +%Y%m%d).tgz
    tar -cf $OF {{file}}
    Note In the preceding example, {{file}} is a custom parameter. When you run the commands, you can set this custom parameter to the name of the file to be archived. Example: /app/usrcredential. Custom parameters can be used in scenarios that require dynamic values and multi-purpose values. We recommend that you specify custom parameters for security-sensitive data or data that changes with the environment. This data includes AccessKey pairs, instance IDs, authorization codes, time parameters, and critical system files.

Procedure in the ECS console

  1. Log on to the ECS console.
  2. In the left-side navigation pane, choose Maintenance & Monitoring > ECS Cloud Assistant.
  3. In the top navigation bar, select a region.
  4. In the upper-right corner, click Create or Run Command.
  5. In the Command Information section, configure the parameters described in the following table.
    Parameter Description
    Command Source Select the command source.
    • Enter Command Content: creates a command.
    • Select Saved Command: selects an existing command.
    Command Name Enter a name for the command.
    Implementation plan Select a plan on how to run the command.
    • Immediate execution: The command is run immediately after you click Run or Execute and Save.
    • After the next startup of the system: The command is run the next time the selected instances are started after you click Run or Execute and Save.
    • After each system startup: The command is run each time the selected instances are started after you click Run or Execute and Save.
    • Run on Schedule: The command is run at a specified interval, at a specified time, or on a schedule after you click Run or Execute and Save. If you set Implementation plan to Run on Schedule, the following options are available:
      • Run at Fixed Interval: Use a rate expression to specify an interval at which to run the command. You can specify the interval in seconds, minutes, hours, or days. This option is applicable when tasks need to be executed at a fixed interval.
        Note When you set an interval, take note of the following limits:
        • The specified interval can only be anywhere from 60 seconds to 7 days and must be longer than the timeout period of the recurring task.
        • The specified interval is the amount of time elapsed between two consecutive times that the command is run on the selected instances. This interval does not relate to the amount of time required to run the command each time. For example, assume that you set the interval to 5 minutes and that it takes 2 minutes to run the command each time. Each time the command is run, the system waits 3 minutes before it runs the command again.
        • A task is not executed immediately after the task is created. For example, assume that you set the interval to 5 minutes for a task. The task begins to be executed 5 minutes after it is created.
      • Run Only Once at Specified Time: Specify a point in time and a time zone to run the command only once.

        For example, if you set Execution Time to 2022-05-17 17:30:50 and Time Zone to (GMT+8:00) Asia/Shanghai, the command was run only once at 17:30:50 on May 17, 2022 (UTC+8).

      • Run on Clock-based Schedule: Use a cron expression to specify a schedule on which to run the command. Set Execution Frequency to a cron expression that defines a schedule accurate to the second, minute, hour, day of the month, month, day of the week, or year, and select a time zone from the Time Zone drop-down list. The system calculates the execution times of the command based on this cron expression and time zone and runs the command as scheduled. This option provides flexibility and is applicable when tasks need to executed on a regular basis. For more information about cron expressions, see Cron expression.
        Note The minimum interval must be 10 seconds or more and cannot be shorter than the timeout period of the recurring task.

        For example, if you set Execution Frequency to 0 0 12 ? * WED 2022 and set Time Zone to (GMT+8:00) Asia/Shanghai, the system runs the command at 12:00 every Wednesday in 2022 (UTC+8).

    Command type Select a command type.
    • For Linux instances, select Shell, Python, or Perl.
    • For Windows instances, select Bat or PowerShell.
    Command Enter or paste the content of the command.

    For information about sample shell commands, see View instance configurations.

    Use Parameters Specifies whether to use parameters.

    If you turn on Use Parameters, you can specify custom parameters in the {{key}} format in the Command field.

    Command Description Enter a description for the command. We recommend that you enter identifiable command information (such as the purpose of the command) for easy management and maintenance.
    Username Specify the username that is used to run the command on ECS instances.

    The best practice is to run commands based on the least privilege principle. We recommend that you run Cloud Assistant commands as a regular user. For more information, see Run Cloud Assistant commands as a regular user.

    By default, Cloud Assistant commands are run by the root user on Linux instances and by the system user on Windows instances.

    Execution Path Specify an execution path for the command. Default execution paths for instances that use different types of operating system:
    • For Linux instances, the default execution path is the /home directory of the root user.
    • For Windows instances, the default execution path is C:\Windows\system32.
    Timeout Period Specify a timeout period for the command to be run on instances. If a task that runs a command times out, Cloud Assistant forcefully stops the task process.

    Unit: seconds. Default value: 60. Minimum value: 10. If you set Timeout Period to a value of less than 10, the system changes the value to 10 to ensure that the command can be run.

  6. In the Select Instances and Select Managed Instances sections, select the instances on which you want to run the command.
    Note A managed instance is an instance that is managed by Cloud Assistant but not provided by Alibaba Cloud. For more information, see Manage servers that are not provided by Alibaba Cloud.
  7. Click Execute and Save or Run to immediately run the command task.

Procedure by using the CLI

Example on how to run a command only once

  • Sample request:

    Call the RunCommand operation to create and run a Cloud Assistant command named update to update the operating system on instances.

    aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
    --Name 'update' --Username 'root' --Type 'RunShellScript' \
    --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
    --Timeout '60' --RepeatMode 'Once' --ContentEncoding 'Base64' \
    --InstanceId.1 'i-bp12e0ib2ztibede****'
    Note Values enclosed in single quotation marks ('') are example values of the parameters and must be changed based on actual conditions.
    Parameter Example Description
    RegionId cn-hangzhou The ID of region in which to create the command.
    Name update The name of the command.
    Username root The username used to run the command on ECS instances.
    Type RunShellScript The command type.
    • For Linux instances, set the value to RunShellScript.
    • For Windows instances, set the value to RunBatScript or RunPowershellScript.
    CommandContent eXVtIHVwZGF0ZSAteQ== The Base64-encoded content of the command.
    Timeout 60 The timeout period.
    RepeatMode Once The execution plan.
    ContentEncoding Base64 The encoding format.
    InstanceId.1 i-bp12e0ib2ztibede**** The ID of ECS instance N on which to run the command. In this example, the N value is 1.

    For more information, see RunCommand.

  • Sample success response:
    {
            "CommandId": "c-hz018qlm868****",
            "InvokeId": "t-hz018qlm86d****",
            "RequestId": "1D24FA80-64DB-4842-AB20-25207994418F"
    }

Example on how to run a command on a regular basis

  • Sample request:

    Call the RunCommand operation to create and run a Cloud Assistant command named update to update the operating system on instances at 12:00 every day in 2022 (UTC+8).

    aliyun ecs RunCommand --RegionId 'cn-hangzhou' \
    --Name 'update' --Description 'update' --Username 'root' --Type 'RunShellScript' \
    --CommandContent 'eXVtIC15IHVwZGF0ZQ==' \
    --Timeout '60' --RepeatMode 'Period' --ContentEncoding 'Base64' \
    --Frequency '0 0 12 * * ? 2022 Asia/Shanghai' \
    --InstanceId.1 'i-bp12e0ib2ztibede****'
    Note Values enclosed in single quotation marks ('') are example values of the parameters and must be changed based on actual conditions.
    Parameter Example Description
    RegionId cn-hangzhou The ID of region in which to create the command.
    Name update The name of the command.
    Description update The description of the command.
    Username root The username used to run the command on ECS instances.
    Type RunShellScript The command type.
    • For Linux instances, set the value to RunShellScript.
    • For Windows instances, set the value to RunBatScript or RunPowershellScript.
    CommandContent eXVtIC15IHVwZGF0ZQ== The Base64-encoded content of the command.
    Timeout 60 The timeout period.
    RepeatMode Period The execution plan.
    ContentEncoding Base64 The encoding format.
    Frequency 0 0 12 * * ? 2022 Asia/Shanghai' The schedule on which to run the command.
    InstanceId.1 i-bp12e0ib2ztibede**** The ID of ECS instance N on which to run the command. In this example, the N value is 1.

    For more information, see RunCommand.

  • Sample success response:
    {
            "CommandId": "c-hz018qlm868****",
            "InvokeId": "t-hz018qlm86d****",
            "RequestId": "1D24FA80-64DB-4842-AB20-25207994418F"
    }