Starting AWS Config with the AWS CLI
Note
Before setting up AWS Config with the AWS CLI, you need to create an S3 bucket, an SNS topic, and an IAM role with attached policies as prerequisites. You can then use the AWS CLI to specify the bucket, topic, and role for AWS Config. To set up your prerequisites for AWS Config, see Prerequisites.
To start AWS Config with the AWS CLI, use the put-configuration-recorder, put-delivery-channel, and start-configuration-recorder commands, as follows:
The
put-configuration-recorder
command creates a new configuration recorder to record your specified resource configurations.The
put-delivery-channel
command creates a delivery channel object to deliver configuration information to an S3 bucket and SNS topic.After a delivery channel is created, the
start-configuration-recorder
starts recording your selected resource configurations, which you can see in your AWS account.
Note
You can have only one configuration recorder and only one delivery channel for each AWS Region in your account.
You can specify the name of the recorder and the Amazon Resource Name (ARN) of the IAM role assumed by AWS Config and used by the configuration recorder. AWS Config automatically assigns the name of "default" when creating the configuration recorder. You cannot change the name of the configuration recorder after it has been created. To change the configuration recorder name, you must delete it and create a new configuration recorder with a new name.
To set up AWS Config for Multi-Account Multi-Region Data Aggregation with the AWS CLI, see Setting Up an Aggregator Using the AWS Command Line Interface. You must create a separate configuration recorder for each Region in each AWS account that you would want to record configuration items.
put-configuration-recorder
Your put-configuration-recorder
command should look like the following
example.
$ aws configservice put-configuration-recorder \ --configuration-recorder
file://configurationRecorder.json
\ --recording-groupfile://recordingGroup.json
This command uses the --configuration-recorder
and ---recording-group
fields.
Note
Recording group and configuration recorder
The --recording-group
field specifies which resource types are recorded.
The --configuration-recorder
field specifies name
and roleArn
as well as the default recording frequency for the configuration recorder (recordingMode
).
You can also use this field override the recording frequency for specific resource types.
put-configuration-recorder
uses the following options for the --recording-group
parameter:
-
allSupported=true
– AWS Config records configuration changes for all supported resource types, excluding the global IAM resource types. When AWS Config adds support for a new resource type, AWS Config automatically starts recording resources of that type. -
includeGlobalResourceTypes=true
– This option is a bundle which only applies to the global IAM resource types: IAM users, groups, roles, and customer managed policies. These global IAM resource types can only be recorded by AWS Config in Regions where AWS Config was available before February 2022. You cannot be record the global IAM resouce types in Regions supported by AWS Config after February 2022. This list where you cannot record the global IAM resource types includes the following Regions:Asia Pacific (Hyderabad)
Asia Pacific (Melbourne)
Canada West (Calgary)
Europe (Spain)
Europe (Zurich)
Israel (Tel Aviv)
Middle East (UAE)
Important
Aurora global clusters are recorded in all enabled Regions
The
AWS::RDS::GlobalCluster
resource type will be recorded in all supported AWS Config Regions where the configuration recorder is enabled, even ifincludeGlobalResourceTypes
is set tofalse
. TheincludeGlobalResourceTypes
option is a bundle which only applies to IAM users, groups, roles, and customer managed policies.If you do not want to record
AWS::RDS::GlobalCluster
in all enabled Regions, use one of the following recording strategies:Record all current and future resource types with exclusions (
EXCLUSION_BY_RESOURCE_TYPES
), orRecord specific resource types (
INCLUSION_BY_RESOURCE_TYPES
).
For more information, see Selecting Which Resources are Recorded.
Important
includeGlobalResourceTypes and the exclusion recording strategy
The
includeGlobalResourceTypes
field has no impact on theEXCLUSION_BY_RESOURCE_TYPES
recording strategy. This means that the global IAM resource types (IAM users, groups, roles, and customer managed policies) will not be automatically added as exclusions forexclusionByResourceTypes
whenincludeGlobalResourceTypes
is set tofalse
.The
includeGlobalResourceTypes
field should only be used to modify theAllSupported
field, as the default for theAllSupported
field is to record configuration changes for all supported resource types excluding the global IAM resource types. To include the global IAM resource types whenAllSupported
is set totrue
, make sure to setincludeGlobalResourceTypes
totrue
.To exclude the global IAM resource types for the
EXCLUSION_BY_RESOURCE_TYPES
recording strategy, you need to manually add them to theresourceTypes
field ofexclusionByResourceTypes
.Note
Required and optional fields
Before you can set
includeGlobalResourceTypes
totrue
, set theallSupported
field totrue
.Optionally, you can set the
useOnly
field ofRecordingStrategy
toALL_SUPPORTED_RESOURCE_TYPES
.Note
Overriding fields
If you set
includeGlobalResourceTypes
tofalse
but list global IAM resource types in theresourceTypes
field of RecordingGroup, AWS Config will still record configuration changes for those specified resource types regardless of if you set theincludeGlobalResourceTypes
field to false.If you do not want to record configuration changes to the global IAM resource types (IAM users, groups, roles, and customer managed policies), make sure to not list them in the
resourceTypes
field in addition to setting theincludeGlobalResourceTypes
field to false. -
recordingStrategy
– Specifies the recording strategy for the configuration recorder. TherecordingGroup.json
file specifies which types of resources AWS Config will record:-
If you set the
useOnly
field of RecordingStrategy toALL_SUPPORTED_RESOURCE_TYPES
, AWS Config records configuration changes for all supported resource types, excluding the global IAM resource types. Optionally, you can set theallSupported
field of RecordingGroup totrue
. When AWS Config adds support for a new resource type, AWS Config automatically starts recording resources of that type. -
If you set the
useOnly
field of RecordingStrategy toINCLUSION_BY_RESOURCE_TYPES
, AWS Config records configuration changes for only the resource types you specify in theresourceTypes
field of RecordingGroup. If you set the
useOnly
field of RecordingStrategy toEXCLUSION_BY_RESOURCE_TYPES
, AWS Config records configuration changes for all supported resource types except the resource types that you specify as to exclude from being recorded in theresourceTypes
field of ExclusionByResourceTypes.
Note
Required and optional fields
The
recordingStrategy
field is optional when you set theallSupported
field of--recording-group
totrue
.The
recordingStrategy
field is optional when you list resource types in theresourceTypes
field of--recording-group
.The
recordingStrategy
field is required if you list resource types to exclude from recording in theresourceTypes
field ofexclusionByResourceTypes
.Note
Overriding fields
If you choose
EXCLUSION_BY_RESOURCE_TYPES
for the recording strategy, theexclusionByResourceTypes
field will override other properties in the request.For example, even if you set
includeGlobalResourceTypes
to false, the global IAM resource types will still be automatically recorded in this option unless those resource types are specifically listed as exemptions in theresourceTypes
field ofexclusionByResourceTypes
.Note
Global resource types and the resource exclusion recording strategy
By default, if you choose the
EXCLUSION_BY_RESOURCE_TYPES
recording strategy, when AWS Config adds support for a new resource type in the Region where you set up the configuration recorder, including global resource types, AWS Config starts recording resources of that type automatically.Unless specifically listed as exclusions,
AWS::RDS::GlobalCluster
will be recorded automatically in all supported AWS Config Regions were the configuration recorder is enabled.IAM users, groups, roles, and customer managed policies will be recorded in the Region where you set up the configuration recorder if that is a Region where AWS Config was available before February 2022. You cannot be record the global IAM resouce types in Regions supported by AWS Config after February 2022. This list where you cannot record the global IAM resource types includes the following Regions:
Asia Pacific (Hyderabad)
Asia Pacific (Melbourne)
Canada West (Calgary)
Europe (Spain)
Europe (Zurich)
Israel (Tel Aviv)
Middle East (UAE)
The following shows the Request syntax for the
recordingGroup.json
.{ "allSupported":
boolean
, "exclusionByResourceTypes": { "resourceTypes": [Comma-separated list of resource types to exclude
] }, "includeGlobalResourceTypes":boolean
, "recordingStrategy": { "useOnly": "Recording strategy for the configuration recorder
" }, "resourceTypes": [Comma-separated list of resource types to include
] }Note
Pre-existing AWS Config role
If you have used an AWS service that uses AWS Config, such as AWS Security Hub or AWS Control Tower, and an AWS Config role has already been created, make sure that the IAM role that you use when setting up AWS Config keeps the same minimum permissions as the already created AWS Config role. You must do this so that the other AWS service continues to run as expected.
For example, if AWS Control Tower has an IAM role that allows AWS Config to read Amazon Simple Storage Service (Amazon S3) objects, make sure that the same permissions are granted within the IAM role you use when setting up AWS Config. Otherwise, it may interfere with how AWS Control Tower operates. For more information about IAM roles for AWS Config, see Identity and Access Management for AWS Config.
Note
High Number of AWS Config Evaluations
You may notice increased activity in your account during your initial month recording with AWS Config when compared to subsequent months. During the initial bootstrapping process, AWS Config runs evaluations on all the resources in your account that you have selected for AWS Config to record.
If you are running ephemeral workloads, you may see increased activity from AWS Config as it records configuration changes associated with creating and deleting these temporary resources. An ephemeral workload is a temporary use of computing resources that are loaded and run when needed. Examples include Amazon Elastic Compute Cloud (Amazon EC2) Spot Instances, Amazon EMR jobs, and AWS Auto Scaling. If you want to avoid the increased activity from running ephemeral workloads, you can run these types of workloads in a separate account with AWS Config turned off to avoid increased configuration recording and rule evaluations.
Note
Region Availability
Before specifying a resource type for AWS Config to track, check Resource Coverage by Region Availability to see if the resource type is supported in the AWS Region where you are setting up AWS Config. If a resource type is supported by AWS Config in at least one Region, you can enable the recording of that resource type in all Regions supported by AWS Config, even if the specified resource type is not supported in the AWS Region where you are setting up AWS Config.
-
put-configuration-recorder
uses the following fields for the --configuration-recorder
parameter:
name
– The name of the configuration recorder. AWS Config automatically assigns the name of "default" when creating the configuration recorder.roleARN
– Amazon Resource Name (ARN) of the IAM role assumed by AWS Config and used by the configuration recorder.recordingMode
– Specifies the default recording frequency that AWS Config uses to record configuration changes. AWS Config supports Continuous recording and Daily recording. Continuous recording allows you to record configuration changes continuously whenever a change occurs. Daily recording allows you to receive a configuration item (CI) representing the most recent state of your resources over the last 24-hour period, only if it’s different from the previous CI recorded.-
recordingFrequency
– The default recording frequency that AWS Config uses to record configuration changes.Note
AWS Firewall Manager depends on continuous recording to monitor your resources. If you are using Firewall Manager, it is recommended that you set the recording frequency to Continuous.
-
recordingModeOverrides
– This field allows you to specify your overrides for the recording mode. It is an array ofrecordingModeOverride
objects. EachrecordingModeOverride
object in therecordingModeOverrides
array consists of three fields:description
– A description that you provide for the override.recordingFrequency
– The recording frequency that will be applied to all the resource types specified in the override.resourceTypes
– A comma-separated list that specifies which resource types AWS Config includes in the override.
-
Note
Required and optional fields
The recordingMode
field for put-configuration-recorder
is optional. By default, the recording frequency for the configuration recorder is set to Continuous recording.
Note
Limits
Daily recording is not supported for the following resource types:
AWS::Config::ResourceCompliance
AWS::Config::ConformancePackCompliance
AWS::Config::ConfigurationRecorder
For the Record all current and future supported resource types (ALL_SUPPORTED_RESOURCE_TYPES
) recording strategy, these resource types will be set to Continuous recording.
The configurationRecorder.json
file specifies name
and roleArn
as well as the default recording frequency for the configuration recorder (recordingMode
).
You can also use this field override the recording frequency for specific resource types.
{ "name": "default", "roleARN": "
arn:aws:iam::123456789012:role/config-role
", "recordingMode": { "recordingFrequency":CONTINUOUS
orDAILY
, "recordingModeOverrides": [ { "description": "Description you provide for the override
", "recordingFrequency":CONTINUOUS
orDAILY
, "resourceTypes": [Comma-separated list of resource types to include in the override
] } ] } }
put-delivery-channel
To set up the delivery channel, use the put-delivery-channel
command.
$ aws configservice put-delivery-channel --delivery-channel file://deliveryChannel.json
The deliveryChannel.json file specifies the delivery channel attributes.
{ "name": "default", "s3BucketName": "config-bucket-123456789012", "snsTopicARN": "arn:aws:sns:us-east-2:123456789012:config-topic", "configSnapshotDeliveryProperties": { "deliveryFrequency": "Twelve_Hours" } }
This example sets the following attributes:
-
name
– The name of the delivery channel. By default, AWS Config assigns the name ofdefault
to a new delivery channel.You cannot update the delivery channel name with the
put-delivery-channel
command. For the steps to change the name, see Renaming the Delivery Channel. -
s3BucketName
– The name of the S3 bucket where AWS Config delivers configuration snapshots and configuration history files.If you specify a bucket that belongs to another AWS account, that bucket must have policies that grant access permissions to AWS Config. For more information, see Permissions for the Amazon S3 Bucket for the AWS Config Delivery Channel.
-
snsTopicARN
– The Amazon Resource Name (ARN) of the Amazon SNS topic where AWS Config sends notifications about configuration changes.If you choose a topic from another account, that topic must have policies that grant access permissions to AWS Config. For more information, see Permissions for the Amazon SNS Topic.
-
configSnapshotDeliveryProperties
– Contains thedeliveryFrequency
attribute, which sets how often AWS Config delivers configuration snapshots.
start-configuration-recorder
To finish turning on AWS Config, use the start-configuration-recorder
command.
$ aws configservice start-configuration-recorder --configuration-recorder-name
configRecorderName