Creating Instance Pools

Use instance pools to create and manage multiple compute instances within the same region as a group.

When you create an instance pool, you use an instance configuration as the template to create instances in the pool. You can also attach existing instances to a pool by updating the pool.

Optionally, you can associate one or more load balancers and network load balancers 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.

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.

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.

Propagation of Tagging on Resources

OCI services propagate all of a primary resource's freeform tags and defined tags to secondary resources when both resources support the type of tags. For example, when instance pools create instances, the tags from the instance pool and the instance configuration propagate to the resources created. Resources include instances created by the pool, primary VNICs, secondary VNICs, and boot volumes and block volumes created with the instance. Tags are not propagated to existing instances that are attached to the pool.

Sometimes, the tags on the instance pool, the instance configuration, and the resources might conflict. In those cases, the tag values from the instance configuration are propagated to the resources, overwriting both the instance pool and resource tag values. If the instance pool and resource tags conflict and the instance configuration doesn't have a tag, the tag values from the instance pool are propagated to the resources, overwriting the resource tag values.

Distributing Instances Across Fault Domains for High Availability

By default, the instances in a pool are distributed across all fault domains in a best-effort manner based on capacity. If capacity isn't available in one fault domain, the instances are placed in other fault domains to allow the instance pool to launch successfully.

In a high availability scenario, you can require that the instances in a pool are evenly distributed across each of the fault domains that you specify. When sufficient capacity isn't available in one of the fault domains, the instance pool will not launch or scale successfully, and a work request for the instance pool will return an "out of capacity" error. To fix the capacity error, either wait for capacity to become available, or update the placement configuration (the availability domain and fault domain) for the instance pool.

Prerequisites

Before you can create an instance pool, you need:

  • An instance configuration. An instance configuration is a template that defines the settings to use when creating instances. When you create the instance pool, monitoring is enabled by default on instances that support monitoring, regardless of the settings in the instance configuration. For more information, see Creating Instance Configurations.

    Note

    You cannot create an instance pool from an instance configuration where the image source is a boot volume.
  • If you want to associate the instance pool with a load balancer or network load balancer, you need a load balancer or network load balancer and backend set. For steps to create a load balancer, see Load Balancer Management. For steps to create a network load balancer, see Network Load Balancer Management.

Using the Console

  1. Open the navigation menu and click Compute. Under Compute, click Instance Pools.
  2. Click Create instance pool.

  3. On the Add basic details page, do the following:

    1. Enter a name for the instance pool. It doesn't have to be unique, and you can change it later. Avoid entering confidential information.
    2. Select the compartment to create the instance pool in.
    3. Select the Instance configuration that you want to use.
    4. Specify the targeted Number of instances for the instance pool.
    5. Show tagging options: Optionally, you can add tags. If you have permissions to create a resource, you also have permissions to add free-form tags to that resource. To add a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure whether you should add tags, skip this option (you can add tags later) or ask your administrator.
  4. Click Next.
  5. On the Configure pool placement page, select the location where you want to place the instances. Do the following:

    1. Select the Availability domain to create the instances in.
    2. 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.
    3. 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.
    4. If secondary VNICs are defined by the instance configuration, a Secondary VNIC section appears. Select the secondary VCN and subnet for the instance pool.
    5. If you want the instance pool to create instances in more than one availability domain, click + Another availability domain. Then, repeat the previous steps.
  6. If you want to associate a load balancer or network load balancer with the instance pool, select the Attach a load balancer check box. Then, do the following:

    1. Specify the type of load balancer you want to associate with the instance pool:

    2. Select the load balancer or network load balancer from the Load Balancer list.

      The choices available in this list are determined by the load balancer type you previously selected and what is available in the current compartment. Click Change Compartment and select another compartment to display the load balancer or network load balancer choices available there.

    3. Select the Backend set on the load balancer or network load balancer to add instances to.
    4. In the Port box, enter 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.

      Load balancer port values can range from 1 to 65535.

      Network load balancer port values can range from 0 to 65535. The value 0 indicates that any port can be used.

    5. In the VNIC list, select 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 balancers you want to associate with the instance pool.

    For background information about load balancers, see Overview of Load Balancer.

  7. Click Next.
  8. Review the instance pool details, and then click Create.

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

Using the CLI

To create an instance pool, use the instance-pool create command:

oci compute-management instance-pool create --compartment-id <COMPARTMENT_OCID> --instance-configuration-id <INSTANCE_CONFIGURATION_OCID> --placement-configurations <file://path/to/file.json> --size <NUMBER_OF_INSTANCES>

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

For information about using the CLI, see Command Line Interface (CLI).