Skip to content

Latest commit

 

History

History
135 lines (78 loc) · 7.16 KB

README.md

File metadata and controls

135 lines (78 loc) · 7.16 KB

AwsCommunity::Resource::Lookup

This resource uses AWS Cloud Control API to perform a lookup of a resource of a given type (such as, AWS::EC2::VPC) in your AWS account and current region, based on a query you specify. If only one match is found, this resource returns the primary ID of the resource (in the AWS::EC2::VPC example, the VPC ID) and the resource properties, that you can then reference in your template with the Fn::GetAtt intrinsic function. Specify resource type search targets that are supported by Cloud Control API.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
    "Type" : "AwsCommunity::Resource::Lookup",
    "Properties" : {
        "TypeName" : String,
        "JmesPathQuery" : String,
        "ResourceLookupRoleArn" : String,
        "ResourceModel" : String,
        "LookupSerialNumber" : String,
        "Tags" : Tags,
    }
}

YAML

Type: AwsCommunity::Resource::Lookup
Properties:
    TypeName: String
    JmesPathQuery: String
    ResourceLookupRoleArn: String
    ResourceModel: String
    LookupSerialNumber: String
    Tags: Tags

Properties

TypeName

The resource type name you wish to use for the lookup operation.

Required: Yes

Type: String

Pattern: ^[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}::[A-Za-z0-9]{2,64}$

Update requires: Replacement

JmesPathQuery

A query, in JMESPath (https://jmespath.org/) format, to perform the resource lookup; for example: Tags[?Key == 'Owner' && Value == 'test-only']. When you specify a new value on resource updates (for example, when you update the stack that describes this resource), a new lookup will be performed.

Required: Yes

Type: String

Minimum Length: 1

Maximum Length: 4096

Update requires: Replacement

ResourceLookupRoleArn

The Amazon Resource Name (ARN) of the IAM role you wish to use for performing resource lookup operations in your AWS account on your behalf; for example: arn:aws:iam::111122223333:role/my-example-role. The role whose ARN you specify for this property is passed to AWS Cloud Control API's ListResources and GetResource actions when this resource type calls them on your behalf against resource type targets (such as, AWS::EC2::VPC). As for the role, for example, you could create an IAM role whose Service Principal is cloudformation.amazonaws.com in the trust policy, and whose policy is e.g., a ReadOnlyAccess AWS managed policy, or another managed policy you choose, or your own policy, depending on which permissions you require.

Required: Yes

Type: String

Pattern: ^arn:aws(-[a-z]+)*:iam::[0-9]{12}:role/[\w+=,.@-]{1,64}$

Update requires: Replacement

ResourceModel

The model of the resource you're using: this additional information is required if you're using a resource type shown in the Resources that require additional information page (https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/resource-operations-list.html#resource-operations-list-containers). Specify the required properties using the JSON format; for example, to specify LoadBalancerArn and its ARN value for AWS::ElasticLoadBalancingV2::Listener (that you specify in the TypeName property): {"LoadBalancerArn": "REPLACE_WITH_YOUR_LOAD_BALANCER_ARN"}.

Required: No

Type: String

Pattern: ^[\s\S]*$

Update requires: Replacement

LookupSerialNumber

Optional, numeric integer value (such as 1, 2), that you can specify to induce a new search on e.g., stack updates without modifying the value for JmesPathQuery. Specify a value that is different from the previous one to induce the update; note that either adding this property to the resource if not present before an update, or removing it if previously added to the resource, will yield the same effect of changing the property value and will induce an update.

Required: No

Type: String

Pattern: ^[0-9]*$

Update requires: Replacement

Tags

Optional key-value pairs object (such as, Env: Dev, Name: Test) to associate to the AWS Systems Manager Parameter Store parameter resource, that the implementation of this resource type creates in your account to persist the lookup result.

Required: No

Type: Tags

Update requires: No interruption

Return Values

Ref

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the ResourceLookupId.

Fn::GetAtt

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

ResourceIdentifier

The resource identifier. For example, the ID of a VPC if you looked up an AWS::EC2::VPC resource type for which only one match was found.

ResourceLookupId

When this resource type finds only one match as the result of a lookup operation, it then creates an AWS Systems Manager Parameter Store parameter resource in your account and current region to persist the lookup result for subsequent use (for example, when its Read handler is invoked). ResourceLookupId holds the name of the Parameter Store parameter; for example: /CloudFormation/AwsCommunity/Resource/Lookup/resource-lookup-id-11112222-3333-aaaa-bbbb-ccccddddeeee.

ResourceProperties

The resource properties. For example, the properties of a VPC if you looked up an AWS::EC2::VPC resource type for which only one match was found.