Updating Instance Pools

You can change the size of an instance pool, attach existing instances to a pool, attach load balancers, and update various other properties.

For background information about instance pools and instance configurations, see Using Instance Configurations and Instance Pools.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

For administrators: For a typical policy that gives access to instance pools and instance configurations, see Let users manage compute instance configurations, instance pools, and cluster networks.

Updating the Size of a Pool

You can manually update the number of instances for an instance pool.

When you increase the size of a pool, the pool creates instances using the pool's instance configuration as a template. If you want to add existing instances to the pool, you can instead attach instances to the pool.

When you decrease the size of a pool, the pool terminates (deletes) the extra instances. The oldest instances are terminated first. If you need to perform tasks on an instance before it is deleted, you should instead detach the instance from the pool and then delete the instance separately.

To automatically adjust the number of instances in an instance pool based on performance metrics or a schedule, enable autoscaling for the instance pool.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Click Edit.
  4. Specify the updated number of instances for the instance pool, and then click Save Changes.

When you update the instance pool size, it triggers a scaling event. Keep the following things in mind:

  • If the instance pool's lifecycle state is Running, the pool creates new instances or terminates existing instances at that time, to match the new size of the pool. To balance the instances within an instance pool across placements (availability domain and fault domain), instances are terminated first based on how many instances from the instance pool are in that availability domain and fault domain. Within a placement, instances are terminated in the order that the instances were created, first-in, first-out.
  • If the instance pool's lifecycle state is Stopped, for an increase in size, new instances are configured for the pool, but are not launched. For a decrease in size, the instances are terminated.
To track the progress of the operation and troubleshoot errors that occur during instance creation, use the associated work request.
Important

If the instance pool has been in the scaling or provisioning state for an extended period of time, it might be because the number of instances requested has exceeded your tenancy's service limits for that shape and availability domain. Check your tenancy's service limits for Compute.

Using the API

To update the size of an instance pool, use the UpdateInstancePool operation.

Using the CLI

To update the size of an instance pool, use the instance-pool update command:

oci compute-management instance-pool update --instance-pool-id <INSTANCE_POOL_OCID> --size <NUMBER>

Attaching an Instance to a Pool

You can attach an existing instance to an instance pool. This lets you select which instances you want to manage as a group.

When you attach an instance, the pool size is increased.

Important

If an autoscaling configuration is associated with the instance pool, ensure that the autoscaling policy defines a maximum pool size that's large enough for the expanded pool. You can do this by editing the autoscaling policy. If you attach an instance and it causes the pool size to increase above the maximum autoscaling target, a future autoscaling event might decrease the pool size and terminate instances.

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

Prerequisites

To attach an instance to a pool, all of the following things must be true:

  • The instance and the pool are running.
  • The instance is the same machine type as the pool, either virtual machine or bare metal.
  • The instance is in the same availability domain and fault domain as the pool.
  • The instance's primary VNIC is in the same VCN and subnet as the pool.
  • If secondary VNICs are defined, the instance's secondary VNIC is in the same VCN and subnet as the secondary VNICs used by other instances in the pool.
  • The instance is not attached to another pool.

You also need the name or OCID  of the instance that you want to attach.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instances.
  2. Click the instance that you're interested in.
  3. Click More Actions, and then click Attach Instance to Instance Pool.
  4. In the Input type list, select either Instance name or Instance OCID. Then, select the name of the instance or enter its OCID.
  5. Click Attach Instance.

    To track the progress of the operation and troubleshoot errors that occur during instance creation, use the associated work request.

Using the API

To attach an existing instance to an instance pool, use the AttachInstancePoolInstance operation.

Using the CLI

To attach an existing instance to an instance pool, use the instance-pool-instance attach command:

oci compute-management instance-pool-instance attach --instance-id <INSTANCE_OCID>

Detaching an Instance from a Pool

You can detach an instance from an instance pool when you no longer want to manage the instance as part of the pool.

