LinearB On-Prem Agent - Ingress Usage Scenarios

This guide covers different ingress configuration scenarios for the LinearB On-Prem Agent (v4.0.11+).

Overview

Starting from version 4.0.11, the LinearB On-Prem Agent provides flexible ingress configuration options to support various deployment scenarios:

Install ingress controller with the agent (default behavior)
Use an existing ingress controller in your namespace
Disable ingress entirely and use LoadBalancer service
Multi-host configuration with single or multiple hostnames
TLS/HTTPS configuration with certificate management
Chart-specific ingress override for granular control per subchart

The global.RECEIVER_INGRESS flag is still supported for backward compatibility with existing installations.

Configuration Options

Ingress Configuration Parameters

Add these parameters to your local-values.yaml file:

global:
  # Legacy flag (still supported for backward compatibility)
  # Controls both ingress controller installation and Ingress resource creation
  RECEIVER_INGRESS: true|false

  # Global ingress control (new in v4.0.11+)
  ingress:
    # Whether to install the ingress-nginx controller
    # Condition priority: ingress.installController > global.ingress.installController > global.RECEIVER_INGRESS
    installController: true|false

ingress:
  # Input for optional ingress-nginx chart

  controller:
    # IngressClass name that the controller watches
    ingressClass: "linearb-opa-ingress-class"

    ingressClassResource:
      # IngressClass resource name to create
      name: "linearb-opa-ingress-class"

onprem-receiver:
  ingress:
    # Whether to create Ingress resource for onprem-receiver
    # Priority: global.RECEIVER_INGRESS (if defined) > onprem-receiver.ingress.enabled
    enabled: true|false

    # IngressClass name for the Ingress resource (spec.ingressClassName)
    # Falls back to controller.ingressClass if not specified
    className: "linearb-opa-ingress-class"

Usage Scenarios

Scenario 1: Default Installation (Install Ingress Controller)

Use case: You don't have an ingress controller in your namespace and want the agent to install one.

Configuration:

global:
  RECEIVER_INGRESS: "true"  # Legacy flag (still supported)
  # ... other global settings

Or using the new parameters (v4.0.11+):

global:
  ingress:
    installController: true  # Install ingress-nginx controller
  # ... other global settings

ingress:
  installController: true  # Can also be set here (takes priority over global)
  controller:
    ingressClass: "linearb-opa-ingress-class"
    ingressClassResource:
      name: "linearb-opa-ingress-class"

onprem-receiver:
  ingress:
    enabled: true
    className: "linearb-opa-ingress-class"

What happens: - The agent installs ingress-nginx controller in your namespace - The controller watches for Ingress resources with ingressClassName: "linearb-opa-ingress-class" - Creates an Ingress resource for the onprem-receiver service with the specified className - Service type is set to ClusterIP

Scenario 2: Use Existing Ingress Controller

Use case: Your cluster or namespace already has an ingress controller installed, and you want to use it instead of installing a new one.

Configuration:

global:
  RECEIVER_INGRESS: "true"  # Enable Ingress resource creation
  ingress:
    installController: false  # Don't install ingress-nginx controller
  # ... other global settings

ingress:
  installController: false  # Don't install ingress-nginx controller (takes priority over global)

onprem-receiver:
  ingress:
    enabled: true
    className: "nginx"  # Or your existing ingress class name (e.g., "traefik", "haproxy")

What happens: - The agent does NOT install a new ingress controller - Creates an Ingress resource for the onprem-receiver service with ingressClassName: "nginx" - The existing ingress controller in your namespace handles the traffic based on the className - Service type is set to ClusterIP

Important notes: - Make sure your existing ingress controller is configured to watch the namespace where the agent is deployed - Update className to match your existing ingress controller's IngressClass name - If using a non-nginx ingress controller, you may need to adjust ingress annotations in helm/onprem-receiver/values.yaml

Scenario 3: Disable Ingress (Use LoadBalancer)

Use case: You don't want to use ingress and prefer to expose the service via LoadBalancer or NodePort.

Configuration:

global:
  RECEIVER_INGRESS: "false"  # Legacy flag (still supported)
  # ... other global settings

Or using the new parameters:

global:
  ingress:
    installController: false  # Don't install ingress controller
  # ... other global settings

onprem-receiver:
  ingress:
    enabled: false  # Don't create Ingress resource

What happens: - No ingress controller is installed - No Ingress resource is created for onprem-receiver - Service type is set to LoadBalancer

Scenario 4: Multi-Host Configuration

Use case: You want to expose the onprem-receiver service on multiple hostnames (e.g., for different domains or environments).

Configuration:

global:
  RECEIVER_INGRESS: "true"
  ingress:
    installController: true  # Install ingress controller (or false if using existing)

