Skip to content

Planning and Prerequisites⚓︎

This page lists what a Kubernetes cluster needs before xControl is installed on it, what to obtain from Expeto, and the decisions to make before you write the values.yaml for the install. Work through it once; the install page assumes everything here is in place.

Cluster requirements⚓︎

Requirement Detail
Kubernetes A conformant cluster running Kubernetes 1.29 or later. kubectl (or oc on OpenShift) access with rights to create namespaces, CustomResourceDefinitions and cluster-scoped RBAC, because the chart installs the CloudNativePG operator.
Nodes Three worker nodes. The database runs as a three-instance PostgreSQL cluster with one instance per node; on fewer nodes the extra instances stay Pending. Node sizes are in the sizing guide.
Storage A default StorageClass providing ReadWriteOnce volumes. The database claims three volumes of 42 GiB each by default; xView adds 20 GiB for metrics. All of it should be redundant SSD-class storage.
Ingress controller Any controller with an IngressClass. The chart renders Ingress objects for the dialects it knows: standard (including the open-source ingress-nginx), the NGINX Inc. operator, the OpenShift router, HAProxy and the AWS load balancer controller. The dialect is detected from the installed IngressClass objects.
DNS One DNS name for the installation, for example xcontrol.example.com, resolving to the ingress controller. Users, Agents and xView reach xControl through that name.
TLS A certificate for that name. Either let cert-manager issue it (the chart marks its Ingress objects for ACME when asked), reference an existing TLS Secret, or terminate TLS in front of the cluster.
cert-manager Optional. The chart can install it as a dependency when the cluster has none. Do not enable that on a cluster that already runs cert-manager, for example through an OpenShift operator.
Outbound access The nodes pull images from docker.expeto.io, and the machine running Helm pulls charts from repo.expeto.io.
Inbound access Users on the ingress name over HTTPS. Every Site's Agent also connects to that name over HTTPS; nothing else is inbound. xControl itself makes no connection to the Sites.

Tools⚓︎

  • kubectl (or oc), configured for the target cluster and namespace.
  • Helm 3.17 or later. Upgrades of release 3.3.22 and later adopt the bundled CustomResourceDefinitions with --take-ownership, which earlier Helm versions lack.
  • jq, used by the credential commands on the install page.

Any GitOps system that renders Helm charts, such as Argo CD or Flux, works as well. See GitOps installs below for the values that change in that mode.

What to obtain from Expeto⚓︎

Expeto Support issues one set of credentials per installation. The same username and password authenticate both the Helm repository and the container registry, and the chart writes them into the image pull Secret it creates.

Decisions to make before installing⚓︎

Decision Value Notes
Hostname global.config.primaryDomain The DNS name above. Additional names go in global.config.extraDomains.
TLS global.config.acmeTls true annotates every Ingress for cert-manager's ACME issuer. Alternatively set a TLS Secret under global.config.frontend.ingress.tls.
Ingress dialect global.config.frontend.ingress.flavor Detected on a live install. Set it explicitly whenever the chart is rendered without cluster access, which is the case in GitOps pipelines and with helm template.
Monitoring xview.enabled or kubemonitoring.enabled xView is the platform monitoring system and includes Grafana; kubemonitoring is a namespace-scoped Prometheus for the xControl workloads alone. Enable one of the two, never both: the chart refuses to install with both enabled.
Database topology cluster.mode standalone for a single installation. replica builds a hot standby of another installation at a second site; see Upgrade, backup and geo-redundancy.
Backups cluster.backups Continuous WAL archiving and scheduled base backups to S3-compatible object storage. Decide the bucket and retention before go-live.
Platform global.k8sPlatform Detected. Override only when rendering offline for a specific platform (openshift, eks, aks, microk8s, tanzu).

GitOps installs⚓︎

When a pipeline renders the chart and applies the manifests, Helm's cluster lookups return nothing. Set these values so the rendered output does not depend on them:

global:
  createSecrets: false        # supply the database and application Secrets yourself
  config:
    frontend:
      ingress:
        flavor: standard      # or the dialect your controller speaks
imagePullSecrets:
  - name: expeto
    create: false             # the pull Secret already exists in the namespace

Render once with helm template to see the names and shape of the Secrets the chart expects, then create them from your secret store before the first sync.

Namespace⚓︎

Install xControl into its own namespace. The examples in this section use xcontrol as both the namespace and the Helm release name. On OpenShift, create a project instead of a namespace.