Installing knext (cluster prerequisites)
Cluster prerequisites and the one-command operator install bundle.
This is the cloud-agnostic install page. It covers the cluster prerequisites and the order to install them, then installs the knext control plane (the Go operator) from its published bundle. The per-cloud guides — GKE, EKS, AKS, OKE, OpenShift — link back here for the shared steps.
The operator is the control plane. Installing knext means installing the Go operator
(kn-next-operator) plus the cluster pieces it depends on. After that, you deploy apps by applying
NextApp resources — see Operator & the NextApp CRD.
Install order
| # | Prerequisite | Why |
|---|---|---|
| 1 | Kubernetes 1.27+ and kubectl | The cluster and client. |
| 2 | Knative Serving + Kourier | Scale-to-zero serving and the ingress knext targets. |
| 3 | cert-manager | Backs the operator's webhook certificate. |
| 4 | The knext operator bundle | The control plane itself. |
| 5 | A NextApp smoke test | Confirms the install works end to end. |
1 · Kubernetes cluster and kubectl
You need a Kubernetes cluster (1.27+) and a configured kubectl. Any conformant distribution works;
the per-cloud guides cover provider specifics.
2 · Knative Serving + Kourier
knext deploys each app as a Knative Service, so Knative Serving must be installed, with a networking layer. knext targets Kourier.
Knative Serving only programs routes against Kourier if its config-network ConfigMap (in the
knative-serving namespace) sets ingress-class to the full controller-qualified value. The install
bundle ships a config-network ConfigMap that pins it:
data:
ingress-class: kourier.ingress.networking.knative.devApply the bundle with kubectl apply --server-side so this ConfigMap merges into the one Knative
Serving already owns (which holds other networking keys) instead of clobbering it. If
kubectl apply --server-side reports a field-ownership conflict — for example because a GitOps
tool like Argo CD or Flux already manages this ConfigMap — add --force-conflicts to take over just
the keys the bundle sets. The short kourier.knative.dev form does not match Kourier's ingress
class and leaves routes unprogrammed.
If Knative routes never become reachable even though Kourier is installed, the usual cause is a
missing or wrong ingress-class: the routes are never wired to the installed Kourier ingress.
Setting ingress-class explicitly to the controller-qualified value (above) fixes routing.
Port 9091 belongs to Knative, not to your app. On a stock Serving install (default
config-observability), the queue-proxy sidecar binds :9091 inside every revision pod for its own
user-metrics server. knext apps therefore serve their Prometheus metrics on :9464 by default —
no serving ConfigMap needs editing. Do not override METRICS_PORT to 9091: the app loses the
port race against queue-proxy and crash-loops with EADDRINUSE. kn-next doctor detects this
collision and says how to resolve it.
3 · cert-manager
The operator runs a validating webhook, which needs a serving certificate.
cert-manager must be installed in the cluster before you apply the
bundle — the bundle ships the operator's Issuer/Certificate for the webhook, which are
cert-manager.io/v1 resources. On a fresh cluster without cert-manager, applying the operator
bundle fails with no matches for kind "Certificate" in version "cert-manager.io/v1".
Install it first, then wait for the webhook to be ready:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=120s \
-n cert-manager deployment/cert-manager deployment/cert-manager-webhook deployment/cert-manager-cainjector4 · Install the operator
The operator image and the install.yaml bundle are built and published automatically for each
release. Every build generates an SBOM, is Trivy-scanned before it is pushed (HIGH/CRITICAL
findings block publication), carries SLSA provenance, and is cosign-signed on the pushed
digest. The published install.yaml (CRDs + RBAC + manager Deployment + webhook + cert-manager
resources + the config-network and config-features ConfigMaps above) is regenerated with that
same pushed digest, so the bundle you apply references exactly the image that was scanned and
signed. See Security → Supply chain.
Install the control plane with one apply:
kubectl apply --server-side -f https://github.com/getknext-dev/knext/releases/download/operator-latest/install.yamlThe latest/download/install.yaml URL resolves only once a release has been cut. If no release
exists yet — or you are building from a fork — generate the bundle locally instead, from the
operator source directory:
make build-installer IMG=<some-registry>/kn-next-operator:tag
kubectl apply --server-side -f dist/install.yamlThe checked-in dist/install.yaml carries a clearly-fake all-zeros bootstrap digest until the first
published release.
The published bundle's manager image is digest-pinned (@sha256:…), never :latest. You can
verify the operator image signature with cosign:
cosign verify ghcr.io/getknext-dev/kn-next-operator@sha256:<digest> \
--certificate-identity-regexp 'https://github.com/getknext-dev/knext/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comVerify the operator is up:
kubectl wait --for=condition=Available -n kn-next-operator-system \
deployment/kn-next-operator-controller-manager --timeout=120sThe operator's readiness probe gates on its admission webhook actually serving TLS, not just
on the process being alive. The NextApp validating webhook fails closed, so a "ready" operator
whose webhook wasn't serving yet would reject every NextApp apply with a connection error —
gating readiness on the webhook means Available implies admission works, and the kubectl wait
above is sufficient before your first apply.
The bundle is Kourier-targeted. The Kourier ingress-class from step 2 is correct for the
Kourier path and must not be applied to an istio-only dev cluster.
5 · Verify with a NextApp
With the operator running, deploy a NextApp resource and confirm the operator reconciles it into a
reachable Knative Service. Follow Getting started to build and apply your
first app, and see Operator & the NextApp CRD for the resource reference.