All Products
Search

This Product

    Elastic Compute Service:ModifyInstanceVpcAttribute

    Document Center

    Elastic Compute Service:ModifyInstanceVpcAttribute

    Last Updated:Sep 07, 2026

    Modifies the VPC, private IP address, security group, or vSwitch of a VPC-type ECS instance.

    Operation description

    When you call this operation, the ECS instance must be in the Stopped (Stopped) state.

    • When you modify the private IP address or vSwitch of an instance, take note of the following items:

      • A newly created ECS instance must be restarted before you can call this operation.

      • After a successful modification, the ECS instance must be restarted before you can call this operation again.

    • When you modify the VPC of an instance, take note of the following items:

      • Instance:

        • Instance status: The instance cannot be locked, pending release, expired, in expiration recycling, or in overdue payment recycling. For more information, see Instance lifetime.

        • ECS instances that are associated with load balancing instances are not supported.

        • The instance cannot be in use by other cloud services. For example, the instance cannot be in migration, cannot be undergoing a VPC change, and databases deployed on the instance cannot be managed by Data Transmission Service (DTS).

      • Network:

        • Instances configured with EIP in network interface controller (NIC) visible pattern or multi-EIP to NIC visible pattern are not supported.

        • Instances attached to high availability (HA) virtual IP addresses (HaVips) are not supported.

        • Instances whose vSwitches are associated with custom route tables are not supported.

        • Instances with Global Accelerator (GA) enabled are not supported.

        • Instances attached to secondary Elastic Network Interfaces (ENIs) are not supported.

        • Instances that have been allocated IPv6 addresses are not supported.

        • Instances whose primary NIC has multiple IP addresses are not supported.

        • The specified vSwitch must belong to the destination VPC.

        • The zone of the vSwitch must remain the same before and after the modification.

        • If you specify a private IP for the primary NIC, the IP address must be within the CIDR block of the vSwitch and available. If you do not specify one, an IP address is randomly allocated. Make sure that the destination vSwitch has sufficient available IP addresses.

        • If you use a VPC shared by another account, make sure that the destination security group is created by your account in the shared VPC, not by the VPC owner's account.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    ecs:ModifyInstanceVpcAttribute

    update

    *Instance

    acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

    *VSwitch

    acs:vpc:{#regionId}:{#accountId}:vswitch/{#vswitchId}
    • vpc:tag
    • vpc:VPC
    		 None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    InstanceId

    string

    Yes

    The instance ID.

    Note

    When you call this operation, the ECS instance must be in the Stopped (Stopped) state. For other restrictions on the instance, carefully read the operation description section.

    i-bp1iudwa5b1tqag1****
    VSwitchId

    string

    Yes

    The vSwitch ID.

    • If the specified ID is the current vSwitch of the instance, the vSwitch remains unchanged.

    • If the specified ID is a new vSwitch and the VpcId parameter is empty, the new and original vSwitches must belong to the same zone and the same VPC.

    • If the VpcId parameter is not empty, the vSwitch specified by this parameter must belong to the specified VPC and must be in the same zone as the original vSwitch.

    vsw-bp1s5fnvk4gn3tw12****
    PrivateIpAddress

    string

    No

    The new private IP address.

    Note

    The PrivateIpAddress parameter depends on VSwitchId. The specified IP address must be within the CIDR block of the vSwitch.

    Default value: If this parameter is not specified, a private IP address is randomly assigned from the CIDR block of the vSwitch.

    172.17.**.**
    VpcId

    string

    No

    The ID of the destination VPC.

    vpc-bp1vwnn14rqpyiczj****
    SecurityGroupId

    array

    No

    The IDs of the security groups to which the instance is added after the VPC is changed. This parameter is required only when the VpcId parameter is specified.

    • The security groups must belong to the same VPC as the destination VPC.

    • You can specify one or more security groups for the instance. The number of security groups is subject to the limits on the number of security groups to which an instance can belong. For more information, see Limits.

    • All security groups in the list must be of the same type.

    • Switching between security group types is supported. When you switch an ECS instance between security group types, make sure that you understand the differences in security group rule configurations between the two types to avoid impacts on instance networking. For more information, see Security group overview.

    sg-o6w9l8bc8dgmkw87****

    string

    No

    The security group ID.

    sg-o6w9l8bc8dgmkw87****

    Response elements

    Element

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

    Examples

    Success response

    JSON format

    {
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidTarget.TrafficMirrorSession Instance is target of traffic mirror session.
    400 InvalidSource.TrafficMirrorSession Instance is source of traffic mirror session.
    400 InvalidPrivateIpAddress.Malformed Specified private IP address is malformed. The specified private IP address is invalid.
    400 InvalidPrivateIpAddress.Duplicated Specified private IP address is duplicated.
    400 IncorrectVSwitchStatus The current status of virtual switch does not support this operation. The specified vSwitch is in the Pending state and cannot be deleted.
    400 IncorrectInstanceStatus The current status of instance does not support this operation. The instance is in a state that does not support the current operation.
    400 OperationDenied Specified operation is denied as your instance is not in VPC. The specified instance does not reside in a VPC.
    400 InvalidVSwitchId.Mismatch Specified instance and virtual switch are not in the same zone. The specified instance and vSwitch are not in the same zone.
    400 InvalidPrivateIpAddress.Mismatch Specified private IP address is not in the CIDR block of virtual switch. The specified private IP address is not in the CIDR block of the specified vSwitch.
    400 InvalidPrivateIp.Changing Previous action is not finished yet. The private IP address is being modified.
    400 PrimaryEniHasSubIp Primary network interface of the specified instance has more than one private ip. The primary ENI has multiple secondary private IP addresses.
    400 VSwitchIdNotMatch The subnet of private ip is different to the instance, please unbind ha vip. The vSwitch CIDR block does not contain the specified IP address. Check the configuration.
    400 InvalidOperation.EniCountExceeded The number of ENIs in an enterprise security group has reached the maximum limit.
    400 InvalidParameter.SecurityGroupId Security group ids are invalid. Invalid security group ID
    400 InvalidVSwitch.IllegalStatus The operation is not allowed in the current VSwitch state. Expecting state includes "Created", but current state is "%s". The current VSwitch status does not support this operation.
    400 QuotaExceeded.PrivateIpAddress There are not enough private IPs in the specified VSwitch. The current VSwitch does not have enough Ip
    401 InvalidOperation.SecurityGroupNotAuthorized The specified security group is not authorized to operate. You do not have permission to operate the current security group.
    500 InternalError The request processing has failed due to some unknown error.
    403 OperationDenied The Specified operation is denied as your instance is locked for security reasons.
    403 InvalidIp.Ipv6Assigned The specified instance has been assigned IPv6 address.
    403 SecurityGroupInstanceLimitExceed %s The maximum number of instances in the security group has been reached.
    403 InvalidInstance.HasTransitionRecord The operation is denied because the specified instance has a migration plan.
    403 InvalidInstanceStatus.NotNormal The Specified operation is denied due to instance status.
    403 InvalidVpcId.SharedVpc The Specified operation is denied as your targe vpc is SharedVpc.
    403 InvalidOperation.NotAllowed The operation is denied because the specified VPC has advanced features enabled.
    403 InvalidParameter.ToSecurityGroupId %s
    403 InvalidOperation.ResourceManagedByCloudProduct %s You cannot modify security groups managed by cloud services.
    403 InvalidOperation.VswAndEcsAvailabilityZoneMismatch Specified instance and virtual switch are not in the same zone. The instance and the destination VSwitch do not belong to the same zone.
    403 InvalidOperation.CloudBoxEcsNotSupport Cloud box ecs instance does not support modifying VPC. Cloud box instances do not support modifying VPC
    403 AclLimitExceed %s The number of ACL rules for an ENI or instance exceeds the upper limit.
    404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The specified instanceId is invalid.
    404 InvalidVSwitchId.NotFound Specified virtual switch does not exist. The specified vSwitch ID does not exist.
    404 NoSuchResource The specified resource is not found. The specified resource does not exist.
    404 InvalidParameter.InvalidInstanceId The specified InstanceId does not exist.
    404 InvalidParameter.VSwitchId The specified virtual vswitch does not exist. The specified vSwitch does not exist.
    404 InvalidRegion.ValueNotSupported The specified Region does not exist.
    404 InvalidInstance.AttachedEni The Specified operation is denied due to elastic network interface. The VPC cannot be changed while the instance has secondary ENIs bound.
    404 InvalidIp.MultiPrimaryIp The Specified operation is denied due to multi private ip. This operation is not allowed while the primary ENI has multiple private IP addresses.
    404 InvalidIp.Ipv6 The Specified operation is denied due to ipv6.
    404 InvalidVSwitch.NotBelongToVpc %s The specified VSwitchId does not belong to the specified VPC. Check whether the parameter value is correct.
    404 InvalidParameter.EniNo %s
    404 InvalidSecurityGroupId.NotFound %s The specified security group ID does not exist.
    404 InvalidParameter.SecurityGroupIdRepeated %s
    404 InvalidSecurityGroupType.NotSupportClassic The specified SecurityGroupIds have classic group type. The specified security group is in the classic network. Check whether the specified SecurityGroupIds.N parameter is valid.
    404 InvalidSecurityGroupVpc.NotBelongToOneVpc The specified SecurityGroupIds are belong to different vpc. The specified security groups belong to different VPCs. Check whether the specified SecurityGroupIds.N parameter is valid. You can call the DescribeSecurityGroups operation to query the VPCs to which the security groups belong.
    404 EnterpriseGroupLimited.MutliGroupType The specified instance can not join multi SecurityGroup types.
    404 InvalidParameter.AlreadyInTargetVpc The specified instance is already in the destination VPC.
    404 InvalidParameter.SecurityGroupId The specified SecurityGroupId.N is invalid or does not exist.
    404 JoinedGroupLimitExceed The specified instance has exceed quota of SecurityGroup.
    404 InvalidParameter.MustBeEmpty The specified parameter SecurityGroupId.N and VpcId need be empty. The SecurityGroupId.N and VpcId parameters must be left empty.
    404 InvalidParameter.NotEnoughIpInVSwitch The specified virtual switch has not enough available ip.
    404 InvalidDependence.MutliDirectlyEip The Specified operation is denied due to multi directly Eips.
    404 InvalidDependence.HaVip The Specified operation is denied due to HaVip.
    404 InvalidDependence.NextHopOfCustomRouter The Specified operation is denied due to next hop of Custom Router. This operation is not allowed when the instance is the next hop of custom routes.
    404 InvalidDependence.BeenUsedAsAppServer The Specified operation is denied due to AppServer.
    404 InvalidDependence.GrantAccess The Specified operation is denied due to grant access. The ECS instance may use other products (such as DBS, DTS, DMS, and Workbench), have records of authorization for other products, and have reverse access rules.
    404 InvalidDependence.BindGA The Specified operation is denied due to GA.
    404 InvalidDependence.SLB The Specified operation is denied as your instance with alb or clb. The operation is denied because the instance is associated with an ALB instance or a CLB instance.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.