Skip to content

mkectl check ports

mkectl check ports#

Validate live network connectivity between MKE4 nodes before a fresh install or an in-place upgrade

Synopsis#

Validate that the network path between the hosts in an MKE 4 config is open for the ports k0s and its components require, node to node (east-west).

The check adapts to the cluster it finds:

  • Fresh hosts: every required port is bound with a short-lived listener and dialed from each peer, proving the port is both free and reachable.
  • An existing cluster: ports the running stack already holds are dialed against the live service and never bound, so the check can be run before an in-place upgrade. Which process holds each port is read from the node, so a port squatted on by something that is not part of the cluster is reported as a conflict rather than mistaken for the real service.

Each port is reported as one of the following. The two failure verdicts differ in what the check was able to prove, which is what decides where to look:

ok reachable from every peer that needs it

path-blocked nothing held the port, so the check bound its own listener and confirmed it was up. No peer could reach it, so traffic is being dropped between the nodes. Look at the firewall.

service-unreachable a cluster service held the port, so the check bound nothing and dialed the real service, which did not answer. The cause is not proven: each row reports what the service's bind address implies. Loopback-only means no peer can ever reach it and no firewall change helps.

conflicted held by a process that is not part of the cluster stack, so MKE cannot bind it and the wrong process would answer. Reachability is not tested.

unverifiable held by a live service on UDP, where reachability cannot be tested without disrupting it.

Connectivity is best-effort: a host that fails to connect is listed as a skipped node, with the reason, and the hosts that did answer are still reported. This command is reached for when something is already broken, so one unreachable host does not hide every other result. Results are printed to stdout, or written to the output directory's preChecks.txt when --output is set.

The command exits non-zero if any port failed, so it can gate a CI/CD pipeline or a maintenance window. A skipped host does not by itself fail it -- read the skipped list before treating a pass as cluster-wide. The --check-ports preflight on apply and upgrade is stricter: there, a host that could not be probed fails the run, because those commands must not proceed on a cluster whose nodes were never shown to reach each other.

Unverifiable ports do not fail the check but are always listed, so "everything passed" never hides an untested path.

mkectl check ports [flags]

Options#

      --concurrency int    Maximum number of nodes to configure in parallel, set to 0 for unlimited (default 30)
  -h, --help               help for ports
      --probe-dir string   remote directory to upload and run the port probe from; use an exec-capable path when /tmp is mounted noexec (default "/tmp")

Options inherited from parent commands#

  -d, --data-dir string                                             Path to use for storing kubernetes provider data. Applies to all nodes in the cluster. If desiring to reuse docker data dir, please use a path under it instead of the exact path. Defaults to /var/lib/k0s (default "/var/lib/k0s")
  -f, --file string                                                 path to the config file. Not needed for restore where config is loaded from the backup (default "mke4.yaml")
      --force                                                       Bypass user confirmations
      --kubeconfig string                                           path to the kubeconfig file of the existing or restored cluster. DO NOT USE when creating a new cluster (default "/home/runner/.mke/mke.kubeconf")
  -l, --logLevel string                                             specify a log level (info, warn, debug, trace, error) (default "info")
      --no-color                                                    when provided, disables colored output
      --no-pretty-print                                             when provided, disables pretty print output formatting
  -o, --output string[="/home/runner/.local/state/mke/mke-check"]   Path to create the upgrade output files (summary, configs, checks). If not provided, they will be printed to standard output.
      --version version[=true]                                      --version, --version=raw prints version information and quits; --version=vX.Y.Z... sets the reported version