instances

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

Overview

Name	instances
Type	Resource
Id	aws.sso_admin.instances

Fields

The following fields are returned by SELECT queries:

describe_instance

Name	Datatype	Description
created_date	string (date-time)	The date the instance was created.
encryption_configuration_details	object	Contains the encryption configuration for your IAM Identity Center instance, including the encryption status, KMS key type, and KMS key ARN.
identity_store_id	string	The identifier of the identity store that is connected to the instance of IAM Identity Center. (pattern: <code>[a-zA-Z0-9-]*</code>)
instance_arn	string	The ARN of the instance of IAM Identity Center under which the operation will run. For more information about ARNs, see Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces in the Amazon Web Services General Reference. (pattern: <code>arn:aws(-[a-z]{1,5}){0,3}:sso:::instance/(sso)?ins-[a-zA-Z0-9-.]{16}</code>)
name	string	Specifies the instance name. (pattern: <code>[\w+=,.@-]+</code>)
owner_account_id	string	The identifier of the Amazon Web Services account for which the instance was created. (pattern: <code>\d{12}</code>)
permission_sets_enabled	boolean	Indicates whether permission sets are enabled for this Identity Center instance.
status	string	The status of the instance. (CREATE_IN_PROGRESS, CREATE_FAILED, DELETE_IN_PROGRESS, ACTIVE)
status_reason	string	Provides additional context about the current status of the IAM Identity Center instance. This field is particularly useful when an instance is in a non-ACTIVE state, such as CREATE_FAILED. When an instance fails to create or update, this field contains information about the cause, which may include issues with KMS key configuration, permission problems with the specified KMS key, or service-related errors. (pattern: <code>[\p{L}\p{M}\p{Z}\p{S}\p{N}\p{P}]*</code>)

list_instances

