Document changes of Filters to Params

Author: mdbooth

docs/book/src/topics/crd-changes/v1alpha7-to-v1beta1.md

@@ -14,7 +14,7 @@
       - [Change to image](#change-to-image)
       - [Removal of imageUUID](#removal-of-imageuuid)
       - [Changes to ports](#changes-to-ports)
-      - [Additon of floatingIPPoolRef](#additon-of-floatingippoolref)
+      - [Addition of floatingIPPoolRef](#addition-of-floatingippoolref)
     - [`OpenStackCluster`](#openstackcluster)
       - [Removal of cloudName](#removal-of-cloudname-1)
       - [identityRef is now required](#identityref-is-now-required)
@@ -30,6 +30,7 @@
       - [Changes to apiServerLoadBalancer](#changes-to-apiserverloadbalancer)
       - [Changes to bastion](#changes-to-bastion)
     - [Changes to filters](#changes-to-filters)
+      - [Filters are replaced by params with separate id and filter](#filters-are-replaced-by-params-with-separate-id-and-filter)
       - [Changes to filter tags](#changes-to-filter-tags)
       - [Field capitalization consistency](#field-capitalization-consistency)
 
@@ -171,8 +172,8 @@ Note that this is in contrast `identityRef` in `OpenStackMachine`, which remains
 
 #### Change to externalNetworkID
 
-The field `externalNetworkID` has been renamed to `externalNetwork` and is now a `NetworkFilter` object rather than a string ID.
-The `NetworkFilter` object allows selection of a network by name, by ID or by tags.
+The field `externalNetworkID` has been renamed to `externalNetwork` and is now a `NetworkParam` object rather than a string ID.
+The `NetworkParam` object allows selection of a network by id or filter parameters.
 
 ```yaml
 externalNetworkID: "e60f19e7-cb37-49f9-a2ee-0a1281f6e03e"
@@ -189,7 +190,8 @@ It is now possible to specify a `NetworkFilter` object to select the external ne
 
 ```yaml
 externalNetwork:
-  name: "public"
+  filter:
+    name: "public"
 ```
 
 If a network is provided, it'll be added to `OpenStackCluster.Status.ExternalNetwork`. If the network can't be found, an error will be returned.
@@ -239,7 +241,7 @@ The new field has IPv4 validation added.
 
 #### Change to subnet
 
-In v1beta1, `Subnet` of `OpenStackCluster` is modified to `Subnets` to allow specification of two existent subnets for the dual-stack scenario.
+In v1beta1, `Subnet` of `OpenStackCluster` is modified to `Subnets` to allow specification of two existing subnets for the dual-stack scenario.
 
 ```yaml
   subnet:
@@ -253,10 +255,12 @@ In v1beta1, this will be automatically converted to:
     - id: a532beb0-c73a-4b5d-af66-3ad05b73d063
 ```
 
-`Subnets` allows specifications of maximum two `SubnetFilter` one being IPv4 and the other IPv6. Both subnets must be on the same network. Any filtered subnets will be added to `OpenStackCluster.Status.Network.Subnets`.
+`Subnets` allows specifications of maximum two `SubnetParam`s one being IPv4 and the other IPv6. Both subnets must be on the same network. Any filtered subnets will be added to `OpenStackCluster.Status.Network.Subnets`.
 
 When subnets are not specified on `OpenStackCluster` and only the network is, the network is used to identify the subnets to use. If more than two subnets exist in the network, the user must specify which ones to use by defining the `OpenStackCluster.Spec.Subnets` field.
 
+See [Filters are replaced by params with separate id and filter](#filters-are-replaced-by-params-with-separate-id-and-filter) for changes to the `SubnetFilter`.
+
 #### Change to nodeCidr and dnsNameservers
 
 In v1beta1, `OpenStackCluster.Spec.ManagedSubnets` array field is introduced. The `NodeCIDR` and `DNSNameservers` fields of `OpenStackCluster.Spec` are moved into that structure (renaming `NodeCIDR` to `CIDR`). For example:
@@ -386,11 +390,66 @@ spec:
     bastion:
       spec:
         image:
-          name: foobar
+          filter:
+            name: foobar
 ```
 
 ### Changes to filters
 
+#### Filters are replaced by params with separate id and filter
+
+We previously defined filters for specifying each of the following:
+* Images
+* Networks
+* Subnets
+* Security Groups
+* Routers
+
+Taking Images as an example, in `OpenStackMachineSpec` the `image` parameter accepted the following fields:
+* id
+* name
+* tags
+
+However, there were 2 different behaviours here depending on which fields were specified. If `id` was specified we both ignored all other fields, and made no attempt to validate the id because it cannot be known unless it exists. If `id` was not specified we performed an OpenStack query using the other parameters to determine the id. This behaviour is both difficult to describe and validate, so in v1beta1 we have separated the 2 different behaviours into different fields. The `id` field remains, but all other fields become part of a new `filter` parameter. It is required to specify either `id` or `filter`. Specifying both, neither, or an empty filter, will now result in an admission failure (the API server will reject the operation immediately).
+
+We have also added validation to the id field, which must now parse as a uuid. An id field which does not parse as a uuid will also result in an admission failure.
+
+Specifying a filter object by id remains unchanged.
+```yaml
+  image:
+    id: 02e31c38-d5ba-4c57-addb-00fc71eb5b19
+```
+
+Specifying a filter object by a filter parameter must now move filter parameters into the filter field:
+```yaml
+  image:
+    name: my-image
+    tags:
+    - my-tag
+```
+becomes:
+```yaml
+  image:
+    filter:
+      name: my-image
+      tags:
+      - my-tag
+```
+
+The same principle applies to all the filter types. For example:
+
+To specify `externalNetwork` by id in `OpenStackClusterSpec`:
+```yaml
+  externalNetwork:
+    id: 0a5d4e3d-0a2c-4bed-9172-72544db1f8da
+```
+or by name:
+```yaml
+  externalNetwork:
+    filter:
+      name: my-external-network
+```
+
 #### Changes to filter tags
 
 We currently define filters on 4 different Neutron resources which are used throughout the API: