Managing activation keys

Activation keys provide a method to automate system registration and subscription attachment. You can create multiple keys and associate them with different environments and content views. For example, you might create a basic activation key with a subscription for CentOS workstations and associate it with content views from a particular environment.

You can use activation keys during content host registration to improve the speed, simplicity and consistency of the process. Note that activation keys are used only when hosts are registered. If changes are made to an activation key, it is applicable only to hosts that are registered with the amended activation key in the future. The changes are not made to existing hosts.

Activation keys can define the following properties for content hosts:

  • Associated subscriptions and subscription attachment behavior

  • Available products and repositories

  • A lifecycle environment and a content view

  • Host collection membership

  • System purpose

Content view conflicts between host creation and registration

When you provision a host, orcharhino uses provisioning templates and other content from the content view that you set in the host group or host settings. When the host is registered, the content view from the activation key overwrites the original content view from the host group or host settings. Then orcharhino uses the content view from the activation key for every future task, for example, rebuilding a host.

When you rebuild a host, ensure that you set the content view that you want to use in the activation key and not in the host group or host settings.

Using the same activation key with multiple content hosts

You can apply the same activation key to multiple content hosts if it contains enough subscriptions. However, activation keys set only the initial configuration for a content host. When the content host is registered to an organization, the organization’s content can be attached to the content host manually.

Using multiple activation keys with a content host

A content host can be associated with multiple activation keys that are combined to define the host settings. In case of conflicting settings, the last specified activation key takes precedence. You can specify the order of precedence by setting a host group parameter as follows:

$ hammer hostgroup set-parameter \
--hostgroup "My_Host_Group" \
--name "My_Activation_Key" \
--value "name_of_first_key", "name_of_second_key", ...

Creating an activation key

You can use activation keys to define a specific set of subscriptions to attach to hosts during registration. The subscriptions that you add to an activation key must be available within the associated content view.

Subscription Manager attaches subscriptions differently depending on the following factors:

  • Are there any subscriptions associated with the activation key?

  • Is the auto-attach option enabled?

Based on the previous factors, there are three possible scenarios for subscribing with activation keys:

  1. Activation key that attaches subscriptions automatically.

    With no subscriptions specified and auto-attach enabled, hosts using the activation key search for the best fitting subscription from the ones provided by the content view associated with the activation key. This is similar to entering the subscription-manager --auto-attach command.

  2. Activation key providing a custom set of subscription for auto-attach.

    If there are subscriptions specified and auto-attach is enabled, hosts using the activation key select the best fitting subscription from the list specified in the activation key. Setting system purpose on the activation key does not affect this scenario.

  3. Activation key with the exact set of subscriptions.

    If there are subscriptions specified and auto-attach is disabled, hosts using the activation key are associated with all subscriptions specified in the activation key. Setting system purpose on the activation key does not affect this scenario.

Custom Products

If a custom product, typically containing content not provided by Red Hat, is assigned to an activation key, this product is always enabled for the registered content host regardless of the auto-attach setting.

To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Procedure

  1. In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys and click Create Activation Key.

  2. In the Name field, enter the name of the activation key.

  3. If you want to set a limit, clear the Unlimited hosts checkbox, and in the Limit field, enter the maximum number of systems you can register with the activation key. If you want unlimited hosts to register with the activation key, ensure the Unlimited Hosts checkbox is selected.

  4. Optional: In the Description field, enter a description for the activation key.

  5. From the Environment list, select the environment to use.

  6. From the Content View list, select a content view to use.

  7. Click Save.

  8. Optional: For CentOS 8 hosts, in the System Purpose section, you can configure the activation key with system purpose to set on hosts during registration to enhance subscriptions auto attachment.

CLI procedure

  1. Create the activation key:

    $ hammer activation-key create \
--name "My_Activation_Key" \
--unlimited-hosts \
--description "Example Stack in the Development Environment" \
--lifecycle-environment "Development" \
--content-view "Stack" \
--organization "My_Organization"

  2. Obtain a list of your subscription IDs:

    $ hammer subscription list --organization "My_Organization"

  3. Attach the CentOS subscription UUID to the activation key:

    $ hammer activation-key add-subscription \
