Connect to an instance by using Workbench - Elastic Compute Service

Workbench is a browser-based tool for connecting to Elastic Compute Service (ECS) instances. It requires no software installation and supports both Linux and Windows instances through Secure Shell (SSH) and Remote Desktop Protocol (RDP) connections.

Connection methods

Connection	Instance OS	Default port
SSH	Linux	22
RDP	Windows	3389

Both public and private IP addresses are supported. Use a public IP address to connect over the internet, or a private IP address to connect within your Virtual Private Cloud (VPC).

References

Features

Beyond basic connectivity, Workbench provides tools for managing and operating ECS instances directly from the browser.

File management: Upload, download, and manage files on Linux instances through a visual interface. For more information, see File management.
AI Agent mode: Describe operations and maintenance (O&M) tasks in natural language, and let the AI agent plan and run them on Linux instances. For more information, see AI Agent mode.
Terminal Assistant: Generate scripts and commands for O&M tasks. For more information, see Terminal Assistant.
Intelligent command completion: Get real-time predictions for commands, parameters, and options as you type. For more information, see Intelligent command completion.
System management: Monitor system status in real time and manage users, logon logs, and system services on Linux instances. For more information, see System management.
Script library: Save frequently used commands or script snippets and run them with a single click in any instance session. For more information, see Script library.
Multi-terminal: Connect to multiple ECS instances simultaneously and run the same commands across all of them. For more information, see Multi-terminal.
Software installation: Deploy software such as Docker and MySQL through AI Agent or CloudOps Orchestration Service (OOS) predefined packages. For more information, see Software installation.

Connection workflow

The following diagram shows the workflow for connecting to an instance through Workbench.

Find the target instance. Locate the ECS instance in the console.
Configure network access. Add security group rules and, if applicable, instance firewall rules to allow inbound traffic from the Workbench server.
Start a Workbench session. In the console, select the Workbench connection option and enter the username and password or key pair credentials.
Create the service-linked role (first connection only). If the AliyunServiceRoleForECSWorkbench role does not exist, a dialog box prompts you to grant Workbench the required permissions. Click OK to create the role automatically.
Connect and operate. After authentication, Workbench opens a terminal (Linux) or remote desktop (Windows) session in the browser.

Service-linked role

Workbench uses the AliyunServiceRoleForECSWorkbench service-linked role to access ECS instances on your behalf. This role is created automatically the first time you connect to an instance through Workbench.

On the first connection, a dialog box appears:

Click OK to create the service-linked role.

If you are a Resource Access Management (RAM) user, ask your Alibaba Cloud account administrator to attach the AliyunECSWorkbenchFullAccess system policy to your RAM user before you connect. This policy grants the permission required to create the service-linked role.

For more information, see Service-linked roles.

RAM user permissions

After the service-linked role is created, a RAM user needs the following access policy to connect to instances through Workbench.

Allow access to all instances

{
  "Version": "1",
  "Statement": [
    {
      "Action": "ecs-workbench:LoginInstance",
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

Restrict access to specific instances

To limit which instances a RAM user can connect to, specify instance resources explicitly:

{
  "Version": "1",
  "Statement": [
    {
      "Action": "ecs-workbench:LoginInstance",
      "Resource": [
        "acs:ecs-workbench:{#regionId}:{#accountId}:workbench/{#instanceId}",
        "acs:ecs-workbench:{#regionId}:{#accountId}:workbench/{#instanceId}"
      ],
      "Effect": "Allow"
    }
  ]
}

Replace the placeholders with your values:

Placeholder	Description	Wildcard
`{#regionId}`	Region ID of the instance	`*` for all regions
`{#accountId}`	Alibaba Cloud account ID	`*` for all accounts
`{#instanceId}`	ECS instance ID	`*` for all instances

Example: Allow a RAM user to connect to instances i-001 and i-002 in all regions:

{
  "Version": "1",
  "Statement": [
    {
      "Action": "ecs-workbench:LoginInstance",
      "Resource": [
        "acs:ecs-workbench:*:*:workbench/i-001",
        "acs:ecs-workbench:*:*:workbench/i-002"
      ],
      "Effect": "Allow"
    }
  ]
}

Security group configuration

To connect to an instance through Workbench over SSH or RDP, add a security group rule that allows inbound traffic from the Workbench server. For more information, see Add a security group rule.

Important

If a firewall is enabled on the instance, update the firewall rules to match the security group rules.

Configure the security group rule with the following settings:

Authorization Policy	Priority	Protocol Type	Port Range	Authorization object
Allow	1	Custom TCP	See the port details below	See the CIDR blocks below

Port range:

Linux instances: Select SSH (22). The default SSH port is 22.
Windows instances: Select RDP (3389). The default RDP port is 3389.

Important

If you changed the port of the remote connection service on the instance, specify the actual port.

Authorization object:

Public network connections: 161.117.0.0/16
Private network connections: 100.104.0.0/16

Warning

Setting the authorization object to 0.0.0.0/0 allows all IP addresses to access the remote connection port. This poses security risks. Use this setting with caution.