Creating an Instance Pool

An instance pool is a group of compute instances within the same region.

Performing operations such as reset or terminate on the pool object performs that operation on all instances that are members of the pool. Performing these operations on an individual instance that is a member of the pool does not affect any other member instances.

Creating an instance pool requires an instance configuration and a placement configuration. Instances that are added to the pool in a pool update can be created with different instance and placement configurations.

For instances in a pool, the value of the displayName property in the instance configuration is ignored. Instances in a pool are named inst-aaaaa-pool_name, where aaaaa is five random alphanumeric characters.

Placement Configuration

In addition to an instance configuration, pool creation requires a placement configuration. Values specified in a placement configuration override values specified in the instance configuration.

A placement configuration can specify fault domains, primary subnet, and secondary VNIC subnets.

Fault Domains

If you do not specify a fault domain in either the instance configuration or the placement configuration, the system automatically selects the best fault domains for the pool instances. If you specify only a single fault domain, all instances will be placed in only that fault domain. If you specify more than one fault domain, pool instances are placed in those fault domains evenly, providing better High Availability for the pool. If one fault domain cannot accommodate additional instances, instance creation stops. The system will not place more instances in one fault domain than in another fault domain.

If some instances cannot launch because of resource constraints, those instances remain in the Provisioning state and the pool remains in the Scaling state. Once size instances are launched, the pool can transition to the Running state. While the pool is in the Scaling state, pool instances that are in the Running state are available to use.

The following are examples of actions you can take if a pool instance fails to launch because of resource constraints:

Update the pool and reduce the "Number of instances" or size value.
Update the pool and change the Fault Domains specification in the Compute Web UI or in a new instance or placement configuration.
Update the pool to specify a new instance configuration that creates instances that require fewer resources.
Stop an instance that is not a member of a pool in the same fault domain where the pool instance is failing to launch because of resource constraints.
Terminate an instance that is not a member of a pool in the same fault domain where the pool instance is failing to launch because of resource constraints.

Using the Compute Web UI

In the navigation menu, click Compute, and then click Instance Configurations.
If the instance configuration that you want to use to create this pool is not listed, use the Compartment drop-down menu above the instance configurations list to select the correct compartment.
Click the instance configuration that you want to use for the instances in this pool.
In the Resources box on the instance configuration details page, click Attached Instance Pools. Use the Compartment drop-down menu above the instance pools list to list pools in other compartments.

Click the Create Instance Pool button.
In the Attach Instance Pool to instance_configuration_name dialog, enter the following information:
- Name: Enter a name for the instance pool. The name does not need to be unique. This name is used in the names of the created instances. If you do not provide a name for the pool, the default name of the instance pool is instancepoolYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.
- Create in Compartment: Select a compartment for this instance pool definition. Note that the instances in the pool will be created in the compartment that is specified in the instance configuration.
- Number of instances: Specify the number of instances to create in this instance pool.
- Pool Placement: Select the Fault Domains, VCN, and Subnet for instances in this instance pool. You can select a different compartment from which to choose the VCN and Subnet. See the descriptions of Placement Configuration and Fault Domains at the beginning of this section.
- Load Balancers: Click the Attach Load Balancers box to specify load balancing for this pool. For information about load balancing, see Load Balancer as a Service. Provide the following information:
  - Select the load balancer to attach to this pool.
  - Select the backend set to which to add these pool instances.
  - Enter the port number on the instances to which the load balancer must direct traffic.
  - Select the VNIC to use when adding the instance to the backend set. The private IP address is used.
  To attach another load balancer, click the Add Load Balancer button. To attach a load balancer after the instance pool is created, see Managing Instance Pool Load Balancer Attachments.
- Tagging: (Optional) Add defined or free-form tags for this instance pool as described in Adding Tags at Resource Creation. Tags can also be applied later.
  
  These tags are applied to the pool definition, not to the member instances.
Click the Create Instance Pool button in the dialog.

The details page of the new pool is displayed. The requested instances are listed in the Attached Instances table in the Resources section as they are created. The new instances are named inst-aaaaa-pool_name, where aaaaa is five random alphanumeric characters. If you change the name of the pool and then add new instances to the pool, the new instances will have the new name.

Click Work Request(s) in the Resources box to check the status of the instance pool create.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to create the instance pool definition: oci iam compartment list
  
  Note that the instances in the pool will be created in the compartment that is specified in the instance configuration.
- The OCID of the instance configuration that you want to use: oci compute-management instance-configuration list
- The size of the instance pool. This is the number of compute instances in the instance pool.
- If you want load balancing for this pool, get the following information:
  - OCID of the load balancer to attach to this pool and name of the backend set to which to add these pool instances: oci lb load-balancer list
  - Port value to use when creating the backend set.
  - VNIC to associate with the load balancer. The value can be PrimaryVnic or the display name of one of the secondary VNICs on the instance configuration that is associated with the instance pool.
Construct an argument for the --placement-configurations option.

See the descriptions of Placement Configuration and Fault Domains at the beginning of this section.

Use the following command to show the content of the placement configurations argument:
```
$ oci compute-management instance-pool create \
--generate-param-json-input placement-configurations
```
If you want load balancing for this pool, construct an argument for the --load-balancers option.

Use the following command to show the content of the load balancers argument:
```
$ oci compute-management instance-pool create \
--generate-param-json-input load-balancers
```
To attach a load balancer after the instance pool is created, see Managing Instance Pool Load Balancer Attachments.
Run the instance pool create command.

Syntax:
```
oci compute-management instance-pool create -c compartment_OCID \
--instance-configuration-id instance_configuration_OCID \
--placement-configurations file://placement_configuration.json \
--size number_of_instances
```
Example:
```
$ oci compute-management instance-pool create \
--compartment-id ocid1.compartment.unique_ID \
--display-name support-pool \
--instance-configuration-id ocid1.instanceConfiguration.unique_ID \
--placement-configurations file://./placement_configurations.json \
--load-balancers file://./load_balancers.json --size 10
```
The value of the --display-name option is the name of the pool. The pool name is not required to be unique. If you do not provide a value for the --display-name option, the default name of the instance pool is instancepoolYYYYMMDDhhmmss, where YYYYMMDDhhmmss is the creation date and time.

The pool name is used in the names of the instances. Instances in a pool are named inst-aaaaa-pool_name, where aaaaa is five random alphanumeric characters. If you change the name of the pool and then add new instances to the pool, the new instances will have the new name.

The output of this command is the same as the output of the instance-pool get command. The list of instances in the pool is not shown.

To list the instances that belong to this pool, use the following command:
```
$ oci compute-management instance-pool list-instances -c compartment_OCID \
--instance-pool-id instance_pool_OCID
```
The output for each instance is abbreviated compared with the output from the instance get command.

The following command shows the same abbreviated output for only the specified instance:
```
$ oci compute-management instance-pool-instance get --instance-id ocid1.instance.unique_ID \
--instance-pool-id ocid1.instancePool.unique_ID
```