How to Update or Replace Your Jama Connect® Application License (Self-Hosted / KOTS)

Published Date: December 5, 2023
Audience: Everyone
Products and Versions Covered:

• Jama Connect® version(s) - All Supported Versions
  • Self-hosted 
    • Replicated KOTS

Summary

This article explains how to update or replace the Jama Connect® application license in a self-hosted KOTS (Kubernetes Off-The-Shelf) environment.

This process applies only to existing Jama Connect installations where a license is being changed, renewed, or replaced.

For new installations, the license application is part of the standard KOTS installation workflow. During initial setup, the installer will prompt you to upload a valid license file, and no additional steps are required beyond the install process.

In some cases, license updates may not be correctly associated with the deployed application version. When this occurs, a manual update is required to ensure the new license is applied correctly.

This article also explains both:

• The standard license update process through the KOTS Admin Console
• The manual update process when the license change sequence is associated with a different application version.

Resolution

Standard License Update Process

1. In the KOTS Admin Console, click Sync License from the dashboard. 
   
2. Confirm that a new sequence is created with the updated license:
3. Alternatively, you can run:Alternatively, you can run:
   • In the above example, sequence 6 is currently deployed. The process of 'syncing' the license creates a new configuration sequence, which must be deployed before any changes take place in the application.

   • kubectl kots get versions jama-k8s

   •        
   • 
4. You must deploy the updated sequence to apply the license change.

For more details, refer to:
https://docs.replicated.com/enterprise/updating-licenses

Manual License Update Process

After syncing the license, if you see that the newly created sequence is on a different application version, you will need to use the following workflow.

Step 1: Verify KOTS Version

kubectl kots version

Step 2: Verify Installed Application

kubectl kots get apps

Example output:

SLUG        STATUS   VERSION
jama-k8s    ready     9.17.3

Step 3: Verify Version History

kubectl kots get versions jama-k8s
VERSION    SEQUENCE    STATUS      SOURCE             CHANNEL ID                     CHANNEL SEQUENCE
9.35.2     19          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     18          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     17          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     16          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     14          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     13          pending     License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.2     3           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    43
9.35.1     4           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    42
9.28.3     5           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    41
9.28.2     6           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    37
9.28.1     7           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    36
9.22.4     8           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    40
9.22.3     9           pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    35
9.22.1     10          pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    33
9.17.3     20          deployed    Config Change      1kUIR8rwKEGe7rk5U7bhiDbd4dQ    39
9.17.3     15          pending     Config Change      1kUIR8rwKEGe7rk5U7bhiDbd4dQ    39
9.17.3     12          pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    39
9.17.3     11          pending     Upstream Update    1kUIR8rwKEGe7rk5U7bhiDbd4dQ    38
9.17.3     2           deployed    License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    39
9.17.3     1           deployed    License Change     1kUIR8rwKEGe7rk5U7bhiDbd4dQ    39

Step 4: Export Current Configuration

For KOTS version v1.108.0 or later:

kubectl kots get config jama-k8s -n default --current --decrypt > config.yaml

For earlier versions, specify the deployed sequence:

kubectl kots get config jama-k8s -n default --sequence=<SEQUENCE_NUMBER> --decrypt > config.yaml

Step 5: Remove Existing Application

kubectl kots remove jama-k8s -n default -f

Step 6: Prepare License File

• Copy your .yaml license file to the application server

Step 6: Reinstall Application with Updated License

kubectl kots install jama-k8s/standardkots \
--app-version-label=<JAMA_APP_VERSION> \
--license-file /path/to/your/license.yaml \
--namespace default \
--config-values /path/to/your/config.yaml

Example:

kubectl kots install jama-k8s/standardkots \
--app-version-label=9.17.3 \
--license-file /home/jama/K8-Customer-ABC123-prod.yaml \
--namespace default \
--config-values /home/jama/config.yaml

The screenshot below demonstrates a successful operation. After that, the KOTS Admin Console should be available with the new license and config restored.

Airgap Environments

Follow the same overall process but additionally include the airgap bundle in the re-installation command:

kubectl kots install jama-k8s/standardkots \
--airgap-bundle /path/to/jama.airgap \
--app-version-label=<JAMA_APP_VERSION> \
--license-file /path/to/your/license.yaml \
--namespace default \
--config-values /path/to/your/config.yaml

Step 7: Disable Automatic Updates (Recommended)

In the KOTS Admin Console:

• Navigate to Dashboard
• Select Configure automatic updates
• Set:
  Do not automatically deploy new versions
  

And set the "Automatically deploy new versions" setting to "Do not automatically deploy new versions".

Troubleshooting

Error: 

failed to forward port: failed to query healthz

Resolution
Create an SSH tunnel:

ssh -L 8800:<SERVER IP>:8800 <USER>@localhost

Post-Update Issues

• Tenant errors (e.g., "tenant is closed")
  → Follow: KOTS - Reset tenant state
• License validation errors
  → Follow: Failed License Upload During KOTS Install

If, after manually updating the license, you run into an error where the application returns an error page stating the "tenant is closed" or "tenant does not exist" then please follow the steps in KOTS - Reset tenant state.

If you run into an error validating the installation, please follow the steps in Failed License Upload During KOTS Install

Additional Resources

• Replicated KOTS Release Notes v1.108.0
• Replicated KOTS - kots cli - install
• Replicated KOTS - Updating Licenses
• Success Programs
• Success Catalog
• Datasheets
• Request a Solution Offering or Training from the Success Catalog

Feedback:
We welcome your input! Please sign in to leave any comments, suggestions, or ideas for improvement below.