Installing and upgrading

Amanda Jennewein
Amanda Jennewein
  • Updated

Complete these tasks to install and upgrade Jama Connect in an internet or airgap environment.

Install Jama Connect in an existing Kubernetes cluster (internet)

Use this workflow to install Jama Connect in an existing Kubernetes environment, including the required configuration steps and access to the Docker images needed for deployment.

Our Docker registry URL is https://registry.jamasoftware.net/docker. 

To install Jama Connect in an internet environment:

1. Store the Artifactory credentials in a Kubernetes-Native secret by running the following command. Replace <username> and <password> with your credentials.

kubectl create secret docker-registry jama-registry-creds \
--docker-server='https://registry.jamasoftware.net/docker' \
--docker-username='<username>' \
--docker-password='<password>' \
-n jama-connect

    If running OpenShift, use oc instead of kubectl.

2. Create values.yaml file (see Appendix A: Configuring the Helm chart).

3. Install the Helm chart:

a. Run the following command to log into our Helm registry.

helm registry login oci://registry.jamasoftware.net/helm/jama-connect

b. At the prompt, enter your Artifactory credentials for username and password.

c. Replace <version> with the Jama Connect version chosen and run the following command to install it:

helm install jama-connect oci://registry.jamasoftware.net/helm/jama-
connect -f values.yaml -n jama-connect --version <version>

d. During the installation, a random password is generated for the Jama Connect root user. Once the installation finishes, a command to retrieve the password will be displayed. If required, the command can be displayed again by running:

helm get notes jama-connect -n jama-connect

If you used a pre-populated database to configure a dataset, the password is the same as in the source Jama Connect instance.

e. Monitor the pods until they are running:

kubectl get pods -n jama-connect

f. Validate application access through the configured Jama Connect URL. While provisioning is in progress, the application might display a message that the tenant does not exist or is closed.

g. Continue with the “after installation” instructions if you prepared a dataset.

If you prepared a dataset, continue with one of these tasks:

Install Jama Connect in an existing Kubernetes cluster (airgap)

Use this workflow to install Jama Connect in an existing Kubernetes cluster in an airgap environment.

To install Jama Connect in an airgap environment:

1. Store registry credentials in a Kubernetes-Native secret with the following command, replacing  <registry>, <username>, and <password> with the URL and credentials required to access the registry:

kubectl create secret docker-registry jama-registry-creds \
--docker-server='<registry>' \
--docker-username='<username>' \
--docker-password='<password>' \
-n jama-connect

    If running OpenShift, use oc instead of kubectl.

2. Create values.yaml file (see Appendix A: Configuring the Helm chart).

3. Install the Helm chart:

a. Run the following command after replacing <version> to install the local Helm chart tgz file.

helm install jama-connect jama-connect-<version>.tgz -f values.yaml
-n jama-connect

During the installation, a random password is generated for the Jama Connect root user. Once the installation finishes, a command to retrieve the password is displayed. If required, the command can be displayed again by running:

helm get notes jama-connect -n jama-connect

If you used a pre-populated database to configure a dataset, the password is the same as in the source
Jama Connect instance. 

b. Monitor the pods until they are running:

kubectl get pods -n jama-connect

c. Validate application access through the configured Jama Connect URL. During provisioning, the application might display a message indicating that the tenant does not exist or is closed.

If you prepared a dataset, continue with one of these tasks:

Post-installation setup

Once the new instance is up and running, you must finish setting up your instance with the dataset.

Follow the instructions for the type of dataset you configured:

Complete your installation for the dataset with a pre-populated database

Once the new instance is up and running, perform the following steps to complete setup with the dataset.

To complete your instance setup with the dataset:

1. Set an environment variable with your tenant name, which is used by subsequent commands.

export TENANT_NAME=jama

2. Restore the tenant assets from the assets.tar.gz that was generated previously:

kubectl get pods -n jama-connect -l app.kubernetes.io/name=core -o json
path='{.items[0].metadata.name}' | \
xargs -r -I{} sh -c 'kubectl exec -n jama-connect -i -c core {} -- tar
-xzvf - -C /home/contour/tenant/${TENANT_NAME} \
< ./assets.tar.gz'

3. Update the application’s base URL to match the information assigned to the instance via the global.url Helm value:

