hsm_clusters

Creates, updates, deletes, gets or lists a hsm_clusters resource.

Overview

Name	`hsm_clusters`
Type	Resource
Id	`oci.kms.hsm_clusters`

Fields

The following fields are returned by SELECT queries:

get
list

The specified HSM Cluster resource.

Name	Datatype	Description
`id`	`string`	The OCID of the HSMCluster resource.
`compartmentId`	`string`	The OCID of the compartment that contains this HSMCluster resource.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly display name for the HSMCluster resource. It does not have to be unique, and it is changeable. Avoid entering confidential information.
`dnsName`	`string`	DNS name for the HSM Cluster -- this will contain information about the region as well.
`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](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`lifecycleState`	`string`	The HSMCluster's current state. Example: `ACTIVE` (CREATING, INITIALIZATION_REQUIRED, INITIALIZING, ACTIVATION_REQUIRED, ACTIVATING, ACTIVE, DELETING, DELETED, PENDING_DELETION, SCHEDULING_DELETION, CANCELLING_DELETION)
`timeCreated`	`string (date-time)`	The date and time this HSM resource was created, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2023-04-03T21:10:29.600Z`
`timeOfDeletion`	`string (date-time)`	An optional property indicating when to delete the key, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2019-04-03T21:10:29.600Z`
`timeUpdated`	`string (date-time)`	The date and time this HSM resource was updated, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2023-04-03T21:10:29.600Z`

A list of HsmCluster resources.

