docs(access operator): early access instructions for using the access…

… operator (#10752)

Signed-off-by: prmellor <pmellor@redhat.com>

documentation/assemblies/security/assembly-access-operator.adoc

@@ -0,0 +1,18 @@
+// This assembly is included in the following assemblies:
+//
+// security/assembly-security.adoc
+
+[id='assembly-access-operator-{context}']
+= Using the Access Operator to manage client connections
+
+[role="_abstract"]
+The Strimzi Access Operator is an optional feature that simplifies the sharing of Kafka connection information and credentials between namespaces
+
+The Access Operator is deployed separately and manages the distribution of connection details, which are stored as a `Secret` resource. 
+The secret contains cluster connection details and optional user credentials, and can be referenced by applications across different namespaces.
+
+//Procedure for deployment of Access Operator
+include::../../modules/deploying/proc-deploy-access-operator.adoc[leveloffset=+1]
+//Procedure for running the Access Operator
+include::../../modules/deploying/proc-using-access-operator.adoc[leveloffset=+1]
+

documentation/assemblies/security/assembly-security.adoc

@@ -81,3 +81,9 @@ include::../../modules/security/proc-configuring-external-clients-to-trust-clust
 
 //user-supplied certs
 include::assembly-using-your-own-certificates.adoc[leveloffset=+1]
+
+//access-operator
+ifdef::Section[]
+include::assembly-access-operator.adoc[leveloffset=+1]
+endif::Section[]
+

documentation/modules/deploying/proc-deploy-access-operator.adoc

@@ -0,0 +1,43 @@
+// This assembly is included in the following assemblies:
+//
+// security/assembly-access-operator.adoc
+
+[id='proc-deploy-access-operator-{context}']
+= Deploying the Access Operator
+
+[role="_abstract"]
+This procedure shows how to deploy the Access Operator for access management of a Kafka cluster.
+You cannot use the Access Operator with a Kafka cluster that is not managed by the Cluster Operator.  
+
+.Prerequisites
+
+* The Access Operator installation files must be downloaded and extracted from the latest release archive (`{ReleaseFile}`) from the {ReleaseDownload}. +
+The installation files are contained in the `./install` directory.
+* xref:deploying-cluster-operator-str[The Cluster Operator must be deployed.]
+
+By default, the Access Operator is deployed in the `strimzi-access-operator` namespace. 
+To deploy the operator in a different namespace, update the `namespace` property in the installation files.
+
+.Procedure
+
+. Deploy the Access Operator using the installation files from the `install` directory:
++
+[source,shell]
+kubectl create -f ./install/access-operator
+
+. Check the status of the deployment:
++
+[source,shell,subs="+quotes"]
+----
+kubectl get deployments
+----
++
+.Output shows the deployment name and readiness
+[source,shell,subs="+quotes"]
+----
+NAME                     READY  UP-TO-DATE  AVAILABLE
+strimzi-access-operator  1/1    1           1
+----
++
+`READY` shows the number of replicas that are ready/expected.
+The deployment is successful when the `AVAILABLE` output shows `1`.

documentation/modules/deploying/proc-using-access-operator.adoc

@@ -0,0 +1,132 @@
+// This assembly is included in the following assemblies:
+//
+// security/assembly-access-operator.adoc
+
+[id='proc-using-access-operator-{context}']
+= Using the Access Operator
+
+[role="_abstract"]
+This procedure shows how to use the Access Operator to manage access to a Kafka cluster.
+The Access Operator simplifies access management by creating a binding `Secret` containing the connection details for a Kafka cluster and optional user credentials.
+
+Kafka instances and Kafka users are specified in a `KafkaAccess` resource.
+Optionally, a listener to connect to the Kafka cluster can also be specified. 
+The operator will look up the Kafka instance and users specified in the `KafkaAccess` resource to create a secret with the details required for connection.
+Any authentication credentials required by a user to connect to Kafka are also added to the secret. 
+If no listener is specified it will choose according to these rules: 
+
+* If only one listener is configured in the `Kafka` resource, that listener is selected.
+* If multiple listeners are configured, the operator selects one with the appropriate security based on `tls` and `authentication` properties in the `Kafka` and `KafkaUser` resources.
+* If multiple listeners with appropriate security are available, the operator selects an internal listener, if present.
+* If multiple internal listeners with appropriate security are available, the operator selects the first listener alphabetically by name.
+
+.Prerequisites
+
+* A Kafka cluster deployed  using a `Kafka` resource and managed by the Cluster Operator.
+* `KafkaUser` resources must be created for any users needing authentication to the Kafka cluster.
+
+Example `KafkaAccess` resource specifications are contained in the `./examples` directory of the latest release archive (`{ReleaseFile}`) from the {ReleaseDownload}.
+
+.Procedure
+
+. Configure a `KafkaAccess` custom resource to bind your applications to the Kafka cluster. 
++
+** Specify the name of the `Kafka` resource to connect to the Kafka cluster.
+** (Optional) Specify the name of the listener used to connect to the Kafka cluster.
+** (Optional) Specify the `KafkaUser` resources representing users requiring access to the Kafka cluster.
++
+Make sure the name, namespace and listener in the `KafkaAccess` custom resource match those of your Kafka instance.
++
+.Example access configuration
+[source,yaml]
+----
+apiVersion: access.strimzi.io/v1alpha1
+kind: KafkaAccess
+metadata:
+  name: my-kafka-access
+spec:
+  kafka:
+    name: my-cluster
+    namespace: kafka
+    listener: tls
+  user:
+    kind: KafkaUser
+    apiGroup: kafka.strimzi.io
+    name: my-user
+    namespace: kafka
+----
+
+. Create the `KafkaAccess` resource in Kubernetes:
++
+[source,shell]
+----
+kubectl apply -f <kafka_access_config_file> -n strimzi-access-operator
+----
+
+. Check the status of the `KafkaAccess` custom resource: 
++
+[source,shell]
+----
+kubectl get kafkaaccess my-kafka-access -o yaml
+----
++
+The status of the resource is updated once the operator creates the binding `Secret`. 
++
+.Status shows binding secret created 
+[source,yaml]
+----
+# ...
+status: 
+  binding: 
+    name: 
+      kafka-binding
+----
+
+. Inspect the created binding secret: 
++ 
+[source,shell]
+kubectl get secret kafka-binding -o yaml
++
+The secret contains connection details and user credentials in various formats to accommodate the requirements of different development environments and applications. 
+The user credentials included depend on the authentication method specified for the `KafkaUser` resource. 
+For example, SCRAM-SHA-512 credentials are provided if that type of authentication is used.
++
+.Example binding secret
+[source,yaml]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: kafka-binding
+type: servicebinding.io/kafka
+data:
+  type: kafka
+  provider: strimzi
+  # Kafka cluster connection properties # <1>
+  bootstrap.servers: my-cluster-kafka-bootstrap:9092
+  bootstrap-servers: my-cluster-kafka-bootstrap:9092  
+  bootstrapServers: my-cluster-kafka-bootstrap:9092
+  # Security protocol option # <2>
+  security.protocol: SSL
+  securityProtocol: SSL
+  # TLS enabled
+  ssl.truststore.crt: my-cluster-cluster-ca-cert # <3>
+  # SCRAM-SHA-512 authentication properties # <4>
+  username: admin
+  password: password
+  sasl.jaas.config: com.example.ScramLoginModule required;
+  sasl.mechanism: SCRAM-SHA-512
+  saslMechanism: SCRAM-SHA-512
+  # mTLS authentication properties # <5>
+  ssl.keystore.crt: user.crt
+  ssl.keystore.key: user.key
+----
+<1> Comma-separated host:port connection details for Kafka clusters.
+<2> The security protocol used for communication with Kafka, which can be `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT` or `SASL_SSL`.
+<3> The Strimzi cluster CA certificate if TLS is enabled.
+<4> Credentials for SCRAM-SHA-512 client authentication.
+<5> Credentials for mTLs client authentication. 
+
+. Make the secret available to your application. 
++ 
+Applications can reference the secret directly, or you can inject it into an application's environment using an operator to implement the link:https://servicebinding.io/spec/core/1.0.0/[Service Binding specification].