Add secret step to OLM policy scoping

Author: adellape

modules/olm-policy-scoping-operator-install.adoc

@@ -19,6 +19,9 @@ Using this example, a cluster administrator can confine a set of Operators to a
 
 . Create a new namespace:
 +
+.Example creation of a `Namespace` object
+[%collapsible]
+====
 [source,terminal]
 ----
 $ cat <<EOF | oc create -f -
@@ -28,9 +31,15 @@ metadata:
   name: scoped
 EOF
 ----
+====
 
-. Allocate permissions that you want the Operator(s) to be confined to. This involves creating a new service account, relevant role(s), and role binding(s).
+. Allocate permissions that you want the Operator(s) to be confined to. This involves creating a new service account, relevant role(s), and role binding(s) in the newly created, designated namespace:
+
+.. Create a service account by running the following command:
 +
+.Example creation of a `ServiceAccount` object
+[%collapsible]
+====
 [source,terminal]
 ----
 $ cat <<EOF | oc create -f -
@@ -41,9 +50,39 @@ metadata:
   namespace: scoped
 EOF
 ----
+====
+
+.. Create a secret by running the following command:
 +
-The following example grants the service account permissions to do anything in the designated namespace for simplicity. In a production environment, you should create a more fine-grained set of permissions:
+.Example creation of a long-lived API token `Secret` object
+[%collapsible]
+====
+[source,terminal]
+----
+$ cat <<EOF | oc create -f -
+apiVersion: v1
+kind: Secret
+type: kubernetes.io/service-account-token <1>
+metadata:
+  name: scoped
+  namespace: scoped
+  annotations:
+    kubernetes.io/service-account.name: scoped
+EOF
+----
+<1> The secret must be a long-lived API token, which is used by the service account.
+====
+
+.. Create a role by running the following command.
 +
+[WARNING]
+====
+In this example, the role grants the service account permissions to do anything in the designated namespace for simplicity. In a production environment, you should create a more fine-grained set of permissions. For more information, see "Fine-grained permissions".
+====
++
+.Example creation of `Role` and `RoleBinding` objects
+[%collapsible]
+====
 [source,terminal]
 ----
 $ cat <<EOF | oc create -f -
@@ -72,11 +111,13 @@ subjects:
   namespace: scoped
 EOF
 ----
+====
 
-. Create an `OperatorGroup` object in the designated namespace. This Operator group targets the designated namespace to ensure that its tenancy is confined to it.
-+
-In addition, Operator groups allow a user to specify a service account. Specify the service account created in the previous step:
+. Create an `OperatorGroup` object in the designated namespace by running the following command. This Operator group targets the designated namespace to ensure that its tenancy is confined to it. In addition, Operator groups allow a user to specify a service account.
 +
+.Example creation of am `OperatorGroup` object
+[%collapsible]
+====
 [source,terminal]
 ----
 $ cat <<EOF | oc create -f -
@@ -86,16 +127,19 @@ metadata:
   name: scoped
   namespace: scoped
 spec:
-  serviceAccountName: scoped
+  serviceAccountName: scoped <1>
   targetNamespaces:
   - scoped
 EOF
 ----
-+
-Any Operator installed in the designated namespace is tied to this Operator group and therefore to the service account specified.
+<1> Specify the service account created in the previous step. Any Operator installed in the designated namespace is tied to this Operator group and therefore to the service account specified.
+====
 
 . Create a `Subscription` object in the designated namespace to install an Operator:
 +
+.Example creation of `Subscription` object
+[%collapsible]
+====
 [source,terminal]
 ----
 $ cat <<EOF | oc create -f -
@@ -115,3 +159,4 @@ EOF
 <2> Specify a namespace where the catalog source was created.
 +
 Any Operator tied to this Operator group is confined to the permissions granted to the specified service account. If the Operator requests permissions that are outside the scope of the service account, the installation fails with relevant errors.
+====