Installation Guide

Prerequisites

Kubernetes 1.24+ or OpenShift 4.x
Helm 3.x
Permission to create a Role/RoleBinding in the target namespace (the chart creates them for you)

Installing via Helm

The chart is published to a Helm repository hosted on GitHub Pages.

Add the repository:

helm repo add smart-proxy https://ivseb.github.io/smart-proxy
helm repo update

Install the chart:

helm install smart-proxy smart-proxy/smart-proxy \
  --namespace smart-proxy --create-namespace

Verify the installation:
```
kubectl get pods -n smart-proxy
```

Installing from source

Alternatively, install straight from a clone of the repository:

git clone https://github.com/ivseb/smart-proxy.git
cd smart-proxy
helm install smart-proxy ./charts/smart-proxy --namespace smart-proxy --create-namespace

Customizing the deployment

All options are documented in charts/smart-proxy/values.yaml. A ready-to-edit production example (OpenShift Route + persistence) is provided in charts/smart-proxy/values.example.yaml:

helm install smart-proxy ./charts/smart-proxy \
  --namespace my-namespace --create-namespace \
  -f charts/smart-proxy/values.example.yaml

Common overrides:

Value	Description	Default
`image.tag`	Image tag to deploy (pin a release in production).	chart `appVersion`
`config.logLevel`	`debug`, `info` or `error`.	`info`
`rbac.openshiftRoutes`	Grant permissions on OpenShift Routes. Set `false` on vanilla Kubernetes.	`true`
`route.enabled`	Expose the admin dashboard via an OpenShift Route.	`false`
`ingress.enabled`	Expose the admin dashboard via a Kubernetes Ingress.	`false`
`persistence.enabled`	Use a PersistentVolumeClaim instead of an ephemeral `emptyDir`.	`false`

See the Configuration Reference for the full list of environment variables and annotations.

Uninstalling

helm uninstall smart-proxy --namespace smart-proxy

Before anything is deleted, a Helm hook Job stops Smart Proxy, points every patched Ingress/Route back at its original Service and wakes every Deployment it put to sleep (with the replica count it had). Your applications keep working without Smart Proxy. Disable this with restoreOnUninstall: false.

Restoring by hand

If you uninstall with --no-hooks, deployed Smart Proxy without Helm, or want to undo its changes for any other reason, stop it and run the restore command with the same namespace settings and service account:

kubectl -n smart-proxy scale deployment/smart-proxy --replicas=0
kubectl -n smart-proxy run smart-proxy-restore --rm -i --restart=Never \
  --image=isebben/smart-proxy:latest \
  --overrides='{"spec":{"serviceAccountName":"smart-proxy-sa"}}' \
  --env=WATCH_NAMESPACE=smart-proxy \
  -- restore

Use the WATCH_NAMESPACE / WATCH_NAMESPACE_SELECTOR values of your installation so every managed namespace is covered.

Local Development (Docker Desktop)

For a full local environment with Smart Proxy and a demo application, use the setup script:

Ensure Docker Desktop is running with Kubernetes enabled.
Run the setup script:
```
./scripts/setup-local.sh
```
This script will:
- Build the Docker image locally.
- Deploy Smart Proxy plus a demo Frontend/Backend/Redis application.
- Configure local Ingress resources.
Access the Dashboard:
- Add 127.0.0.1 admin.local to your /etc/hosts.
- Visit http://admin.local.

Verifying the image

Images published from this repository are signed with cosign using the GitHub Actions identity (keyless):

cosign verify docker.io/isebben/smart-proxy:<tag> \
  --certificate-identity-regexp '^https://github.com/ivseb/smart-proxy/\.github/workflows/docker-publish\.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Docker Image

The image is published on Docker Hub:

docker pull isebben/smart-proxy:latest

https://hub.docker.com/r/isebben/smart-proxy

What's in it, and vulnerabilities

The image is built FROM scratch: Smart Proxy's static binary, its dashboard and the CA certificates, nothing else — no operating system, no shell, no package manager, so no OS packages to have CVEs. It runs as a non-root user and works with OpenShift's random UIDs.

Every build is scanned with Trivy before it is published: any known vulnerability, of any severity, fails the build. govulncheck checks the Go code and modules in CI.
Every week the published latest image and the code are scanned again, so a CVE found after a release shows up as a failed run.
Fixes are released by themselves. Dependabot proposes updates of the Go modules and of the Go version every day, and security fixes as soon as they are known. Every day a workflow merges those whose checks all passed — the tests, the end-to-end suite on a real cluster and the vulnerability scan — except major version changes, left for a person to review. If everything since the latest release is such updates, it tests the result again and publishes a patch release: image, chart and release notes.
No shell to exec into: to troubleshoot from inside the pod's network, attach a debug container, e.g. oc debug deployment/smart-proxy (OpenShift) or kubectl debug -it <pod> --image=busybox --target=smart-proxy.

Scan it yourself:

trivy image --scanners vuln docker.io/isebben/smart-proxy:<tag>