Skip to content

OPA Diagnostics

A comprehensive diagnostics tool for OPA on-premises installations that validates configuration, tests connectivity, and provides detailed system information.

What This Tool Checks

✅ Network Connectivity - Access to LinearB APIs, DataDog, and integrations

✅ Kubernetes Cluster - Node resources, storage classes, and version compatibility

✅ Memory & Resource Analysis - Cluster resource utilization

✅ API Authentication - LinearB token validation

✅ Custom Certificates - SSL certificate validation if required

✅ Integration Connectivity - Source control and project management systems

Integration with Main Chart

OPA Diagnostics is integrated into the main on-prem-agent Helm chart and runs as a Kubernetes CronJob. It is installed automatically alongside other OPA components and runs periodically to monitor your OPA installation health.

Configuration

Diagnostics is enabled by default and runs automatically on a schedule. By default, it runs daily at 2 AM UTC. No additional configuration is required for basic operation.

Schedule Configuration

The diagnostics CronJob runs on a configurable schedule using standard cron syntax:

opa-diagnostics:
  cronjob:
    schedule: "0 2 * * *"  # Daily at 2 AM UTC (default)
    suspend: false  # Set to true to temporarily disable scheduled runs

Common schedule examples: - "0 2 * * *" - Daily at 2 AM - "0 */6 * * *" - Every 6 hours - "0 2 * * 0" - Weekly on Sunday at 2 AM - "0 2 1 * *" - Monthly on the 1st at 2 AM

Optional: Customize Diagnostics

To customize diagnostics behavior or disable it, add the following to your local-values.yaml file:

# ... existing configuration (JFROG_USER, ORG_ID, LINEARB_PUBLIC_API_KEY, etc.) ...

opa-diagnostics:
  enabled: true  # Set to false to disable diagnostics completely (enabled by default)
  runOnInstall: true  # Run diagnostics during helm install/upgrade (enabled by default)
  cronjob:
    schedule: "0 2 * * *"  # Customize the schedule
    suspend: false  # Set to true to suspend the cronjob
  image:
    env:
      plain:
        - name: "ACCOUNT_ID"
          value: "310295"  # Optional: Your LinearB account ID
        - name: "DATADOG_HOST"
          value: "api.datadoghq.com"  # Optional: DataDog host for connectivity testing
  integrations:
    sourceControl:
      - name: "GitHub"
        url: "github.com"
      - name: "GitLab"
        url: "gitlab.com"
    projectManagement:
      name: "Jira"
      url: "your-company.atlassian.net"

Notes: - Diagnostics runs both during installation and on the configured schedule - To disable all diagnostics, set opa-diagnostics.enabled: false in your values file - To disable only the initial install/upgrade job, set opa-diagnostics.runOnInstall: false - To temporarily suspend scheduled runs without disabling, set opa-diagnostics.cronjob.suspend: true - All configuration fields are optional - diagnostics will use sensible defaults

How It Works

When you deploy the on-prem agent using the standard deployment script (./deploy.sh), diagnostics runs in two ways:

1. Initial Installation Job

A one-time Job runs automatically during helm install and helm upgrade operations. This provides immediate validation of your setup:

  1. Validates your configuration
  2. Tests network connectivity to required endpoints
  3. Checks API key authentication
  4. Gathers cluster information
  5. Completes and shows results in the logs

The initial job uses Helm hooks and runs before the deployment completes, giving you immediate feedback.

2. Scheduled CronJob

After installation, a CronJob continues to monitor your OPA installation health on the configured schedule (default: daily at 2 AM UTC). This provides ongoing monitoring and early detection of issues.

Manually Triggering Diagnostics

You can manually trigger a diagnostics run at any time without waiting for the scheduled execution:

# Method 1: Create a job from the cronjob
kubectl create job --from=cronjob/on-prem-agent-opa-diagnostics -n linearb manual-diagnostics-$(date +%s)

# Method 2: Using a more readable timestamp
kubectl create job --from=cronjob/on-prem-agent-opa-diagnostics -n linearb manual-diagnostics-$(date +%Y%m%d-%H%M%S)

Note: The cronjob name may vary based on your Helm release name. To find the exact name:

# List all cronjobs in the namespace
kubectl get cronjobs -n linearb

# Then use the actual cronjob name in the command above

This creates an immediate one-time job based on the cronjob configuration, which is useful for: - Testing after configuration changes - Troubleshooting issues - Getting immediate diagnostics results - Validating fixes before the next scheduled run

Viewing Results

View Initial Installation Diagnostics

After running helm install or helm upgrade, view the results from the initial diagnostics job:

# View logs from the most recent install/upgrade job
# The job name includes the Helm revision number
kubectl get jobs -n linearb -l app.kubernetes.io/name=opa-diagnostics --sort-by=.metadata.creationTimestamp

