diff --git a/docs/labs/node-join-bootstrap-token.md b/docs/labs/node-join-bootstrap-token.md new file mode 100644 index 0000000..e2652ca --- /dev/null +++ b/docs/labs/node-join-bootstrap-token.md @@ -0,0 +1,310 @@ +# AKS Flex Node Join Lab + +This lab walks through joining a VM or bare-metal (BM) host to an existing AKS +cluster using [AKS Flex Node](https://github.com/Azure/AKSFlexNode). AKS Flex +Node allows you to extend your AKS cluster beyond Azure by attaching external +compute resources as worker nodes. + +> **Warning:** AKS Flex Node is currently an experimental feature and is subject +> to change. APIs, CLI flags, and behaviors may change without notice in future +> releases. Do not use this in production environments without understanding the +> risks. + +## Prerequisites + +### Create an AKS Cluster + +Create an AKS cluster with Azure AD enabled and fetch the kubeconfig to your +local machine: + +```bash +# Set variables +RESOURCE_GROUP="my-resource-group" +CLUSTER_NAME="my-aks-cluster" + +# Create the AKS cluster +az aks create \ + --resource-group "$RESOURCE_GROUP" \ + --name "$CLUSTER_NAME" + +# Fetch the admin kubeconfig to your local machine +az aks get-credentials \ + --resource-group "$RESOURCE_GROUP" \ + --name "$CLUSTER_NAME" \ + --admin \ + --overwrite-existing +``` + +Verify connectivity: + +```bash +kubectl get nodes +``` + +Expected output: + +``` +NAME STATUS ROLES AGE VERSION +aks-nodepool1-12345678-vmss000000 Ready 5m v1.30.0 +``` + +### Download the aks-flex-node Binary + +Download the latest `aks-flex-node` binary from the +[releases page](https://github.com/Azure/AKSFlexNode/releases) and upload it +to the VM or BM host: + +```bash +# SSH into the target VM / BM host +ssh @ + +# Switch to root and run the install script +curl -LO https://github.com/Azure/AKSFlexNode/releases/download/v0.0.10/aks-flex-node-linux-amd64.tar.gz +sudo su +tar -xzf aks-flex-node-linux-amd64.tar.gz +cp aks-flex-node-linux-amd64 /usr/local/bin/aks-flex-node +chmod +x /usr/local/bin/aks-flex-node + +# Verify installation +aks-flex-node version +``` + +Expected output: + +``` +AKS Flex Node Agent +Version: v0.0.10 +Git Commit: b53bf43 +Build Time: 2026-02-18T22:58:16Z +``` + +## Steps + +In this lab we will join the VM using a kubeadm-style bootstrapping flow. This +flow uses [Kubernetes TLS bootstrapping](https://kubernetes.io/docs/reference/access-authn-authz/kubelet-tls-bootstrapping/) +with bootstrap tokens — the same mechanism that `kubeadm join` relies on. The +node authenticates with a short-lived bootstrap token, obtains a client +certificate via a Certificate Signing Request (CSR), and then uses that +certificate for all subsequent communication with the API server. + +### Cluster Preparation + +This step creates the necessary configuration on the cluster side to allow the +new node to join. You will create a bootstrap token and the required RBAC +bindings so the node can authenticate and register itself. + +Run the following commands from your local machine (where you have `kubectl` +access to the cluster): + +#### 1. Generate a bootstrap token + +```bash +# Generate token components +TOKEN_ID=$(openssl rand -hex 3) +TOKEN_SECRET=$(openssl rand -hex 8) +BOOTSTRAP_TOKEN="${TOKEN_ID}.${TOKEN_SECRET}" + +# Create the bootstrap token secret +kubectl apply -f - < created +``` + +#### 2. Create RBAC bindings + +```bash +# Allow the bootstrap group to create certificate signing requests +kubectl apply -f - < /dev/null <\" not found\n" func="[collector.go:217]" +level=info msg="Collecting managed cluster spec for /" func="[collector.go:115]" +``` + +#### 3. Verify the node joined + +From your local machine, check that the new node appears in the cluster: + +```bash +kubectl get nodes +``` + +Expected output: + +``` +NAME STATUS ROLES AGE VERSION +aks-nodepool1-12345678-vmss000000 Ready 1h v1.30.0 + Ready 30s v1.30.0 +``` + +The new node should appear with `Ready` status after a short time.