Add org sink README

event-rules/org-sink-rules/README.md

@@ -0,0 +1,21 @@
+This is a CloudFormation template which defines a number of [Amazon EventBridge rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) that implement an _organization sink_ convention. This convention allows for a standard way of responding to AWS activity generated by many different services, across our entire AWS organization.
+
+The template is intended to be deployed as a CloudFormation stack to every region in every account within an AWS Organization.
+
+We use [CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html) to manage the deployment of all these stacks.
+
+Using [automatic deployments](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-manage-auto-deployment.html), StackSets can automatically deploy stacks to many regions in all accounts that belong to an AWS Organization, **excluding** the management account of the organization[^1]. For this reason, we use two separate StackSets to deploy this template:
+- One StackSet is used to deploy stacks to all regions of the management account
+- Another StackSet is used to deploy stacks to all regions of all other accounts within the organization
+
+In order to keep the number of stacks and StackSets manageable, all rules used for various organization sinks are maintained in a single template.
+
+By convention, the rules forward relevant events to a custom event bus, not the default bus. The consumer(s) of any given organization sink bus will only need to subscribe to that custom bus. This avoids needing to handle the account+region where the consumer exist specially. For example, imagine a Lambda function that listens for CloudWatch Alarm events generated across the organization. If the rules being created by this template forwarded all alarm events to the default bus in the account+region where that Lambda function exists, there would need to be a special case where the StackSet did **not** deploy the rules to that account and region, because doing so would mean that CloudWatch Alarms events would end up on the default bus both because that's where they are natively delivered, and because there would be a rule that forwards all those events to the same bus. By using a custom bus, rules can be deployed to all accounts and regions identically.
+
+### Deployment
+
+Updates to the template can be deployed via StackSets using [UpdateStackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStackSet.html) or [update-stack-set](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudformation/update-stack-set.html). When updating stacks via a StackSet operation, it's generally easiest to use the operation to only update the stack template. If you don't include any details about the deployment (regions, accounts, organization units, etc) in the operation, the current details will be maintained. There are operation preferences you may want to set, though, such as `--operation-preferences FailureTolerancePercentage=100,MaxConcurrentPercentage=100,ConcurrencyMode=SOFT_FAILURE_TOLERANCE,RegionConcurrencyType=PARALLEL`.
+
+When first deploying the StackSet, though, you will need to include the deployment details to initially set them on the StackSet. Doing this using the API, CLI or SDK seems very very hard or impossible. **You should do the initial StackSet creation in Console.** Make sure to get the StackSet name and the deployment details (regions, accounts, organizational units, etc) correct.
+
+[^1]: Under _Considerations_: [StackSets doesn't deploy stack instances to the organization's management account, even if the management account is in your organization or in an OU in your organization.](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html#stacksets-orgs-associate-stackset-with-org)