Installation | kube-res-foresight

Choose the components

The platform provides the console, data management, forecasting, and advice. The job engine runs recurring work. Add the Operator for replica changes and admission policies for resource advice on new Pods.

Component	Purpose
Platform	Console, API, metrics, forecasts, and recommendations.
Job engine	Recurring collection, forecasts, backtests, and evaluations; can run with the platform.
Operator	Adjust workload replicas within authorization and bounds.
Resource admission	Apply valid resource advice to new Pod requests / limits.

Deploy the platform with Helm

Run these commands from the repository root with Helm 3, access to Kubernetes, and an image registry. Platform and Operator have separate charts. The platform chart runs the console, API, forecasting, and job engine; it does not install a database or the Operator.

Prepare the separate web/ sources, then build and push the platform image. Replace the example registry and tag.

Bash

docker build -f deploy/docker/Dockerfile --target kube-res-foresight \
  -t registry.example.com/kube-res-foresight:0.1.0 .
docker push registry.example.com/kube-res-foresight:0.1.0

For a trial, the defaults use SQLite and a 5Gi PVC. A working StorageClass is required. SQLite permits only one platform replica.

Bash

helm install kube-res-foresight deploy/helm/kube-res-foresight \
  -n kube-res-foresight --create-namespace \
  --set image.repository=registry.example.com/kube-res-foresight \
  --set image.tag=0.1.0

Database and secrets

For external PostgreSQL or MySQL, create a database and a user allowed to create tables, then prepare a credentials Secret. The platform does not provision a database server. This is an alternative installation; do not run it after the SQLite example.

Bash

kubectl create namespace kube-res-foresight
kubectl -n kube-res-foresight create secret generic kube-res-foresight-credentials \
  --from-file=jwt-secret=./jwt-secret.txt \
  --from-file=secret-key=./secret-key.txt \
  --from-file=database-password=./database-password.txt

The files contain the JWT signing key, an encryption key of at least 32 characters, and the database password, respectively, with no trailing newline. Protect these files and keep them out of version control. Create values-production.yaml:

YAML

image:
  repository: registry.example.com/kube-res-foresight
  tag: "0.1.0"
database:
  driver: postgres
  host: pg.example.internal
  port: 5432
  name: kube-res-foresight
  username: kube-res-foresight
  sslMode: require
secrets:
  existingSecret: kube-res-foresight-credentials
persistence:
  enabled: false

Bash

helm install kube-res-foresight deploy/helm/kube-res-foresight \
  -n kube-res-foresight -f values-production.yaml
kubectl -n kube-res-foresight rollout status deployment/kube-res-foresight
helm test kube-res-foresight -n kube-res-foresight
kubectl -n kube-res-foresight port-forward svc/kube-res-foresight 8080:80

Open http://localhost:8080. The initial login is admin / 123456; change the password immediately. For MySQL, use database.driver: mysql, port 3306, and the corresponding connection settings. sslMode applies only to PostgreSQL; this example requires TLS support on the server.

Value	Purpose
`migration.mode: auto`	Defaults to an init container for SQLite and a pre-install/pre-upgrade hook Job for external databases.
`imagePullSecrets`	Credentials for pulling private images.
`ingress`	Controller class, host, and TLS; disabled by default.
`resources`	Platform container requests / limits; size for module count and history windows.
`secrets.existingSecret`	Reuse stable keys. Default keys: jwt-secret, secret-key, database-password.

Manage mail, model connections, and prediction rules in the console. All deployment settings are listed in platform values.yaml ↗.

Deploy the Operator with Helm

Create a platform developer credential restricted to Operator decision reading and reporting. Save access-key:access-secret in operator-credential.txt without a trailing newline, then create its Secret. The platform chart does not create this credential.

Bash

docker build -f deploy/docker/Dockerfile --target operator \
  -t registry.example.com/kube-res-foresight-operator:0.1.0 .
