Add docs for new domain user setting (#342)

docs for #341

Co-authored-by: Andrew Coates <[email protected]>

cli/README.md

@@ -75,6 +75,20 @@ Use 'provision.properties' for common arguments
                                fail with a descriptive error message. A return
                                value of '0' = indicates no  changes needed; '1'
                                = changes needed; '-1' not compatible
+      -du, --domain-user=<domainUserAlias>
+                             optional custom domain user, to be used when
+                               creating ACLs. By default, specmesh expects the
+                               principle used to authenticate with Kafka to
+                               have the same name as the domain id. For
+                               example, given a domain id of 'urn:acme.
+                               products', specmesh expects the user to be
+                               called 'acme.products', and creates ACLs
+                               accordingly. In some situations, e.g. Confluent
+                               Cloud Service Accounts, the username is system
+                               generated or outside control of administrators.
+                               In these situations, use this option to provide
+                               the generated username and specmesh will
+                               provision ACLs accordingly.
       -s, --secret=<secret>      secret credential for the cluster connection
       -schemaPath, --schema-path=<schemaPath>
                              schemaPath where the set of referenced schemas

kafka/README.md

@@ -103,4 +103,22 @@ The set of ACLs created from the `provisioner-functional-test-api.yaml`
 (pattern=ResourcePattern(resourceType=CLUSTER, name=kafka-cluster, patternType=PREFIXED)
 =(principal=User:simple.provision_demo, host=*, operation=IDEMPOTENT_WRITE, permissionType=ALLOW)), 
 ]
-```
+```
+
+
+### Custom usernames
+
+The normal SpecMesh convention is for domain users to have the same name as the domain id.
+For example, given a spec with `id: 'urn:.london.hammersmith.olympia.bigdatalondon'`, SpecMesh will create ACLs to for a principle with the name `london.hammersmith.olympia.bigdatalondon`.
+
+Some times the name of the principle is not in your control, e.g. at the time of writing, service accounts in Confluent Cloud have a user-defined name, but the _principle_ that Kafka sees is the service account _id_, not name.  
+The Id is system generated, e.g. `sa-dkg9sfd`.
+
+In Confluent Cloud, it is recommended that a service account is created with the domain id as the name, and the account id is passed to specmesh via:
+
+1. If using the [command line](../cli/README.md), use the `--domain-user` command line parameter. E.g. `--domain-user=sa-dkg9sfd`
+2. If using the [`Provisioner` class](src/main/java/io/specmesh/kafka/provision/Provisioner.java), use the `domainUserAlias` method. E.g
+   ```
+   Provisioner.builder()
+      .domainUserAlias("sa-dkg9sfd")
+   ```