Register a third-party server as an Alibaba Cloud managed instance - Elastic Compute Service

Register a third-party server as an Alibaba Cloud managed instance to manage it with Alibaba Cloud services, such as Cloud Assistant, CloudOps Orchestration Service, and Alibaba Cloud DevOps. For example, you can use Cloud Assistant to manage the server without logging in.

Limitations

Third-party server requirements
- Supported operating systems:
  - Alibaba Cloud Linux 2 and 3
  - CentOS 6 and later
  - CoreOS and OpenSUSE
  - Debian 8, 9, 10, and later
  - Red Hat Enterprise Linux (RHEL) 5, 6, 7, and later
  - SUSE Linux Enterprise Server (SLES) 11, 12, 15, and later
  - Ubuntu 12, 14, 16, 18, and later
  - Windows Server 2012, 2016, 2019, and later
- The server must be able to access the public network.
Region availability
The managed instance feature is available only in the following regions:
China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Ulanqab), China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Guangzhou), China (Chengdu), China (Hong Kong), Japan (Tokyo), South Korea (Seoul), Singapore, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Thailand (Bangkok), Germany (Frankfurt), UK (London), US (Silicon Valley), US (Virginia), UAE (Dubai), and SAU (Riyadh).

Billing

The managed instance feature is a free service.
You may be charged for other Alibaba Cloud services that you use. For more information, see the documentation for those services.

Step 1: Create a registration code

To register a third-party server, you must first create a registration code (also called an activation code). This code acts as a credential to verify the server's identity, ensuring that only authorized servers can be registered as Alibaba Cloud managed instances.

Important

You can use one registration code to register up to 1,000 managed instances.
You can create a maximum of 5,000 registration codes per region.
If you have more than 1,000 registration codes, you can create new codes only if your existing code utilization exceeds 50%.
On the ECS Cloud Assistant page, on the Manage Instances tab, click Register Instance. You can view the usage data of your registration codes in the Registered Instances/Registration Quota column.

Go to ECS console - Cloud Assistant.
In the upper-left corner of the page, select a region and resource group.
Important
Registration codes and their corresponding managed instances are specific to the selected region.
We recommend that you select the region with the fastest network connection. You can run the ping command on your third-party server to test the connection speed to different regions. You can obtain the region ID for the <RegionId> placeholder from Regions and zones.
```
ping -c 4 <RegionId>.axt.aliyuncs.com
```
On the Manage Instances tab, create a registration code.
- Scenario 1: If no instances are registered in the current region, click Create Registration Code and go to Step 4.
- Scenario 2: If instances are registered in the current region, click Register Instance. In the Register Instance pane, click Create Registration Code.

In the Create Registration Code pane, configure the parameters for the managed instance.

Parameter	Description
Instance Name Prefix	The prefix of the managed instance names. We recommend that you specify a prefix for easy management.
Source IP Address	The IP address or CIDR block of the managed instance. If you specify a public IP address or CIDR block, only servers with an IP address in the specified range can be registered. If you leave this parameter empty, no IP address restrictions are applied to the servers.
Instance Quota	The maximum number of instances that can be registered with this code. Value range: 1 to 1,000. Default value: 10.
Validity Period	The duration for which the registration code is valid. Expired codes cannot be used to register new servers. Default: 4 hours.
Description	A description of the registration code, such as its purpose. This helps you manage registration codes.
Tag	Add a Tag Key and a Value to the registration code for easy categorization, management, and maintenance. Important Managed instances registered with this code are automatically added with the specified Tag Key and Value.
Resource Group	Select a resource group to which you want to add the managed instances. This helps you manage managed instances based on their purposes or permissions. Important Managed instances that are registered by using the registration code are automatically added to the resource group of the registration code. If you do not specify a resource group, the instances are added to the default resource group. For more information about the RAM policies and resource group-based authorization for managed instances, see Examples of custom RAM policies for managed instances and Resource groups and authorization.