--name "My_Activation_Key" \
--subscription-id My_Subscription_ID \
--organization "My_Organization"

  4. List the product content associated with the activation key:

    1. If Simple Content Access (SCA) is enabled:

      $ hammer activation-key product-content \
--content-access-mode-all true \
--name "My_Activation_Key" \
--organization "My_Organization"

    2. If SCA is not enabled:

      $ hammer activation-key product-content \
--name "My_Activation_Key" \
--organization "My_Organization"

  5. Override the default auto-enable status for the orcharhino Client for CentOS repository. The default status is set to disabled. To enable, enter the following command:

    $ hammer activation-key content-override \
--name "My_Activation_Key" \
--content-label orcharhino Client \
--value 1 \
--organization "My_Organization"

Best Practices for Activation Keys

  • There are two basic approaches for activation keys: Either create a single activation key for a specific kind of use case, for example corporate_webserver_prod, which uses the WebServer content view and selects all subscriptions necessary to run the service. Alternatively, create separate activation keys like basic_centos_prod, webserver_prod, and database_mysql_prod, all using the same content view, that is WebServer, along with a different set of subscriptions.

  • Register hosts to orcharhino with an activation key. You can add additional content using content views, lifecycle environments, subscriptions, and repository sets using the management UI, the API, Hammer scripts, or Ansible.

  • You can attach multiple activation keys to a host as long as all activation keys belong to the same lifecycle environment and content view. This allows you to separately activate additional repositories at a later stage.

  • We recommend using meaningful names for activation keys to indicate the content and lifecycle environment, for example centos_webserver.

Updating subscriptions associated with an activation key

Use this procedure to change the subscriptions associated with an activation key. To use the CLI instead of the orcharhino management UI, see the CLI procedure.

Note that changes to an activation key apply only to machines provisioned after the change.

Procedure

  1. In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys and click the name of the activation key.

  2. Click the Subscriptions tab.

  3. To remove subscriptions, select List/Remove, and then select the checkboxes to the left of the subscriptions to be removed and then click Remove Selected.

  4. To add subscriptions, select Add, and then select the checkboxes to the left of the subscriptions to be added and then click Add Selected.

  5. Click the Repository Sets tab and review the repositories' status settings.

  6. To enable or disable a repository, select the checkbox for a repository and then change the status using the Select Action list.

  7. Click the Details tab, select a content view for this activation key, and then click Save.

CLI procedure

  1. List the subscriptions that the activation key currently contains:

    $ hammer activation-key subscriptions \
--name My_Activation_Key \
--organization "My_Organization"

  2. Remove the required subscription from the activation key:

    $ hammer activation-key remove-subscription \
--name "My_Activation_Key" \
--subscription-id ff808181533518d50152354246e901aa \
--organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  3. Attach new subscription to the activation key:

    $ hammer activation-key add-subscription \
--name "My_Activation_Key" \
--subscription-id ff808181533518d50152354246e901aa \
--organization "My_Organization"

    For the --subscription-id option, you can use either the UUID or the ID of the subscription.

  4. List the product content associated with the activation key:

    $ hammer activation-key product-content \
--name "My_Activation_Key" \
--organization "My_Organization"

  5. Override the default auto-enable status for the required repository:

    $ hammer activation-key content-override \
--name "My_Activation_Key" \
--content-label content_label \
--value 1 \
--organization "My_Organization"

    For the --value option, enter 1 for enable, 0 for disable.

Using activation keys for host registration

You can use activation keys to complete the following tasks:

  • Registering new hosts during provisioning through orcharhino. The kickstart provisioning templates in orcharhino contain commands to register the host using an activation key that is defined when creating a host.

  • Registering existing CentOS hosts. Configure Subscription Manager to use orcharhino Server for registration and specify the activation key when running the subscription-manager register command.

