LinearB's On-Premise Agent Installation Prerequisites Guide

This guide depicts all prerequisites for LinearB's On-Premise Agent installation

OS requirements

- Ubuntu 20.04 LTS

Sizing Requirements

• 32GB of memory available to the cluster - this will provide enough room to perform rolling service updates etc.
• 1TB of disk space

Software requirements

• kubectl
• helm
• Docker CE
• jq
• oras
• yq

Required ports

Make sure the following ports are open on the host you install the agent:

Kubernetes cluster permissions

Most of the agent lives inside its own namespace, but a default installation also creates a few resources that exist at the cluster level rather than inside a namespace. Whoever runs the installation needs permission to create them, or the installation stops with a forbidden error naming the resource.

If your cluster does not allow these, most can be avoided: create the namespace ahead of time and deploy.sh will use it, skip the bundled ingress controller, leave diagnostics disabled, and use a platform other than k3d. The PriorityClasses have their own setting, described next.

Turning off PriorityClasses alone does not make the installation namespace-only. If you are working under a blanket restriction on cluster-scoped resources, work through every row above.

Running without PriorityClasses

The agent creates four PriorityClasses and schedules its workloads with them, so operational jobs can take precedence over background collection when the cluster is busy.

PriorityClass is a cluster-scoped resource. Where the installer is not permitted to create one, turn the feature off rather than leave it on.

At install time this is safe to get wrong. If the installer cannot create the classes, Helm refuses before anything is applied and names the reason:

Error: INSTALLATION FAILED: priorityclasses.scheduling.k8s.io "linearb-critical" is forbidden:
User "..." cannot patch resource "priorityclasses" in API group "scheduling.k8s.io"
at the cluster scope

Nothing is created, there is no half-installed release, and the message tells you which setting to change. Re-run with the feature off and the installation completes normally.

After installation it is not. If the classes are removed later, or were created by someone else and then deleted, the failure is silent:

• Kubernetes resolves the name when a pod is admitted, not when its parent object is created. So the Deployment or Job stays healthy-looking while its pods are refused and the workload never runs.
• Pods already running are unaffected — they keep the priority they were admitted with. Only pods created afterwards are refused, so the problem can surface long after the change that caused it, on an unrelated restart or upgrade.

This second case is the one worth guarding against, and it is why the agent re-checks at runtime rather than only at installation.

To run without them, uncomment the priorityClasses block and the four minio, rabbitmq and redis keys in local-values.yaml (both are marked in local-values.yaml.template). Every pod is then scheduled at the cluster's default priority. Collection still runs. What is lost is ordering: the cluster no longer prefers one LinearB workload over another when resources are short.

If the switch is off but any of those four keys is still set, the deployment stops and names each one, rather than proceeding into the silent failure described above.

The agent also protects itself at runtime: before it places a priority on a collection job it checks that the class exists, and leaves it off if it does not. A job runs unprioritised rather than not at all. This is checked periodically, so a class removed after installation is picked up without a restart.

Egress FQDNs

Kubernetes

• on-prem-api.linearb.io
• <Git provider API endpoint>
• <Git provider HTTPS endpoint>
• api.datadoghq.com (Datadog agent monitoring and logging)
• linearb-data-lake.s3.amazonaws.com (Monitoring and logging)
• linearb-on-prem-dist.jfrog.io (Docker images)
• https://jfrog-prod-euc1-shared-frankfurt-main.s3.amazonaws.com/aol-linearb (Docker images and Helm charts download storage)

GitStream

• api.segment.io (Analytics purposes)
• public-api.linearb.io (Metrics purposes)

Installation Workspace:

LinearB APIs

• linearb.helpdocs.io
• api.linearb.io

Helm charts:

• https://linearb-on-prem-dist.jfrog.io
• https://jfrog-prod-euc1-shared-frankfurt-main.s3.amazonaws.com/aol-linearb (Docker images and Helm charts download storage)

Helm Charts and Docker Images Sources

The LinearB On-Premise Agent uses a combination of internal LinearB components and third-party dependencies:

Docker Images

All LinearB Docker images are hosted on JFrog Artifactory:

• Registry: linearb-on-prem-dist.jfrog.io/artifactory/on-prem-oci
• Authentication: Requires JFrog credentials (provided by LinearB Principal Solution Architect)

LinearB component images include:

• Core Services: agent-api, agent-cli, agent-poller, onprem-receiver, sensors
• Scheduler Components: scheduler, job-lifecycle-manager
• Job Processing: jobs-suite-dispatcher, jobs-suite-worker
• GitStream Components (when enabled): gs-webhook-consumer, gs-action-consumer, gs-rules-resolver
• Utility Services: forward-proxy, job-lifecycle-manager