Click Generate Registration Code.
An installation script is generated. You need to run the script on the third-party server.
Obtain the installation script.
Select the operating system of your server and click Download or Copy to save the installation script to your local machine.
- rpm: for operating systems such as Alibaba Cloud Linux, CentOS, RHEL, and SUSE Linux.
- deb: for operating systems such as Debian and Ubuntu.
- exe: for Windows Server operating systems.
Important
- After the registration code is generated, the installation script is displayed only once, and you must save it to a local path. For example, save it as installAssistant.sh to install registered instances in subsequent steps.
- If you have servers that run different operating systems, you must download the installation script for each operating system.

Step 2: Install the Cloud Assistant Agent on the server and register the instance

Run the installation script from the previous step on your server to register it as a managed instance.

Linux servers

Connect over the public network

Log on to your third-party server.
Create an installation script on the server.
1. Run the following command to create a script file, and then paste the installation script that you copied in Step 1 into the file.
```
vim installAssistant.sh
```
2. Press the Esc key, and enter :wq to save.
Run the following command to grant the execute permission to the installation script.
```
sudo chmod 755 installAssistant.sh
```
Run the following command to install Cloud Assistant Agent on the server.
```
sudo ./installAssistant.sh
```
The following message appears, indicating that the installation is successful.

Connect through a proxy server

This section uses CentOS 7.8 as an example to describe how to install Cloud Assistant Agent and register a managed instance through a proxy server.

Log on to the server by using a method such as SSH.
For more information, see Connection methods.

Run the following command to download Cloud Assistant Agent through the proxy server.

x86-based architecture:

sudo https_proxy=<http://your_proxy_address> && wget https://aliyun-client-assist.oss-accelerate.aliyuncs.com/linux/aliyun_assist_latest.rpm

ARM-based architecture:

sudo https_proxy=<http://your_proxy_address> && wget https://aliyun-client-assist.oss-accelerate.aliyuncs.com/arm/aliyun-assist-latest-1.aarch64.rpm

Important

Replace <http://your_proxy_address> with the address of your proxy server.

Run the following command to install Cloud Assistant Agent.
x86-based architecture:
```
sudo rpm -ivh aliyun_assist_latest.rpm --force
```
ARM-based architecture:
```
sudo rpm -ivh aliyun-assist-latest-1.aarch64.rpm --force
```
Configure a proxy for the Cloud Assistant service.
1. Modify the Cloud Assistant service configuration file.
  Modify the Cloud Assistant service configuration file to set the ALIYUN_ASSIST_PROXY environment variable.
  1. Use Vim to create the /etc/sysconfig/aliyun file.
```
sudo vim /etc/sysconfig/aliyun
```
  2. Enter the following content and save the file.
```
ALIYUN_ASSIST_PROXY=<http://your_proxy_address>
```
    Important
    Replace <http://your_proxy_address> with the address of your proxy server.
2. Run the following command to reload the systemd configuration.
```
sudo systemctl daemon-reload
```
3. Run the following command to restart the Cloud Assistant service.
```
 sudo systemctl restart aliyun.service
```
  After the Cloud Assistant service starts, check the Cloud Assistant log file. By default, the log file is stored in the /usr/local/share/aliyun-assist/{version}/log/aliyun_assist_main.log path. If the log file contains Detected environment variable ALIYUN_ASSIST_PROXY for proxy setting, it indicates that a proxy is configured for the Cloud Assistant service.
Run the following commands to register the managed instance through the proxy server.
1. Run the following command to configure the proxy server.
```
export ALIYUN_ASSIST_PROXY=<http://your_proxy_address>
```
  Important
  Replace <http://your_proxy_address> with the address of your proxy server.
2. Run the following command to register the server as a managed instance.
  Important
  This command is for reference only. Copy the command from the console in Step 1.
```
sudo aliyun-service --register --RegionId "cn-hangzhou" \
   --ActivationCode "a-hz0f5KlGmF/TsM5uBuq7Eqor+****" \
   --ActivationId "045CE381-0404-4F42-A44B-CC232B3E****"
```

