docs(config): refresh the README with more context, content, and samp…

…les (#10836)

updated readme to walk through primary concepts wrt rules, managed rules, custom rules,
triggers, scope, and events.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/@aws-cdk/aws-config/README.md

@@ -15,6 +15,10 @@
 ---
 <!--END STABILITY BANNER-->
 
+[AWS Config](https://docs.aws.amazon.com/config/latest/developerguide/WhatIsConfig.html) provides a detailed view of the configuration of AWS resources in your AWS account.
+This includes how the resources are related to one another and how they were configured in the
+past so that you can see how the configurations and relationships change over time. 
+
 This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
 
 ### Initial Setup
@@ -26,39 +30,126 @@ following resources per region:
 - `ConfigurationRecorder`: Configure which resources will be recorded for config changes.
 - `DeliveryChannel`: Configure where to store the recorded data.
 
-Following are the guides to setup AWS Config:
+The following guides provide the steps for getting started with AWS Config:
 
 - [Using the AWS Console](https://docs.aws.amazon.com/config/latest/developerguide/gs-console.html)
 - [Using the AWS CLI](https://docs.aws.amazon.com/config/latest/developerguide/gs-cli.html)
 
 ### Rules
 
-#### AWS managed rules
+AWS Config can evaluate the configuration settings of your AWS resources by creating AWS Config rules,
+which represent your ideal configuration settings.
+
+See [Evaluating Resources with AWS Config Rules](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) to learn more about AWS Config rules.
+
+#### AWS Managed Rules
+
+AWS Config provides AWS managed rules, which are predefined, customizable rules that AWS Config
+uses to evaluate whether your AWS resources comply with common best practices.
 
-To set up a managed rule, define a `ManagedRule` and specify its identifier:
+For example, you could create a managed rule that checks whether active access keys are rotated
+within the number of days specified.
 
 ```ts
-new ManagedRule(this, 'AccessKeysRotated', {
+import * as config from '@aws-cdk/aws-config';
+import * as cdk from '@aws-cdk/core';
+
+// https://docs.aws.amazon.com/config/latest/developerguide/access-keys-rotated.html
+new config.ManagedRule(this, 'AccessKeysRotated', {
   identifier: config.ManagedRuleIdentifiers.ACCESS_KEYS_ROTATED,
+  inputParameters: {
+     maxAccessKeyAge: 60 // default is 90 days
+  },
+  maximumExecutionFrequency: config.MaximumExecutionFrequency.TWELVE_HOURS // default is 24 hours
+});
+```
+
+Identifiers for AWS managed rules are available through static constants in the `ManagedRuleIdentifiers` class.
+You can find supported input parameters in the [List of AWS Config Managed Rules](https://docs.aws.amazon.com/config/latest/developerguide/managed-rules-by-aws-config.html).
+
+The following higher level constructs for AWS managed rules are available.
+
+##### Access Key rotation
+
+Checks whether your active access keys are rotated within the number of days specified.
+
+```ts
+import * as config from '@aws-cdk/aws-config';
+import * as cdk from '@aws-cdk/aws-cdk';
+
+// compliant if access keys have been rotated within the last 90 days
+new config.AccessKeysRotated(this, 'AccessKeyRotated');
+```
+
+##### CloudFormation Stack drift detection
+
+Checks whether your CloudFormation stack's actual configuration differs, or has drifted,
+from it's expected configuration. 
+
+```ts
+import * as config from '@aws-cdk/aws-config';
+import * as cdk from '@aws-cdk/aws-cdk';
+
+// compliant if stack's status is 'IN_SYNC'
+// non-compliant if the stack's drift status is 'DRIFTED'
+new config.CloudFormationStackDriftDetectionCheck(stack, 'Drift', {
+  ownStackOnly: true, // checks only the stack containing the rule
 });
 ```
 
-Higher level constructs for managed rules are available, see [Managed Rules](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-config/lib/managed-rules.ts).
-Prefer to use those constructs when available (PRs welcome to add more of those).
+##### CloudFormation Stack notifications
+
+Checks whether your CloudFormation stacks are sending event notifications to a SNS topic.
+
+```ts
+import * as config from '@aws-cdk/aws-config';
+import * as cdk from '@aws-cdk/aws-cdk';
+
+// topics to which CloudFormation stacks may send event notifications
+const topic1 = new sns.Topic(stack, 'AllowedTopic1');
+const topic2 = new sns.Topic(stack, 'AllowedTopic2');
+
+// non-compliant if CloudFormation stack does not send notifications to 'topic1' or 'topic2'
+new config.CloudFormationStackNotificationCheck(this, 'NotificationCheck', {
+  topics: [topic1, topic2],
+})
+```
 
 #### Custom rules
 
-To set up a custom rule, define a `CustomRule` and specify the Lambda Function to run and the trigger types:
+You can develop custom rules and add them to AWS Config. You associate each custom rule with an
+AWS Lambda function, which contains the logic that evaluates whether your AWS resources comply
+with the rule.
+
+#### Triggers
+
+AWS Lambda executes functions in response to events that are published by AWS Services.
+The function for a custom Config rule receives an event that is published by AWS Config,
+and is responsible for evaluating the compliance of the rule.
+
+Evaluations can be triggered by configuration changes, periodically, or both.
+To create a custom rule, define a `CustomRule` and specify the Lambda Function
+to run and the trigger types.
 
 ```ts
-new CustomRule(this, 'CustomRule', {
-  lambdaFunction: myFn,
+import * as config from '@aws-cdk/aws-config';
+
+new config.CustomRule(this, 'CustomRule', {
+  lambdaFunction: evalComplianceFn,
   configurationChanges: true,
-  periodic: true
+  periodic: true,
+  maximumExecutionFrequency: config.MaximumExecutionFrequency.SIX_HOURS, // default is 24 hours
 });
 ```
 
-#### Restricting the scope
+When the trigger for a rule occurs, the Lambda function is invoked by publishing an event.
+See [example events for AWS Config Rules](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config_develop-rules_example-events.html)  
+
+The AWS documentation has examples of Lambda functions for evaluations that are
+[triggered by configuration changes](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config_develop-rules_nodejs-sample.html#event-based-example-rule) and [triggered periodically](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config_develop-rules_nodejs-sample.html#periodic-example-rule)
+
+
+#### Scope
 
 By default rules are triggered by changes to all [resources](https://docs.aws.amazon.com/config/latest/developerguide/resource-config-reference.html#supported-resources).
 
@@ -73,50 +164,79 @@ const sshRule = new config.ManagedRule(this, 'SSH', {
   ruleScope: config.RuleScope.fromResource(config.ResourceType.EC2_SECURITY_GROUP, 'sg-1234567890abcdefgh'), // restrict to specific security group
 });
 
-const customRule = new config.CustomRule(this, 'CustomRule', {
-  lambdaFunction: myFn,
+const customRule = new config.CustomRule(this, 'Lambda', {
+  lambdaFunction: evalComplianceFn,
   configurationChanges: true
-  ruleScope: config.RuleScope.fromResources([config.ResourceType.CLOUDFORMATION_STACK, config.Resource.S3_BUCKET]), // restrict to all CloudFormation stacks and S3 buckets
+  ruleScope: config.RuleScope.fromResources([config.ResourceType.CLOUDFORMATION_STACK, config.ResourceType.S3_BUCKET]), // restrict to all CloudFormation stacks and S3 buckets
 });
 
-const customRule = new config.CustomRule(this, 'CustomRule', {
-  lambdaFunction: myFn,
+const tagRule = new config.CustomRule(this, 'CostCenterTagRule', {
+  lambdaFunction: evalComplianceFn,
   configurationChanges: true
   ruleScope: config.RuleScope.fromTag('Cost Center', 'MyApp'), // restrict to a specific tag
 });
 ```
 
 #### Events
 
-To define Amazon CloudWatch event rules, use the `onComplianceChange()` or `onReEvaluationStatus()` methods:
+You can define Amazon EventBridge event rules which trigger when a compliance check fails
+or when a rule is re-evaluated.
+
+Use the `onComplianceChange()` APIs to trigger an EventBridge event when a compliance check
+of your AWS Config Rule fails:
 
 ```ts
-const rule = new CloudFormationStackDriftDetectionCheck(this, 'Drift');
+import * as config from '@aws-cdk/aws-config';
+import * as sns from '@aws-cdk/aws-sns';
+import * as targets from '@aws-cdk/aws-events-targets';
+
+// Topic to which compliance notification events will be published
+const complianceTopic = new sns.Topic(this, 'ComplianceTopic');
+
+const rule = new config.CloudFormationStackDriftDetectionCheck(this, 'Drift');
 rule.onComplianceChange('TopicEvent', {
-  target: new targets.SnsTopic(topic))
+  target: new targets.SnsTopic(complianceTopic),
 });
 ```
 
+Use the `onReEvaluationStatus()` status to trigger an EventBridge event when an AWS Config
+rule is re-evaluated.
+
+```ts
+import * as config from '@aws-cdk/aws-config';
+import * as sns from '@aws-cdk/aws-sns';
+import * as targets from '@aws-cdk/aws-events-targets';
+
+// Topic to which re-evaluation notification events will be published
+const reEvaluationTopic = new sns.Topic(this, 'ComplianceTopic');
+rule.onReEvaluationStatus('ReEvaluationEvent', {
+  target: new targets.SnsTopic(reEvaluationTopic),
+})
+```
+
 #### Example
 
-The following example creates a custom rule that runs on configuration changes to EC2 instances and publishes
-compliance events to an SNS topic.
+The following example creates a custom rule that evaluates whether EC2 instances are compliant.
+Compliance events are published to an SNS topic.
 
 ```ts
 import * as config from '@aws-cdk/aws-config';
 import * as lambda from '@aws-cdk/aws-lambda';
+import * as sns from '@aws-cdk/aws-sns';
+import * as targets from '@aws-cdk/aws-events-targets';
 
-// A custom rule that runs on configuration changes of EC2 instances
-const fn = new lambda.Function(this, 'CustomFunction', {
+// Lambda function containing logic that evaluates compliance with the rule.
+const evalComplianceFn = new lambda.Function(this, 'CustomFunction', {
   code: lambda.AssetCode.fromInline('exports.handler = (event) => console.log(event);'),
   handler: 'index.handler',
   runtime: lambda.Runtime.NODEJS_10_X,
 });
 
+// A custom rule that runs on configuration changes of EC2 instances
 const customRule = new config.CustomRule(this, 'Custom', {
   configurationChanges: true,
-  lambdaFunction: fn,
-  ruleScope: config.RuleScope.fromResource([config.Scope.EC2_INSTANCE]),
+  lambdaFunction: evalComplianceFn,
+  ruleScope: config.RuleScope.fromResource([config.ResourceType.EC2_INSTANCE]),
 });
 
 // A rule to detect stack drifts
@@ -125,7 +245,7 @@ const driftRule = new config.CloudFormationStackDriftDetectionCheck(this, 'Drift
 // Topic to which compliance notification events will be published
 const complianceTopic = new sns.Topic(this, 'ComplianceTopic');
 
-// Send notification on compliance change
+// Send notification on compliance change events
 driftRule.onComplianceChange('ComplianceChange', {
   target: new targets.SnsTopic(complianceTopic),
 });