Managing entitlements

When you purchase an IBM Cloud Pak®, you receive an entitlement to use that software and potentially other dependencies to make that software work. For example, not only do you receive entitlement to the IBM Cloud Pak, but also to Red Hat® OpenShift® Container Platform, the platform on which the IBM Cloud Pak works.

How do entitlement keys work?

Entitlement keys are owned by individuals. You can think of them as something like a combined user ID plus password that tells the entitled registry who you are. Every time a key is used to pull software, the registry checks the current level of entitlement for that individual to determine whether they have access or not.

Instead of having to download and install software, entitlement keys enable you to pull your software into a container environment of your choosing. IBM product containers are accessed by way of the IBM Container Registry (cp.icr.io).

When you install your software, you are directed to use your entitlement key. You can access your entitlement key by creating it through My IBM, then connect to the registry and pull containers. In the My IBM Container Software Library you can add, view, copy, and delete your entitlement keys. You can also view your software entitlements including containers in the My IBM Container Software Library.

Entitlement Keys are used in a command line or in automated CI/CD processes to connect to the registry by using keys and pulling containers into your clusters.

How is entitlement managed?

Entitlement is managed through Passport Advantage. Specifically, access is based on your association in Passport Advantage with the entitlement key having a download role. Your Passport Advantage site administrator manages access to your site, and can also pull containers.

The following examples illustrate common pitfalls when pulling:

• If you attempt to pull a container, but it does not currently have entitlement, you see an error message denying access. Click the provided resolution link in the message. This can happen when your license has lapsed or you have not been granted a role in Passport Advantage.

  

• If you log in to My IBM and do not currently have entitlement, the My IBM page provides instructions to follow the Passport Advantage process to gain access.

  

Accessing entitlements

Passport Advantage

The most common way of accessing your products is through the Passport Advantage client portal. You can now manage entitlements through your portal too. The keys that you find in Passport Advantage are the same keys that are available in My IBM.

IBM Cloud

Alternatively, you can now use the IBM Cloud console to install IBM Cloud Pak and other container software products into your managed clusters. This approach uses the same Passport Advantage entitlements, but it does not require the use of the My IBM entitlement keys.

Instead, you can use the Account menu from the IBM Cloud console to make your Passport Advantage licenses available to IBM Cloud.

FAQs

Q: I know that my company has purchased IBM software, but it’s not listed in the My IBM Container Software Library view. When I try to pull the containers, I get a “You are not authorized” or “Insufficient scope” error message. Why would this happen?

A: The entitlement keys are based on an individual having access to the Passport Advantage ”site" that the software was sold into. If you cannot see the entitlements in My IBM, or get an error trying to pull them from the IBM Entitled Registry, your IBMid likely has not been granted access to the site.

Managing access to sites is the responsibility of the customer site administrator. You might be able to solve this yourself by logging in to the Passport Advantage online customer portal.

If you are prompted for "self-nomination” this means that you don’t have access to any sites. If you can log in but don’t see the relevant site to select, then you need to request access and that request will need to be approved by your site administrator.

Q: I need help with fixing my container software entitlements.

A: Container software entitlement is managed the same way as traditional software entitlement, through the Passport Advantage program. For more information about Passport Advantage entitlement, see Passport Advantage Online for Customers.

And if you need any help with the Passport Advantage site management process, reach out to the eCustomer Care team.

Q: We have a policy to “rotate” our keys every 90 days to ensure that we aren’t using old credentials. How do we do this?

A: To rotate your keys, generate a new key in the My IBM Container Software Library by clicking Add new key. Now you can update your installation to use the new key. Often the entitlement key is stored in a single place (for example, an environment file or OpenShift pull secret) and needs to be updated there only once. After you’ve confirmed the new key is working, delete the old one in My IBM. The “Issue Date” field tells you which of your entitlement keys are older.

Q: If we use an entitlement key that is associated with an individual person’s account, and that person leaves the company, will we need to replace the entitlement key used in our installation?

A: Yes, you need to replace the key in this case. This is because most organizations will have a process to remove this individual from the Passport Advantage Site as soon as possible to revoke their access. And each time a pull from the Registry is initiated, the Registry re-checks the current level of entitlement for the individual who generated the key. Since they no longer have access to the Site, the pull fails.

In this case switch to using the Entitlement Key of another individual that does currently have access to the Passport Advantage Site. Often the Entitlement Key is stored in a single place (for example environment file or OpenShift pull secret) and only needs to be updated there once.

Q: Instead of an individual person’s account, we would like to have one central functional ID account that would be associated with the entitlement key that is used in our installation. That way it isn’t coupled with a specific person’s account. Is this allowed?

A: Yes, you can create an IBMid associated with a functional ID and use the Passport Advantage “Manage Access” tools to grant it Download access to your Passport Advantage Site. However, note that a primary contact, administrative contact, or site technical contact cannot be a functional ID since they are accepting legal terms of responsibility for managing the Site.