add schema examples. fix linter issues

Signed-off-by: Mike Tonks <[email protected]>

text/2023-06-14-cloud-chaos-improvements.md

@@ -3,7 +3,12 @@
 ## Summary
 
 The current ASWChaos, GCPChaos and AzureChaos experiment types are quite basic.
-We would like to improve them and add more types for different cloud resources
+
+We would like to extend them to support selecting instances using additional
+filters such as tags or labels, instance type, availability zone, etc, as
+supported by the different cloud providers.
+
+In future we would like to add more types for different cloud resources
 such as networking.
 
 ## Motivation
@@ -33,11 +38,57 @@ conventions used in the SDK.
 
 Currently, none of these types use `Selectors` currently.  We should use the
 `RecordsController` with the `impl.Select` to lookup matching resources in the
-cloud and save these in the `records` as described [here](https://github.com/chaos-mesh/chaos-mesh/tree/master/controllers/common/records#readme)
+cloud and save these in the `records` as described
+[here](https://github.com/chaos-mesh/chaos-mesh/tree/master/controllers/common/records#readme)
 
 
 ## Detailed design
 
+Add new fields to the existing AWS Chaos, GCP Chaos and Azure Chaos
+definitions, to allow specifying filters.
+
+### AWS Chaos selecting multiple instances using tag
+
+```
+apiVersion: chaos-mesh.org/v1alpha1
+kind: AWSChaos
+metadata:
+  name: ec2-stop-example
+  namespace: chaos-mesh
+spec:
+  action: ec2-stop
+  awsRegion: 'us-east-2'
+  filters:
+  - name: 'tag:environment'
+    value: 'staging'
+  - name: 'instance-type'
+    value: 't2.micro'
+  mode: 'all'
+  duration: '5m'
+```
+
+Supported filters are defined in the AWS SDK. For details see:
+https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html
+
+### GCP Chaos selecting multiple instances using labels
+
+```
+apiVersion: chaos-mesh.org/v1alpha1
+kind: GCPChaos
+metadata:
+  name: node-stop-example
+  namespace: chaos-mesh
+spec:
+  action: node-stop
+  secretName: 'cloud-key-secret'
+  project: 'your-project-id'
+  zone: 'your-zone'
+  filters:
+  - 'labels.environment = staging'
+  - 'name ne .*web'
+  mode: 'all'
+  duration: '5m'
+```
 
 ## Drawbacks
 
@@ -53,13 +104,16 @@ cloud and save these in the `records` as described [here](https://github.com/cha
    However this doesn't seem feasible at this time.  We would need some kind
    of plugin / exnension model to support this.
 
-- Extend the existing AWSChaos, GCPChaos and AzureChaos types
 
-   It might be simpler to add code to the existing types.  However, there are
-   a potentially large number of different cloud resource types, so this would
-   not scale well.
+## Unresolved questions
+
+- Should new chaos types be introduced for additional cloud resource types?
 
-   In addition we might require breaking changes to the structures, so it would
-   be easier to introduce new types and eventually deprecate the old ones.
+   It might be necessary to introduce new chaos types e.g. AWSNetworkChaos,
+   GCPNetworkChaos and so on.
 
-## Unresolved questions
+   It might be necessary to make breaking changes to the structures, so it 
+   in this case it would be easier to introduce new types and eventually
+   deprecate the old ones.
+
+   We need to explore the solution in more detail before we can decide.