Connect over Express Connect to a VPC

This section uses CentOS as an example to describe how to install Cloud Assistant Agent over an Express Connect circuit and then register the managed instance over the internal network of a VPC.

Log on to the server by using a method such as SSH.
For more information, see Connection methods.

Run the following script to register the managed instance over the VPC internal network.

The following code provides an example. Replace the values of RegionId, ActivationCode, and ActivationId with the values from the script generated in Step 1.

CentOS

#/bin/bash
## Note: Set the region ID.
regionId="cn-hangzhou"
if [[ -n $regionId ]]; then
    bucket="aliyun-client-assist-${regionId}.oss-${regionId}-internal.aliyuncs.com"
    ## Download Cloud Assistant Agent.
    wget -q https://${bucket}/linux/aliyun_assist_latest.rpm
    ## Install Cloud Assistant Agent.
    sudo rpm -ivh aliyun_assist_latest.rpm --force
fi
## Register the managed instance over a VPC internal network. Note: You must set the NetworkMode parameter to vpc.
## Copy the values of the RegionId, ActivationCode, and ActivationId parameters from the registration code creation page in the console.
sudo aliyun-service --register \
  --NetworkMode "vpc" \
  --RegionId "${regionId}" \
  --ActivationCode "a-hz0f5KlGmF/TsM5uBuq7Eqor+****" \
  --ActivationId "2C217D35-FE6C-5636-BC3C-CC480D3*****"

Debian and other Linux

#!/bin/bash

## Note: Set the region ID.
regionId="cn-hangzhou"

if [[ -n $regionId ]]; then
    bucket="aliyun-client-assist-${regionId}.oss-${regionId}-internal.aliyuncs.com"
    ## Download Cloud Assistant Agent.
    wget -q https://${bucket}/linux/aliyun_assist_latest.deb
    ## Install Cloud Assistant Agent.
    sudo dpkg -i aliyun_assist_latest.deb
fi


## Register the managed instance over a VPC internal network. Note: You must set the NetworkMode parameter to vpc.
## Copy the values of the RegionId, ActivationCode, and ActivationId parameters from the registration code creation page in the console.
sudo aliyun-service --register \
  --NetworkMode "vpc" \
  --RegionId "${regionId}" \
  --ActivationCode "a-hz0f5KlGmF/TsM5uBuq7Eqor+****" \
  --ActivationId "2C217D35-FE6C-5636-BC3C-CC480D3*****"

Windows servers

Connect over the public network

Log on to the server by using a method such as Remote Desktop Connection.
For more information, see Connection methods.
Upload the installation script to the server.
Use the installation script from Step 1.
Note
Remote Desktop Connection allows you to copy the script file to the server. If your network environment has other restrictions that prevent you from copying files, you can use other software such as FTP to upload the script.
Right-click the installation script and select Run with PowerShell to install Cloud Assistant Agent.

Connect through a proxy server

This section uses Windows Server 2016 Datacenter Edition as an example to describe how to install Cloud Assistant Agent and register a managed instance through a proxy server.

Log on to the server by using a method such as Remote Desktop Connection.
For more information, see Connection methods.
Configure the proxy server for your browser.
1. Choose Start > Control Panel.
2. Click Network and Internet.
3. Click Network and Sharing Center.
4. In the lower-left corner, click Internet Options.
5. On the Connect tab, click LAN settings.
6. In the Proxy server section, specify the address and port of your proxy server, and click OK.
Download the Cloud Assistant Agent installation package.
1. From the Start menu, choose Windows PowerShell > Windows PowerShell.
2. Right-click Windows PowerShell and select Run as administrator.
3. In the Windows PowerShell window, run the following command to download the Cloud Assistant Agent installation package.
```
Invoke-WebRequest -Uri 'https://aliyun-client-assist.oss-accelerate.aliyuncs.com/windows/aliyun_agent_latest_setup.exe' -OutFile 'C:\\aliyun_agent_latest_setup.exe'
```
After the download is complete, install Cloud Assistant Agent.
1. Go to the C:\ drive.
2. Double-click aliyun_agent_latest_setup.exe and follow the instructions in the installation wizard to install Cloud Assistant Agent.
Configure a proxy server for Cloud Assistant.
1. Choose Start > Control Panel.
2. Click System and Security.
3. Click System.
4. In the navigation pane on the left, click Advanced system settings.
5. On the Premium tab, click Environment Variable.
6. In the System Variable section, click New Resources.
7. Set Variable Name and Variable value and click OK.
  - Variable Name: Enter ALIYUN_ASSIST_PROXY.
  - Variable value: Enter the address of your proxy server.
