Merge pull request #2630 from replicatedhq/sdk-license-updates

Clarify how licenses are updated with KOTS/SDK

Author: paigecalvert

docs/enterprise/updating-licenses.md

@@ -1,30 +1,87 @@
 # Updating Licenses
 
-You can check if there are any changes on your license using the License tab on the Replicated KOTS Admin Console.
+This topic describes how to update a license from the KOTS Admin Console.
 
 ## Update Online Licenses
 
-Click **Sync license** on the right side of the license pane to get the latest updates on your current license.
+To update licenses in online environments:
 
-![Online License](/images/online-license-tab.png)
+1. In the Admin Console, go to the **License** tab.
 
-- A **License is already up to date** note appears if no changes are detected.
-- A **License synced successfully** note appears when the changes are successfully applied.
+1. Click **Sync license** to get the latest updates.
+
+   ![Online License](/images/online-license-tab.png)
+
+   [View a larger version of this image](/images/online-license-tab.png)
+
+   :::note
+   If no changes are detected, a **License is already up to date** message appears.
+   :::
+
+   When the license is updated, KOTS makes a new version available that includes the license changes:
+
+   ![License updated successfully](/images/kots-license-update-message.png)
+
+   [View a larger version of this image](/images/kots-license-update-message.png)
+
+1. In the dialog, click **Go to new version** to navigate to the **Version history** page.
+
+1. On the **Version history** page, next to the new version labeled **License Change**, click **Deploy** then **Yes, deploy**.
+
+    ![Deploy license change](/images/kots-deploy-license-change.png)
+
+    [View a larger version of this image](/images/kots-deploy-license-change.png)
+
+    The version with the license change is then displayed as the currently deployed version, as shown below: 
+
+    ![Currently deployed version](/images/kots-license-change-currently-deployed.png)
+
+    [View a larger version of this image](/images/kots-license-change-currently-deployed.png)
 
 ## Update Air Gap Licenses
 
-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 machine where you can access a browser. 
+
+1. In the Admin Console, go to the **License** tab.
+
+1. Click **Upload license** and select the new license.
+
+   ![Airgap License](/images/airgap-license-tab.png)
+
+   [View a larger version of this image](/images/airgap-license-tab.png)
+
+   :::note
+   If no changes are detected, a **License is already up to date** message appears.
+   :::
+
+   When the license is updated, KOTS makes a new version available that includes the license changes:
+
+   ![License updated successfully](/images/kots-airgap-license-update-message.png)
+
+   [View a larger version of this image](/images/kots-airgap-license-update-message.png)
+
+1. In the dialog, click **Go to new version** to navigate to the **Version history** page.
+
+1. On the **Version history** page, next to the new version labeled **License Change**, click **Deploy** then **Yes, deploy**.
+
+    ![Deploy license change](/images/kots-deploy-license-change.png)
+
+    [View a larger version of this image](/images/kots-deploy-license-change.png)
+
+    The version with the license change is then displayed as the currently deployed version, as shown below: 
 
-![Airgap License](/images/airgap-license-tab.png)
+    ![Currently deployed version](/images/kots-license-change-currently-deployed.png)
 
-- A **License is already up to date** note appears if no changes are detected.
-- A **License uploaded successfully** note appears when the changes are successfully applied.
+    [View a larger version of this image](/images/kots-license-change-currently-deployed.png)
 
 ## Upgrade from a Community License
 
 If you have a community license, you can change your license by uploading a new one. This allows you to upgrade from a community version of the software without having to reinstall the Admin Console and the application.
 
 To change a community license to another license:
 
-1. In the License tab of the Admin Console, click **Change license**.
-1. In the dialog, upload the new license file that you received from your vendor.
+1. Download the new license.
+1. In the **License** tab of the Admin Console, click **Change license**.
+1. In the dialog, upload the new license file.

docs/vendor/licenses-about.mdx

