Skip to content

Verify the Installation⚓︎

After helm install reports success, confirm that every tier of xControl answers before you hand the installation over or connect the first Site. The checks below take a few minutes and need only kubectl and a browser.

Workloads⚓︎

All pods in the namespace must be Running (or Completed for one-off jobs) with no restarts accumulating:

kubectl -n xcontrol get pods
kubectl -n xcontrol get pods --field-selector=status.phase!=Running,status.phase!=Succeeded

The second command lists anything unhealthy and should print nothing. A pod stuck in Init is usually waiting for the database: kubectl -n xcontrol describe pod <pod> names the init container, and kubectl -n xcontrol get clusters.postgresql.cnpg.io shows whether the PostgreSQL cluster is Cluster in healthy state.

Helm's own smoke test connects to the API server from inside the cluster:

helm test xcontrol -n xcontrol

Endpoints⚓︎

Every Ingress must carry the hostname you configured and an address:

kubectl -n xcontrol get ingress

Then, from a machine that resolves the hostname:

Check URL Expected
API liveness https://xcontrol.example.com/alive HTTP 200
Web interface https://xcontrol.example.com/ngui/ The login page, redirected through Keycloak
Single sign-on https://xcontrol.example.com/auth/realms/expeto Realm metadata as JSON
Platform Guide https://xcontrol.example.com/admin-docs/ This documentation
xView, when enabled https://xcontrol.example.com/nms/ Grafana, signed in through Keycloak 
curl -sS -o /dev/null -w '%{http_code}\n' https://xcontrol.example.com/alive

Sign in to the web interface with the administrator credentials from the install page and confirm the Dashboard loads.

Connect the first Site⚓︎

A Site in xControl represents one xCore or xRouter installation. Its Agent authenticates with a Site identifier and an API token that you create here before installing the core.

  1. In the web interface, go to Sites and click Add to create the Site. Give it the name the network team knows it by, select its Customer, and set Site type to xCore or xRouter. The Site's numeric identifier appears in its URL and on its detail page; the core's Helm values refer to it as the site ID.
  2. Open the Site, click Edit and select the API Tokens tab.
  3. Switch Enable on to allow API tokens for this Site, then click Add and name the token. Copy the token value when it is shown; it is the core's apiToken and is not displayed again.
  4. Create at least one System under the Site so the core has a network segment to serve, following Systems.

Through the REST API the same steps are POST /v1/sites, POST /v1/site-feature-api-tokens with type: api_token_site_feature, and POST /v1/sites/command/createToken.

Once the core is installed with that Site identifier and token, the Site shows Connected in the Sites list within a minute, and its Agent version and IP address appear on the detail page. A Site that stays Disconnected has not reached xControl: check that the core resolves and can reach https://xcontrol.example.com on port 443, and that its Helm values carry the right identifier and token.

Where to look when something fails⚓︎

Symptom Where to look
Pods Pending kubectl -n xcontrol describe pod <pod>: node resources, or a PersistentVolumeClaim with no StorageClass to bind to.
Database instances not all ready kubectl -n xcontrol describe clusters.postgresql.cnpg.io; one instance per node is required.
Login page loads, sign-in fails Keycloak pod logs: kubectl -n xcontrol logs statefulset/xcontrol-keycloak.
API answers, web interface blank Browser console for a blocked cross-origin request; the frontend and API must share the hostname.
Certificate errors kubectl -n xcontrol get certificates,certificaterequests when cert-manager issues the certificate; the issuer must be able to solve the ACME challenge on the hostname.
Agent never connects API server logs: kubectl -n xcontrol logs deployment/xcontrol-xcontrol-api, filtered on the Site identifier.

For platform-wide monitoring and alerting after go-live, see xView and the xControl alerts.