a. Log in as root.

b. Select the Organizations tab.

c. Select Change URL.

d. Monitor the logs until you see Completed URL update.

kubectl logs -n jama-connect -l app.kubernetes.io/name=core -c core
--prefix=true -f

4. If you want to use SAML on the new instance with a different configuration from the previous instance, reconfigure SAML authentication.

5. Perform a full reindex:

a. Log in as root.

b. Select the Index/Search tab.

c. Select Index Items.

Your instance setup with a dataset for a pre-populated database is now complete.

Complete your installation for the dataset with a .jama backup file

Once the new instance is up and running, perform the following steps to complete setup with the dataset.

To complete your instance setup with the dataset:

1. If you want to use SAML on the new instance with a different configuration from the previous one, enable SAML on the new instance. It is disabled by default.

2. Set core.tenant-manager.application.env.RESTORE_BACKUP_FILE to an empty string so that the core pod unmounts the hostPath volume.

3. If using global.core.enableHorizontalScaling: true, set core.replicaCounts.jobs: 3 to have multiple core-jobs now that the .jama backup file has been restored.

4. Run a Helm upgrade to apply the value changes, if needed. 

5. Delete the /data/restore directory from the node(s) because it is no longer required.

Your instance setup using a dataset created with a .jama backup file is now complete.

Upgrade Jama Connect (internet)

Use this workflow to upgrade Jama Connect in an internet Kubernetes environment.

Important considerations

  • Values file used by the current Helm release, plus any changes required for the target version. Current values can be retrieved by running:
helm get values jama-connect -n jama-connect -o yaml
  • You have planned a maintenance window since upgrades require downtime.

To upgrade Jama Connect (internet):

1. For a dry run, execute the command, replacing <version> with the target Jama Connect version:

helm upgrade jama-connect oci://registry.jamasoftware.net/helm/jama-con
nect \
-n jama-connect \
-f values.yaml \
--version <version> \
--dry-run

2. If there are no errors, execute the same Helm upgrade command without the --dry-run parameter.

helm upgrade jama-connect oci://registry.jamasoftware.net/helm/jama-con
nect \
-n jama-connect \
-f values.yaml \
--version <version> \

3. Monitor the pods until they are running:

kubectl get pods -n jama-connect

4. Use the configured Jama Connect URL to validate access to the application.

The application might display a message that the tenant is being upgraded.

Upgrade Jama Connect (airgap)

Use this workflow to upgrade Jama Connect in an airgap Kubernetes environment.

Important considerations

  • Values file used by the current Helm release, plus any changes required for the target version. Current values can be retrieved by running:
helm get values jama-connect -n jama-connect -o yaml
  • You have planned a maintenance window since upgrades require downtime.
  • For airgap environments, you must prepare airgap artifacts.

To upgrade Jama Connect (airgap):

1. For a dry run, install the local Helm chart tgz file with this command, replacing <version> with the target Jama Connect version:

helm upgrade jama-connect jama-connect-<version>.tgz -f values.yaml -n
jama-connect --dry-run

2. If there are no errors, execute the same Helm upgrade command without the --dry-run parameter.

helm upgrade jama-connect jama-connect-<version>.tgz -f values.yaml -n
jama-connect

3. Monitor the pods until they are running:

kubectl get pods -n jama-connect

4. Use the configured Jama Connect URL to validate access to the application.

The application might show a message saying that the tenant is being upgraded.

Troubleshooting installation and upgrades

Use this information to troubleshoot any issues when you install or upgrade Jama Connect.

VERIFY PREFLIGHT CHECKS

  • Before installing or upgrading Jama Connect, our Helm chart verifies that the database server is accessible with the provided credentials.
  • If installation or upgrade failed with an error similar to:

Error: INSTALLATION FAILED: failed pre-install: 1 error occurred:

* job connect-preflight failed: BackoffLimitExceeded

  • Run the following command to check for errors in the preflight checks:
kubectl logs -l app.kubernetes.io/name=connect-preflight --all-containe
rs=true -n jama-connect

CREATE SUPPORT BUNDLE

Use these scripts in this GitHub repository to collect diagnostic information when troubleshooting.

In This Section

 

 

 

 

 

 

 

Related to

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.