Class: AWSCDK::CloudAssemblySchema::CcAPIContextQuery

Inherits:
ContextLookupRoleOptions
  • Object
show all
Defined in:
cloud_assembly_schema/cc_api_context_query.rb

Overview

Query input for lookup up CloudFormation resources using CC API.

The example below is required to successfully compile CDK (otherwise, the CDK build will generate a synthetic example for the below, but it doesn't have enough type information about the literal string union to generate a validly compiling example).

Examples:

require 'aws-cdk-cloud-assembly-schema'

x = {
    type_name: "AWS::Some::Type",
    expected_match_count: "exactly-one",
    resource_model: {SomeArn: "arn:aws:...."},
    properties_to_return: ["SomeProp"],
    account: "11111111111",
    region: "us-east-1",
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(account:, region:, assume_role_additional_options: nil, lookup_role_arn: nil, lookup_role_external_id: nil, properties_to_return:, type_name:, dummy_value: nil, exact_identifier: nil, expected_match_count: nil, ignore_error_on_missing_context: nil, property_match: nil, resource_model: nil) ⇒ CcAPIContextQuery

Returns a new instance of CcAPIContextQuery.

Parameters:

  • account (String) —

    Query account.

  • region (String) —

    Query region.

  • assume_role_additional_options (Hash{String => Object}, nil) (defaults to: nil) —

    Additional options to pass to STS when assuming the lookup role.

  • lookup_role_arn (String, nil) (defaults to: nil) —

    The ARN of the role that should be used to look up the missing values.

  • lookup_role_external_id (String, nil) (defaults to: nil) —

    The ExternalId that needs to be supplied while assuming this role.

  • properties_to_return (Array<String>) —

    This is a set of properties returned from CC API that we want to return from ContextQuery.

  • type_name (String) —

    The CloudFormation resource type.

  • dummy_value (Object, nil) (defaults to: nil) —

    The value to return if the resource was not found and ignoreErrorOnMissingContext is true.

  • exact_identifier (String, nil) (defaults to: nil) —

    Identifier of the resource to look up using GetResource.

  • expected_match_count (String, nil) (defaults to: nil) —

    Expected count of results if propertyMatch is specified.

  • ignore_error_on_missing_context (Boolean, nil) (defaults to: nil) —

    Ignore an error and return the dummyValue instead if the resource was not found.

  • property_match (Hash{String => Object}, nil) (defaults to: nil) —

    Returns any resources matching these properties, using ListResources.

  • resource_model (Hash{String => Object}, nil) (defaults to: nil) —

    The resource model to use to select the resources, using ListResources..



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 38

def initialize(account:, region:, assume_role_additional_options: nil, lookup_role_arn: nil, lookup_role_external_id: nil, properties_to_return:, type_name:, dummy_value: nil, exact_identifier: nil, expected_match_count: nil, ignore_error_on_missing_context: nil, property_match: nil, resource_model: nil)
  @account = 
  Jsii::Type.check_type(@account, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "account")
  @region = region
  Jsii::Type.check_type(@region, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "region")
  @assume_role_additional_options = assume_role_additional_options
  Jsii::Type.check_type(@assume_role_additional_options, JSON.parse(Base64.strict_decode64("eyJjb2xsZWN0aW9uIjp7ImVsZW1lbnR0eXBlIjp7InByaW1pdGl2ZSI6ImFueSJ9LCJraW5kIjoibWFwIn19")), "assumeRoleAdditionalOptions") unless @assume_role_additional_options.nil?
  @lookup_role_arn = lookup_role_arn
  Jsii::Type.check_type(@lookup_role_arn, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "lookupRoleArn") unless @lookup_role_arn.nil?
  @lookup_role_external_id = lookup_role_external_id
  Jsii::Type.check_type(@lookup_role_external_id, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "lookupRoleExternalId") unless @lookup_role_external_id.nil?
  @properties_to_return = properties_to_return
  Jsii::Type.check_type(@properties_to_return, JSON.parse(Base64.strict_decode64("eyJjb2xsZWN0aW9uIjp7ImVsZW1lbnR0eXBlIjp7InByaW1pdGl2ZSI6InN0cmluZyJ9LCJraW5kIjoiYXJyYXkifX0=")), "propertiesToReturn")
  @type_name = type_name
  Jsii::Type.check_type(@type_name, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "typeName")
  @dummy_value = dummy_value
  Jsii::Type.check_type(@dummy_value, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJhbnkifQ==")), "dummyValue") unless @dummy_value.nil?
  @exact_identifier = exact_identifier
  Jsii::Type.check_type(@exact_identifier, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "exactIdentifier") unless @exact_identifier.nil?
  @expected_match_count = expected_match_count
  Jsii::Type.check_type(@expected_match_count, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJzdHJpbmcifQ==")), "expectedMatchCount") unless @expected_match_count.nil?
  @ignore_error_on_missing_context = ignore_error_on_missing_context
  Jsii::Type.check_type(@ignore_error_on_missing_context, JSON.parse(Base64.strict_decode64("eyJwcmltaXRpdmUiOiJib29sZWFuIn0=")), "ignoreErrorOnMissingContext") unless @ignore_error_on_missing_context.nil?
  @property_match = property_match
  Jsii::Type.check_type(@property_match, JSON.parse(Base64.strict_decode64("eyJjb2xsZWN0aW9uIjp7ImVsZW1lbnR0eXBlIjp7InByaW1pdGl2ZSI6ImFueSJ9LCJraW5kIjoibWFwIn19")), "propertyMatch") unless @property_match.nil?
  @resource_model = resource_model
  Jsii::Type.check_type(@resource_model, JSON.parse(Base64.strict_decode64("eyJjb2xsZWN0aW9uIjp7ImVsZW1lbnR0eXBlIjp7InByaW1pdGl2ZSI6ImFueSJ9LCJraW5kIjoibWFwIn19")), "resourceModel") unless @resource_model.nil?
end

Instance Attribute Details

#account ⇒ String (readonly)

Query account.

Returns:

  • (String) 


70
71
72
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 70

def 
  @account
end

#assume_role_additional_options ⇒ Hash{String => Object}? (readonly)

Note:

Default: - No additional options.

Additional options to pass to STS when assuming the lookup role.

  • RoleArn should not be used. Use the dedicated lookup_role_arn property instead.
  • ExternalId should not be used. Use the dedicated lookup_role_external_id instead.

Returns:

  • (Hash{String => Object}, nil)

See Also:



83
84
85
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 83

def assume_role_additional_options
  @assume_role_additional_options
end

#dummy_value ⇒ Object? (readonly)

Note:

Default: - No dummy value available

The value to return if the resource was not found and ignoreErrorOnMissingContext is true.

If supplied, dummy_value should be an array of objects.

dummy_value does not have to have elements, and it may have objects with different properties than the properties in properties_to_return, but it will be easiest for downstream code if the dummy_value conforms to the expected response shape.

Returns:

  • (Object, nil) 


132
133
134
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 132

def dummy_value
  @dummy_value
end

#exact_identifier ⇒ String? (readonly)

Note:

Default: - Either exactIdentifier or propertyMatch should be specified.

Identifier of the resource to look up using GetResource.

Specifying exactIdentifier will return exactly one result, or throw an error unless ignore_error_on_missing_context is set.

Returns:

  • (String, nil) 


140
141
142
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 140

def exact_identifier
  @exact_identifier
end

#expected_match_count ⇒ String? (readonly)

Note:

Default: 'any'

Expected count of results if propertyMatch is specified.

If the expected result count does not match the actual count, by default an error is produced and the result is not committed to cached context, and the user can correct the situation and try again without having to manually clear out the context key using cdk context --remove

If the value of * ignore_error_on_missing_context is true, the value of expected_match_count is at-least-one | exactly-one and the number of found resources is 0, dummy_value is returned and committed to context instead.

Returns:

  • (String, nil) 


155
156
157
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 155

def expected_match_count
  @expected_match_count
end

#ignore_error_on_missing_context ⇒ Boolean? (readonly)

Note:

Default: false

Ignore an error and return the dummyValue instead if the resource was not found.

  • In case of an exact_identifier lookup, return the dummy_value if the resource with that identifier was not found.
  • In case of a property_match lookup, return the dummy_value if expected_match_count is at-least-one | exactly-one and the number of resources found was 0.

if ignore_error_on_missing_context is set, dummy_value should be set and be an array.

Returns:

  • (Boolean, nil) 


167
168
169
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 167

def ignore_error_on_missing_context
  @ignore_error_on_missing_context
end

#lookup_role_arn ⇒ String? (readonly)

Note:

Default: - None

The ARN of the role that should be used to look up the missing values.

Returns:

  • (String, nil) 


88
89
90
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 88

def lookup_role_arn
  @lookup_role_arn
end

#lookup_role_external_id ⇒ String? (readonly)

Note:

Default: - No ExternalId will be supplied

The ExternalId that needs to be supplied while assuming this role.

Returns:

  • (String, nil) 


93
94
95
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 93

def lookup_role_external_id
  @lookup_role_external_id
end

#properties_to_return ⇒ Array<String> (readonly)

This is a set of properties returned from CC API that we want to return from ContextQuery.

If any properties listed here are absent from the target resource, an error will be thrown.

The returned object will always include the key Identifier with the CC-API returned field Identifier.

Notes on property completeness

CloudControl API's ListResources may return fewer properties than GetResource would, depending on the resource implementation.

The returned properties here are currently selected from the response object that CloudControl API returns to the CDK CLI.

However, if we find there is need to do so, we may decide to change this behavior in the future: we might change it to perform an additional GetResource call for resources matched by property_match.

Returns:

  • (Array<String>) 


114
115
116
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 114

def properties_to_return
  @properties_to_return
end

#property_match ⇒ Hash{String => Object}? (readonly)

Note:

Default: - Either exactIdentifier or propertyMatch should be specified.

Returns any resources matching these properties, using ListResources.

By default, specifying propertyMatch will successfully return 0 or more results. To throw an error if the number of results is unexpected (and prevent the query results from being committed to context), specify expected_match_count.

Notes on property completeness

CloudControl API's ListResources may return fewer properties than GetResource would, depending on the resource implementation.

The resources that property_match matches against will only ever be the properties returned by the ListResources call.

Returns:

  • (Hash{String => Object}, nil) 


185
186
187
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 185

def property_match
  @property_match
end

#region ⇒ String (readonly)

Query region.

Returns:

  • (String) 


74
75
76
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 74

def region
  @region
end

#resource_model ⇒ Hash{String => Object}? (readonly)

Note:

Default: - no resource Model is provided

The resource model to use to select the resources, using ListResources..

This is needed for sub-resources where the parent Arn is required.

See https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/resource-operations-list.html#resource-operations-list-containers

Returns:

  • (Hash{String => Object}, nil) 


194
195
196
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 194

def resource_model
  @resource_model
end

#type_name ⇒ String (readonly)

The CloudFormation resource type.

See https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html

Returns:

  • (String) 


120
121
122
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 120

def type_name
  @type_name
end

Class Method Details

.jsii_properties ⇒ Object 



196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 196

def self.jsii_properties
  {
    :account => "account",
    :region => "region",
    :assume_role_additional_options => "assumeRoleAdditionalOptions",
    :lookup_role_arn => "lookupRoleArn",
    :lookup_role_external_id => "lookupRoleExternalId",
    :properties_to_return => "propertiesToReturn",
    :type_name => "typeName",
    :dummy_value => "dummyValue",
    :exact_identifier => "exactIdentifier",
    :expected_match_count => "expectedMatchCount",
    :ignore_error_on_missing_context => "ignoreErrorOnMissingContext",
    :property_match => "propertyMatch",
    :resource_model => "resourceModel",
  }
end

Instance Method Details

#to_jsii ⇒ Object 



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'cloud_assembly_schema/cc_api_context_query.rb', line 214

def to_jsii
  result = {}
  result.merge!(super)
  result.merge!({
    "account" => @account,
    "region" => @region,
    "assumeRoleAdditionalOptions" => @assume_role_additional_options,
    "lookupRoleArn" => @lookup_role_arn,
    "lookupRoleExternalId" => @lookup_role_external_id,
    "propertiesToReturn" => @properties_to_return,
    "typeName" => @type_name,
    "dummyValue" => @dummy_value,
    "exactIdentifier" => @exact_identifier,
    "expectedMatchCount" => @expected_match_count,
    "ignoreErrorOnMissingContext" => @ignore_error_on_missing_context,
    "propertyMatch" => @property_match,
    "resourceModel" => @resource_model,
  })
  result.compact
end