onprem-receiver:
  ingress:
    enabled: true
    className: "linearb-opa-ingress-class"
    hosts:
      # Option 1: Single host
      - host: "on-prem-api.example.com"
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: on-prem-agent-onprem-receiver

      # Option 2: Multiple hosts
      # - host: "on-prem-api.example.org"
      #   paths:
      #     - path: /
      #       pathType: Prefix
      #       backend:
      #         service:
      #           name: on-prem-agent-onprem-receiver

      # Option 3: No host specified (accepts all hosts)
      # - paths:
      #     - path: /
      #       pathType: Prefix
      #       backend:
      #         service:
      #           name: on-prem-agent-onprem-receiver

What happens: - Ingress routes traffic from specified host(s) to the onprem-receiver service - You can define multiple hosts with different paths - If no host is specified, the ingress accepts all hosts (default behavior)

Scenario 5: TLS/HTTPS Configuration

Use case: You want to secure your ingress with TLS certificates.

Configuration:

global:
  RECEIVER_INGRESS: "true"
  ingress:
    installController: true  # Install ingress controller (or false if using existing)

onprem-receiver:
  ingress:
    enabled: true
    className: "linearb-opa-ingress-class"
    hosts:
      - host: "on-prem-api.example.com"
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: on-prem-agent-onprem-receiver

    # TLS configuration
    tls:
      - hosts:
          - "on-prem-api.example.com"
        secretName: on-prem-tls

      # Multiple certificates for multiple hosts
      # - hosts:
      #     - "on-prem-api.example.org"
      #   secretName: on-prem-tls-org

What happens: - Ingress terminates TLS using the certificate from the specified Kubernetes secret - The secret must exist in the same namespace as the ingress - Multiple TLS configurations can reference different secrets for different hosts

Creating the TLS secret:

# Create TLS secret from certificate files
kubectl create secret tls on-prem-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key \
  -n linearb

# Or for cert-manager (automatic certificate provisioning)
# Create a Certificate resource that references your Issuer

Scenario 6: Chart-Specific Ingress Override

Use case: You want to control ingress at the subchart level when global.RECEIVER_INGRESS is not set.

Configuration:

# Option 1: Enable ingress via subchart setting (when RECEIVER_INGRESS is not set)
global:
  # RECEIVER_INGRESS is not defined
  ingress:
    installController: true  # Install ingress controller

onprem-receiver:
  ingress:
    enabled: true  # Enable ingress for this chart
    className: "linearb-opa-ingress-class"

Or:

# Option 2: Disable ingress via subchart setting (when RECEIVER_INGRESS is not set)
global:
  # RECEIVER_INGRESS is not defined
  ingress:
    installController: false  # Don't install ingress controller

onprem-receiver:
  ingress:
    enabled: false  # Disable ingress for this chart

What happens: - When global.RECEIVER_INGRESS is not defined, the onprem-receiver.ingress.enabled setting controls ingress creation - If you do set global.RECEIVER_INGRESS, it will take precedence over the subchart setting

Priority order: - For Ingress resource creation: global.RECEIVER_INGRESS (if defined) > onprem-receiver.ingress.enabled - For controller installation: ingress.installController > global.ingress.installController > global.RECEIVER_INGRESS

Backward Compatibility

Automatic className Detection on Upgrade

Starting from v4.0.11, the agent automatically detects and preserves the existing ingress className during upgrades:

On upgrade: If an existing Ingress resource with className: "nginx" is found, it will be automatically preserved
On fresh install: New installations will use className: "linearb-opa-ingress-class" by default

This means you can upgrade from v4.0.10 or earlier without any configuration changes, and your existing ingress will continue to work.

Legacy RECEIVER_INGRESS Flag

The legacy global.RECEIVER_INGRESS flag is fully supported for backward compatibility:

RECEIVER_INGRESS	Behavior
`"true"`	Installs ingress controller + creates Ingress
`"false"`	No ingress controller, uses LoadBalancer service

If global.RECEIVER_INGRESS is defined, it takes precedence over onprem-receiver.ingress.enabled. To use subchart-level control, leave global.RECEIVER_INGRESS undefined.

Migration Examples

Migrating from global.RECEIVER_INGRESS to new parameters

Before (v4.0.10 and earlier):

global:
  RECEIVER_INGRESS: "true"

After (v4.0.11+, no changes needed):

global:
  RECEIVER_INGRESS: "true"  # Keep this - className "nginx" will be auto-detected and preserved

# Or explicitly use new parameters with existing className:
ingress:
  installController: true
  enabled: true
  className: "nginx"  # Explicitly maintain existing className

# Or migrate to new default className (requires manual override):
ingress:
  installController: true
  enabled: true
  className: "linearb-opa-ingress-class"  # New installations default

Troubleshooting

Ingress controller not receiving traffic

Verify the ingress controller is running in your namespace:
```
kubectl get pods -n linearb | grep ingress
```

Check the Ingress resource:

kubectl get ingress -n linearb
kubectl describe ingress on-prem-agent-onprem-receiver -n linearb

Verify the ingress class matches your controller:
```
kubectl get ingressclass
```

Service is LoadBalancer instead of ClusterIP

This usually means ingress is disabled. Check your configuration:

