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

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

Token Server

Ingress

Upgrading

Uninstall

​Prerequisites

​Install

​Supplying your config

​Inline config (simplest)

​Existing ConfigMap or Secret

​Redis backend

​Token Server

​Ingress

​Upgrading

​Uninstall

Prerequisites

Install

Supplying your config

Inline config (simplest)

Existing ConfigMap or Secret

Redis backend

Token Server

Ingress

Upgrading

Uninstall