@@ -43,19 +43,51 @@ Built-in fields are reserved field names. You can specify the values for these f
 
 You can also create custom license fields to define entitlements specific to the customer. For example, you can create a custom license field to limit the number of active users permitted. For more information about creating custom license fields, see [Managing Custom License Fields](licenses-adding-custom-fields).
 
-## About License Handling
+## About Updating Licenses
 
-This section describes the default behavior for handling license updates and expiration.
+This section includes information about making changes to customer licenses, including editing license details in the Vendor Portal as well as how customers can update or replace licenses.
 
-### Updating and Replacing Licenses
+### Editing License Details and Entitlements
 
-You can make changes to a customer in the Vendor Portal to edit their license details, including the license type or the customer name, at any time. The license ID, which is the unique identifier for the customer, never changes. For more information about how to edit customers, see [Edit a Customer](releases-creating-customer#edit-a-customer) in _Creating and Managing Customers_.
+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.
+For more information about how to edit licenses, see [Edit a Customer](releases-creating-customer#edit-a-customer) in _Creating and Managing Customers_.
+
+### License Updates with KOTS
+
+When you edit customer licenses for an application installed with KOTS, your customers can use the KOTS Admin Console to get the latest license details from the Vendor Portal, then deploy a new version that includes the license changes. Deploying a new version with the license changes ensures that any license fields that you have templated in your release using [KOTS template functions](/reference/template-functions-about) are rendered with the latest license details.
+
+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).
+* An application status changes. See [Current State](instance-insights-details#current-state) in _Instance Details_.
+
+For more information, see [Updating Licenses](/enterprise/updating-licenses).
+
+### Air Gap License Updates with KOTS
+
+To update licenses in air gap installations, customers need to upload the updated license file to the Admin Console.
+
+After you update the license fields in the Vendor Portal, you can notify customers by either sending them a new license file or instructing them to log into their Download Portal to downlaod the new license.
+
+For more information, see [Updating Licenses](/enterprise/updating-licenses).
+
+### Retrieving License Details with the SDK API
+
+The [Replicated SDK](replicated-sdk-overview) includes an in-cluster API that can be used to retrieve up-to-date customer license information from the Vendor Portal during runtime through the [`license`](/reference/replicated-sdk-apis#license) endpoints. This means that you can add logic to your application to get the latest license information without the customer needing to perform a license update. The SDK API polls the Vendor Portal for updated data every four hours.
+
+In KOTS installations that include the SDK, users need to update their licenses from the Admin Console as described in [License Updates with KOTS](#license-updates-with-kots) above. However, any logic in your application that uses the SDK API will update the user's license information without the customer needing to deploy a license update in the Admin Console.
+
+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).
+
+### Replacing Licenses
 
 Community licenses are the only license type that can be replaced with a new license without needing to reinstall the application. For more information, see [Community Licenses](licenses-about-types).
 
-### License Expiration Handling {#expiration}
+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.
+
+## About License Expiration Handling {#expiration}
 
 The built-in `expires_at` license field defines the expiration date for a customer license. When you set an expiration date in the Vendor Portal, the `expires_at` field is set to midnight UTC on the date selected.
 
@@ -66,19 +98,6 @@ Replicated enforces the following logic when a license expires:
 * Expired licenses cannot pull application images through the proxy service or from the Replicated registry.
 * (KOTS Only) KOTS prevents instances with expired licenses from receiving updates.
 
-### Synchronizing Licenses with KOTS
-
-When you edit customer licenses for an application installed with KOTS, your customers can use the admin console to update their license.
-
-For online instances, license updates are pulled from the Vendor Portal when:
-* An automatic or manual update check is performed by KOTS.
-* A customer selects **Sync license** in the admin console.
-* An application status changes. See [Current State](instance-insights-details#current-state) in _Instance Details_.
-
-For air gap instances, because air gap licenses are signed with the updated fields, customers must upload a regenerated license file to the admin console every time you modify license fields. After you update the license fields in the Vendor Portal, you can notify customers by either sending them a new license file or instructing them to log into their download portal to retrieve the updated license. Then, they can click **Upload license** on the **License** tab of the admin console to upload the new license file.
-
-For more information, see [Updating Licenses](/enterprise/updating-licenses).
-
 ## About Customer Channel Assignment {#channel-assignment}
 
 This section provides information about managing the channel a customer is assigned, including changing the assigned channel and manaing channel assignments for customers with or without the KOTS entitlement. For information about how to assign a customer to a channel, see [Create a Customer](releases-creating-customer#create-a-customer) in _Creating and Managing Customers_.
@@ -87,9 +106,9 @@ This section provides information about managing the channel a customer is assig
 
 <ChangeChannel/>
 
-For example, if the latest release promoted to the Beta channel is version 1.25.0 and version 1.10.0 is marked as required, when you edit an existing customer to assign them to the Beta channel, then the Replicated admin console always fetches 1.25.0, even though 1.10.0 is marked as required. The required release 1.10.0 is ignored and is not available to the customer for upgrade.
+For example, if the latest release promoted to the Beta channel is version 1.25.0 and version 1.10.0 is marked as required, when you edit an existing customer to assign them to the Beta channel, then the KOTS Admin Console always fetches 1.25.0, even though 1.10.0 is marked as required. The required release 1.10.0 is ignored and is not available to the customer for upgrade.
 
-For more information about how to mark a release as required, see [Properties](releases-about#properties) in _About Channels and Releases_. For more information about how to synchronize licenses in the admin console, see [Updating Licenses](/enterprise/updating-licenses).
+For more information about how to mark a release as required, see [Properties](releases-about#properties) in _About Channels and Releases_. For more information about how to synchronize licenses in the Admin Console, see [Updating Licenses](/enterprise/updating-licenses).
 
 ### Assigning KOTS and Helm-Only Customers
 
@@ -165,7 +184,7 @@ From the **Manage customer** page, you can view and edit the customer's license
 
 ### Support Bundles Page
 
-The **Support bundles** page for a customer displays details about the support bundles collected from the customer. Customers with the **Support Bundle Upload Enabled** entitlement can provide support bundles through the Replicated admin console, or you can upload support bundles manually in the Vendor Portal by going to **Troubleshoot > Upload a support bundle**. For more information about uploading and analyzing support bundles, see [Inspecting Support Bundles](support-inspecting-support-bundles).
+The **Support bundles** page for a customer displays details about the support bundles collected from the customer. Customers with the **Support Bundle Upload Enabled** entitlement can provide support bundles through the KOTS Admin Console, or you can upload support bundles manually in the Vendor Portal by going to **Troubleshoot > Upload a support bundle**. For more information about uploading and analyzing support bundles, see [Inspecting Support Bundles](support-inspecting-support-bundles).
 
 The following shows an example of the **Support bundles** page:
 

docs/vendor/licenses-reference-sdk.mdx

@@ -6,7 +6,7 @@ This topic describes how to query license entitlements at runtime using the Repl
 
 The Replicated SDK retrieves up-to-date customer license information from the Vendor Portal during runtime. This means that any changes to customer licenses are reflected in real time in the customer environment. For example, you can revoke access to your application when a license expires, expose additional product functionality dynamically based on entitlements, and more. For more information about distributing the SDK with your application, see [About the Replicated SDK](replicated-sdk-overview).
 
-After the Replicated SDK is initialized and running in a customer environment, you can use the following SDK API endpoints to get information about the license that was used to install:
+After the Replicated SDK is initialized and running in a customer environment, you can use the following SDK API endpoints to get information about the license:
 * `/api/v1/license/info`: List license details, including the license ID, the channel the customer is assigned, and the license type.
 * `/api/v1/license/fields`: List all the fields in the license.  
 * `/api/v1/license/fields/{field_name}`: List details about a specific license field, including the field name, description, type, and the value.