LinearB On-Prem Agent v4 Upgrade Guide

This guide outlines the steps to upgrade the LinearB On-Prem Agent to version 4.x.x. The process includes backing up and restoring critical data, updating configurations, and deploying the updated version of the agent.

New in Version 4.1.8

In version 4.1.8 the default resource requests and limits were increased for some of the On-Prem Agent services. Please refer to the prerequisites for the recommended minimal cluster size. On clusters with less than 32GB of available memory might fail to upgrade in place as both old and new versions of each service need to be up at the same time.

MinIO update strategy migration (Argo CD with ServerSideApply only)

The chart's MinIO Deployment uses Recreate as its update strategy (minio.deploymentUpdate.type: Recreate). For most upgrade paths this is a routine change — helm upgrade correctly removes the previous strategy.rollingUpdate fields via its three-way strategic-merge.

Argo CD with ServerSideApply (SSA) is an exception. SSA preserves fields that are not in the new apply set (so stale strategy.rollingUpdate.maxSurge etc. stay on the live object owned by the original field manager). The API server then rejects the upgrade:

Deployment.apps "<release>-minio" is invalid: spec.strategy.rollingUpdate:
Forbidden: may not be specified when strategy `type` is 'Recreate'

For Argo CD + SSA users, the chart ships an opt-in pre-upgrade Job (minio-strategy-migrator) that handles this transition automatically. Enable it once on the upgrading release:

infra:
  minio:
    strategyMigrator:
      enabled: true

It checks the live MinIO Deployment's strategy.type and, if it is still RollingUpdate, deletes the Deployment so the next Argo sync can recreate it. PVC minio-pvc is annotated with helm.sh/resource-policy: keep, so MinIO data is preserved.

If you prefer a manual one-time cleanup instead:

kubectl delete deploy <release>-minio -n <namespace>

Or keep your release on RollingUpdate:

minio:
  deploymentUpdate:
    type: RollingUpdate

When infra.minio.strategyMigrator.enabled: true and the live strategy already matches Recreate, the hook short-circuits (logs "live strategy=Recreate matches chart — nothing to do" and exits 0).

Prerequisites

Before starting the upgrade, ensure you have the following:

• Access to the Kubernetes cluster with the LinearB On-Prem Agent deployed.
• kubectl installed and configured.
• Permissions to manage Kubernetes resources.

- Review README-prerequisites.md to ensure your environment meets the requirements for the LinearB On-Prem Agent.

Upgrade Process

In order to upgrade the agent from an existing installation to version 4.x.x, follow these steps:

1. Backup the file that holds all the integrations and sensitive keys which resides in the MinIO pod (the file named db.json)
2. Make sure you are in the correct context and namespace where the LinearB On-Prem Agent is deployed. For example:

   kubectl config use-context k3d-linearb-onprem-739552390
   

./backup_restore_db_json.sh --backup

Afterwards, please verify that the file was created in the current directory and that it contains the necessary data.

In case you were using k8s native secrets to store integration information (INTEGRATIONS_STORAGE_BACKEND=secrets), please keep the contents using this command:

# Get the actual secret
kubectl get secret integrations -n linearb
# Remove the protective null finalizer:
kubectl patch secret integrations -n linearb -p '{"metadata":{"finalizers":null}}' --type=merge

1. Delete the existing LinearB On-Prem Agent namespace:

kubectl delete namespace linearb

1. Migrate existing local-values.yaml to new format:

   cp local-values.yaml local-values.yaml.v3
   cp public/local-values.yaml.template local-values.yaml
   yq -i '(.global) *= load("local-values.yaml.v3").image.env.chartValues' local-values.yaml 
   

   Notes:

2. As datadog is now managed by the on-prem-agent chart, please make sure you also update the datadog-agent section in local-values.yaml which is commented by default in local-values.yaml.template .

3. In case you have JFROG_HOST set, please change it to "linearb-on-prem-dist.jfrog.io/artifactory/on-prem-oci" as this is the default registry for helm and docker.

4. In OPA v3, local-values.yaml is used as input for all of the helm releases which the OPA consists of. In case you don't have local-values.yaml, you can get the effective values in your current cluster by running:

   helm get values infra -n linearb
   

   You should get all the relevant values.

5. Migrate services requests and limits: In OPA v3, services requests and limits were optionally supplied by local-values-.yaml in the following format:

resources:
  limits:
    cpu: 150m
    memory: 128Mi
  requests:
    cpu: 100m
    memory: 128Mi 

• In OPA v3, you could also change the resources configurations for the batch pods that scheduler-worker, scheduler-sensors-worker scheduler-pm-worker by creating local-values-.yaml With the content: image: env: chartValuesV2:
  • name: WORKER_REQUEST_CPU value: "400m"
  • name: WORKER_REQUEST_MEMORY value: "100Mi"
  • name: WORKER_LIMIT_CPU value: "1000"
  • name: WORKER_LIMIT_MEMORY value: "1000"

This can now be achieved by appending this to local-values.yaml:

  scheduler-sensors-worker:
    image:
      env:
        plain:
          - name: WORKER_REQUEST_CPU
            value: "400m"
          - name: WORKER_REQUEST_MEMORY
            value: "200Mi"
          - name: WORKER_LIMIT_CPU
            value: "1000m"
          - name: WORKER_LIMIT_MEMORY
            value: "500Mi"

• Migrate custom root certificates: Custom root certificate were placed in ~/linearb-onprem/deploy/certs . Now they are a part of the input for the on-prem-agent in .global.CUSTOM_SSL_CERT path, enter it as a multiline yaml starting with |-

• Ingress configuration (New in v4.0.11+): Starting from v4.0.11, ingress configuration has been significantly enhanced with the following new features:

• Controller installation control: Use global.ingress.installController or ingress.installController to control whether the ingress-nginx controller is installed
• Chart-specific override: Use onprem-receiver.ingress.enabled to override the global RECEIVER_INGRESS setting
• Multi-host support: Configure single or multiple hostnames for your ingress
• TLS configuration: Secure your ingress with TLS certificates
• Existing controller support: Set installController: false to use an existing ingress controller in your namespace

The global.RECEIVER_INGRESS flag is still supported for backward compatibility. For detailed configuration examples and advanced scenarios, refer to Ingress Usage Scenarios.

1. Deploy the version 4.x.x of the LinearB On-Prem Agent - Please refer to the Agent Installation Guide [README-deploy.md]. If installing on the same cluster, it is advisable to install on a new name space.

2. Once the deployment is complete and all pods are in a running state, restore the backup data by running the following command:

   ./backup_restore_db_json.sh --restore
   

   If you were using secrets as a backend, please create the integrations secret mentioned in step 1 manually in the new namespace after deployment.

3. To ensure that the integrations’ data has been restored successfully, run the following command:

   kubectl exec -it $(kubectl get pod  -n linearb -l app.kubernetes.io/name=agent-cli -o jsonpath="{.items[0].metadata.name}") -- python agent-cli.py list-integrations
   

   Note: If the namespace differs from the default linearb, replace linearb in the above command with the appropriate namespace. In the output you should see the list of integrations you have seen in the previous version.