Clarify how licenses are updated with KOTS/SDK #2630
Conversation
replicated-ci
added
type::docs
✅ Deploy Preview for replicated-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Deploy Preview for replicated-docs-upgrade ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| * (KOTS Only) KOTS prevents instances with expired licenses from receiving updates. | ||
|
|
||
| ### Synchronizing Licenses with KOTS | ||
| ## About Updating Licenses |
There was a problem hiding this comment.
Shuffled around the headings a bit so that everything related to license updates is under the same h2
| For online instances, KOTS pulls license details from the Vendor Portal when: | ||
| * A customer clicks **Sync license** in the Admin Console. | ||
| * An automatic or manual update check is performed by KOTS. | ||
| * An update is performed with Replicated Embedded Cluster. See [Performing Updates with Embedded Cluster](/enterprise/updating-embedded). |
There was a problem hiding this comment.
- An update is performed with Replicated Embedded Cluster. See Performing Updates with Embedded Cluster.
Added this one
| The [Replicated SDK](replicated-sdk-overview) includes an in-cluster API that retrieves up-to-date customer license information from the Vendor Portal during runtime through the [`license`](/reference/replicated-sdk-apis#license) endpoints. This means that any changes to customer licenses are reflected in real time in the customer environment, without the customer needing to perform a license update. | ||
|
|
||
| For information about how to use the SDK API to query license entitlements at runtime, see [Querying Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk). | ||
|
|
There was a problem hiding this comment.
This means that any changes to customer licenses are reflected in real time in the customer environment, without the customer needing to perform a license update.
I went back and forth on adding more details to this. For example, maybe we want to list the events that trigger the SDK API to poll the Vendor Portal, and/or explain more about how this works for KOTS installs that include the SDK
There was a problem hiding this comment.
I commented on this above actually. I think we should clarify that getting license updates with the SDK is dependent on how the vendor's app calls the SDK's API. If you never call it, the SDK has the latest info but your app doesn't.
It might be worth mentioning somewhere how often the SDK refreshes its data. We used to call the vendor portal on demand every time you asked the SDK for data. Now I don't even remember how often that is (every four hours or something, I don't know).
There was a problem hiding this comment.
Yeah Gerard had confirmed that it's four hours: https://replicated.slack.com/archives/C036BTS7JCE/p1725839954144509?thread_ts=1725651251.725129&cid=C036BTS7JCE
docs/vendor/licenses-about.mdx
Outdated
| You can make changes to a customer in the Vendor Portal to edit their license details, such as the license type or customer name, at any time. You can also add, remove, and edit license options and custom fields. The license ID, which is the unique identifier for the customer, never changes. | ||
|
|
||
| Unless the existing customer is using a community license, it is not possible to replace one license with another license without reinstalling the application. When you need to make changes to a customer's entitlements, Replicated recommends that you edit the customer's license details in the Vendor Portal, rather than issuing a new license. When you update the license in the Vendor Portal, the customer does not need to reinstall to get the updates. | ||
| When you make changes to a license in the Vendor Portal, the customer does not need to reinstall to get the updates. |
There was a problem hiding this comment.
This is only true with the SDK. With KOTS, you do have to deploy an update.
There was a problem hiding this comment.
I think this was trying to say you don't have to fully reinstall versus just deploying an update. But I think this sentence can probably just be deleted because I don't know if anyone was worried about having to totally reinstall the app to get a license update
docs/vendor/licenses-about.mdx
Outdated
|
|
||
| ### Air Gap License Updates with KOTS | ||
|
|
||
| To update licenses in air gap installations, customers need to upload the regenerated license file to the Admin Console. |
There was a problem hiding this comment.
Regenerated might be technically true, but I might just say the updated license file instead.
docs/vendor/licenses-about.mdx
Outdated
|
|
||
| ### Retrieving License Details with the SDK API | ||
|
|
||
| The [Replicated SDK](replicated-sdk-overview) includes an in-cluster API that retrieves up-to-date customer license information from the Vendor Portal during runtime through the [`license`](/reference/replicated-sdk-apis#license) endpoints. This means that any changes to customer licenses are reflected in real time in the customer environment, without the customer needing to perform a license update. |
There was a problem hiding this comment.
This could be clarified a bit. The SDK has the latest info available, but the vendor's app needs to call the SDK's endpoints to get that latest information. So it's not just like because the SDK is getting updated, that's reflected in the vendor's app. It all depends on how they use the SDK's license endpoints.
| The [Replicated SDK](replicated-sdk-overview) includes an in-cluster API that retrieves up-to-date customer license information from the Vendor Portal during runtime through the [`license`](/reference/replicated-sdk-apis#license) endpoints. This means that any changes to customer licenses are reflected in real time in the customer environment, without the customer needing to perform a license update. | ||
|
|
||
| For information about how to use the SDK API to query license entitlements at runtime, see [Querying Entitlements with the Replicated SDK API](/vendor/licenses-reference-sdk). | ||
|
|
There was a problem hiding this comment.
I commented on this above actually. I think we should clarify that getting license updates with the SDK is dependent on how the vendor's app calls the SDK's API. If you never call it, the SDK has the latest info but your app doesn't.
It might be worth mentioning somewhere how often the SDK refreshes its data. We used to call the vendor portal on demand every time you asked the SDK for data. Now I don't even remember how often that is (every four hours or something, I don't know).
docs/enterprise/updating-licenses.md
Outdated
| Click **Upload license** on the right side of the license pane and select the latest license from your machine. | ||
| To update licenses in air gap environments: | ||
|
|
||
| 1. Download the new license. Ensure that it is available on the air gapped machine where KOTS and the application are installed. |
There was a problem hiding this comment.
You'd actually want it on the machine where your browser is, since you're uploading it via browser.
Updated "About Customers" with more info about license updates in KOTS and getting license details from the Vendor Portal with the SDK API: https://deploy-preview-2630--replicated-docs.netlify.app/vendor/licenses-about#about-updating-licenses
Updated the screenshots in the existing docs on how to updates licenses from the Admin Console: https://deploy-preview-2630--replicated-docs.netlify.app/enterprise/updating-licenses