access_grants_instances

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

Overview

Name	access_grants_instances
Type	Resource
Id	aws.s3control.access_grants_instances

Fields

The following fields are returned by SELECT queries:

get_access_grants_instance

Name	Datatype	Description
access_grants_instance_arn	string	The Amazon Resource Name (ARN) of the S3 Access Grants instance.
access_grants_instance_id	string	The ID of the S3 Access Grants instance. The ID is default. You can have one S3 Access Grants instance per Region per account.
created_at	string	The date and time when you created the S3 Access Grants instance.
identity_center_application_arn	string	If you associated your S3 Access Grants instance with an Amazon Web Services IAM Identity Center instance, this field returns the Amazon Resource Name (ARN) of the IAM Identity Center instance application; a subresource of the original Identity Center instance. S3 Access Grants creates this Identity Center application for the specific S3 Access Grants instance.
identity_center_arn	string	If you associated your S3 Access Grants instance with an Amazon Web Services IAM Identity Center instance, this field returns the Amazon Resource Name (ARN) of the IAM Identity Center instance application; a subresource of the original Identity Center instance. S3 Access Grants creates this Identity Center application for the specific S3 Access Grants instance.
identity_center_instance_arn	string	The Amazon Resource Name (ARN) of the Amazon Web Services IAM Identity Center instance that you are associating with your S3 Access Grants instance. An IAM Identity Center instance is your corporate identity directory that you added to the IAM Identity Center. You can use the ListInstances API operation to retrieve a list of your Identity Center instances and their ARNs.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_access_grants_instance	select	x-amz-account-id, region		Retrieves the S3 Access Grants instance for a Region in your account. Permissions You must have the s3:GetAccessGrantsInstance permission to use this operation. GetAccessGrantsInstance is not supported for cross-account access. You can only call the API from the account that owns the S3 Access Grants instance.
create_access_grants_instance	insert	x-amz-account-id, region		Creates an S3 Access Grants instance, which serves as a logical grouping for access grants. You can create one S3 Access Grants instance per Region per account. Permissions You must have the s3:CreateAccessGrantsInstance permission to use this operation. Additional Permissions To associate an IAM Identity Center instance with your S3 Access Grants instance, you must also have the sso:DescribeInstance, sso:CreateApplication, sso:PutApplicationGrant, and sso:PutApplicationAuthenticationMethod permissions.
delete_access_grants_instance	delete	x-amz-account-id, region		Deletes your S3 Access Grants instance. You must first delete the access grants and locations before S3 Access Grants can delete the instance. See DeleteAccessGrant and DeleteAccessGrantsLocation. If you have associated an IAM Identity Center instance with your S3 Access Grants instance, you must first dissassociate the Identity Center instance from the S3 Access Grants instance before you can delete the S3 Access Grants instance. See AssociateAccessGrantsIdentityCenter and DissociateAccessGrantsIdentityCenter. Permissions You must have the s3:DeleteAccessGrantsInstance permission to use this operation.
list_access_grants_instances	exec	x-amz-account-id, region	nextToken, maxResults	Returns a list of S3 Access Grants instances. An S3 Access Grants instance serves as a logical grouping for your individual access grants. You can only have one S3 Access Grants instance per Region per account. Permissions You must have the s3:ListAccessGrantsInstances permission to use this operation.

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)
x-amz-account-id	string	The Amazon Web Services account ID of the S3 Access Grants instance.
maxResults	integer	The maximum number of access grants that you would like returned in the List Access Grants response. If the results include the pagination token NextToken, make another call using the NextToken to determine if there are more results.
nextToken	string	A pagination token to request the next page of results. Pass this value into a subsequent List Access Grants Instances request in order to retrieve the next page of results.

SELECT examples

get_access_grants_instance

Retrieves the S3 Access Grants instance for a Region in your account. Permissions You must have the s3:GetAccessGrantsInstance permission to use this operation. GetAccessGrantsInstance is not supported for cross-account access. You can only call the API from the account that owns the S3 Access Grants instance.

SELECT
access_grants_instance_arn,
access_grants_instance_id,
created_at,
identity_center_application_arn,
identity_center_arn,
identity_center_instance_arn
FROM aws.s3control.access_grants_instances
WHERE `x-amz-account-id` = '{{ x-amz-account-id }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples

create_access_grants_instance

Creates an S3 Access Grants instance, which serves as a logical grouping for access grants. You can create one S3 Access Grants instance per Region per account. Permissions You must have the s3:CreateAccessGrantsInstance permission to use this operation. Additional Permissions To associate an IAM Identity Center instance with your S3 Access Grants instance, you must also have the sso:DescribeInstance, sso:CreateApplication, sso:PutApplicationGrant, and sso:PutApplicationAuthenticationMethod permissions.

INSERT INTO aws.s3control.access_grants_instances (
IdentityCenterArn,
Tags,
`x-amz-account-id`,
region
)
SELECT 
'{{ IdentityCenterArn }}',
'{{ Tags }}',
'{{ x-amz-account-id }}',
'{{ region }}'
RETURNING
access_grants_instance_arn,
access_grants_instance_id,
created_at,
identity_center_application_arn,
identity_center_arn,
identity_center_instance_arn
;

Manifest

# Description fields are for documentation purposes
- name: access_grants_instances
props:
  - name: x-amz-account-id
    value: "{{ x-amz-account-id }}"
    description: Required parameter for the access_grants_instances resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the access_grants_instances resource.
  - name: IdentityCenterArn
    value: "{{ IdentityCenterArn }}"
  - name: Tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

DELETE examples

delete_access_grants_instance

Deletes your S3 Access Grants instance. You must first delete the access grants and locations before S3 Access Grants can delete the instance. See DeleteAccessGrant and DeleteAccessGrantsLocation. If you have associated an IAM Identity Center instance with your S3 Access Grants instance, you must first dissassociate the Identity Center instance from the S3 Access Grants instance before you can delete the S3 Access Grants instance. See AssociateAccessGrantsIdentityCenter and DissociateAccessGrantsIdentityCenter. Permissions You must have the s3:DeleteAccessGrantsInstance permission to use this operation.

DELETE FROM aws.s3control.access_grants_instances
WHERE `x-amz-account-id` = '{{ x-amz-account-id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

list_access_grants_instances

Returns a list of S3 Access Grants instances. An S3 Access Grants instance serves as a logical grouping for your individual access grants. You can only have one S3 Access Grants instance per Region per account. Permissions You must have the s3:ListAccessGrantsInstances permission to use this operation.

EXEC aws.s3control.access_grants_instances.list_access_grants_instances 
@x-amz-account-id='{{ x-amz-account-id }}' --required, 
@region='{{ region }}' --required, 
@nextToken='{{ nextToken }}', 
@maxResults='{{ maxResults }}'
;