You can register hosts with orcharhino using the host registration feature in the orcharhino management UI, Hammer CLI, or the orcharhino API. For more information, see Registering Hosts in Managing Hosts.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Register Host.

  2. From the Activation Keys list, select the activation keys to assign to your host.

  3. Click Generate to create the registration command.

  4. Click on the files icon to copy the command to your clipboard.

  5. Connect to your host using SSH and run the registration command.

  6. Ensure that the appropriate repositories have been enabled:

    • On CentOS: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

CLI procedure

  1. Generate the host registration command using the Hammer CLI:

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key"

    If your hosts do not trust the SSL certificate of orcharhino Server, you can disable SSL validation by adding the --insecure flag to the registration command.

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true

  2. Connect to your host using SSH and run the registration command.

  3. Ensure that the appropriate repositories have been enabled:

    • On CentOS: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

API procedure

  1. Generate the host registration command using the orcharhino API:

    $ curl -X POST https://orcharhino.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"] }}'

    If your hosts do not trust the SSL certificate of orcharhino Server, you can disable SSL validation by adding the --insecure flag to the registration command.

    $ curl -X POST https://orcharhino.example.com/api/registration_commands \
--user "My_User_Name" \
-H 'Content-Type: application/json' \
-d '{ "registration_command": { "activation_keys": ["My_Activation_Key_1, My_Activation_Key_2"], "insecure": true }}'

    Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing Content.

    To enter a password as a command line argument, use username:password syntax. Keep in mind this can save the password in the shell history. Alternatively, you can use a temporary personal access token instead of a password. To generate a token in the orcharhino management UI, navigate to My Account > Personal Access Tokens.

  2. Connect to your host using SSH and run the registration command.

  3. Ensure that the appropriate repositories have been enabled:

    • On CentOS: Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

Multiple activation keys

You can use multiple activation keys when registering a content host. You can then create activation keys for specific subscription sets and combine them according to content host requirements. For example, the following command registers a content host to your organization with both VDC and OpenShift subscriptions:

$ subscription-manager register --org="My_Organization" \
--activationkey="ak-VDC,ak-OpenShift"
Settings conflicts

If there are conflicting settings in activation keys, the rightmost key takes precedence.

  • Settings that conflict: Service Level, Release Version, Environment, Content View, and Product Content.

  • Settings that do not conflict and the host gets the union of them: Subscriptions and Host Collections.

  • Settings that influence the behavior of the key itself and not the host configuration: Content Host Limit and Auto-Attach.

Enabling auto-attach

When auto-attach is enabled on an activation key and there are subscriptions associated with the key, the subscription management service selects and attaches the best-matched associated subscriptions based on a set of criteria like currently installed products, architecture, and preferences like service level.

You can enable auto-attach and have no subscriptions associated with the key. This type of key is commonly used to register virtual machines when you do not want the virtual machine to consume a physical subscription, but to inherit a host-based subscription from the hypervisor.

Auto-attach is enabled by default. Disable the option if you want to force attach all subscriptions associated with the activation key.

Procedure

  1. In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys.

  2. Click the activation key name that you want to edit.

  3. Click the Subscriptions tab.

  4. Click the edit icon next to Auto-Attach.

  5. Select or clear the checkbox to enable or disable auto-attach.

  6. Click Save.

CLI procedure

  • Enter the following command to enable auto-attach on the activation key:

    $ hammer activation-key update --name "My_Activation_Key" \
--organization "My_Organization" --auto-attach true

Enabling and disabling repositories on activation key

As a Simple Content Access (SCA) user, you can enable or disable repositories on an activation key in the orcharhino management UI.

Procedure

  1. In the orcharhino management UI, navigate to Content > Lifecycle > Activation Keys.

  2. Select an activation key.

  3. Select the Repository Sets tab.

  4. From the dropdown, you can filter the Repository type column to Custom or Red Hat, if desired.

  5. Select the desired repositories or click the Select All checkbox to select all repositories.

  6. From the Select Action list, select Override to Enabled, Override to Disabled, or Reset to Default.

The text and illustrations on this page are licensed by ATIX AG under a Creative Commons Attribution–Share Alike 3.0 Unported ("CC-BY-SA") license. This page also contains text from the official Foreman documentation which uses the same license ("CC-BY-SA").