The third-party images the agent depends on (ingress-nginx, MinIO, RabbitMQ, Redis, socat and the Datadog agent) are served from the same registry, under image-dependencies/. Your cluster only needs to reach this registry, or your own mirror of it (see Customizing Container Registry). It never pulls from Docker Hub, registry.k8s.io or other upstream registries.

Helm Chart Dependencies

The main on-prem-agent chart (located in helm/on-prem-agent) includes both internal and external dependencies:

Internal Charts (Local)

• libchart: Common templates and helpers
• infra: Infrastructure components and configurations
• All LinearB service charts (agent-api, sensors, scheduler, etc.)

Prerequisites for LinearB's On-Premise Agent Installation

Make sure you have the following from your LinearB Solution Architect:

• LinearB API Token
• LinearB Organization ID
• LinearB Admin Account ID
• JFrog Credentials
• DataDog API key (optional)

Download the deployment package

Each release is published as a zip file in LinearB's JFrog repository, https://linearb-on-prem-dist.jfrog.io/artifactory/on-prem-public/ (for example v5.0.5.zip). The package contains the installation scripts (deploy.sh, prerequisites.sh, set-up-k3d.sh), the local-values.yaml.template file, and these guides. The repository requires the JFrog credentials you received from LinearB.

Create a working directory for the installation and download the package into it. Use either the helper script or curl:

Option 1: helper script (latest version)

The linearb-agent.sh script finds the newest release, downloads it, and extracts it to opa-<version>/ next to the script.

mkdir linearb-agent && cd linearb-agent
read -p "JFrog user: " JFROG_USER && read -s -p "JFrog password: " JFROG_KEY && echo

curl -fL -u "$JFROG_USER:$JFROG_KEY" -O \
  https://linearb-on-prem-dist.jfrog.io/artifactory/on-prem-public/linearb-agent.sh
bash linearb-agent.sh -u "$JFROG_USER" -p "$JFROG_KEY"

Option 2: curl (specific version)

mkdir linearb-agent && cd linearb-agent
read -p "JFrog user: " JFROG_USER && read -s -p "JFrog password: " JFROG_KEY && echo

VERSION=v5.0.5
curl -fL -u "$JFROG_USER:$JFROG_KEY" -O \
  "https://linearb-on-prem-dist.jfrog.io/artifactory/on-prem-public/$VERSION.zip"
unzip "$VERSION.zip" -d "opa-$VERSION"

To list the available versions:

curl -fsS -u "$JFROG_USER:$JFROG_KEY" \
  https://linearb-on-prem-dist.jfrog.io/artifactory/api/storage/on-prem-public | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+\.zip' | sort -V

Either way you end up with this layout. local-values.yaml sits one level above the extracted package, so it stays in place when you download a newer version:

linearb-agent/
├── local-values.yaml      # created in the next step
└── opa-v5.0.5/
    ├── deploy.sh
    ├── prerequisites.sh
    ├── local-values.yaml.template
    └── ...

Configure the agent's required variables.

Create a file named local-values.yaml in the parent directory of the extracted package (in the example above, linearb-agent/)

 touch local-values.yaml

Copy the content of local-values.yaml.template to the designated local-values.yaml file.
Afterwards, fill out the required fields in the local-values.yaml file based on the values you received from the LinearB Solution Architect.

Run the command below to verify the configuration and that the software requirements are met.

./prerequisites.sh

Jira Fields Permissions

The following section is relevant only if a Jira integration is configured

When collecting issues as part of the Jira collection by default we query the fields specified below.
This is the mandatory fields list. It is imperative to make sure that the user whose credentials are used have access permissions for these fields:

• aggregateprogress
• aggregatetimeestimate
• aggregatetimeoriginalestimate
• aggregatetimespent
• assignee
• attachment
• comment
• components
• created
• creator
• description
• duedate
• environment
• fixVersions
• issuelinks
• issuerestriction
• issuetype
• labels
• lastViewed
• parent
• priority
• progress
• project
• reporter
• resolution
• resolutiondate
• security
• status
• statuscategorychangedate
• subtasks
• summary
• timeestimate
• timeoriginalestimate
• timespent
• updated
• versions
• votes
• watches
• worklog
• workratio

Selective fields list configuration

The list of queried issue fields is managed by LinearB per Jira integration, and the list above is the default.
To change it, contact LinearB support.
The JIRA_ISSUE_SELECTIVE_FIELDS field in local-values.yaml has been removed. If you customized it, send the value to LinearB support and confirm it has been configured for your integration before upgrading; the chart refuses to render while a customized value is still set.