Deploying with Helm

Prerequisites

Kubernetes 1.25+
Helm 3.8+

Install

helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace

This deploys a single-instance Proxy Hopper with the in-memory backend using the default config.

Supplying your config

Inline config (simplest)

Pass your config.yaml content as a Helm value:

helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace \
  --set-file config.inline=config.yaml

Or in a values.yaml file:

config:
  inline: |
    proxyProviders:
      - name: my-provider
        auth:
          type: basic
          username: user
          password: secret
        ipList:
          - "10.0.0.1:3128"
          - "10.0.0.2:3128"
        regionTag: US-East

    targets:
      - name: general
        regex: '.*'
        ipPool: my-pool
        minRequestInterval: 1s
        numRetries: 3

helm install proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --create-namespace \
  -f values.yaml

Existing ConfigMap or Secret

If you manage config separately (via an operator, external-secrets, or sealed-secrets), reference it:

# Reference a ConfigMap — key must be "config.yaml"
config:
  existingConfigMap: my-proxy-hopper-config

# Or reference a Secret (recommended when auth is enabled)
config:
  existingSecret: my-proxy-hopper-secret

When auth is enabled in your config (API keys, JWT, OIDC), use existingSecret rather than config.inline in a values file. Credentials in plain values files can end up in version control or Helm release history.Create the secret with:

kubectl create secret generic proxy-hopper-config \
  --namespace proxy-hopper \
  --from-file=config.yaml=./config-with-auth.yaml

Redis backend

Enable the bundled Redis subchart for pool state persistence and multi-instance HA:

backend:
  type: redis

redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false
  master:
    persistence:
      size: 1Gi

The chart automatically selects the -redis Docker image and wires the Redis URL when backend.type: redis is set. To use an external Redis instance instead of the bundled subchart:

backend:
  type: redis
  redis:
    url: redis://my-external-redis:6379/0

redis:
  enabled: false

Read-only admin (no database)

If you don’t want to run a database at all, deploy the admin server in read-only mode: it stays fully usable for monitoring (status, targets, pools, providers, metrics) but rejects every mutation, so config comes only from config.inline/existingConfigMap/existingSecret.

admin:
  enabled: true
  readOnly: true

This is independent of configStore.dialect — see Config Store — Going fully database-free for the four combinations, and Admin Server — Read-only mode for what gets rejected and how it’s reported via the status query.

Token Server

If you’re using managed auth, the chart can deploy your token server image alongside Proxy Hopper — a Deployment plus a ClusterIP Service, with a predictable in-cluster URL derived automatically:

tokenServer:
  enabled: true
  image:
    repository: ghcr.io/your-org/my-token-server   # your image — see /developers/token-server
    tag: latest
  port: 9000    # must match the port your token server listens on

Wire it into Proxy Hopper’s own config by referencing the chart’s URL helper — this keeps the URL correct regardless of the Helm release name:

config:
  inline: |
    server:
      authServer:
        url: '{{ include "proxy-hopper.tokenServerUrl" . }}'
        timeoutSeconds: 10
        refreshThresholdSeconds: 60
        retryIntervalSeconds: 30
        maxRetries: 5
        exposeProxyUrl: false

    targets:
      - name: my-target
        regex: '.*'
        authManaged: true
        ipPool: my-pool

If you’re using config.existingConfigMap / config.existingSecret instead of config.inline, the template helper isn’t available — hard-code the in-cluster URL instead:

http://<release-name>-proxy-hopper-token-server:<tokenServer.port>

Your token server image only needs to implement POST /token and GET /health — see Building a Token Server for the contract and a Python library that implements it for you.

Ingress

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: proxy-hopper.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: proxy-hopper-tls
      hosts:
        - proxy-hopper.example.com

Upgrading

helm upgrade proxy-hopper oci://ghcr.io/cams-data/helm/proxy-hopper \
  --namespace proxy-hopper \
  --reuse-values \
  --version <new-version>

Uninstall

helm uninstall proxy-hopper --namespace proxy-hopper

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Prerequisites

Install

Supplying your config

Inline config (simplest)

Existing ConfigMap or Secret

Redis backend

Read-only admin (no database)

Token Server

Ingress

Upgrading

Uninstall

​Prerequisites

​Install

​Supplying your config

​Inline config (simplest)

​Existing ConfigMap or Secret

​Redis backend

​Read-only admin (no database)

​Token Server

​Ingress

​Upgrading

​Uninstall

Prerequisites

Install

Supplying your config

Inline config (simplest)

Existing ConfigMap or Secret

Redis backend

Read-only admin (no database)

Token Server

Ingress

Upgrading

Uninstall