• Record and Delete a Configuration State for Third-Party Resources Using AWS CLI (p. 69)
• Managing a Configuration State for Third-Party Resources Type Using APIs (p. 71)
• Region Support (p. 71)
Step 1: Setup Your Development Environment
Install and configure AWS CloudFormation AWS CLI. The AWS CLI allows you to model and register your custom resources. For more information, see Custom Resources and What Is the CloudFormation Command Line Interface?.
Step 2: Model Your Resource
Create a resource provider schema that conforms to and validates the configuration of the resource type.
1. Use the init command to create your resource provider project and generate the files it requires.
$ cfn init
Initializing new project
2. The init command launches a wizard that walks you through setting up the project, including specifying the resource name. For this walkthrough, specify MyCustomNamespace::Testing::WordPress.
Enter resource type identifier (Organization::Service::Resource):
MyCustomNamespace::Testing::WordPress 3. Enter a package name for your resource.
Enter a package name (empty for default 'com.custom.testing.wordpress'):
com.custom.testing.wordpress
Initialized a new project in /workplace/user/custom-testing-wordpress
Note
In order to guarantee that any project dependencies are correctly resolved, you can import the generated project into your IDE with Maven support.
For example, if you are using IntelliJ IDEA, you would need to do the following:
• From the File menu, choose New, then choose Project From Existing Sources.
• Navigate to the project directory
• In the Import Project dialog box, choose Import project from external model and then choose Maven.
• Choose Next and accept any defaults to complete importing the project.
Step 3: Generate Artifacts
4. Open the mycustomnamespace-testing-wordpress.json file that contains the schema for your resource. Copy and paste the following schema into mycustomnamespace-testing-wordpress.json.
{ "typeName": "MyCustomNamespace::Testing::WordPress",
"description": "An example resource that creates a website based on WordPress 5.2.2.",
"properties": { "Name": {
"description": "A name associated with the website.", "type": "string",
"pattern": "^[a-zA-Z0-9]{1,219}\\Z", "minLength": 1, "maxLength": 219 },
"SubnetId": {
"description": "A subnet in which to host the website.", "pattern": "^(subnet-[a-f0-9]{13})|(subnet-[a-f0-9]{8})\\Z", "type": "string"
},
"InstanceId": {
"description": "The ID of the instance that backs the WordPress site.", "type": "string"
},
"PublicIp": {
"description": "The public IP for the WordPress site.", "type": "string"
}
}, "required": [ "Name", "SubnetId" ],
"primaryIdentifier": [ "/properties/PublicIp", "/properties/InstanceId" ], "readOnlyProperties": [ "/properties/PublicIp", "/properties/InstanceId" ], "additionalProperties": false
}
5. Validate the schema.
$ cfn validate
6. Update the auto-generated files in the resource provider package to view the resource provider schema updates. Upon initiation of the resource provider project, the AWS CLI generates supporting files and code for the resource provider. Regenerate the code to see the updated schema.
$ cfn generate
NoteWhen using Maven, as part of the build process the generate command is automatically run before the code is compiled. So your changes will never get out of sync with the generated code.
Be aware the CloudFormation CLI must be in a location Maven/the system can find. For more information, see Setting up your environment for developing extensions.
For more information on the whole process, see Modeling Resource Providers for Use in AWS CloudFormation.
Step 3: Generate Artifacts
Run the following command to generate artifacts for cfn submit.
Step 4: Register Your Resource
$ mvn package
Step 4: Register Your Resource
AWS Config does not require resource provider handlers to perform configuration tracking for your resource. Run the following command to register your resource.
$ cfn submit
For more information, see Registering Resource Providers for Use in AWS CloudFormation Templates.
Step 5: Publish Resource Configuration
Determine the configuration for MyCustomNamespace::Testing::WordPress.
{
"Name": "MyWordPressSite", "SubnetId": "subnet-abcd0123", "InstanceId": "i-01234567",
"PublicIp": "my-wordpress-site.com"
}
Determine the schema version id from AWS CloudFormation DescribeType.
In the AWS Config see if this resource configuration is accepted. To evaluate compliance you can write AWS Config rules using this resource. For additional information, see Record and Delete a Configuration State for Third-Party Resources Using AWS CLI.
Optional: To automate recording of configuration, implement a periodic or change-based configuration collectors.
Record and Delete a Configuration State for Third-Party Resources Using AWS CLI
The AWS CLI is a unified tool to manage your AWS services. With just one tool to download and configure, you can control multiple AWS services from the command line and use scripts to automate them.
To install the AWS CLI on your local machine, see Installing the AWS CLI in the AWS CLI User Guide.
If necessary, type aws configure to configure the AWS CLI.
Topics
• Record a Configuration Item (p. 69)
• Read the Configuration Item using AWS Config APIs (p. 70)
• Delete the Third-Party Resource (p. 71)
Record a Configuration Item
Record a configuration item for a third-party resource or a custom resource type using the following procedure:
Ensure you register the resource type MyCustomNamespace::Testing::WordPress with its matching schema.
Record and Delete a Configuration State for Third-Party Resources Using AWS CLI 1. Open a command prompt or a terminal window.
2. Type the following command:
aws configservice put-resource-config --resource-type
MyCustomNamespace::Testing::WordPress --resource-id resource-001 --schema-version-id 00000001 --configuration '{
"Id": "resource-001",
"Name": "My example custom resource.", "PublicAccess": false
}'
NoteAs defined in the type schema, writeOnlyProperties will be removed from the configuration prior to being recorded by AWS Config. This means that these values will not be present when the configuration is obtained via read APIs. For more information on writeOnlyProperties, see Resource type schema.
Read the Configuration Item using AWS Config APIs
1. Open a command prompt or a terminal window.
2. Type the following command:
aws configservice list-discovered-resources --resource-type MyCustomNamespace::Testing::WordPress
3. Press Enter.
You should see output similar to the following:
{
"resourceIdentifiers": [ {
"resourceType": "MyCustomNamespace::Testing::WordPress", "resourceId": "resource-001"
} ]
}
4. Type the following command:
aws configservice batch-get-resource-config --resource-keys '[ { "resourceType":
"MyCustomNamespace::Testing::WordPress", "resourceId": "resource-001" } ]' 5. Press Enter.
You should see output similar to the following:
{ "unprocessedResourceKeys": [], "baseConfigurationItems": [ {
"configurationItemCaptureTime": 1569605832.673,
"resourceType": "MyCustomNamespace::Testing::WordPress", "resourceId": "resource-001",
"configurationStateId": "1569605832673", "awsRegion": "us-west-2",
"version": "1.3",
Managing a Configuration State for Third-Party Resources Type Using APIs "supplementaryConfiguration": {},
"configuration": "{\"Id\":\"resource-001\",\"Name\":\"My example custom resource.\",\"PublicAccess\":false}",
"configurationItemStatus": "ResourceDiscovered", "accountId": "AccountId"
} ]
}
Delete the Third-Party Resource
You can record the configuration state for a third-party resource or custom resource type that you want to delete.
• Type the following command:
aws configservice delete-resource-config --resource-type
MyCustomNamespace::Testing::WordPress --resource-id resource-002
If successful, the command executes with no additional output.
Managing a Configuration State for Third-Party Resources Type Using APIs
You can manage a configuration state for third-party resources or custom resource type using PutResourceConfig and DeleteResourceConfig APIs. For more information, see the API Reference.
• PutResourceConfig
• DeleteResourceConfig
Region Support
This feature is supported in the following regions:
Region
Name Region Endpoint Protocol
Asia Pacific
(Mumbai) ap-south-1 config.ap-south-1.amazonaws.com HTTPS
Asia Pacific
(Seoul)
ap-northeast-2 config.ap-northeast-2.amazonaws.com HTTPS
Asia Pacific (Singapore)
ap-southeast-1 config.ap-southeast-1.amazonaws.com HTTPS
Asia Pacific (Sydney)
ap-southeast-2 config.ap-southeast-2.amazonaws.com HTTPS
Asia Pacific
(Tokyo)
ap-northeast-1 config.ap-northeast-1.amazonaws.com HTTPS
Advanced Queries
Region
Name Region Endpoint Protocol
Canada
(Central) ca-central-1 config.ca-central-1.amazonaws.com HTTPS
Europe
(Frankfurt) eu-central-1 config.eu-central-1.amazonaws.com HTTPS Europe
(Ireland) eu-west-1 config.eu-west-1.amazonaws.com HTTPS
Europe
(London) eu-west-2 config.eu-west-2.amazonaws.com HTTPS
Europe
(Paris) eu-west-3 config.eu-west-3.amazonaws.com HTTPS
Europe
(Stockholm) eu-north-1 config.eu-north-1.amazonaws.com HTTPS
South America (São Paulo)
sa-east-1 config.sa-east-1.amazonaws.com HTTPS
US East (N.
Virginia) us-east-1 config.us-east-1.amazonaws.com HTTPS
US East
(Ohio) us-east-2 config.us-east-2.amazonaws.com HTTPS
US West (N.
California) us-west-1 config.us-west-1.amazonaws.com HTTPS
US West
(Oregon) us-west-2 config.us-west-2.amazonaws.com HTTPS
Querying the Current Configuration State of AWS Resources
You can use AWS Config to query the current configuration state of AWS resources based on
configuration properties for a single account and Region or across multiple accounts and Regions. You can perform ad hoc, property-based queries against current AWS resource state metadata across all resources that AWS Config supports. The advanced query feature provides a single query endpoint and a powerful query language to get current resource state metadata without performing service-specific describe API calls. You can use configuration aggregators to run the same queries from a central account across multiple accounts and AWS Regions.
AWS Config uses a subset of structured query language (SQL) SELECT syntax to perform property-based queries and aggregations on the current configuration item (CI) data. The queries range in complexity from simple matches against tag and/or resource identifiers, to more complex queries, such as viewing all Amazon S3 buckets that have versioning disabled. This allows you to query exactly the current resource state you need without performing AWS service-specific API calls.
You can use advanced query for:
• Inventory management; for example, to retrieve a list of Amazon EC2 instances of a particular size.
Features
• Security and operational intelligence; for example, to retrieve a list of resources that have a specific configuration property enabled or disabled.
• Cost optimization; for example, to identify a list of Amazon EBS volumes that are not attached to any EC2 instance.
• Compliance data; for example, to retrieve a list of all your conformance packs and their compliance status.
Topics
• Features (p. 73)
• Limitations (p. 73)
• Region Support (p. 74)
• Query Using the SQL Query Editor (Console) (p. 76)
• Query Using the SQL Query Editor (AWS CLI) (p. 77)
• Example Queries (p. 80)
• Example Relationship Queries (p. 84)
• Query Components (p. 85)
Features
The query language supports querying AWS resources based on CI properties of all AWS resource types supported by AWS Config, including configuration data, tags, and relationships. It is a subset of SQL SELECT command with limitations, as mentioned in the following section. It supports aggregation functions such as AVG, COUNT, MAX, MIN, and SUM.
Limitations
As a subset of SQL SELECT, the query syntax has following limitations:
• No support for ALL, AS, DISTINCT, FROM, HAVING, JOIN, and UNION keywords in a query. NULL value queries are not supported.
• No support for querying on third-party resources. Third-party resources retrieved using advanced queries will have the configuration field set as NULL.
• No support for nested structures (such as tags) to be unpacked with SQL queries.
• When querying against multiple properties within an array of objects, matches are computed against all the array elements. For example, for a resource R with rules A and B, the resource is compliant to rule A but noncompliant to rule B. The resource R is stored as:
{ configRuleList: [
{ configRuleName: 'A', complianceType: 'compliant' }, { configRuleName: 'B', complianceType: 'non_compliant' } ]}
R will be returned by this query:
SELECT configuration WHERE configuration.configRuleList.complianceType = 'non_compliant' AND configuration.configRuleList.configRuleName = 'A'
The first condition configuration.configRuleList.complianceType = 'non_compliant' is applied to ALL elements in R.configRuleList, because R has a rule (rule B) with
Region Support
complianceType = ‘non_compliant’, the condition is evaluated as true. The second condition configuration.configRuleList.configRuleName is applied to ALL elements in
R.configRuleList, because R has a rule (rule A) with configRuleName = ‘A’, the condition is evaluated as true. As both conditions are true, R will be returned.
• The SELECT all columns shorthand (that is SELECT *) selects only the top-level, scalar properties of a CI. The scalar properties returned are accountId, awsRegion, arn, availabilityZone, configurationItemCaptureTime, resourceCreationTime, resourceId, resourceName, resourceType, and version.
• Wildcard limitations:
• Wildcards are supported only for property values and not for property keys (for example, ...WHERE someKey LIKE 'someValue%' is supported but ...WHERE 'someKey%' LIKE 'someValue%' is not supported).
• Support for only suffix wildcards (for example, ...LIKE 'AWS::EC2::%' and ...LIKE 'AWS::EC2::_' is supported but ...LIKE '%::EC2::Instance' and ...LIKE '_::EC2::Instance'is not supported).
• Wildcard matches must be at least three characters long (for example, ...LIKE 'ab%' and ...LIKE 'ab_' is not allowed but ...LIKE 'abc%' and ...LIKE 'abc_' is allowed).
NoteThe "_" (single underscore) is also treated as a wildcard.
• Aggregation limitations:
• Aggregate functions can accept only a single argument or property.
• Aggregate functions cannot take other functions as arguments.
• GROUP BY with an ORDER BY clause referencing aggregate functions may contain only a single property.
• For all other aggregations GROUP BY clauses may contain up to three properties.
• Pagination is supported for all aggregate queries except when ORDER BY clause has an aggregate function. For example, GROUP BY X, ORDER BY Y does not work if Y is an aggregate function.
• No support for HAVING clauses in aggregations.
Region Support
Advanced queries is supported in the following Regions:
Region
name Region Endpoint Protocol
Africa (Cape
Town)* af-south-1 config.af-south-1.amazonaws.com HTTPS
Asia Pacific
(Hong Kong) ap-east-1 config.ap-east-1.amazonaws.com HTTPS
Asia Pacific
(Mumbai) ap-south-1 config.ap-south-1.amazonaws.com HTTPS
Asia Pacific
(Seoul)
ap-northeast-2 config.ap-northeast-2.amazonaws.com HTTPS
Asia Pacific (Singapore)
ap-southeast-1 config.ap-southeast-1.amazonaws.com HTTPS
Asia Pacific (Sydney)
ap-southeast-2 config.ap-southeast-2.amazonaws.com HTTPS
Region Support
(Beijing)* cn-north-1 config.cn-north-1.amazonaws.com.cn HTTPS China
(Milan)* eu-south-1 config.eu-south-1.amazonaws.com HTTPS
Europe
Query Using the SQL Query Editor (Console)
*Saved queries is not available in Africa (Cape Town) and Europe (Milan) Regions.
*Advanced queries for multi-account multi-regions is not available in Africa (Cape Town), Europe (Milan), China (Beijing), and China (Ningxia) Regions.
Query Using the SQL Query Editor (Console)
You can either use AWS sample queries or you can create your own query called as custom queries.
Prerequisites
You must have permissions for config:SelectResourceConfig and
config:SelectAggregateResourceConfig APIs. For more information, see SelectResourceConfig API and SelectAggregateResourceConfig API.
You must have permissions for the AWSConfigUserAccess IAM managed policy. For more information, see Granting Permissions for AWS Config Administration (p. 6057).
If you are using AWSServiceRoleForConfig (service linked role) or AWSConfigRole, you will have permissions to save a query. If you are not using either of these roles, you must have permissions to config:PutStoredQuery, config:GetStoredQuery, config:TagResource, config:UntagResource, config:ListTagsForResource and config:GetResources.
Use an AWS Sample Query
1. Sign in to the AWS Management Console and open the AWS Config console at https://
console.aws.amazon.com/config/.
2. Choose Advanced queries from the left navigation to query your resource configurations for a single account and Region or for multiple accounts and Regions.
3. On the Advanced queries page, choose an appropriate query from the list of queries. You can filter a query either by the name, description, creator or tags. To filter AWS queries, choose Creater and enter AWS. The query is displayed in the SQL query editor. If required, you can edit this query.
Important
An updated list of properties and their data types is available in GitHub.
NoteTo run a query on an aggregator, create an aggregator. For more information, see Setting Up an Aggregator Using the Console (p. 6042). If you already have an aggregator set up, in the query scope, choose the aggregator to run an advanced query on that aggregator.
When you select an aggregator, consider adding the AWS account ID and AWS Region in the query statement to view that information in the results.
4. To save this query to a new query, choose Save As.
• In the Query Name field, update the name of the query.
• In the Description field, update the description of the query.
• Enter up to 50 unique tags for this query.
• Choose Save.
5. Choose Run. The query results are displayed in the table below the query editor.
6. Choose Export as to export the query results in CSV or JSON format.
NoteThe query results are paginated. When you choose export, upto 500 results are exported.
You can also use the APIs to retrieve all the results. The results are paginated and you can retrieve 100 results at a time.
Query Using the SQL Query Editor (AWS CLI)
Create your custom query
1. Sign in to the AWS Management Console and open the AWS Config console at https://
console.aws.amazon.com/config/.
2. Choose Advanced queries from the left navigation to query your resource configurations for a single account and Region or for multiple accounts and Regions.
3. To create your custom query, choose New query.
Important
An updated list of properties and their data types is available in GitHub.
NoteTo view or edit a custom query, filter a query either by the name, description, creator or tags. To filter custom queries, choose Creater and enter Custom.
4. On the Query editor page, create your own query for this account and Region. You can also select an appropriate aggregator to create a query for multiple accounts and Regions.
NoteTo run a query on an aggregator, create an aggregator. For more information, see Setting Up an Aggregator Using the Console (p. 6042). If you already have an aggregator set up, in the query scope, choose the aggregator to run an advanced query on that aggregator.
When you select an aggregator, consider adding the AWS account ID and AWS Region in the query statement to view that information in the results.
5. Edit if you wish you make changes to this query. Choose Save Query to save this query.
• In the Query Name field, update the name of the query.
• In the Description field, update the description of the query.
• Enter up to 50 unique tags for this query.
• Choose Save.
6. Choose Run. The query results are displayed in the table below the query editor.
7. Choose Export as to export the query results in CSV or JSON format.
NoteThe query results are paginated. When you choose export, upto 500 results are exported.
You can also use the APIs to retrieve all the results. The results are paginated and you can retrieve 100 results at a time.
Query Using the SQL Query Editor (AWS CLI)
To install the AWS Command Line Interface (AWS CLI) on your local computer, see Installing the AWSAWS CLI in the AWS CLI User Guide.
Query Resource Configuration Data
To query your resource configuration data using the query editor (AWS CLI) for a single account and Region
1. Open a command prompt or a terminal window.
2. Type the following command to query your resource configuration data.
aws configservice select-resource-config --expression "SELECT resourceId WHERE resourceType='AWS::EC2::Instance'"
Depending on your query, the output looks like the following.
Query Using the SQL Query Editor (AWS CLI)
"{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}"
] }
To query your resource configuration data using the query editor (AWS CLI) for multiple accounts and Regions
1. Open a command prompt or a terminal window.
2. Type the following command to query your resource configuration data.
aws configservice select-aggregate-resource-config --expression "SELECT resourceId WHERE resourceType='AWS::EC2::Instance'" --configuration-aggregator-name my-aggregator
Depending on your query, the output looks like the following.
{
"{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}", "{\"resourceId\":\"ResourceId\"}"
] }
Note
While using the AWS::IAM::User resource type in an advanced query, use awsRegion = 'global'.
Save a Query
1. Open a command prompt or a terminal window.
Query Using the SQL Query Editor (AWS CLI)
2. Type the following command to save a query.
aws configservice put-stored-query --stored-query "{\"QueryName\": \"cli-test\", \"Expression\": \"SELECT *\", \"Description\": \"cli test query\" }"
--tags "[{ \"Key\": \"first-tag\", \"Value\": \"\" }, { \"Key\": \"second-tag
\", \"Value\": \"non-empty-tag-value\" }]"
3. Depending on your query, the output looks like the following.
{ "QueryArn": "arn:aws:config:eu-central-1:Account ID:stored-query/cli-test/query-e65mijt4rmam5pab"
}
Note
--tags is optional. When you pass the tags, the saved tags will not be returned by either list-stored-queries or get-stored-query. You must use list-tag-for-resources to retrieve the associated tags for a saved query.
--tags is optional. When you pass the tags, the saved tags will not be returned by either list-stored-queries or get-stored-query. You must use list-tag-for-resources to retrieve the associated tags for a saved query.