Install#

What you need#

• A Kubernetes cluster, version 1.25 or later, and helm.
• A storage class that can make ReadWriteOnce volumes. PostgreSQL gets a volume of 1Gi and ClickHouse one of 2Gi by default. Name a class with global.storageClass if the cluster has no default one.
• Room for the pods: the default requests add up to 1.6 cores and 3 GiB of memory.
• Pull access to the images. During the 0.9.0 beta the images and the chart are private: you need a GitHub account that Hyvop has given read access, and a token of it with the read:packages scope (see "Private packages" below). The Community packages are meant to become public later; from then on none of those steps is needed. To pull from your own registry instead, set global.imageRegistry (air-gapped.md explains the rewrite rule).

One install per namespace: the objects have fixed hyvop-* names.

Install#

From the registry, where the chart is published as an OCI artifact at ghcr.io/hyvop-inc:

helm install hyvop oci://ghcr.io/hyvop-inc/charts/hyvop --version 0.9.0 --namespace hyvop --create-namespace

The chart's version and the product's version are the same: a chart of version X.Y.Z runs the images built from the tag vX.Y.Z.

Put your settings in a file and pass it with -f my-values.yaml rather than a long list of --set. A key the chart does not know, or a value of the wrong type, stops the install with its path (configuration.md).

Wait for the pods:

kubectl get pods -n hyvop

The first start takes a few minutes: the stores initialise their volumes, and core prepares its schema.

Private packages (the 0.9.0 beta)#

While the packages are private, three things need your GitHub login. The token is yours: keep it in an environment variable or a secret store, never in a values file or a command line you share.

# 1. the chart: log helm in to the registry
echo "$GITHUB_TOKEN" | helm registry login ghcr.io -u <github-user> --password-stdin

# 2. the images: a pull secret in the namespace the chart installs into
kubectl create namespace hyvop
kubectl -n hyvop create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io --docker-username=<github-user> --docker-password="$GITHUB_TOKEN"

# 3. name the secret: it is put on every pod of the release
helm install hyvop oci://ghcr.io/hyvop-inc/charts/hyvop --version 0.9.0 --namespace hyvop \
  --set 'global.imagePullSecrets={ghcr-pull}'

Once the Community packages are public, drop the three steps: install as shown above with no login and no imagePullSecrets.

Verify the signatures#

Every release image carries an SBOM and a provenance attestation, and is signed with cosign, keyless. The chart is signed the same way.

for image in hyvop-core hyvop-ui hyvop-ingestor-aws hyvop-ingestor-azure hyvop-ingestor-gcp; do
  cosign verify \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    --certificate-identity-regexp "(?i)^https://github.com/hyvop-inc/${image}/\.github/workflows/ci\.yml@refs/tags/v" \
    "ghcr.io/hyvop-inc/${image}:0.9.0"
done

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '(?i)^https://github.com/hyvop-inc/hyvop-chart/\.github/workflows/release\.yml@refs/' \
  ghcr.io/hyvop-inc/charts/hyvop:0.9.0

cosign verify-attestation --type spdxjson reads the SBOM; --type slsaprovenance the provenance. While the packages are private, log in first (docker login ghcr.io with the same token).

Open the UI#

kubectl port-forward svc/hyvop-ui 8080:80 -n hyvop

Then open http://localhost:8080. Without an ingress that is the address core uses in sign-in redirects and in links in e-mail (core.env.FRONTEND_URL, taken from the first ingress host when there is one).

If the browser reports a CORS error on this page, ui.env.API_BASE_URL was set in your install; empty it and upgrade:

helm upgrade hyvop oci://ghcr.io/hyvop-inc/charts/hyvop --version 0.9.0 -n hyvop --reuse-values --set ui.env.API_BASE_URL=

values.yaml turns the ingress on (ingress.enabled: true, class nginx, host hyvop.test). Set ingress.hosts[0].host to the name that leads to your ingress controller, or ingress.enabled=false if you reach the UI by port-forward only.

The first administrator#

A new install has no account and no default login. The first person to open the UI is asked for a name, an organisation, an e-mail address and a password of at least 8 characters, and becomes the administrator. No e-mail is sent. Everyone else joins by invitation from an administrator.

Until that account exists, anyone who can reach the UI can create it. To close that gap, give a setup code and the screen asks for it:

helm upgrade hyvop ./hyvop -n hyvop --reuse-values --set core.setupCode="$(openssl rand -hex 24)"

Better still, install with --set core.setupCode=... from the start. To read the code again:

kubectl get secret hyvop-core-secrets -n hyvop -o jsonpath="{.data.setup-code}" | base64 -d

The code is not used once an account exists.

HTTP and HTTPS#

The ingress serves plain HTTP by default: passwords and sessions cross the network in clear. Before anyone but you can reach it, turn on one of:

• ingress.https=true: the chart makes a self-signed certificate for the host and keeps it (browsers warn about it).
• ingress.tls: the Secret(s) holding a certificate of your own.
• ingress.certManager.clusterIssuer (or issuer): cert-manager issues the certificate.

Any of them makes the ingress serve HTTPS only and send plain requests on to HTTPS. If a load balancer in front of the cluster ends TLS, leave HTTPS off at the ingress and set core.env.FRONTEND_URL to the https:// address. Traffic from core to the ingestors is always TLS, with a certificate the chart issues from a private authority (internalTls.existingSecret brings your own).

Signing in through your identity provider#

core.env.AUTH_MODE=OIDC with core.env.OIDC_ISSUER_URI, OIDC_CLIENT_ID and OIDC_CLIENT_SECRET signs people in through any OpenID Connect provider. Register the redirect address <the address of Hyvop>/api/auth/oidc/callback/oidc with the provider. Single sign-on is an Enterprise feature: see editions.md. A Community install that is configured for it starts all the same and people sign in with their e-mail and password; the sign-in page says why.

Keycloak is off by default (keycloak.enabled: false). When you switch it on, the chart installs a development server (start-dev, no database). Use it to try sign-in, and your own provider otherwise.

What is installed#

Every pod is denied network access by default and allowed only the paths the chart documents, where the cluster's network plugin enforces NetworkPolicy. What may leave the cluster is listed in air-gapped.md.

Next#

Connect a cloud account: AWS, Azure or GCP. Keep a copy of the secrets listed in backup-and-restore.md before you rely on the install.