This chapter outlines the changes introduced in version 1.12 and provides a step-by-step guide  for upgrading from version 1.11.

Before You Upgrade

Back up your configuration

•Save the Process Manager, Storage, and Sync Service settings from the Admin Client to local files, just in case.

Remove the RabbitMQ PVC

Version 1.12 changes the RabbitMQ security context handling by introducing fsGroupChangePolicy: OnRootMismatch. If an existing RabbitMQ PVC is reused, RabbitMQ may fail to start because the persisted Erlang cookie was created with permissions that are incompatible with the new security context.

Cookie file /var/lib/rabbitmq/.erlang.cookie must be accessible by owner only.

To avoid this issue, RabbitMQ must be restarted with a fresh data directory.

Warning: Deleting the RabbitMQ PVC permanently removes all persisted RabbitMQ data, including queued messages. Before proceeding, ensure that all locate requests have completed and that no messages remain in the RabbitMQ queues.

The Network Locator Helm chart uses the fixed PVC name rabbitmq-data-claim. Delete the PVC before running the Helm upgrade:

kubectl scale statefulset network-locator-rabbitmq-statefulset --replicas=0 -n <NAMESPACE>
kubectl delete pvc rabbitmq-data-claim --namespace <NAMESPACE>

During the Helm upgrade, a new PVC is created automatically and RabbitMQ initializes a new Erlang cookie with permissions compatible with the updated security context

Back up your Locator-UI workflow (optional)

•The locator-UI workflow is automatically provisioned on every deployment, including upgrades.

•Any custom modifications you have made to the locator-UI workflow will be overwritten.

•Before upgrading, export and back up your current workflow.

•After the upgrade, manually re-apply your customizations on top of the updated workflow

Kubernetes Dashboard is replaced by Headlamp

If you did not use the Kubernetes Dashboard in the past you can ignore this section

•The Kubernetes Dashboard has been replaced with Headlamp because Kubernetes Dashboard is deprecated and no longer actively maintained.

•Headlamp provides a modern, actively maintained interface for managing and monitoring Kubernetes resources.

•If you have used the Kubernetes Dashboard previously through the locator helm chart you need to actively migrate to Headlamp.

•Headlamp is disabled by default and replaces the old Dashboard deployment.

•Steps to migrate to Headlamp:

1.Remove the old global.kubernetesDashboard configuration from values.yaml.

2.Enable Headlamp:

global:
 headlamp:
   enableDeployment: true

3.Configure the Headlamp OIDC client secret:

headlamp:
 image:
   registry: vertigisapps.azurecr.io/ghcr.io
 config:
   baseURL: "/dashboard-<RELEASE-NAME>"
 
kubernetes-dashboard-proxy:
 headlampOidc:
   # Generate a strong random secret. Helm uses this value for both the
   # Headlamp OAuth2 client in Keycloak and this proxy configuration.
   # Example: openssl rand 32
   clientSecret: <HEADLAMP_OIDC_CLIENT_SECRET>

4.After the helm upgrade Assign the headlamp role to authorized internal users in the network-locator-internal Keycloak realm.

Custom CA certificates (optional)

•Network Locator backend services can now trust certificates issued by a private or internal certificate authority.

•Create a Kubernetes Secret in the same namespace as the Network Locator deployment.

•The Secret must contain one or more PEM-encoded certificate files with the .crt extension:

kubectl create secret generic <CUSTOM-CA-SECRET-NAME> \
 --namespace <NAMESPACE> \
 --from-file=./cert1.crt \
 --from-file=./cert2.crt

Reference the Secret in your values.yaml file:

global:
 customCa:
   existingSecret: <CUSTOM-CA-SECRET-NAME>

•Network Locator combines all .crt files in the Secret into a trusted CA bundle when each supported backend pod starts.

•For more information, including how to update certificates, see Configure Custom CA Certificates.

Step by Step Upgrade Instructions

1.Make sure you have a valid connection to your kubernetes cluster

2.Login to the VertiGIS Container Registry

a.helm registry login vertigisapps.azurecr.io

3.Deploy version 1.12 using HELM.

helm upgrade <RELEASENAME> oci://vertigisapps.azurecr.io/network-locator/helm-chart \
   --namespace <NAMESPACE> \
   -f values.yaml \
   --wait \
    --version 1.12.0 \
    --timeout 30m0s \

After the Upgrade

Workflow changes (optional)

•Re-apply your workflow customizations as described above

Custom Mail and Document Templates

Network Locator does not automatically update existing mail or document templates during an upgrade. This prevents custom customer templates from being overwritten.

If you want Guardian-submitted requests to address the selected customer and provide the customer-specific download link (Download without login), compare your customized templates with the 1.12 default templates and merge the required changes manually. Refer to Templates Reference and Text Variables.

•external_user_data contains the selected customer's name, company, and address. Use it before user_data and retain a fallback to user_data for requests submitted directly by the user.

•external_download_url contains the customer-specific result link. Use it before download_url and retain a fallback to download_url.