instance_pools

Creates, updates, deletes, gets or lists an instance_pools resource.

Overview

Name	instance_pools
Type	Resource
Id	oci.compute.instance_pools

Fields

The following fields are returned by SELECT queries:

get

The instance pool was retrieved.

Name	Datatype	Description
id	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the instance pool.
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the instance pool.
definedTags	object	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
instanceConfigurationId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the instance configuration associated with the instance pool.
instanceDisplayNameFormatter	string	A user-friendly formatter for the instance pool's instances. Instance displaynames follow the format. The formatter does not retroactively change instance's displaynames, only instance displaynames in the future follow the format (x-default-description: null)
instanceHostnameFormatter	string	A user-friendly formatter for the instance pool's instances. Instance hostnames follow the format. The formatter does not retroactively change instance's hostnames, only instance hostnames in the future follow the format (x-default-description: null)
lifecycleManagement	object	The lifecycle management options for the instance pool.
lifecycleState	string	The current state of the instance pool. (PROVISIONING, SCALING, STARTING, STOPPING, TERMINATING, STOPPED, TERMINATED, RUNNING)
loadBalancers	array	The load balancers attached to the instance pool.
placementConfigurations	array	The placement configurations for the instance pool.
size	integer	The number of instances that should be in the instance pool.
timeCreated	string (date-time)	The date and time the instance pool was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z

list

Summary information for an instance pool.