Name	Datatype	Description
created_date	string (date-time)	The date and time that the Identity Center instance was created.
identity_store_id	string	The identifier of the identity store that is connected to the Identity Center instance. (pattern: <code>[a-zA-Z0-9-]*</code>)
instance_arn	string	The ARN of the Identity Center instance under which the operation will be executed. For more information about ARNs, see Amazon Resource Names (ARNs) and Amazon Web Services Service Namespaces in the Amazon Web Services General Reference. (pattern: <code>arn:aws(-[a-z]{1,5}){0,3}:sso:::instance/(sso)?ins-[a-zA-Z0-9-.]{16}</code>)
name	string	The name of the Identity Center instance. (pattern: <code>[\w+=,.@-]+</code>)
owner_account_id	string	The Amazon Web Services account ID number of the owner of the Identity Center instance. (pattern: <code>\d{12}</code>)
primary_region	string	The primary Region where the IAM Identity Center instance was originally enabled. The primary Region cannot be removed. (pattern: <code>([a-z]+-){2,3}\d</code>)
regions	array	The list of Regions enabled in the IAM Identity Center instance, including Regions with ACTIVE, ADDING, or REMOVING status.
status	string	The current status of this Identity Center instance. (CREATE_IN_PROGRESS, CREATE_FAILED, DELETE_IN_PROGRESS, ACTIVE)
status_reason	string	Provides additional context about the current status of the IAM Identity Center instance. This field is particularly useful when an instance is in a non-ACTIVE state, such as CREATE_FAILED. When an instance creation fails, this field contains information about the cause, which may include issues with KMS key configuration or insufficient permissions. (pattern: <code>[\p{L}\p{M}\p{Z}\p{S}\p{N}\p{P}]*</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_instance	select	region		Returns the details of an instance of IAM Identity Center. The status can be one of the following: CREATE_IN_PROGRESS - The instance is in the process of being created. When the instance is ready for use, DescribeInstance returns the status of ACTIVE. While the instance is in the CREATE_IN_PROGRESS state, you can call only DescribeInstance and DeleteInstance operations. DELETE_IN_PROGRESS - The instance is being deleted. Returns AccessDeniedException after the delete operation completes. ACTIVE - The instance is active.
list_instances	select	region		Lists the details of the organization and account instances of IAM Identity Center that were created in or visible to the account calling this API.
create_instance	insert	region		Creates an instance of IAM Identity Center for a standalone Amazon Web Services account that is not managed by Organizations or a member Amazon Web Services account in an organization. You can create only one instance per account and across all Amazon Web Services Regions. The CreateInstance request is rejected if the following apply: The instance is created within the organization management account. An instance already exists in the same account.
update_instance	update	region, InstanceArn		Update the details for the instance of IAM Identity Center that is owned by the Amazon Web Services account. In a single UpdateInstance request, you can perform only one of the following operations: Update the encryption configuration of the instance by specifying EncryptionConfiguration. Enable permission sets for the instance by specifying PermissionSetsEnabled. A request that specifies both EncryptionConfiguration and PermissionSetsEnabled returns a ValidationException. To perform both operations, call UpdateInstance separately for each. The two calls can be made in parallel.
delete_instance	delete	region		Deletes the instance of IAM Identity Center. Only the account that owns the instance can call this API. Neither the delegated administrator nor member account can delete the organization instance, but those roles can delete their own instance.

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
region	string	AWS region (default: us-east-1)

SELECT examples

describe_instance

Returns the details of an instance of IAM Identity Center. The status can be one of the following: CREATE_IN_PROGRESS - The instance is in the process of being created. When the instance is ready for use, DescribeInstance returns the status of ACTIVE. While the instance is in the CREATE_IN_PROGRESS state, you can call only DescribeInstance and DeleteInstance operations. DELETE_IN_PROGRESS - The instance is being deleted. Returns AccessDeniedException after the delete operation completes. ACTIVE - The instance is active.

SELECT
created_date,
encryption_configuration_details,
identity_store_id,
instance_arn,
name,
owner_account_id,
permission_sets_enabled,
status,
status_reason
FROM aws.sso_admin.instances
WHERE region = '{{ region }}' -- required
;

list_instances

Lists the details of the organization and account instances of IAM Identity Center that were created in or visible to the account calling this API.

SELECT
created_date,
identity_store_id,
instance_arn,
name,
owner_account_id,
primary_region,
regions,
status,
status_reason
FROM aws.sso_admin.instances
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_instance

Creates an instance of IAM Identity Center for a standalone Amazon Web Services account that is not managed by Organizations or a member Amazon Web Services account in an organization. You can create only one instance per account and across all Amazon Web Services Regions. The CreateInstance request is rejected if the following apply: The instance is created within the organization management account. An instance already exists in the same account.

INSERT INTO aws.sso_admin.instances (
Name,
ClientToken,
Tags,
region
)
SELECT 
'{{ Name }}',
'{{ ClientToken }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
instance_arn
;

Manifest

# Description fields are for documentation purposes
- name: instances
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the instances resource.
  - name: Name
    value: "{{ Name }}"
    description: |
      The name of the instance of IAM Identity Center.
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      Specifies a unique, case-sensitive ID that you provide to ensure the idempotency of the request. This lets you safely retry the request without accidentally performing the same operation a second time. Passing the same value to a later call to an operation requires that you also pass the same value for all other parameters. We recommend that you use a UUID type of value. If you don't provide this value, then Amazon Web Services generates a random one for you. If you retry the operation with the same ClientToken, but with different parameters, the retry fails with an IdempotentParameterMismatch error.
  - name: Tags
    description: |
      Specifies tags to be attached to the instance of IAM Identity Center.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

UPDATE examples

update_instance

Update the details for the instance of IAM Identity Center that is owned by the Amazon Web Services account. In a single UpdateInstance request, you can perform only one of the following operations: Update the encryption configuration of the instance by specifying EncryptionConfiguration. Enable permission sets for the instance by specifying PermissionSetsEnabled. A request that specifies both EncryptionConfiguration and PermissionSetsEnabled returns a ValidationException. To perform both operations, call UpdateInstance separately for each. The two calls can be made in parallel.

UPDATE aws.sso_admin.instances
SET 
Name = '{{ Name }}',
InstanceArn = '{{ InstanceArn }}',
EncryptionConfiguration = '{{ EncryptionConfiguration }}',
PermissionSetsEnabled = {{ PermissionSetsEnabled }}
WHERE 
region = '{{ region }}' --required
AND InstanceArn = '{{ InstanceArn }}' --required;

DELETE examples

delete_instance

Deletes the instance of IAM Identity Center. Only the account that owns the instance can call this API. Neither the delegated administrator nor member account can delete the organization instance, but those roles can delete their own instance.

DELETE FROM aws.sso_admin.instances
WHERE region = '{{ region }}' --required
;