Name	Datatype	Description
`id`	`string`	The OCID of a HSMCluster resource.
`compartmentId`	`string`	The OCID of the compartment that contains a particular HSMCluster resource.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly name for a HSMCluster resource. It does not have to be unique, and it is changeable. Avoid entering confidential information.
`dnsName`	`string`	DNS name for the HSMCluster -- this will contain information about the region as well.
`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](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`lifecycleState`	`string`	A HSMCluster resource's current lifecycle state. Example: `ACTIVE` (x-obmcs-enumref: #/definitions/HsmCluster/lifecycleState)
`timeCreated`	`string (date-time)`	The date and time a dedicated KMS resource was created, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2023-04-03T21:10:29.600Z`
`timeOfDeletion`	`string (date-time)`	An optional property indicating when to delete the resource, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2019-04-03T21:10:29.600Z`
`timeUpdated`	`string (date-time)`	The date and time a dedicated KMS resource was updated, expressed in [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp format. Example: `2023-04-03T21:10:29.600Z`

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`hsmClusterId`, `region`	`opc-request-id`	Retrieves configuration details for the specified HSM Cluster resource.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning read operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />read operations exceeds 10 requests per second for a given tenancy.<br />
`list`	`select`	`compartmentId`, `region`	`limit`, `page`, `opc-request-id`, `sortBy`, `sortOrder`	Lists all HSM cluster resources contained within the specified compartment.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning read operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />read operations exceeds 10 requests per second for a given tenancy.<br />
`create`	`insert`	`region`, `compartmentId`, `displayName`	`opc-request-id`, `opc-retry-token`	Creates a new HSM cluster resource.<br />
`update`	`update`	`hsmClusterId`, `region`	`if-match`, `opc-request-id`	Modifies properties of an HSM cluster resource, including `displayName`, `freeformTags` and `definedTags`.<br /><br />As a provisioning operation, this call is subject to a Key Management limit that applies to<br />the total number of requests across all provisioning write operations. Key Management might<br />throttle this call to reject an otherwise valid request when the total rate of provisioning<br />write operations exceeds 10 requests per second for a given tenancy.<br />
`cancel_hsm_cluster_deletion`	`exec`	`hsmClusterId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Cancels deletion of specified HSM Cluster, restores it and associated HSM partitions to pre-deletion states.
`change_compartment`	`exec`	`hsmClusterId`, `region`, `compartmentId`	`if-match`, `opc-request-id`, `opc-retry-token`	Moves a HSM Cluster resource to a different compartment within the same tenancy.<br />
`download_certificate_signing_request`	`exec`	`hsmClusterId`, `region`	`opc-request-id`, `opc-retry-token`, `if-match`	Retrieves the certificate signing request for the designated HSM Cluster resource.<br />
`schedule_hsm_cluster_deletion`	`exec`	`hsmClusterId`, `region`	`if-match`, `opc-request-id`, `opc-retry-token`	Schedules HSM cluster for deletion, update its lifecycle state to 'PENDING_DELETION' <br />and deletes it after the retention period.<br />
`upload_partition_certificates`	`exec`	`hsmClusterId`, `region`, `partitionCertificate`, `partitionOwnerCertificate`	`opc-request-id`, `opc-retry-token`, `if-match`	Uploads the partition owner certificates to the HSM Cluster resource.<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 of the compartment.
`hsmClusterId`	`string`	The OCID of the HSM Cluster. This is a unique identifier assigned to each hsmCluster.
`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)
`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.
`limit`	`integer`	The maximum number of items to return in a paginated "List" call.
`opc-request-id`	`string`	Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service.
`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 (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
`page`	`string`	The value of the `opc-next-page` response header from the previous "List" call.
`sortBy`	`string`	The field to sort by. You can specify only one sort order. The default order for `TIMECREATED` is descending. The default order for `DISPLAYNAME` is ascending.
`sortOrder`	`string`	The sort order to use, either ascending (`ASC`) or descending (`DESC`).

`SELECT` examples

get
list

Retrieves configuration details for the specified HSM Cluster resource. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning read operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning read operations exceeds 10 requests per second for a given tenancy.

SELECT
id,
compartmentId,
definedTags,
displayName,
dnsName,
freeformTags,
lifecycleState,
timeCreated,
timeOfDeletion,
timeUpdated
FROM oci.kms.hsm_clusters
WHERE hsmClusterId = '{{ hsmClusterId }}' -- required
AND region = '{{ region }}' -- required
AND opc-request-id = '{{ opc-request-id }}'
;

Lists all HSM cluster resources contained within the specified compartment. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning read operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning read operations exceeds 10 requests per second for a given tenancy.

SELECT
id,
compartmentId,
definedTags,
displayName,
dnsName,
freeformTags,
lifecycleState,
timeCreated,
timeOfDeletion,
timeUpdated
FROM oci.kms.hsm_clusters
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND opc-request-id = '{{ opc-request-id }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
;

`INSERT` examples

create
Manifest

Creates a new HSM cluster resource.

INSERT INTO oci.kms.hsm_clusters (
compartmentId,
definedTags,
displayName,
freeformTags,
region,
opc-request-id,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ displayName }}' /* required */,
'{{ freeformTags }}',
'{{ region }}',
'{{ opc-request-id }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
dnsName,
freeformTags,
lifecycleState,
timeCreated,
timeOfDeletion,
timeUpdated
;

# Description fields are for documentation purposes
- name: hsm_clusters
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the hsm_clusters resource.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The OCID of the compartment where you want to create this HSM cluster resource.
  - 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](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly display name for the HSM cluster resource. It does not have to be unique, and it is 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](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: opc-request-id
    value: "{{ opc-request-id }}"
    description: Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service. 
    description: Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service. 
  - 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 (e.g., 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 (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 

`UPDATE` examples

update

Modifies properties of an HSM cluster resource, including displayName, freeformTags and definedTags. As a provisioning operation, this call is subject to a Key Management limit that applies to the total number of requests across all provisioning write operations. Key Management might throttle this call to reject an otherwise valid request when the total rate of provisioning write operations exceeds 10 requests per second for a given tenancy.

UPDATE oci.kms.hsm_clusters
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}'
WHERE 
hsmClusterId = '{{ hsmClusterId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND opc-request-id = '{{ opc-request-id}}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
dnsName,
freeformTags,
lifecycleState,
timeCreated,
timeOfDeletion,
timeUpdated;

Lifecycle Methods

cancel_hsm_cluster_deletion
change_compartment
download_certificate_signing_request
schedule_hsm_cluster_deletion
upload_partition_certificates

Cancels deletion of specified HSM Cluster, restores it and associated HSM partitions to pre-deletion states.

EXEC oci.kms.hsm_clusters.cancel_hsm_cluster_deletion 
@hsmClusterId='{{ hsmClusterId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}'
;

Moves a HSM Cluster resource to a different compartment within the same tenancy.

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

Retrieves the certificate signing request for the designated HSM Cluster resource.

EXEC oci.kms.hsm_clusters.download_certificate_signing_request 
@hsmClusterId='{{ hsmClusterId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}'
;

Schedules HSM cluster for deletion, update its lifecycle state to 'PENDING_DELETION' and deletes it after the retention period.

EXEC oci.kms.hsm_clusters.schedule_hsm_cluster_deletion 
@hsmClusterId='{{ hsmClusterId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"timeOfDeletion": "{{ timeOfDeletion }}"
}'
;

Uploads the partition owner certificates to the HSM Cluster resource.

EXEC oci.kms.hsm_clusters.upload_partition_certificates 
@hsmClusterId='{{ hsmClusterId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@if-match='{{ if-match }}' 
@@json=
'{
"partitionCertificate": "{{ partitionCertificate }}", 
"partitionOwnerCertificate": "{{ partitionOwnerCertificate }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

Lifecycle Methods​