Name	Datatype	Description
id	string	The OCID of the instance pool.
availabilityDomains	array	The availability domains for the instance pool.
compartmentId	string	The OCID of the compartment containing the instance pool.
definedTags	object	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
displayName	string	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
freeformTags	object	Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
instanceConfigurationId	string	The OCID of the instance configuration associated with the instance pool.
lifecycleState	string	The current state of the instance pool. (PROVISIONING, SCALING, STARTING, STOPPING, TERMINATING, STOPPED, TERMINATED, RUNNING)
size	integer	The number of instances that should be in the instance pool.
timeCreated	string (date-time)	The date and time the instance pool was created, in the format defined by [RFC3339](https:​//tools.ietf.org/html/rfc3339). Example: 2016-08-25T21:10:29.600Z

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	instancePoolId, region		Gets the specified instance pool
list	select	compartmentId, region	displayName, limit, page, sortBy, sortOrder, lifecycleState	Lists the instance pools in the specified compartment.
attach	insert	instancePoolId, region, loadBalancerId, backendSetName, port, vnicSelection	opc-retry-token, if-match	Attach a load balancer to the instance pool.<br />
create	insert	region, compartmentId, instanceConfigurationId, placementConfigurations, size	opc-retry-token	Creates an instance pool.<br /><br />To determine whether capacity is available for a specific shape before you create an instance pool,<br />use the [CreateComputeCapacityReport](#/en/iaas/latest/ComputeCapacityReport/CreateComputeCapacityReport)<br />operation.<br />
update	update	instancePoolId, region	opc-retry-token, if-match	Update the specified instance pool.<br /><br />The OCID of the instance pool remains the same.<br />
terminate	delete	instancePoolId, region	if-match	Terminate the specified instance pool.<br /><br />Warning: When you delete an instance pool, the resources that were created by the pool are permanently<br />deleted, including associated instances, attached boot volumes, and block volumes.<br /><br />If an autoscaling configuration applies to the instance pool, the autoscaling configuration will be deleted<br />asynchronously after the pool is deleted. You can also manually delete the autoscaling configuration using<br />the DeleteAutoScalingConfiguration operation in the Autoscaling API.<br />
change_compartment	exec	instancePoolId, region, compartmentId	if-match, opc-request-id, opc-retry-token	Moves an instance pool into a different compartment within the same tenancy. For<br />information about moving resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br /><br />When you move an instance pool to a different compartment, associated resources such as the instances in<br />the pool, boot volumes, VNICs, and autoscaling configurations are not moved.<br />
detach_instance_pool_instance	exec	instancePoolId, region, instanceId	opc-retry-token	Detaches an instance from an instance pool.<br />
detach_load_balancer	exec	instancePoolId, region, loadBalancerId, backendSetName	opc-retry-token, if-match	Detach a load balancer from the instance pool.<br />
reset_instance_pool	exec	instancePoolId, region	opc-retry-token, if-match	Performs the reset (immediate power off and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />
softreset_instance_pool	exec	instancePoolId, region	opc-retry-token, if-match	Performs the softreset (ACPI shutdown and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br /><br />Softreset gracefully reboots the instances by sending a shutdown command to the operating systems.<br />After waiting 15 minutes for the OS to shut down, the instances are powered off and then powered back on.<br />
softstop_instance_pool	exec	instancePoolId, region	opc-retry-token, if-match	Performs the softstop (ACPI shutdown and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br /><br />Softstop gracefully reboots the instances by sending a shutdown command to the operating systems.<br />After waiting 15 minutes for the OS to shutdown, the instances are powered off and then powered back on.<br />
start_instance_pool	exec	instancePoolId, region	opc-retry-token, if-match	Performs the start (power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />
stop_instance_pool	exec	instancePoolId, region	opc-retry-token, if-match	Performs the stop (immediate power off) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />
termination_proceed_instance_pool_instance	exec	instancePoolId, region, instanceId	opc-retry-token	Marks an instance in an instance pool to be ready for termination.<br />

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
compartmentId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
instancePoolId	string	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the instance pool.
region	string	OCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
displayName	string	A filter to return only resources that match the given display name exactly.
if-match	string	For optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleState	string	A filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limit	integer	For list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine). Example: 50
opc-request-id	string	Unique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-token	string	A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
page	string	For list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
sortBy	string	The field to sort by. You can provide one sort order (sortOrder). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive. Note: In general, some "List" operations (for example, ListInstances) let you optionally filter by availability domain if the scope of the resource type is within a single availability domain. If you call one of these "List" operations without specifying an availability domain, the resources are grouped by availability domain, then sorted.
sortOrder	string	The sort order to use, either ascending (ASC) or descending (DESC). The DISPLAYNAME sort order is case sensitive.

SELECT examples

get

Gets the specified instance pool

SELECT
id,
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
instanceDisplayNameFormatter,
instanceHostnameFormatter,
lifecycleManagement,
lifecycleState,
loadBalancers,
placementConfigurations,
size,
timeCreated
FROM oci.compute.instance_pools
WHERE instancePoolId = '{{ instancePoolId }}' -- required
AND region = '{{ region }}' -- required
;

list

Lists the instance pools in the specified compartment.

SELECT
id,
availabilityDomains,
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
lifecycleState,
size,
timeCreated
FROM oci.compute.instance_pools
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND displayName = '{{ displayName }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

INSERT examples

attach

Attach a load balancer to the instance pool.<br />

INSERT INTO oci.compute.instance_pools (
backendSetName,
loadBalancerId,
port,
vnicSelection,
instancePoolId,
region,
opc-retry-token,
if-match
)
SELECT 
'{{ backendSetName }}' /* required */,
'{{ loadBalancerId }}' /* required */,
{{ port }} /* required */,
'{{ vnicSelection }}' /* required */,
'{{ instancePoolId }}',
'{{ region }}',
'{{ opc-retry-token }}',
'{{ if-match }}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
instanceDisplayNameFormatter,
instanceHostnameFormatter,
lifecycleManagement,
lifecycleState,
loadBalancers,
placementConfigurations,
size,
timeCreated
;

create

Creates an instance pool.<br /><br />To determine whether capacity is available for a specific shape before you create an instance pool,<br />use the [CreateComputeCapacityReport](#/en/iaas/latest/ComputeCapacityReport/CreateComputeCapacityReport)<br />operation.<br />

INSERT INTO oci.compute.instance_pools (
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
instanceDisplayNameFormatter,
instanceHostnameFormatter,
lifecycleManagement,
loadBalancers,
placementConfigurations,
size,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ instanceConfigurationId }}' /* required */,
'{{ instanceDisplayNameFormatter }}',
'{{ instanceHostnameFormatter }}',
'{{ lifecycleManagement }}',
'{{ loadBalancers }}',
'{{ placementConfigurations }}' /* required */,
{{ size }} /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
instanceDisplayNameFormatter,
instanceHostnameFormatter,
lifecycleManagement,
lifecycleState,
loadBalancers,
placementConfigurations,
size,
timeCreated
;

Manifest

# Description fields are for documentation purposes
- name: instance_pools
props:
  - name: instancePoolId
    value: "{{ instancePoolId }}"
    description: Required parameter for the instance_pools resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the instance_pools resource.
  - name: backendSetName
    value: "{{ backendSetName }}"
    description: |
      The name of the backend set on the load balancer to add instances to.
  - name: loadBalancerId
    value: "{{ loadBalancerId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the load balancer to attach to the instance pool.
  - name: port
    value: {{ port }}
    description: |
      The port value to use when creating the backend set.
  - name: vnicSelection
    value: "{{ vnicSelection }}"
    description: |
      Indicates which VNIC on each instance in the pool should be used to associate with the load balancer.
      Possible values are "PrimaryVnic" or the displayName of one of the secondary VNICs on the instance configuration
      that is associated with the instance pool.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment containing the instance pool.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined tags for this resource. Each key is predefined and scoped to a
      namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly name. Does not have to be unique, and it's changeable.
      Avoid entering confidential information.
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      Free-form tags for this resource. Each tag is a simple key-value pair with no
      predefined name, type, or namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: instanceConfigurationId
    value: "{{ instanceConfigurationId }}"
    description: |
      The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the instance configuration associated
      with the instance pool.
  - name: instanceDisplayNameFormatter
    value: "{{ instanceDisplayNameFormatter }}"
    description: |
      A user-friendly formatter for the instance pool's instances. Instance displaynames follow the format.
      The formatter does not retroactively change instance's displaynames, only instance displaynames in the future follow the format
  - name: instanceHostnameFormatter
    value: "{{ instanceHostnameFormatter }}"
    description: |
      A user-friendly formatter for the instance pool's instances. Instance hostnames follow the format.
      The formatter does not retroactively change instance's hostnames, only instance hostnames in the future follow the format
  - name: lifecycleManagement
    description: |
      The lifecycle management options for the instance pool.
    value:
      lifecycleActions:
        preTermination:
          isEnabled: {{ isEnabled }}
          onTimeout:
            preserveBlockVolumeMode: "{{ preserveBlockVolumeMode }}"
            preserveBootVolumeMode: "{{ preserveBootVolumeMode }}"
          timeout: {{ timeout }}
  - name: loadBalancers
    description: |
      The load balancers to attach to the instance pool.
    value:
      - backendSetName: "{{ backendSetName }}"
        loadBalancerId: "{{ loadBalancerId }}"
        port: {{ port }}
        vnicSelection: "{{ vnicSelection }}"
  - name: placementConfigurations
    description: |
      The placement configurations for the instance pool. Provide one placement configuration for
      each availability domain.
      To use the instance pool with a regional subnet, provide a placement configuration for
      each availability domain, and include the regional subnet in each placement
      configuration.
      To use compute cluster with instance pool, provide a single placement configuration.
    value:
      - availabilityDomain: "{{ availabilityDomain }}"
        computeClusterId: "{{ computeClusterId }}"
        faultDomains: "{{ faultDomains }}"
        primarySubnetId: "{{ primarySubnetId }}"
        primaryVnicSubnets:
          ipv6AddressIpv6SubnetCidrPairDetails:
            - ipv6SubnetCidr: "{{ ipv6SubnetCidr }}"
          isAssignIpv6Ip: {{ isAssignIpv6Ip }}
          subnetId: "{{ subnetId }}"
        secondaryVnicSubnets: "{{ secondaryVnicSubnets }}"
  - name: size
    value: {{ size }}
    description: |
      The number of instances that should be in the instance pool.
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
  - name: if-match
    value: "{{ if-match }}"
    description: For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value. 
    description: For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value. 

UPDATE examples

update

Update the specified instance pool.<br /><br />The OCID of the instance pool remains the same.<br />

UPDATE oci.compute.instance_pools
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
instanceConfigurationId = '{{ instanceConfigurationId }}',
instanceDisplayNameFormatter = '{{ instanceDisplayNameFormatter }}',
instanceHostnameFormatter = '{{ instanceHostnameFormatter }}',
lifecycleManagement = '{{ lifecycleManagement }}',
placementConfigurations = '{{ placementConfigurations }}',
size = {{ size }}
WHERE 
instancePoolId = '{{ instancePoolId }}' --required
AND region = '{{ region }}' --required
AND opc-retry-token = '{{ opc-retry-token}}'
AND if-match = '{{ if-match}}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
freeformTags,
instanceConfigurationId,
instanceDisplayNameFormatter,
instanceHostnameFormatter,
lifecycleManagement,
lifecycleState,
loadBalancers,
placementConfigurations,
size,
timeCreated;

DELETE examples

terminate

Terminate the specified instance pool.<br /><br />Warning: When you delete an instance pool, the resources that were created by the pool are permanently<br />deleted, including associated instances, attached boot volumes, and block volumes.<br /><br />If an autoscaling configuration applies to the instance pool, the autoscaling configuration will be deleted<br />asynchronously after the pool is deleted. You can also manually delete the autoscaling configuration using<br />the DeleteAutoScalingConfiguration operation in the Autoscaling API.<br />

DELETE FROM oci.compute.instance_pools
WHERE instancePoolId = '{{ instancePoolId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods

change_compartment

Moves an instance pool into a different compartment within the same tenancy. For<br />information about moving resources between compartments, see<br />[Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br /><br />When you move an instance pool to a different compartment, associated resources such as the instances in<br />the pool, boot volumes, VNICs, and autoscaling configurations are not moved.<br />

EXEC oci.compute.instance_pools.change_compartment 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;

detach_instance_pool_instance

Detaches an instance from an instance pool.<br />

EXEC oci.compute.instance_pools.detach_instance_pool_instance 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"instanceId": "{{ instanceId }}", 
"isAutoTerminate": {{ isAutoTerminate }}, 
"isDecrementSize": {{ isDecrementSize }}
}'
;

detach_load_balancer

Detach a load balancer from the instance pool.<br />

EXEC oci.compute.instance_pools.detach_load_balancer 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}' 
@@json=
'{
"backendSetName": "{{ backendSetName }}", 
"loadBalancerId": "{{ loadBalancerId }}"
}'
;

reset_instance_pool

Performs the reset (immediate power off and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />

EXEC oci.compute.instance_pools.reset_instance_pool 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

softreset_instance_pool

Performs the softreset (ACPI shutdown and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br /><br />Softreset gracefully reboots the instances by sending a shutdown command to the operating systems.<br />After waiting 15 minutes for the OS to shut down, the instances are powered off and then powered back on.<br />

EXEC oci.compute.instance_pools.softreset_instance_pool 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

softstop_instance_pool

Performs the softstop (ACPI shutdown and power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br /><br />Softstop gracefully reboots the instances by sending a shutdown command to the operating systems.<br />After waiting 15 minutes for the OS to shutdown, the instances are powered off and then powered back on.<br />

EXEC oci.compute.instance_pools.softstop_instance_pool 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

start_instance_pool

Performs the start (power on) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />

EXEC oci.compute.instance_pools.start_instance_pool 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

stop_instance_pool

Performs the stop (immediate power off) action on the specified instance pool,<br />which performs the action on all the instances in the pool.<br />

EXEC oci.compute.instance_pools.stop_instance_pool 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

termination_proceed_instance_pool_instance

Marks an instance in an instance pool to be ready for termination.<br />

EXEC oci.compute.instance_pools.termination_proceed_instance_pool_instance 
@instancePoolId='{{ instancePoolId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"instanceId": "{{ instanceId }}"
}'
;