How a cluster fits together

This page is for the administrator meeting Kubernetes for the first time. It explains the machines a cluster is made of, the words the rest of this documentation uses, and — most importantly — which command runs on which machine. If you have run Kubernetes before, skim the table at the end and move on to Before you begin.

What Kubernetes is, in one paragraph

Kubernetes runs applications packaged as containers across a group of machines. You describe what should be running — this application, three copies, this much memory — and Kubernetes keeps reality matching that description: it places the containers on machines with capacity, restarts them when they fail, and moves them when a machine goes away. The group of machines, taken together, is a cluster. Each machine in it is a node.

The two kinds of node

A cluster has two kinds of node, and the distinction decides where almost every command in this documentation runs.

Control-plane nodes decide. They run the components that hold the cluster’s state and give instructions to everything else:

• the API server — the front door. Every tool, every node and every person talks to the cluster through it, on port 6443.
• etcd — the database. Everything the cluster knows lives here, which is why its loss is the loss of the cluster, and why backups matter.
• the scheduler and controller manager — the processes that choose where containers run and act when reality drifts from the description.

Worker nodes run your applications. Each one runs a kubelet — the agent that takes instructions from the control plane — and containerd, the runtime that actually starts and stops containers.

Control-plane nodes are also machines and can also run application containers, but on a cluster created by BKE they are reserved for cluster management by default, and application workloads land on the workers. This is why a working cluster needs both kinds: a control plane with no workers has nowhere to put your applications.

How many of each. Control-plane nodes come in odd numbers. etcd accepts a write only when a majority of its members agree, so three nodes tolerate the loss of one, five tolerate two — and two are worse than one, because losing either stops the majority. One control-plane node is acceptable for evaluation; production wants three. Workers are simpler: as many as your applications need.

The first control-plane node

One control-plane node is special during installation, and this documentation refers to it often.

The first control-plane node is the machine that creates the cluster. It is where your licence is registered, where install.sh --role master runs, and where the administrator credentials are written. Every other node — additional control-plane nodes included — joins the cluster this node created. Once the cluster is running, the first node has no ongoing special status; it is one control-plane member among equals.

During an upgrade the word appears again with a related but different meaning: upgrade.sh --role first runs on whichever control-plane node you choose to upgrade first, and --role other on every remaining node. The roles describe order, not importance.

The words you will meet

Pod. The unit Kubernetes actually runs: one or more containers that live and die together. You will mostly see pods when checking that something is running: kubectl get pods -A.

Namespace. A named compartment inside the cluster. Components install into namespaces (kube-system, longhorn-system), and your applications get their own. Namespaces keep names, permissions and quotas apart.

Service. A stable name and address in front of a set of pods, so other things can reach them while individual pods come and go.

kubectl. The command-line client for the cluster. It talks to the API server, so it works from any machine that has a kubeconfig — a file carrying the cluster’s address and a credential. Installation writes an administrator kubeconfig on the first control-plane node, which is why the kubectl commands in these pages are run there. Reading uses kubectl get and kubectl describe; creating and changing things uses YAML files and kubectl apply -f <file> — a pattern several pages in this documentation use, shown in full in Ingress with Kong.

Helm and charts. Helm is the installer Kubernetes applications are commonly packaged for; a package is a chart, and an installed chart is a release. BKE uses Helm to install the components below. You do not need to operate Helm yourself — apply.sh does — but helm list -A on the first control-plane node shows what is installed, and the release names appear in these pages.

What BKE adds on top

Kubernetes alone gives you a cluster that can run containers. It does not give you storage, a way in for outside traffic, certificates, logs or monitoring. BKE installs those as components, each one a well-known open-source project, pinned to versions tested together:

Component	What it does for you
metrics-server	resource figures — makes kubectl top and autoscaling work
cert-manager	obtains and renews TLS certificates
Longhorn	storage — persistent volumes for applications that keep data
Kong	ingress — routes HTTP traffic from outside the cluster to your applications
Kuma	service mesh — optional traffic control between applications
Fluent Bit	collects logs from every node and ships them to a destination you choose
netdata	monitoring — per-node and per-container metrics and dashboards

Which of these are installed, and how each is configured, is declared in one file: /etc/bke/config.yaml. The config.yaml page walks through it.

Which command runs where

This table is the map for the rest of the documentation. Every page that follows tells you again in context, but it is worth seeing whole once.

Command	Runs on	When
check.sh	every node	before installing or upgrading that node
register.sh	the machine that will be the first control-plane node	once per cluster, before anything is installed
install.sh --role master	the first control-plane node	once — this creates the cluster
install.sh --role worker	every other node, workers and additional control-plane nodes	once per node
kubeadm join	each new node, with a token minted on the first control-plane node	once per node, after its install.sh
apply.sh	one control-plane node	after the nodes have joined, and again whenever config.yaml changes
upgrade.sh --role first	one control-plane node	each upgrade, first
upgrade.sh --role other	every remaining node, one at a time	each upgrade, after the first
version.sh	any node	whenever you want to know what it is running

Two points that save confusion later:

• install.sh --role worker is also how an additional control-plane node is provisioned. The role tells the script whether to create a cluster, and only the very first node does that. What makes the node a control-plane member is the join command it runs afterwards — Adding nodes shows both forms.
• apply.sh is run once per cluster, not once per node. It installs components into the cluster through the API server, so running it from one control-plane node reaches everything.

The files on a node

Everything BKE reads on a machine lives under /etc/bke/:

Path	What it is	Which nodes have it
/etc/bke/license	your licence token, mode 0600	the first control-plane node
/etc/bke/config.yaml	the description of your cluster	the first control-plane node
/etc/bke/secrets.d/	credentials for components, one directory per Secret	the control-plane node you run apply.sh on
/etc/bke/values/	per-component configuration files — yours to edit	the control-plane node you run apply.sh on
/etc/bke/version	a record of the BKE version this node was provisioned at	every node

The whole journey

An installation, start to finish, in the order the pages describe it:

1. Prepare — read Before you begin, run check.sh on every machine.
2. Register — bind your licence to the first control-plane node.
3. Create — install.sh --role master on that node.
4. Join — install.sh --role worker and kubeadm join on every other node.
5. Describe — write /etc/bke/config.yaml, and place credentials in /etc/bke/secrets.d/.
6. Install components — apply.sh, read the report, then --commit.
7. Keep it current — Upgrading covers moving between BKE versions.

Reference architecture, further on, shows the production shape around the cluster — load balancers, where traffic enters, and which addresses must outlive individual machines. Reading it before you choose hostnames and the control-plane endpoint will spare you the two decisions that are hardest to change afterwards.