resource_shares

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

Overview

Name	`resource_shares`
Type	Resource
Id	`aws.ram.resource_shares`

Fields

The following fields are returned by SELECT queries:

get_resource_shares

Name	Datatype	Description
`name`	`string`	The name of the resource share.
`allow_external_principals`	`boolean`	Indicates whether principals outside your organization in Organizations can be associated with a resource share. True – the resource share can be shared with any Amazon Web Services account. False – the resource share can be shared with only accounts in the same organization as the account that owns the resource share.
`creation_time`	`string (date-time)`	The date and time when the resource share was created.
`feature_set`	`string`	Indicates what features are available for this resource share. This parameter can have one of the following values: STANDARD – A resource share that supports all functionality. These resource shares are visible to all principals you share the resource share with. You can modify these resource shares in RAM using the console or APIs. This resource share might have been created by RAM, or it might have been CREATED_FROM_POLICY and then promoted. CREATED_FROM_POLICY – The customer manually shared a resource by attaching a resource-based policy. That policy did not match any existing managed permissions, so RAM created this customer managed permission automatically on the customer's behalf based on the attached policy document. This type of resource share is visible only to the Amazon Web Services account that created it. You can't modify it in RAM unless you promote it. For more information, see PromoteResourceShareCreatedFromPolicy. PROMOTING_TO_STANDARD – This resource share was originally CREATED_FROM_POLICY, but the customer ran the PromoteResourceShareCreatedFromPolicy and that operation is still in progress. This value changes to STANDARD when complete. (CREATED_FROM_POLICY, PROMOTING_TO_STANDARD, STANDARD)
`last_updated_time`	`string (date-time)`	The date and time when the resource share was last updated.
`owning_account_id`	`string`	The ID of the Amazon Web Services account that owns the resource share.
`resource_share_arn`	`string`	The Amazon Resource Name (ARN) of the resource share
`resource_share_configuration`	`object`	The configuration of the resource share
`status`	`string`	The current status of the resource share. (PENDING, ACTIVE, FAILED, DELETING, DELETED)
`status_message`	`string`	A message about the status of the resource share.
`tags`	`array`	The tag key and value pairs attached to the resource share.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get_resource_shares`	`select`	`region`		Retrieves details about the resource shares that you own or that are shared with you. Always check the NextToken response parameter for a null value when calling a paginated operation. These operations can occasionally return an empty set of results even when there are more results available. The NextToken response parameter value is null only when there are no more results to display.
`create_resource_share`	`insert`	`region`, `name`		Creates a resource share. You can provide a list of the Amazon Resource Names (ARNs) for the resources that you want to share, a list of principals you want to share the resources with, the permissions to grant those principals, and optionally source constraints to enhance security for service principal sharing. Sharing a resource makes it available for use by principals outside of the Amazon Web Services account that created the resource. Sharing doesn't change any permissions or quotas that apply to the resource in the account that created it.
`associate_resource_share`	`update`	`region`, `resourceShareArn`		Adds the specified list of principals, resources, and source constraints to a resource share. Principals that already have access to this resource share immediately receive access to the added resources. Newly added principals immediately receive access to the resources shared in this resource share.
`delete_resource_share`	`delete`	`resourceShareArn`, `region`	`clientToken`	Deletes the specified resource share. This doesn't delete any of the resources that were associated with the resource share; it only stops the sharing of those resources through this resource share.
`accept_resource_share_invitation`	`exec`	`region`, `resourceShareInvitationArn`		Accepts an invitation to a resource share from another Amazon Web Services account. After you accept the invitation, the resources included in the resource share are available to interact with in the relevant Amazon Web Services Management Consoles and tools.
`disassociate_resource_share`	`exec`	`region`, `resourceShareArn`		Removes the specified principals, resources, or source constraints from participating in the specified resource share.
`promote_resource_share_created_from_policy`	`exec`	`resourceShareArn`, `region`		When you attach a resource-based policy to a resource, RAM automatically creates a resource share of featureSet=CREATED_FROM_POLICY with a managed permission that has the same IAM permissions as the original resource-based policy. However, this type of managed permission is visible to only the resource share owner, and the associated resource share can't be modified by using RAM. This operation promotes the resource share to a STANDARD resource share that is fully manageable in RAM. When you promote a resource share, you can then manage the resource share in RAM and it becomes visible to all of the principals you shared it with. Before you perform this operation, you should first run PromotePermissionCreatedFromPolicyto ensure that you have an appropriate customer managed permission that can be associated with this resource share after its is promoted. If this operation can't find a managed permission that exactly matches the existing CREATED_FROM_POLICY permission, then this operation fails.
`reject_resource_share_invitation`	`exec`	`region`, `resourceShareInvitationArn`		Rejects an invitation to a resource share from another Amazon Web Services account.
`update_resource_share`	`exec`	`region`, `resourceShareArn`		Modifies some of the properties of the specified resource share.

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)
`resourceShareArn`	`string`	Specifies the Amazon Resource Name (ARN) of the resource share to promote.
`clientToken`	`string`	Specifies a unique, case-sensitive identifier 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.

`SELECT` examples

get_resource_shares

Retrieves details about the resource shares that you own or that are shared with you. Always check the NextToken response parameter for a null value when calling a paginated operation. These operations can occasionally return an empty set of results even when there are more results available. The NextToken response parameter value is null only when there are no more results to display.

SELECT
name,
allow_external_principals,
creation_time,
feature_set,
last_updated_time,
owning_account_id,
resource_share_arn,
resource_share_configuration,
status,
status_message,
tags
FROM aws.ram.resource_shares
WHERE region = '{{ region }}' -- required
;

`INSERT` examples

create_resource_share
Manifest

Creates a resource share. You can provide a list of the Amazon Resource Names (ARNs) for the resources that you want to share, a list of principals you want to share the resources with, the permissions to grant those principals, and optionally source constraints to enhance security for service principal sharing. Sharing a resource makes it available for use by principals outside of the Amazon Web Services account that created the resource. Sharing doesn't change any permissions or quotas that apply to the resource in the account that created it.

INSERT INTO aws.ram.resource_shares (
name,
resourceArns,
principals,
tags,
allowExternalPrincipals,
clientToken,
permissionArns,
sources,
resourceShareConfiguration,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ resourceArns }}',
'{{ principals }}',
'{{ tags }}',
{{ allowExternalPrincipals }},
'{{ clientToken }}',
'{{ permissionArns }}',
'{{ sources }}',
'{{ resourceShareConfiguration }}',
'{{ region }}'
RETURNING
client_token,
resource_share
;

# Description fields are for documentation purposes
- name: resource_shares
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the resource_shares resource.
  - name: name
    value: "{{ name }}"
  - name: resourceArns
    value:
      - "{{ resourceArns }}"
  - name: principals
    value:
      - "{{ principals }}"
  - name: tags
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
  - name: allowExternalPrincipals
    value: {{ allowExternalPrincipals }}
  - name: clientToken
    value: "{{ clientToken }}"
  - name: permissionArns
    value:
      - "{{ permissionArns }}"
  - name: sources
    value:
      - "{{ sources }}"
  - name: resourceShareConfiguration
    description: |
      The configuration of the resource share
    value:
      retainSharingOnAccountLeaveOrganization: {{ retainSharingOnAccountLeaveOrganization }}

`UPDATE` examples

associate_resource_share

Adds the specified list of principals, resources, and source constraints to a resource share. Principals that already have access to this resource share immediately receive access to the added resources. Newly added principals immediately receive access to the resources shared in this resource share.

UPDATE aws.ram.resource_shares
SET 
resourceShareArn = '{{ resourceShareArn }}',
resourceArns = '{{ resourceArns }}',
principals = '{{ principals }}',
clientToken = '{{ clientToken }}',
sources = '{{ sources }}'
WHERE 
region = '{{ region }}' --required
AND resourceShareArn = '{{ resourceShareArn }}' --required
RETURNING
client_token,
resource_share_associations;

`DELETE` examples

delete_resource_share

Deletes the specified resource share. This doesn't delete any of the resources that were associated with the resource share; it only stops the sharing of those resources through this resource share.

DELETE FROM aws.ram.resource_shares
WHERE resourceShareArn = '{{ resourceShareArn }}' --required
AND region = '{{ region }}' --required
AND clientToken = '{{ clientToken }}'
;

Lifecycle Methods

accept_resource_share_invitation
disassociate_resource_share
promote_resource_share_created_from_policy
reject_resource_share_invitation
update_resource_share

Accepts an invitation to a resource share from another Amazon Web Services account. After you accept the invitation, the resources included in the resource share are available to interact with in the relevant Amazon Web Services Management Consoles and tools.

EXEC aws.ram.resource_shares.accept_resource_share_invitation 
@region='{{ region }}' --required 
@@json=
'{
"resourceShareInvitationArn": "{{ resourceShareInvitationArn }}", 
"clientToken": "{{ clientToken }}"
}'
;

Removes the specified principals, resources, or source constraints from participating in the specified resource share.

EXEC aws.ram.resource_shares.disassociate_resource_share 
@region='{{ region }}' --required 
@@json=
'{
"resourceShareArn": "{{ resourceShareArn }}", 
"resourceArns": "{{ resourceArns }}", 
"principals": "{{ principals }}", 
"clientToken": "{{ clientToken }}", 
"sources": "{{ sources }}"
}'
;

When you attach a resource-based policy to a resource, RAM automatically creates a resource share of featureSet=CREATED_FROM_POLICY with a managed permission that has the same IAM permissions as the original resource-based policy. However, this type of managed permission is visible to only the resource share owner, and the associated resource share can't be modified by using RAM. This operation promotes the resource share to a STANDARD resource share that is fully manageable in RAM. When you promote a resource share, you can then manage the resource share in RAM and it becomes visible to all of the principals you shared it with. Before you perform this operation, you should first run PromotePermissionCreatedFromPolicyto ensure that you have an appropriate customer managed permission that can be associated with this resource share after its is promoted. If this operation can't find a managed permission that exactly matches the existing CREATED_FROM_POLICY permission, then this operation fails.

EXEC aws.ram.resource_shares.promote_resource_share_created_from_policy 
@resourceShareArn='{{ resourceShareArn }}' --required, 
@region='{{ region }}' --required
;

Rejects an invitation to a resource share from another Amazon Web Services account.

EXEC aws.ram.resource_shares.reject_resource_share_invitation 
@region='{{ region }}' --required 
@@json=
'{
"resourceShareInvitationArn": "{{ resourceShareInvitationArn }}", 
"clientToken": "{{ clientToken }}"
}'
;

Modifies some of the properties of the specified resource share.

EXEC aws.ram.resource_shares.update_resource_share 
@region='{{ region }}' --required 
@@json=
'{
"resourceShareArn": "{{ resourceShareArn }}", 
"name": "{{ name }}", 
"allowExternalPrincipals": {{ allowExternalPrincipals }}, 
"clientToken": "{{ clientToken }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​