Updating an Instance Pool

When you update an instance pool, you can change the name of the pool, the size of the pool, the instance configuration that is used to create new instances, the fault domains, VCN, and subnet.

To attach or detach an instance, see Attaching an Instance to an Instance Pool and Detaching an Instance from an Instance Pool.

To attach load balancers or detach load balancer attachments, see Managing Instance Pool Load Balancer Attachments.

Configuration changes do not affect existing instances; configuration changes only affect new instances. New instances will be provisioned using the new instance configuration and placement configuration.

If you increase the size of the pool, new instances are provisioned. The new instances are launched evenly across the fault domains specified by the instance configuration or the placement configuration.

If you decrease the size of the pool, instances are terminated evenly across the fault domains specified by the instance configuration or the placement configuration. In each fault domain, instances are terminated in creation date order, oldest first.

You cannot select which instances to terminate when you decrease the size of a pool. If you terminate an individual instance that is a member of a pool, as described in Terminating an Instance, a new instance is automatically provisioned to keep the pool at the specified pool size.

If you increase the size of the pool, and some new instances cannot be provisioned because of resource constraints, those instances remain in Provisioning state and the pool remains in Scaling state until all instances are provisioned. See the suggested remedies in Creating an Instance Pool.

Using the Compute Web UI

  1. In the navigation menu, click Compute, and then click Instance Pools.

  2. If the instance pool that you want to update is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.

  3. For the instance pool that you want to update, click the Actions menu, and click the Edit option.

  4. In the Update Instance Pool dialog, make the changes.

  5. When you are finished editing, click the Update Instance Pool button in the dialog.

Using the OCI CLI

  1. Get the OCID of the instance pool that you want to update: oci compute-management instance-pool list

  2. Run the instance pool update command.

    Syntax:

    oci compute-management instance-pool update \
--instance-pool-id instance_pool_OCID \
options_with_values_to_update

    Example:

    $ oci compute-management instance-pool update \
--instance-pool-id ocid1.instancePool.unique_ID \
--instance-configuration-id new_instance_configuration_OCID --size 20

    The output of this command is the same as the output of the instance-pool get command.

Attaching an Instance to an Instance Pool

When you attach an instance to an instance pool, the pool size increases.

Important:

If an autoscaling configuration is associated with the instance pool, then ensure that the autoscaling policy defines a target pool size that is large enough for the expanded pool. The next time the scheduled autoscaling policy runs, the target pool size is reset to the value that is set in the policy; if the policy size is smaller than the current size, instances will be deleted.

If load balancers are attached to the pool, then the instance is also added to the load balancers.

Ensure the following conditions before you attach an instance to an instance pool:

  • Both the pool and the instance to be attached are running.

  • The instance is not attached to another pool.

  • The instance is in the same fault domain as the pool.

  • The primary VNIC of the instance is in the same VCN and subnet as the pool.

  • If secondary VNICs are defined, then the secondary VNIC of the instance is in the same VCN and subnet as the secondary VNICs used by other instances in the pool.

To attach an instance that is in a fault domain that is not included in the pool instance configuration, or is using a VCN and subnet that are not specified by the pool instance configuration, first update the instance configuration, then attach the instance. To update the instance configuration, create and attach a new instance configuration as shown in Updating an Instance Pool.

Using the Compute Web UI

  1. In the navigation menu, click Compute, and then click Instance Pools.

  2. If the instance pool that you want to update is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.

  3. Click the name of the instance pool to which you want to attach an instance.

  4. On the instance pool details page, scroll down to the Resources section and click Attached Instances.

  5. Click the Attach Instance button on the Attached Instances table.

  6. In the Input type field of the Attach Instance dialog, select either Instance name or Instance OCID.

    • If you select Instance name, a list of instances is displayed. The list of instances is labeled "Potentially attachable instances" because instances must meet certain criteria to be eligible to be attached. For example, the instance must be in the same VCN and subnet that is specified by the instance pool configuration, and the instance must not already be attached to this pool or any other pool. See the list of criteria at the top of the Attach Instance dialog.

      If an instance that you think should be attachable is not shown in the list, try using Instance OCID.

    • If you select Instance OCID, a text field labeled Instance OCID is displayed where you can paste the OCID of the instance that you want to attach.

  7. Click the Attach button on the dialog.

    Even if the criteria listed in the dialog are met, the instance could fail to attach for some other reason. In the Resources box, click Work Requests and click the applicable work request in the list to troubleshoot any problems.

Using the OCI CLI

  1. Get the information you need to run the command.

    • OCID of the instance pool that you want to update: oci compute-management instance-pool list

    • OCID of the instance that you want to attach: oci compute instance list

  2. Run the instance pool attach instance command.

    $ oci compute-management instance-pool-instance attach \
--instance-pool-id ocid1.instancePool.unique_ID \
--instance-id ocid1.instance.unique_ID

    The output of this command is the same as the output of the instance get command. If you run the instance-pool get command, you see that the size property is incremented.

Detaching an Instance from an Instance Pool

When you detach an instance from a pool, you can choose whether to delete the instance or to retain the instance separate from the pool.

Using the OCI CLI, you can choose whether to replace the detached instance by creating a new instance in the pool. If you don't replace the detached instance, then the pool size is decremented.

If load balancers are attached to the pool, then the instance is removed from the load balancers.

Using the Compute Web UI

  1. In the navigation menu, click Compute, and then click Instance Pools.

  2. If the instance pool that you want to update is not listed, use the Compartment drop-down menu above the instance pools list to select the correct compartment.

  3. Click the name of the instance pool from which you want to detach an instance.

  4. On the instance pool details page, scroll down to the Resources section and click Attached Instances to display the list of attached instances.

  5. For the instance that you want to detach, click the Actions menu and click Detach to display the Confirm instance detachment dialog.

  6. (Optional) To delete the instance and its boot volume, click the button under "Permanently terminate (delete) this instance and its attached boot volume."

  7. Click the Confirm button to detach the instance.

    The pool size is decremented.

Using the OCI CLI

  1. Get the information you need to run the command.

    • OCID of the instance pool that you want to update: oci compute-management instance-pool list

    • OCID of the instance that you want to detach: oci compute-management instance-pool list-instances

  2. Run the instance pool detach instance command.

    Syntax:

    oci compute-management instance-pool-instance detach \
--instance-pool-id instance_pool_OCID --instance-id instance_OCID \
--is-auto-terminate [true|false] --is-decrement-size [true|false]

    Provide the following options if you do not want the default behavior:

    --is-auto-terminate

    If true, permanently terminate (delete) the instance and its attached boot volume when the instance is detached from the instance pool. The default value is false.

    --is-decrement-size

    If true, decrement the pool size when the instance is detached from the instance pool. This is the default.

    If false, provision a new, replacement instance using the pool’s instance configuration after the existing instance is detached from the instance pool. The pool size remains the same as it was before you performed this detach operation.

    Example:

    In the following example, the specified instance is detached from the pool and terminated, and a new instance is provisioned for the pool.

    $ oci compute-management instance-pool-instance detach \
--instance-pool-id ocid1.instancePool.unique_ID \
--instance-id ocid1.instance.unique_ID \
--is-auto-terminate true --is-decrement-size false

    The output of this command is the same as the output of the instance-pool get command.