8. In Windows PowerShell, run the following commands to restart the Cloud Assistant service.
  1. Run the following command to stop the Cloud Assistant service.
```
net stop AliyunService
```
  2. Run the following command to restart the Cloud Assistant service.
```
net start AliyunService
```
In Windows PowerShell, register the managed instance through the proxy server.
1. Run the following command to go to the Cloud Assistant installation directory.
```
cd C:\ProgramData\aliyun\assist\{version}
```
  Important
  Replace {version} with the version number of Cloud Assistant that you installed.
2. Run the following command to register the server as a managed instance.
  The following command provides an example. Replace the values of RegionId, ActivationCode, and ActivationId with the values from the script generated in Step 1.
```
 .\aliyun_assist_service.exe  --register  --RegionId="cn-hangzhou" --ActivationCode="a-hz0f6dB8Fg6hhtK0A5n9xqqdH****" --ActivationId="0A2E5ECE-5C71-4FA3-807B-05962C25****"
```

Connect over Express Connect to a VPC

This section uses Windows Server 2016 Datacenter Edition as an example to describe how to install Cloud Assistant Agent and register the managed instance over an Express Connect circuit.

Log on to the server by using a method such as Remote Desktop Connection.
For more information, see Connection methods.
From the Start menu, choose Windows PowerShell > Windows PowerShell.
Right-click Windows PowerShell and select Run as administrator.

In the Windows PowerShell window, run the following command.

The following command provides an example. Replace the values of RegionId, ActivationCode, and ActivationId with the values from the script generated in Step 1.

$RegionId = "cn-hangzhou"
$Bucket = "aliyun-client-assist-${RegionId}.oss-${RegionId}-internal.aliyuncs.com"

Invoke-WebRequest -Uri "https://${Bucket}/windows/aliyun_agent_latest_setup.exe" `
-OutFile 'C:\\aliyun_agent_latest_setup.exe'
&"C:\\aliyun_agent_latest_setup.exe" '/S' '--register' `
'--NetworkMode="vpc"' '--RegionId="cn-hangzhou"' `
'--ActivationCode="a-hz0f6dB8Fg6hhtK0A5n9xqqdH****"' `
'--ActivationId="0A2E5ECE-5C71-4FA3-807B-05962C25****"'
type C:\ProgramData\aliyun\assist\hybrid\instance-id
Start-Sleep -s 30
net stop AliyunService
net start AliyunService

Step 3: Verify the connection

After installing the Cloud Assistant Agent and registering the instance, return to the ECS console to verify its connection status. If the connection status is Normal, the third-party server is successfully managed.

Go to ECS console - Cloud Assistant.
In the upper-left corner of the page, select a region and resource group.
On the Manage Instances tab, view the list of managed instances.
By default, all resources under your Alibaba Cloud account are displayed. To view the managed instances and registration codes in a specific resource group, select the resource group from the All Account Resources drop-down list in the upper-left corner.
As shown in the preceding figure, a Connection Status of Normal indicates that the server is successfully managed.

After your third-party server is registered as a managed instance, you can use Cloud Assistant to manage the server without logging in. For more information about how to use Cloud Assistant, see Create and run a command and Send a file to an ECS instance.

(Optional) Deregister a third-party server

If you no longer need to manage your third-party server with Alibaba Cloud, you can deregister the managed instance and then stop and uninstall the Cloud Assistant service.

Linux servers