helm get values on-prem-agent -n linearb | grep -A5 ingress

Customizing Container Registry

Overview

The LinearB On-Prem Agent uses a centralized registry configuration that allows you to customize which container registry to pull images from. This is useful when: - You want to use a private mirror/proxy registry - You have corporate policies requiring images to come from specific registries - You're running in an air-gapped environment

Default Registry Configuration

By default, the agent uses the following registry:

global:
  JFROG_HOST: "linearb-on-prem-dist.jfrog.io/artifactory/on-prem-oci"

Architecture

The agent uses a hybrid approach for registry configuration:

External subcharts (minio, rabbitmq, redis, datadog, fluent-bit): Use YAML anchors to reference the registry
Internal charts (agent-api, scheduler, sensors, etc.): Can use Helm templating helpers to dynamically build registry paths

Overriding the Registry

Option 1: Override global.JFROG_HOST Only

For services that use the registry split (like rabbitmq, redis):

# my-custom-values.yaml
global:
  JFROG_HOST: "my-custom-registry.io/artifactory/custom-path"

# These services automatically use the JFROG_HOST reference
rabbitmq:
  image:
    registry: *jfrog_registry  # Automatically uses global.JFROG_HOST
    repository: image-dependencies/rabbitmq

redis:
  image:
    registry: *jfrog_registry  # Automatically uses global.JFROG_HOST
    repository: image-dependencies/redis

Important: YAML anchors only work within the default values.yaml file and cannot be used in override files.

Option 2: Full Override for External Subcharts

For external subcharts that require full repository paths (like minio):

# my-custom-values.yaml
global:
  JFROG_HOST: "my-custom-registry.io/artifactory/custom-path"

minio:
  image:
    repository: "my-custom-registry.io/artifactory/custom-path/image-dependencies/minio"
  mcImage:
    repository: "my-custom-registry.io/artifactory/custom-path/image-dependencies/mc"

datadog-agent:
  registry: "my-custom-registry.io/artifactory/custom-path"

fluent-bit:
  image:
    registry: "my-custom-registry.io/artifactory/custom-path"

socat:
  image:
    registry: "my-custom-registry.io/artifactory/custom-path"

Option 3: Using --set Flags

helm upgrade my-release ./helm/on-prem-agent \
  --set global.JFROG_HOST="my-custom-registry.io/artifactory/custom-path" \
  --set minio.image.repository="my-custom-registry.io/artifactory/custom-path/image-dependencies/minio" \
  --set minio.mcImage.repository="my-custom-registry.io/artifactory/custom-path/image-dependencies/mc" \
  --set datadog-agent.registry="my-custom-registry.io/artifactory/custom-path"

Complete Override Example

Here's a complete example for switching to a custom registry:

# custom-registry-values.yaml
global:
  JFROG_HOST: "harbor.mycompany.com/linearb-mirror"
  JFROG_USER: "myuser"
  JFROG_KEY: "mypassword"

# External charts requiring full paths
minio:
  image:
    repository: "harbor.mycompany.com/linearb-mirror/image-dependencies/minio"
  mcImage:
    repository: "harbor.mycompany.com/linearb-mirror/image-dependencies/mc"

rabbitmq:
  image:
    registry: "harbor.mycompany.com/linearb-mirror"
    repository: image-dependencies/rabbitmq

redis:
  image:
    registry: "harbor.mycompany.com/linearb-mirror"
    repository: image-dependencies/redis

datadog-agent:
  registry: "harbor.mycompany.com/linearb-mirror"

fluent-bit:
  image:
    registry: "harbor.mycompany.com/linearb-mirror"

socat:
  image:
    registry: "harbor.mycompany.com/linearb-mirror"

ingress:
  global:
    registry: "harbor.mycompany.com/linearb-mirror"
  defaultBackend:
    image:
      registry: "harbor.mycompany.com/linearb-mirror"
  controller:
    image:
      registry: "harbor.mycompany.com/linearb-mirror"
    admissionWebhooks:
      patch:
        image:
          registry: "harbor.mycompany.com/linearb-mirror"

Important Notes

YAML Anchor Limitation: YAML anchors (like *jfrog_registry) only work within a single YAML file. When you provide override values in a custom file or via --set, you must provide complete, fully-qualified values.
Registry Authentication: Update global.JFROG_USER and global.JFROG_KEY if your custom registry requires authentication.

Image Pull Secrets: Ensure your imagePullSecrets are configured correctly for your custom registry:

global:
  imagePullSecrets:
    - regcred  # Update this secret with your registry credentials

Chart Dependencies: Don't forget to update the registry for chart dependencies in Chart.yaml if you're also mirroring Helm charts.

Testing Registry Configuration

After applying custom registry values, verify the configuration:

# Check the rendered templates
helm template on-prem-agent ./helm/on-prem-agent -f custom-registry-values.yaml | grep -i "repository:\|registry:"

# Check running pods
kubectl get pods -n linearb -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

Additional Resources

For questions or issues, please contact LinearB support.