Oracle Cloud Infrastructure Documentation

Updating Instance Pools

You can change the size of an instance pool, attach existing instances to a pool, attach load balancers and network 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 deletes (terminates) the extra instances. Instances are terminated in this order: the number of instances is balanced across availability domains, and then balanced across fault domains. Finally, within a fault domain, the oldest instance is terminated first. If you need to perform tasks on an instance before deletion, 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.

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 Scaling, the pool creates new instances or deletes existing instances at that time, to match the new size of the pool. To balance the instances across placements (availability domain and fault domain), instances are deleted first based on how many instances from the instance pool are in that availability domain and fault domain. Within a placement, the oldest instances are terminated first.
  • 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 pool name or Instance pool OCID. Then, select the name of the instance pool 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 menu. Then, click Detach instance.
  5. If you want to delete the instance and its boot volume, select Permanently terminate (delete) this instance and its attached boot volume.
  6. If you want the pool to remain the same size after you detach the instance, you can provision a replacement instance. Select Replace the instance with a new instance, using the pool’s instance configuration as a template for the instance.

  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 or network 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 or network 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 Balancer service, see Overview of Load Balancer.

Prerequisites

You must have a load balancer or network load balancer and backend set to associate with the instance pool. See the following for background information:

These sections include instructions on how to create load balancers and network load balancers.

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:

    • Specify the load balancer type you are associating with the instance pool:

      • Load balancer
      • Network load balancer
    • Load balancer: The load balancer or network load balancer to associate with the instance pool.
    • Backend set: The name of the backend set on the load balancer or network load balancer to add instances to.
    • Port: The server port on the instances to which the load balancer or network load balancer must direct traffic. This value applies to all instances that use this load balancer or network 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 or network load balancer attachment.

  6. If you want to associate additional load balancers and network load balancers with the instance pool, click + Another load balancer. Then, repeat the previous steps. Do this for each additional load balancer or network load balancer that 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.
  7. Click Attach.

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 or network 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 menu for the load balancer or network 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 want the instances in the pool to use the settings from the new instance configuration, such as a new shape, detach the existing instances from the instance pool and provision new instances.

    Note

    When you detach instances from an instance pool, the existing instances are detached before new instances are provisioned. Depending on your requirements, you might want to increase the size of the instance pool before detaching instances.
  • 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. For any other updates, create and then attach a new instance configuration with the settings that 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.