From e92079cc0c51943c0a5a1a2178943eddd5a17c56 Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 13:32:23 -0500 Subject: [PATCH 1/6] add activation keys docs --- .vscode/settings.json | 4 ++-- docs/modules/ROOT/pages/how-tos/_nav.adoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 9cdf79f9..f7519959 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,4 @@ { - "asciidoc.antora.enableAntoraSupport": true, - "editor.wordWrap": "on" + "editor.wordWrap": "on", + "asciidoc.antora.enableAntoraSupport": true } diff --git a/docs/modules/ROOT/pages/how-tos/_nav.adoc b/docs/modules/ROOT/pages/how-tos/_nav.adoc index 1e0f0fc5..df901c54 100644 --- a/docs/modules/ROOT/pages/how-tos/_nav.adoc +++ b/docs/modules/ROOT/pages/how-tos/_nav.adoc @@ -13,7 +13,7 @@ *** xref:how-tos/configuring/custom-tags.adoc[Using custom tags] *** xref:how-tos/configuring/dynamic-labels.adoc[Using dynamic labels] *** xref:how-tos/configuring/overriding-compute-resources.adoc[Overriding compute resources] -*** xref:how-tos/configuring/entitlement-subscription.adoc[Using Red Hat entitlement subscription] +*** xref:how-tos/configuring/activation-keys-subscription.adoc[Using Red Hat subscription content] *** xref:how-tos/configuring/reconfiguring-build-pipeline.adoc[Reconfiguring the build pipeline] ** xref:how-tos/testing/index.adoc[Testing your components and applications] *** xref:how-tos/testing/build/index.adoc[Build-time tests] From eec34406d3e39b63d373328938ae68f88d3e515a Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 15:51:46 -0500 Subject: [PATCH 2/6] add activation keys docs --- .../activation-keys-subscription.adoc | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc diff --git a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc new file mode 100644 index 00000000..14de209f --- /dev/null +++ b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc @@ -0,0 +1,53 @@ += 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. + +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]. + +To learn how to create an activation keys see the https://docs.redhat.com/en/documentation/subscription_central/1-latest/html/getting_started_with_activation_keys_on_the_hybrid_cloud_console/index[Red Hat documentation]. + +When your activation key is created, you will need to create a secret with two values: your "org id" and the name of your activation key. + + +== Create activation key secrets + +You will need to create a secret in your Konflux namespace. You can do it in two ways: + +. <> +. <> + + +[[Create-activation-key-through-the-UI]] +=== Create activation key secret through the UI + +1. Access the Secrets section in the konflux UI and click on *Add secret*. +2. Set the secret name to activation-key. +3. Add the first key with the name *org* and and set the value to your org id. +4. Add a second key with the name *activationkey* and set the value to the name of your activation key. +5. Save the secret by clicking *Add secret* + +[[Create-activation-key-through-console]] +=== Create activation key secret through console + +Alternatively, you can create the secret through the CLI. After logging into your cluster and navigating to your namespace, run the following command: + +---- +kubectl create secret generic activation-key -n --from-literal=org= --from-literal=activationkey= +---- + + +== Using subscription content in a build + +=== 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. + +TIP: If your activation key includes more repositories than the defaults add the following command inside your Containerfile in order update repository metadata. + +---- +subscription-manager --refresh +---- + +=== 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. \ No newline at end of file From e7d77cdaf8013b01c9219e072aa53a92abcb5b24 Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 17:11:15 -0500 Subject: [PATCH 3/6] fix xref --- .../pages/how-tos/configuring/activation-keys-subscription.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc index 14de209f..46f467b6 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc @@ -2,7 +2,7 @@ Most Red Hat software requires a subscripition to access. Activation keys are the preferred method for using Red Hat subscriptions with Konflux builds. -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]. +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]. To learn how to create an activation keys see the https://docs.redhat.com/en/documentation/subscription_central/1-latest/html/getting_started_with_activation_keys_on_the_hybrid_cloud_console/index[Red Hat documentation]. From e671cdb2b8ffed478080b4a75004b7633516d7b4 Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 17:20:18 -0500 Subject: [PATCH 4/6] add a warning to the entitlement certificates page --- .../pages/how-tos/configuring/entitlement-subscription.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/entitlement-subscription.adoc b/docs/modules/ROOT/pages/how-tos/configuring/entitlement-subscription.adoc index 97a3c636..56613186 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/entitlement-subscription.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/entitlement-subscription.adoc @@ -1,5 +1,8 @@ = Using Red Hat entitlement subscription +WARNING: This page has been superceded by xref:./activation-keys-subscription.adoc[Using Red Hat activation keys to access subscription content]. While the instructions here still work, this method is discouraged by Red Hat and users are advised that subscription entitlement certificates may be revoked as part of normal operations. Under normal circumstances this is intentional and managed by subscription-manager in order to refresh entitlement data but with these instructions it will results in build failures and require manual user intervention. + + Entitlement subscription allows users to install RPMs that are not accessible without it. In order to use it in your builds, you must have access to an entitlement subscription and possess the neccessary entitlement certificate files. To obtain them, review https://developers.redhat.com/articles/2022/01/24/create-entitled-builds-red-hat-subscriptions-openshift[Subscription benefits for secure deployments] guide. From 121400aed3aa7d79e1810a10053c46f8926d9069 Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 18:07:17 -0500 Subject: [PATCH 5/6] fix subscription-manager register command formatting --- .../pages/how-tos/configuring/activation-keys-subscription.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc index 46f467b6..6e4de04c 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc @@ -50,4 +50,4 @@ subscription-manager --refresh === 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. \ No newline at end of file +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. \ No newline at end of file From 5cf5b3e29246099c7e0163ee27bb3037ce800e29 Mon Sep 17 00:00:00 2001 From: Brian Cook Date: Tue, 3 Dec 2024 18:19:32 -0500 Subject: [PATCH 6/6] adding text to help the user decide whether to use the default name or not (scope impact of the added key) --- .../activation-keys-subscription.adoc | 27 ++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc index 6e4de04c..9669ff15 100644 --- a/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc +++ b/docs/modules/ROOT/pages/how-tos/configuring/activation-keys-subscription.adoc @@ -9,9 +9,22 @@ To learn how to create an activation keys see the https://docs.redhat.com/en/doc When your activation key is created, you will need to create a secret with two values: your "org id" and the name of your activation key. -== Create activation key secrets +== Adding activation keys to the workspace -You will need to create a secret in your Konflux namespace. You can do it in two ways: +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. + +=== Adding subscription entitlement for an entire workspace or an individual build + +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. + +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: + +---- +- name: ACTIVATION_KEY + value: my-custom-key-name +---- + +== Create the activation key secrets . <> . <> @@ -20,11 +33,11 @@ You will need to create a secret in your Konflux namespace. You can do it in two [[Create-activation-key-through-the-UI]] === Create activation key secret through the UI -1. Access the Secrets section in the konflux UI and click on *Add secret*. -2. Set the secret name to activation-key. -3. Add the first key with the name *org* and and set the value to your org id. -4. Add a second key with the name *activationkey* and set the value to the name of your activation key. -5. Save the secret by clicking *Add secret* +. Access the Secrets section in the konflux UI and click on *Add secret*. +. Set the secret name to activation-key. +. Add the first key with the name *org* and and set the value to your org id. +. Add a second key with the name *activationkey* and set the value to the name of your activation key. +. Save the secret by clicking *Add secret* [[Create-activation-key-through-console]] === Create activation key secret through console