When you detach an instance from a pool, you can choose whether to delete the instance or to retain it. You can also choose whether to replace the detached instance by creating a new instance in the pool. If you don't replace the detached instance, the pool size is decreased.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Under Resources, click Attached Instances.
  4. For the instance that you want to detach, click the Actions icon (three dots). Then, click Detach Instance.
  5. If you want to delete the instance and its boot volume, select the Permanently terminate (delete) this instance and its attached boot volume check box.
  6. If you want the pool to remain the same size after you detach the instance, you can provision a replacement instance. Select the Replace the instance with a new instance, using the pool’s instance configuration as a template for the instance check box.
  7. Click Detach (or Detach and Terminate, if you're also deleting the instance).

    To track the progress of the operation and troubleshoot errors that occur during instance creation, use the associated work request.

Using the API

To detach an instance from an instance pool, use the DetachInstancePoolInstance operation.

Using the CLI

To detach an instance from an instance pool, use the instance-pool-instance detach command:

oci compute-management instance-pool-instance detach --instance-id <INSTANCE_OCID>

Attaching a Load Balancer to a Pool

Optionally, you can associate a load balancer with an instance pool. If you do this, when you add an instance to the instance pool, the instance is automatically added to the load balancer's backend set . After the instance reaches a healthy state (the instance is listening on the configured port number), incoming traffic is automatically routed to the new instance. For background information about the Load Balancing service, see Overview of Load Balancing.

Prerequisites

You must have a load balancer and backend set to associate with the instance pool. For steps to create a load balancer, see Load Balancer Management.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Under Resources, click Load Balancers.
  4. Click Attach a Load Balancer.
  5. Enter the following:

    • Load balancer: The load balancer to associate with the instance pool.
    • Backend set: The name of the backend set on the load balancer to add instances to.
    • Port: The server port on the instances to which the load balancer must direct traffic. This value applies to all instances that use this load balancer attachment.
    • VNIC: The VNIC  to use when adding the instance to the backend set. Instances that belong to a backend set are also called backend servers. The private IP address is used. This value applies to all instances that use this load balancer attachment.
  6. Click Attach.
  7. If you want to associate additional load balancers with the instance pool, click + Another Load Balancer. Then, repeat the previous steps. Do this for each additional load balancer you want to associate with the instance pool.

    To track the progress of the operation and troubleshoot errors that occur during instance creation, use the associated work request.

Using the API

To attach a load balancer to an instance pool, use the AttachLoadBalancer operation.

Using the CLI

To attach a load balancer to an instance pool, use the instance-pool attach-lb command:

oci compute-management instance-pool attach-lb --backend-set-name <NAME> --instance-pool-id <INSTANCE_POOL_OCID> --load-balancer-id <LOAD_BALANCER_OCID> --port <PORT> --vnic-selection <PrimaryVnic_OR_displayName>

Detaching a Load Balancer from a Pool

You can detach a load balancer from an instance pool.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Under Resources, click Load Balancers.
  4. Click the Actions icon (three dots) for the load balancer you want to detach.
  5. Click Detach Load Balancer, and then click Detach to confirm.

    To track the progress of the operation and troubleshoot errors that occur during instance creation, use the associated work request.

Using the API

To detach a load balancer from an instance pool, use the DetachLoadBalancer operation.

Using the CLI

To detach a load balancer from an instance pool, use the instance-pool detach-lb command:

oci compute-management instance-pool detach-lb --backend-set-name <NAME> --instance-pool-id <INSTANCE_POOL_OCID> --load-balancer-id <LOAD_BALANCER_OCID>

Updating the Instance Configuration for a Pool

To update the instance configuration that an instance pool uses when creating instances, you can do either of the following things:

  • Create a new instance configuration with the desired settings, and then attach the new instance configuration to the pool.
  • If you only want to update the display name or tags of an existing instance configuration, you can update the pool's existing instance configuration. Use the UpdateInstanceConfiguration operation. For any other updates, create and then attach a new instance configuration with the settings you want to use.

Using the Console

To attach a new instance configuration to a pool:

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Click Edit.
  4. For Instance configuration, select the instance configuration that you want the pool to use when creating new instances.
  5. Click Save.

Using the API

To attach a new instance configuration to a pool, use the UpdateInstancePool operation.

Using the CLI

To attach a new instance configuration to a pool, use the instance-pool update command:

oci compute-management instance-pool update --instance-pool-id <INSTANCE_POOL_OCID> --instance-configuration-id <INSTANCE_CONFIGURATION_OCID>

Renaming an Instance Pool

You can rename an instance pool without changing its Oracle Cloud Identifier (OCID).

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Click Edit.
  4. Enter a new name. Avoid entering confidential information.
  5. Click Save.

Using the API

To rename an instance pool, use the UpdateInstancePool operation.

Using the CLI

To rename an instance pool, use the instance-pool update command:

oci compute-management instance-pool update --instance-pool-id <INSTANCE_POOL_OCID> --display-name <INSTANCE_POOL_NAME>

Updating the Placement for a Pool

You can update the location where the instances in an instance pool are placed. The placement includes the availability domains, fault domains, and subnets for the instances in the pool.

When you remove an availability domain from a pool, the pool permanently deletes all of its instances in that availability domain. The pool replaces the instances with new instances in the availability domains that are still associated with the pool.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Click Edit.
  4. Select the Availability domain to create the instances in.
  5. For the Fault domains box, do one of the following things:

    • If you want the system to make a best effort to distribute instances across fault domains based on capacity, leave the box blank.
    • If you want to require that the instances in the pool are distributed evenly in one or more fault domains, select the fault domains to place the instances in. The pool will not launch or scale successfully if sufficient capacity is unavailable in the selected fault domains. For more information, see Distributing Instances Across Fault Domains for High Availability.
  6. In the Primary VNIC section, configure the network details for the instances:

    • Virtual cloud network: The virtual cloud network (VCN) to create the instances in.
    • Subnet: A subnet within the cloud network to attach the instances to. The subnets are either public or private. Private means the instances in that subnet can't have public IP addresses. For more information, see Access to the Internet. Subnets can also be either AD-specific or regional (regional ones have "regional" after the name). We recommend using regional subnets. For more information, see About Regional Subnets.
  7. If secondary VNICs are defined by the instance configuration, a Secondary VNIC section appears. Select the secondary VCN and subnet for the instance pool.
  8. If you want the instance pool to create instances in more than one availability domain, click + Another Availability Domain. Then, repeat the previous steps.
  9. If you no longer want the pool to contain instances in a specific availability domain, click the X next to the availability domain that you want to remove. Any existing instances in that availability domain will be deleted and replaced with new instances in an availability domain that is still associated with the pool.
  10. Click Save.

Using the API

To update the placement for an instance pool, use the UpdateInstancePool operation.

Using the CLI

To update the placement for an instance pool, use the instance-pool update command:

oci compute-management instance-pool update --instance-pool-id <INSTANCE_POOL_OCID> --placement-configurations <file://path/to/file.json>

<file://path/to/file.json> is the path to a JSON file that defines the placement configurations. For information about how to generate an example of the JSON file, see Advanced JSON Options.

Tagging Resources

You can add tags to your resources to help you organize them according to your business needs. You can add tags at the time you create a resource, or you can update the resource later with the desired tags. For general information about applying tags, see Resource Tags.
To manage tags for an instance pool

Using the Console:

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click the instance pool that you're interested in.
  3. Click the Tags tab to view or edit the existing tags. Or click More Actions, and then click Add tags to add new ones.

Using the API: Use the UpdateInstancePool operation.