Skip to content

INSTALL.md

Latest commit

 

History

History
147 lines (105 loc) · 5.84 KB

INSTALL.md

File metadata and controls

147 lines (105 loc) · 5.84 KB
Raw

Install Guide

Last verified against: Kairos v3.6.0+, CAPI v1.13.3, cert-manager v1.15+, provider v0.1.0-beta.1.

Two install paths: the released artifact (recommended for users) and a developer install from source.

Path 1 — Released artifact (kubectl apply)

Use this if you want to consume a tagged release.

Prerequisites

  1. A Kubernetes cluster acting as the management cluster (kind, EKS, GKE, AKS, etc.).
  2. cert-manager v1.15+ installed. Verify it is present before continuing: 
    kubectl get crd certificates.cert-manager.io
    If not installed: 
    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.2/cert-manager.yaml
kubectl wait --for=condition=Available --timeout=2m -n cert-manager deploy/cert-manager-webhook
  3. Cluster API core v1.13.3+ installed. Easiest path: 
    kubectl apply -f https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.13.3/cluster-api-components.yaml
    Or use clusterctl init --infrastructure docker (or vsphere, kubevirt, ...) if you already have clusterctl configured — clusterctl init installs Cluster API core as a side effect of installing the infrastructure provider.
  4. kubectl configured to use the management cluster.

Install

kubectl apply -f https://github.com/kairos-io/cluster-api-provider-kairos/releases/download/v0.1.0-beta.1/kairos-capi-provider.yaml

This applies the all-in-one provider manifest: CRDs, RBAC, webhook configurations, and the controller Deployment in the kairos-capi-system namespace.

Verify

kubectl get pods -n kairos-capi-system
kubectl get crds | grep kairos

Expected: one Deployment kairos-capi-controller-manager in kairos-capi-system with status Available, and four CRDs:

  • kairosconfigs.bootstrap.cluster.x-k8s.io
  • kairosconfigtemplates.bootstrap.cluster.x-k8s.io
  • kairoscontrolplanes.controlplane.cluster.x-k8s.io
  • kairoscontrolplanetemplates.controlplane.cluster.x-k8s.io

Uninstall

kubectl delete -f https://github.com/kairos-io/cluster-api-provider-kairos/releases/download/v0.1.0-beta.1/kairos-capi-provider.yaml

Re-install note: if you are re-installing across a name-prefix change or a previous failed install, stale MutatingWebhookConfiguration and ValidatingWebhookConfiguration objects from the previous install may point at a webhook Service that no longer exists. Delete them before re-installing:

kubectl get mutatingwebhookconfigurations | grep kairos
kubectl get validatingwebhookconfigurations | grep kairos
# Delete any stale entries before re-applying
kubectl delete mutatingwebhookconfiguration <stale-name>
kubectl delete validatingwebhookconfiguration <stale-name>

Path 2 — Developer install (from source)

Use this if you are hacking on the provider itself.

Prerequisites

  • Go toolchain 1.26.3 (matches go.mod directive go 1.26.0 / toolchain go1.26.0).
  • A Kubernetes cluster acting as the management cluster.
  • cert-manager and Cluster API core installed (same as Path 1).
  • kubectl configured to use the management cluster.

Install

git clone https://github.com/kairos-io/cluster-api-provider-kairos.git
cd cluster-api-provider-kairos
make deploy

This installs CRDs, RBAC, webhooks, and the controller to the kairos-capi-system namespace. The controller uses the image from IMG (default: ghcr.io/kairos-io/cluster-api-provider-kairos:latest). To use a different image:

IMG=MY_REGISTRY/cluster-api-provider-kairos:dev make deploy

CRD installation note: make deploy uses kustomize build config/crd | kubectl apply -f -, which applies kustomize-managed labels that CAPI's conversion webhook expects (cluster.x-k8s.io/v1beta1, cluster.x-k8s.io/v1beta2). If you apply raw CRD YAML via kubectl apply -f config/crd/bases/, those labels are absent and CAPI core may reject the CRDs. Use make deploy or bin/kustomize build config/crd | kubectl apply -f -.

Run the controller on your host (optional)

To run the controller on your host instead of deploying to the cluster:

make install     # installs only the CRDs via kustomize
make run         # runs the controller in the foreground against your kubeconfig

Uninstall

make undeploy
make uninstall

Network reachability requirement for non-CAPK infrastructure

Starting with v0.1.0-alpha.2 (carried forward in v0.1.0-beta.1), the controller no longer SSHes into nodes to retrieve the workload kubeconfig. Instead, control-plane nodes POST their kubeconfig back to a Secret in the management cluster.

Workload nodes running on non-CAPK infrastructure (CAPV / CAPM3 / Tinkerbell and any future provider) must have network reachability to the management cluster's API server URL. This includes bare-metal nodes provisioned via Metal3 — they POST their kubeconfig to a Secret in the management cluster. Verify reachability from a sample workload node before deploying:

curl -k https://<mgmt-api-server-host>:6443/api

For air-gapped or strictly-segmented network environments, enable the opt-in SSHFallback mechanism on the KairosControlPlane. This requires a host-key-verified SSH identity Secret and a known_hosts Secret. See QUICKSTART_CAPV.md — Air-gapped fallback for the full configuration steps.

Next steps

For the current release status, breaking changes, and security caveats, read the v0.1.0-beta.1 release notes.