# View logs from the latest job
POD_NAME=$(kubectl get pods -n linearb -l app.kubernetes.io/name=opa-diagnostics --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')
kubectl logs -n linearb $POD_NAME

# Or use helm status to see the job
helm status on-prem-agent -n linearb

Check CronJob Status

# View the cronjob configuration and last schedule time
kubectl get cronjob -n linearb -l app.kubernetes.io/name=opa-diagnostics

# Describe the cronjob for detailed information
kubectl describe cronjob -n linearb on-prem-agent-opa-diagnostics

View Job Execution History

# List all diagnostics jobs (initial, scheduled, and manual)
kubectl get jobs -n linearb -l app.kubernetes.io/name=opa-diagnostics

# Get the latest diagnostics pods
kubectl get pods -n linearb -l app.kubernetes.io/name=opa-diagnostics --sort-by=.metadata.creationTimestamp

View Diagnostics Output

# View logs from the most recent diagnostics run
POD_NAME=$(kubectl get pods -n linearb -l app.kubernetes.io/name=opa-diagnostics --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}')
kubectl logs -n linearb $POD_NAME

# View logs from a specific pod
kubectl logs -n linearb <diagnostics-pod-name>

# Example:
kubectl logs -n linearb on-prem-agent-opa-diagnostics-28459840-jgvzt

# Follow logs in real-time (useful for install/upgrade or manual triggers)
kubectl logs -n linearb -f <diagnostics-pod-name>

Configuration

Inherited Values

The following values are automatically inherited from your main local-values.yaml configuration:

  • LINEARB_PUBLIC_API_HOST - LinearB API endpoint
  • LINEARB_PUBLIC_API_KEY - Your LinearB API token
  • ORG_ID - Your LinearB organization ID
  • LINEARB_DATA_LAKE_S3_BUCKET - S3 bucket for data storage

These values are used automatically by diagnostics - you don't need to configure them separately.

Diagnostics-Specific Configuration

All diagnostics settings are optional. Set these values in your local-values.yaml file under the opa-diagnostics: section if you want to customize behavior:

Setting Description Default
enabled Enable/disable all diagnostics true (enabled by default)
runOnInstall Run diagnostics during helm install/upgrade true (enabled by default)
cronjob.schedule Cron schedule for diagnostics runs "0 2 * * *" (daily at 2 AM UTC)
cronjob.suspend Temporarily suspend scheduled runs false
cronjob.concurrencyPolicy How to handle concurrent job runs (Forbid/Replace/Allow) Forbid
ACCOUNT_ID LinearB account ID for validation Not set
DATADOG_HOST Datadog API endpoint for connectivity testing Not set
integrations.sourceControl List of Git providers to test (GitHub, GitLab, etc.) Common providers (GitHub, GitLab, Bitbucket)
integrations.projectManagement Project management tool to test (Jira, etc.) Jira

Example Configuration

opa-diagnostics:
  enabled: true
  cronjob:
    schedule: "0 */12 * * *"  # Run every 12 hours
    suspend: false
  image:
    env:
      plain:
        - name: "ACCOUNT_ID"
          value: "310295"
        - name: "DATADOG_HOST"
          value: "api.datadoghq.com"
  integrations:
    sourceControl:
      - name: "GitHub Enterprise"
        url: "github.company.com"
      - name: "GitLab"
        url: "gitlab.company.com"
    projectManagement:
      name: "Jira"
      url: "jira.company.com"

Output Example

🔍 Running OPA 4 Installation Diagnostics...
🌐 API Endpoint: on-prem-api.linearb-dev-01.io

📡 Network Connectivity Checks
✅ on_prem_api: on-prem-api.linearb-dev-01.io - SUCCESS
✅ datadog_api: https://api.datadoghq.com - SUCCESS

🔌 Integrations Connectivity Checks
✅ Source Control GitHub: Connection successful
✅ Source Control GitLab: Connection successful

🔑 API Key Validation
✅ LinearB API Token: SUCCESS
✅ LinearB Org ID: SUCCESS

☸️ Cluster Information
✅ Kubernetes Version: v1.31.5+k3s1
✅ Cluster Nodes: 2 nodes detected
✅ Storage Classes: 1 available

📊 DIAGNOSTIC SUMMARY
Overall Status: ⚠️ WARNING
Errors: 1 | Warnings: 2

Troubleshooting

Common Issues

  • Environment variables not set: Ensure global values are configured in your main values file
  • API connectivity failures: Check network policies and firewall rules
  • Certificate validation errors: Verify custom certificate configuration
  • RBAC permission errors: Service account needs cluster-reader permissions (automatically configured)

Understanding Results

  • ✅ SUCCESS - Everything is working correctly
  • ⚠️ WARNING - May need attention but not blocking (e.g., RBAC permission issues for optional features)
  • ❌ ERROR - Must be resolved for optimal operation
  • ℹ️ INFO - Informational messages or skipped checks

Common Warnings (Safe to Ignore)

The following warnings are expected and safe to ignore in most deployments:

⚠️ Persistent Volumes: Unable to list persistent volumes (insufficient permissions)
⚠️ Pods: Unable to list pods (insufficient permissions)

These warnings occur when the diagnostics service account lacks certain optional RBAC permissions. They do not affect the core functionality of the diagnostics or the OPA installation.

Advanced Configuration

Detailed Pod Analysis

Enable comprehensive pod information collection:

opa-diagnostics:
  cluster:
    collectDetailedPodInfo: true

CronJob Configuration

The diagnostics runs as a Kubernetes CronJob with the following default settings:

Schedule Configuration

  • Schedule: "0 2 * * *" (Daily at 2 AM UTC)
  • Concurrency Policy: Forbid (prevents concurrent runs)
  • Starting Deadline: 200s (max delay after missed schedule)
  • Successful Jobs History: 3 (keeps last 3 successful runs)
  • Failed Jobs History: 1 (keeps last failed run)

Job Execution Settings

  • Restart Policy: Never
  • Backoff Limit: 1 retry
  • Active Deadline: 300s (5 minutes timeout)
  • TTL After Finished: 1800s (results kept for 30 minutes after completion)

Support

For issues or questions:

  1. Capture Complete Output - Save the full diagnostics log
  2. Check Prerequisites - Verify Kubernetes and network requirements
  3. Contact LinearB Support - Provide diagnostics output and environment details