Complete reference for OptiPod command-line tools and utility scripts.

OptiPod provides several command-line tools and scripts to help with:

• Viewing and analyzing recommendations
• Setting up development environments
• Managing Prometheus authentication
• Validating documentation
• Running local CI checks

All scripts are located in the scripts/ directory of the OptiPod repository.

Generates comprehensive reports comparing current CPU/memory requests/limits versus OptiPod recommended values.

scripts/optipod-recommendation-report.sh [OPTIONS]

The recommendation report script reads OptiPod recommendations from workload annotations and generates detailed comparison reports. It supports both JSON and HTML output formats, with filtering and sorting capabilities.

• kubectl - Kubernetes command-line tool
• jq - JSON processor
• Access to a Kubernetes cluster with OptiPod installed

—output, -o json|html Output format. Default: json

• json - Machine-readable JSON format
• html - Interactive HTML report with filtering and sorting

—file, -f PATH Write output to file instead of stdout

—namespace, -n NAMESPACE Restrict report to a specific namespace. Default: all namespaces

—kinds KINDS Comma-separated list of workload kinds to scan. Default: deploy,sts,ds

• deploy - Deployments
• sts - StatefulSets
• ds - DaemonSets

—help, -h Show help message

Generate JSON report (default):

./scripts/optipod-recommendation-report.sh

Generate HTML report:

./scripts/optipod-recommendation-report.sh --output html --file report.html
open report.html  # macOS
xdg-open report.html  # Linux

Filter by namespace:

./scripts/optipod-recommendation-report.sh --namespace production

Only scan Deployments:

./scripts/optipod-recommendation-report.sh --kinds deploy

Scan Deployments and StatefulSets:

./scripts/optipod-recommendation-report.sh --kinds deploy,sts

The JSON output includes:

Metadata:

{
  "generatedAt": "2025-01-28T10:30:00Z",
  "context": "my-cluster",
  "namespace": null,
  "kinds": ["deploy", "sts", "ds"]
}

Counts:

{
  "counts": {
    "scannedWorkloads": 10,
    "scannedNamespaces": 3,
    "workloadsWithRecommendations": 8,
    "recordsWithRecommendations": 12,
    "warningRecords": 2
  }
}

Totals (aggregated across all workloads):

{
  "totals": {
    "cpuRequests": {
      "currentMilli": 5000,
      "recommendedMilli": 3000,
      "deltaMilli": -2000
    },
    "memoryRequests": {
      "currentBytes": 10737418240,
      "recommendedBytes": 5368709120,
      "deltaBytes": -5368709120
    },
    "impact": {
      "cpuRequests": {
        "currentMilli": 15000,
        "recommendedMilli": 9000,
        "deltaMilli": -6000
      }
    }
  }
}

Records (per-container details):

{
  "records": [
    {
      "kind": "Deployment",
      "namespace": "production",
      "workload": "my-app",
      "pods": 3,
      "container": "app",
      "policy": "production-policy",
      "policyUID": "abc123...",
      "lastRecommendation": "2025-01-28T10:30:00Z",
      "hasRecommendation": true,
      "warnings": [],
      "current": {
        "requests": { "cpu": "1000m", "memory": "2Gi" },
        "limits": { "cpu": "2000m", "memory": "4Gi" }
      },
      "recommended": {
        "requests": { "cpu": "500m", "memory": "1Gi" },
        "limits": null
      },
      "delta": {
        "cpuReqMilli": -500,
        "memReqBytes": -1073741824,
        "impactCpuReqMilli": -1500,
        "impactMemReqBytes": -3221225472,
        "cpuReqDirection": "decrease",
        "memReqDirection": "decrease",
        "cpuReqPercent": -50.00,
        "memReqPercent": -50.00
      }
    }
  ]
}

The HTML report provides:

Summary Dashboard:

• Workloads optimized percentage (donut chart)
• Total CPU and memory savings
• Requests summary table

Interactive Filtering:

• Search by workload, container, or policy name
• Filter by namespace
• Filter by workload type (Deployment, StatefulSet, DaemonSet)
• Filter by change direction (increases, decreases)
• Filter by warnings

Sorting Options:

• Largest total decrease (default)
• CPU delta
• Memory delta
• Warnings

Detailed Table:

• Per-container current vs recommended resources
• Delta calculations with visual indicators
• Warning badges with tooltips
• Last recommendation timestamp

The script detects and reports potential issues:

CPU_REQ_EXCEEDS_LIMIT:

• Recommended CPU request exceeds current CPU limit
• May cause validation errors if applied with updateRequestsOnly: true

MEM_REQ_EXCEEDS_LIMIT:

• Recommended memory request exceeds current memory limit
• May cause validation errors if applied with updateRequestsOnly: true

UPDATE_REQUESTS_ONLY_CONFLICT:

• Policy has updateRequestsOnly: true but recommendations exceed limits
• Requires either updating limits or changing policy configuration

The script reads these annotations from workloads:

Management annotations:

• optipod.io/managed - Indicates OptiPod management
• optipod.io/policy - Policy name
• optipod.io/policy-uid - Policy UID
• optipod.io/last-recommendation - Timestamp

Recommendation annotations (per container):

