Skip to content

Install the Operator⚓︎

The xCore operator ships as the xfabric Helm chart. Installing it puts the operator, the Expeto Agent and the bundled data-backend operators into one namespace, applies the CustomResourceDefinitions, and installs the netcfg node-configuration operator unless the cluster already runs it. The core itself is created afterwards by applying a Site definition.

Add the Helm repository⚓︎

helm repo add expeto https://repo.expeto.io/repository/ngc \
    --username '<username>' --password '<password>'
helm repo update
helm search repo expeto/xfabric

Write the values file⚓︎

Keep the installation's settings in a values.yaml under version control. A minimal file:

agent:
  connections:
    siteId: "3051"                              # numeric Site ID from xControl
    serverUri: https://xcontrol.example.com
    brokerUri: https://xcontrol.example.com
  • agent.connections.siteId is the Site the Agent registers as. The install is refused unless it is set to an all-digit value.
  • agent.connections.serverUri and brokerUri point at your xControl installation. Both default to Expeto's hosted service.
  • The API token and the registry credentials are secrets; pass them on the command line as shown below, or pre-create the Secrets and reference them (agent.existingCredsSecret, global.imageCredentials.create: false).

Other values you may need at install time:

Value Default Purpose
mariadb-operator.enabled, dragonfly-operator.enabled true Bundled data-backend operators. Set false for the one the cluster already runs.
netcfg.enabled true Bundled netcfg operator. Set false when another Expeto release on the cluster (xRouter, xControl with netcfg, or a second xCore) already runs it; the install fails its singleton check otherwise.
crds.install true Apply the CustomResourceDefinitions before every install and upgrade. With false, apply them yourself first.
metallb.enabled false Bundle MetalLB with FRR-K8s on a cluster that has no load balancer.
bgp.enabled false Let the operator emit BGP resources into MetalLB's namespace. Required when the Site has a BGP router with impl: metallb, the default; MetalLB must already be installed. A gobgp router does not need it.
metallbNamespace detected Namespace of the MetalLB controller, when detection fails.
kube-prometheus-stack.enabled false Bundle a Prometheus stack on a cluster without one. Keep false on OpenShift.
metrics.serviceMonitor.enabled false Create a ServiceMonitor for the operator's own metrics when prometheus-operator is present.
nfMonitoring.enabled false Render scrape configurations for the network functions when prometheus-operator is present.
image.tag chart appVersion Pin the operator to a specific build.
agent.image.tag the Agent build the chart pins The Agent build; the chart of xCore 4.0.6 pins a 3.3.22 Agent. It must not be newer than the xControl it registers with, and an Agent older than 3.3.22-beta8 cannot manage the Site's MME.
agent.hostAliases [] Extra /etc/hosts entries (ip, hostnames) for the Agent pod, for example to reach xControl through an in-cluster ingress under its public name.
imageOverrides.<key> unset Replace one network-function image with a full repository:tag; the keys are listed in the chart's files/operator/versions.yaml. The operator replaces the override's registry host with global.imageRegistry, so the image must be in that registry.
global.imageRegistry docker.expeto.io Mirror registry for air-gapped clusters. The uninstall hook's image does not follow it; on a mirror, also set imageOverrides.helm_kubectl.
preDeleteDrain.mode abort What helm uninstall does while a Site exists: abort refuses, drain deletes the Sites first (test clusters only), disabled installs no check. See Uninstall.
preDeleteDrain.timeoutSeconds 180 How long drain waits for the Sites to be deleted.
agent.smfRulesConfigMapRef unset Customer-managed SMF routing rules; see Upgrade, change and uninstall.

Run helm show values expeto/xfabric for the complete file with its inline comments. Helm checks the values against the chart's schema on every install and upgrade: an unknown key in the chart's own sections (agent, bgp, preDeleteDrain and others), or a value outside an allowed set, stops the command with an error that names it.

Install⚓︎

helm install xcore expeto/xfabric -n xcore --create-namespace -f values.yaml \
    --set global.imageCredentials.username='<username>' \
    --set global.imageCredentials.password='<password>' \
    --set agent.apiToken='<site API token>'
kubectl -n xcore rollout status deployment/xcore-xfabric

The chart's install-time guards check for the Multus and cert-manager CustomResourceDefinitions, and for a running netcfg operator when the bundled one is disabled, and stop with a hint when one is missing. On success the namespace holds the operator Deployment, the Agent StatefulSet with its CLI sidecar, the bundled MariaDB and Dragonfly operators, and the netcfg operator with its node agent.

The operator detects OpenShift; no profile file is needed. The chart never bundles cert-manager, and MetalLB and the Prometheus stack are off by default, which is what OpenShift requires: the platform owns those CustomResourceDefinitions and provides the operators through OperatorHub. The operator's ServiceMonitor is enabled automatically when user-workload monitoring serves its CustomResourceDefinition; the command below sets it explicitly. Decide per cluster whether the bundled MariaDB and Dragonfly operators are wanted:

helm install xcore expeto/xfabric -n xcore --create-namespace -f values.yaml \
    --set metrics.serviceMonitor.enabled=true \
    --set global.imageCredentials.username='<username>' \
    --set global.imageCredentials.password='<password>' \
    --set agent.apiToken='<site API token>'

Install the cert-manager Operator and, for BGP, the MetalLB Operator from OperatorHub first, then add --set bgp.enabled=true. A cluster that already runs the MariaDB or Dragonfly operator takes --set mariadb-operator.enabled=false or --set dragonfly-operator.enabled=false so that two controllers never reconcile the same resources.

When the registry credential is managed outside Helm (a secret store, External Secrets), create the Secret first and tell the chart not to:

kubectl create namespace xcore
kubectl -n xcore create secret docker-registry expeto \
    --docker-server=docker.expeto.io \
    --docker-username='<username>' --docker-password='<password>'
helm install xcore expeto/xfabric -n xcore -f values.yaml \
    --set global.imageCredentials.create=false \
    --set agent.apiToken='<site API token>'

The same applies to the Agent's token: create a Secret whose .creds key holds SECRET=<token> and set agent.existingCredsSecret to its name.

Run the preflight check⚓︎

The chart's Helm tests run the operator's preflight inside the cluster and report every dependency, required and optional, with a fix hint for anything missing:

helm test xcore -n xcore --filter name=xcore-xfabric-test-preflight --logs

Required checks are Multus, cert-manager and the netcfg operator. Optional ones cover whereabouts, MetalLB, FRR-K8s, prometheus-operator and duplicate MariaDB or Dragonfly operators elsewhere on the cluster. The same report is available at any time from the operator pod:

kubectl -n xcore exec deployment/xcore-xfabric -- /opt/taiga/app preflight

Note

Run the test with the --filter shown. A bare helm test also runs the bundled Dragonfly operator's connection test, which addresses a Service name that chart does not create and fails regardless of the installation's health.

Next step⚓︎

Apply the Site definition agreed with Expeto Support during the design phase. Until a Site exists the operator runs idle and the Agent waits for its network functions.