docker push registry.example.com/kube-res-foresight-operator:0.1.0
kubectl -n kube-res-foresight create secret generic kube-res-foresight-platform \
  --from-file=credential=./operator-credential.txt
helm install kube-res-foresight-operator deploy/helm/kube-res-foresight-operator \
  -n kube-res-foresight \
  --set image.repository=registry.example.com/kube-res-foresight-operator \
  --set image.tag=0.1.0 \
  --set platform.url=http://kube-res-foresight.kube-res-foresight.svc \
  --set platform.credentialSecret.name=kube-res-foresight-platform
kubectl -n kube-res-foresight rollout status deployment/kube-res-foresight-operator

The Operator defaults to two replicas with leader election and needs no CRD. Configure workloads and scaling rules through platform modules. Check that HPA/KEDA does not control the same target before enabling the global auto-mode setting and module Auto mode. Configure Kyverno separately for new Pod resource admission.

Prometheus and Grafana

With the Prometheus Operator CRDs installed, enable discovery, alert rules, and the Grafana dashboard ConfigMap. Replace the example release=prom selector label to match your Prometheus. Grafana needs a sidecar configured to load dashboard ConfigMaps.

Bash

helm upgrade kube-res-foresight deploy/helm/kube-res-foresight \
  -n kube-res-foresight --reuse-values \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.serviceMonitor.labels.release=prom \
  --set metrics.prometheusRule.enabled=true \
  --set metrics.prometheusRule.labels.release=prom \
  --set metrics.grafanaDashboard.enabled=true
helm upgrade kube-res-foresight-operator deploy/helm/kube-res-foresight-operator \
  -n kube-res-foresight --reuse-values \
  --set metrics.serviceMonitor.enabled=true \
  --set metrics.serviceMonitor.labels.release=prom

Helm upgrade and uninstall

Back up the database before upgrading and keep the original Secret. Changing the encryption key prevents decryption of existing connection passwords. The chart runs regular migrations, not the retired-table cleanup performed by --upgrade.

Bash

helm upgrade kube-res-foresight deploy/helm/kube-res-foresight \
  -n kube-res-foresight --reuse-values --set image.tag=NEW_TAG
helm upgrade kube-res-foresight-operator deploy/helm/kube-res-foresight-operator \
  -n kube-res-foresight --reuse-values --set image.tag=NEW_TAG

To remove the execution component and platform:

Bash

helm uninstall kube-res-foresight-operator -n kube-res-foresight
helm uninstall kube-res-foresight -n kube-res-foresight

SQLite updates use Recreate with a brief interruption. Uninstall retains the chart-created platform Secret and SQLite PVC. External databases and user-created Secrets remain unchanged. Uninstalling the Operator leaves the workload replica counts it last wrote.

Build the platform

Use the Go, Node.js, and pnpm toolchains declared by the repository. The web/ frontend is a separate repository; prepare its sources before building.

Bash

cd web
pnpm install --frozen-lockfile
cd ..
make package-web
mkdir -p target/bin
go build -o target/bin/kube-res-foresight ./cmd

Configure and start

Set the database, listener, logging, and stable JWT key in config.yaml. Choose SQLite, MySQL, or PostgreSQL. Environment variables use KUBE_RES_FORESIGHT_; credentials use the encryption key KUBE_RES_FORESIGHT_SECRET_KEY.

Bash

# First installation: explicit migration
target/bin/kube-res-foresight server --config config.yaml --migration

# Start the platform and job engine
target/bin/kube-res-foresight all --config config.yaml

The example port is 20001. Open http://localhost:20001 after startup. The server and job commands can also run separately.

Existing installations and execution

Keep the existing database connection, path, and key values. Back up before upgrading and review the cleanup performed by --upgrade. Normal startup does not remove retired tables.

Prepare cluster permissions, credentials, certificates, and policies for execution. Begin in Observe and review resource references and replica ownership before authorizing changes.

Deployment guide ↗ · Operator installation ↗