• optipod.io/recommendation.<container>.cpu-request
• optipod.io/recommendation.<container>.memory-request
• optipod.io/recommendation.<container>.cpu-limit
• optipod.io/recommendation.<container>.memory-limit

• 0 - Success
• 2 - Invalid arguments or missing dependencies

• Requires OptiPod to be installed and generating recommendations
• Only shows workloads with OptiPod annotations
• Impact calculations multiply per-container deltas by pod count
• HTML report is self-contained (no external dependencies)

Creates Kubernetes secrets for Prometheus authentication.

scripts/create-prometheus-secrets.sh

Interactive script that creates Kubernetes secrets for authenticating with Prometheus. Supports basic auth, bearer token, and mTLS authentication methods.

• kubectl - Kubernetes command-line tool
• Access to a Kubernetes cluster

Run the script and follow the interactive prompts:

./scripts/create-prometheus-secrets.sh

The script will:

1. Prompt for authentication method (basic auth, bearer token, or mTLS)
2. Collect required credentials
3. Create the appropriate Kubernetes secret
4. Provide Helm values for using the secret

Basic Auth:

• Prompts for username and password
• Creates secret with username and password keys

Bearer Token:

• Prompts for token value
• Creates secret with token key

mTLS:

• Prompts for client certificate and key file paths
• Creates secret with tls.crt and tls.key keys

$ ./scripts/create-prometheus-secrets.sh
Select authentication method:
1) Basic Auth
2) Bearer Token
3) mTLS
Choice: 1

Enter username: admin
Enter password: ********

Creating secret 'prometheus-auth' in namespace 'optipod-system'...
secret/prometheus-auth created

Add this to your Helm values:
  prometheus:
    auth:
      type: basic
      secretName: prometheus-auth

Runs local CI checks before committing code.

scripts/ci-checks-local.sh

Runs the same checks that CI runs, allowing you to catch issues before pushing code. This includes linting, formatting, tests, and validation.

• Go 1.22+
• golangci-lint
• kubectl
• All project dependencies

1. Go formatting - Verifies code is formatted with gofmt
2. Go linting - Runs golangci-lint
3. Go tests - Runs unit tests
4. Go vet - Runs go vet
5. Manifest validation - Validates Kubernetes manifests
6. Documentation validation - Checks documentation links and format

./scripts/ci-checks-local.sh

• 0 - All checks passed
• 1 - One or more checks failed

Runs linting checks on the codebase.

scripts/lint-local.sh

Runs golangci-lint with the project’s configuration to check for code quality issues.

• golangci-lint

./scripts/lint-local.sh

Uses .golangci.yml in the project root for linter configuration.

Sets up pre-commit hooks for the repository.

scripts/setup-pre-commit.sh

Installs and configures pre-commit hooks to automatically run checks before each commit.

• pre-commit (Python package)

# Install pre-commit
pip install pre-commit

# Run setup script
./scripts/setup-pre-commit.sh

• Go formatting check
• Go linting
• YAML validation
• Markdown linting
• Secret detection
• Trailing whitespace removal

Validates documentation for correctness and consistency.

scripts/validate-docs.sh

Checks documentation files for:

• Broken internal links
• Invalid markdown syntax
• Missing required sections
• Inconsistent formatting

• markdown-link-check (optional)
• markdownlint (optional)

./scripts/validate-docs.sh

• 0 - All documentation is valid
• 1 - Validation errors found

Synchronizes documentation between docs/ and website/.

scripts/sync-docs.sh

Ensures documentation is synchronized between the Markdown (docs/) and MDX (website/) versions.

./scripts/sync-docs.sh

1. Compares content between docs/ and website/src/content/docs/docs/
2. Reports any differences
3. Optionally syncs changes

Generates documentation index files.

scripts/generate-docs-index.sh

Creates index files that list all documentation pages for easy navigation.

./scripts/generate-docs-index.sh

Generates docs/INDEX.md with links to all documentation files.

Builds the documentation website.

scripts/build-docs.sh

Builds the Astro-based documentation website for production deployment.

• Node.js 18+
• npm

./scripts/build-docs.sh

Builds website to website/dist/ directory.

# Run all CI checks locally
./scripts/ci-checks-local.sh

# If checks pass, commit
git add .
git commit -m "feat: add new feature"

# Generate HTML report
./scripts/optipod-recommendation-report.sh --output html --file report.html

# Open in browser
open report.html  # macOS
xdg-open report.html  # Linux

# Create secret interactively
./scripts/create-prometheus-secrets.sh

# Update Helm values with provided configuration
helm upgrade optipod charts/optipod -f values.yaml

# Validate documentation
./scripts/validate-docs.sh

# Sync docs/ and website/
./scripts/sync-docs.sh

# Build website to test
./scripts/build-docs.sh

If you get “Permission denied”:

chmod +x scripts/*.sh

Install required tools:

# macOS
brew install kubectl jq golangci-lint

# Linux (Ubuntu/Debian)
apt-get install kubectl jq
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Ensure kubectl is configured to access your cluster:

kubectl config current-context
kubectl get nodes

• Annotations Reference - Annotation format used by recommendation report
• Reviewing Recommendations - Guide to reviewing recommendations
• CRD Specification - OptimizationPolicy field reference
• Contributing Guide - Development workflow and guidelines