Log on to the server by using a method such as SSH.
For more information, see Connection methods.
Run the following command to deregister the managed instance.
```
sudo aliyun-service --deregister
```
Stop and uninstall the Cloud Assistant daemon.
1. Run the following command to stop the Cloud Assistant daemon.
```
sudo /usr/local/share/assist-daemon/assist_daemon --stop
```
  Note
  The default path of the Cloud Assistant daemon is /usr/local/share/assist-daemon/assist_daemon.
2. Run the following command to uninstall the Cloud Assistant daemon.
```
sudo /usr/local/share/assist-daemon/assist_daemon --delete
```
Run the following command to stop Cloud Assistant Agent.
Note
Different Linux kernel versions use different init services. Linux distributions with newer kernels, such as Ubuntu 18.04, typically use the systemd init service. This section uses the systemd init service as an example. For more information about other init services, see Stop and uninstall Cloud Assistant Agent.
```
sudo systemctl stop aliyun.service
```
Run the following command to uninstall Cloud Assistant Agent.
- For RPM-based package management systems:
```
sudo rpm -qa | grep aliyun_assist | xargs sudo rpm -e
```
- For DEB-based package management systems:
```
sudo dpkg -r aliyun-assist
```
Delete the directories of the Cloud Assistant daemon and Cloud Assistant Agent.
1. Run the following command to delete the directory of the Cloud Assistant daemon.
```
sudo rm -rf /usr/local/share/assist-daemon
```
2. Run the following command to delete the directory of Cloud Assistant Agent.
```
sudo rm -rf /usr/local/share/aliyun-assist
```

Windows servers

Note

This section uses Windows Server 2019 as an example. On other Windows versions, the paths for Windows PowerShell and services may differ.

Log on to the server by using a method such as Remote Desktop Connection.
For more information, see Connection methods.
Run Windows PowerShell.
1. Click the Start menu.
2. Choose Windows PowerShell > Windows PowerShell.
3. Right-click Windows PowerShell and select Run as administrator.
In the Windows PowerShell window, run the following command to deregister the managed instance.
```
aliyun-service --deregister
```
Open the Services window.
1. Click the Start menu.
2. Choose Windows Administrative Tools > Service.
Find Aliyun Assist Service and click Stop the service.

FAQ

Why is my managed instance disconnected?

If the Cloud Assistant status is abnormal or disconnected, the issue may be related to the running status of the Cloud Assistant Agent. Log on to the managed server and run the systemctl status aliyun.service command to check the agent's running status.

running indicates that Cloud Assistant is running properly.
If the status is not running, run the systemctl restart aliyun.service command to restart Cloud Assistant. For more information about Cloud Assistant issues, see Check the status of Cloud Assistant and troubleshoot exceptions.
For other issues, collect the logs from /usr/local/share/aliyun-assist/<version>/log and contact Alibaba Cloud technical support.

How do I view existing registration codes?

Click Register Instance. In the Register Instance pane that appears, you can view the list of existing registration codes and create new ones.

Why does the validity period exceed the limit?

If the message Activation TTL exceeds limit. is displayed when you create a registration code, the corresponding error code is ActivationTTL.ExceedLimit. This indicates that the value of the Validity Period parameter is invalid. Reduce the value of the Validity Period parameter and try again. The default Validity Period of a registration code is 4 hours.
If the registration of a third-party server fails and the error code activation_has_expired is reported, it means the registration code has expired. Create a new registration code and register the server again.

References

After you successfully register a managed instance, you can use various online services provided by Alibaba Cloud, such as Cloud Assistant, CloudOps Orchestration Service, and Alibaba Cloud DevOps:
- Cloud Assistant: Automates O&M tasks such as running scripts, polling processes, installing or uninstalling software, starting or stopping services, and installing patches or security updates. For more information, see Overview.
- CloudOps Orchestration Service: Automates the management and execution of O&M tasks. For more information, see What is OOS?.
You can also call the following Cloud Assistant API operations to manage activation codes and managed instances.