Merge pull request #190 from brianwcook/auth-prefetch

added information about prefetching RPMs that require a subscription

docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc

@@ -1,6 +1,6 @@
 = Using Red Hat activation keys to access subscription content
 
-Most Red Hat software requires a subscripition to access. Activation keys are the preferred method for using Red Hat subscriptions with Konflux builds.
+Most Red Hat software requires a subscripition to access. Activation keys are the preferred method for using Red Hat subscriptions with Konflux builds and are supported by the all types of container builds, including hermetic builds using the prefetch-dependencies task.
 
 NOTE: Previously, mounting entitlement certificates directly as secrets was advocated but this is discouraged by Red Hat since those certificates are intended to be regularly revoked and refreshed by the subscription-manager system. Direct use of entitlement certificates is still supported by Konflux but discouraged. Entitlement certificate docs are xref:./entitlement-subscription.adoc[here].
 
@@ -11,25 +11,22 @@ When your activation key is created, you will need to create a secret with two v
 
 == Adding activation keys to the workspace
 
-You will need to create one or more secrets in your Konflux namespace (one per activation key). First, decide what to name the secrets and the scope they should have.
+You will need to create one or more secrets in your Konflux namespace (one per activation key). First, decide what to name the secrets and the scope they should have. You can control the scope of the activation key you add with the name.
 
-=== Adding subscription entitlement for an entire workspace or an individual build
+=== Adding subscription entitlement for an entire workspace
 
-You can control the scope of the activation key you add with the name. The `+buildah+` tasks expect an activation key with a default name of `+activation-key+`. If you use this name for your secret, all of the builds in your workspace will automatically use the activation key.
+Both the `+buildah+` and `+prefetch-dependencies+` tasks accept an activation key with a default name of `+activation-key+`. If you use this name for your secret, all of the builds in your workspace will automatically use the activation key.
 
-Sometimes, you only want certain builds to have the activation key, particularly when you need to have more than one key with different repository configurations in the same workspace. To do this, just select a different name for the activation key (not `+activation-key+`). Then, add a parameter to your pipeline:
+=== Adding subscription entitlement for a specific component build
+Sometimes, you only want certain builds to have the activation key, particularly when you need to have more than one key with different repository configurations in the same workspace. To do this, choose a different name for your activation key secret (not `+activation-key+`). Then, add a parameter to your ccomponent's pipeline yaml:
 
 ----
 - name: ACTIVATION_KEY
-  value: my-custom-key-name
+  value: my-secret-name
 ----
 
 == Create the activation key secrets
 
-. <<Create-activation-key-through-the-UI>>
-. <<Create-activation-key-through-console>>
-
-
 [[Create-activation-key-through-the-UI]]
 === Create activation key secret through the UI
 
@@ -51,16 +48,23 @@ kubectl create secret generic activation-key -n <your-tenant> --from-literal=org
 
 == Using subscription content in a build
 
-=== Automatic registration
+=== Non-hermetic (network connected) builds:
+
+==== Automatic registration
 
-The buildah task will use a provided activation key to register itself with Red Hat subscription manager and moount the necessary credentials so that can be used by the builds. 
+The buildah task will use a provided activation key to register itself with Red Hat subscription manager and mount the necessary certificates to the build environment. Simply add `+dnf+` or `+yum install+` commands to your Containerfile. 
 
-TIP: If your activation key includes more repositories than the defaults add the following command inside your Containerfile in order update repository metadata.
+TIP: If your activation key includes more than the default repositories, add the following command inside your Containerfile in order update repository metadata:
 
 ----
 subscription-manager --refresh
 ----
 
-=== Explicit registration
+==== Explicit registration
+
+If you include a `+subscription-manager register+`  command in your Containerfile, automatic registration will be disabled. You can control subscription-manager directly using the normal commands.
+
+=== Hermetic (network isolated) builds:
 
-If you include a `+subscription-manager register+`  command in your Containerfile, automatic registration will be disabled. You can control subscription-manager directly using the normal commands.
+The prefetch-dependencies task can use an activation key to register and fetch RPMs. All repositories configured for the activation key will be enabled for prefetch. 
+If the default name was used for the secret (activation-key) no configuration is necessary. Otherwise, provide the ACTIVATION_KEY parameter to the build pipeline as noted above.