Beskar7 is a Kubernetes operator that implements the Cluster API infrastructure provider contract for managing bare-metal machines using the Redfish API. It allows you to provision and manage the lifecycle of Kubernetes clusters on physical hardware directly through Kubernetes-native APIs.

Beskar7 now automatically detects and handles vendor-specific hardware quirks! Dell, HPE, Lenovo, and Supermicro systems with zero configuration. (until bugs are found :D ) (automatic detection is still experimental)

• Dell PowerEdge: Automatic BIOS attribute handling (testing advised following microcode upgrades)
• HPE ProLiant: UEFI Target Boot Override
• Lenovo ThinkSystem: UEFI with intelligent BIOS fallback
• Supermicro: UEFI and BIOS-attribute methods (fallback behavior depends on BMC)

Quick Start Guide → | Detailed Documentation →

Alpha: This project is currently under active development. Key features are being implemented, and the APIs may change. Not yet suitable for production use.

• Provisioning Modes: RemoteConfig, PreBakedISO, PXE, iPXE
• OS Families: Kairos (recommended), Flatcar, openSUSE Leap Micro
• Boot Modes: UEFI (recommended), Legacy BIOS
• Vendor Support: Dell, HPE, Lenovo, Supermicro (automatic detection experimental)
• ✅ Hardware Management: Power control, boot configuration, status monitoring
• ✅ Cluster API Integration: Full CAPI provider implementation

To prepare for real hardware testing, ensure you configure reconciliation timeouts via flags or env (see docs/state-management.md) and follow the testing instructions below.

Comprehensive documentation is available in the docs/ directory:

• Getting Started - Complete documentation index and navigation
• Quick Start Guide - Get up and running quickly
• API Reference - Complete API documentation
• Hardware Compatibility - Vendor support matrix
• PXE/iPXE Setup Guide - Infrastructure requirements for network boot
• Deployment Best Practices - Production deployment guidance
• Troubleshooting - Common issues and solutions

Beskar7 consists of several custom controllers that work together:

• PhysicalHost Controller: Manages individual bare-metal hosts discovered via Redfish. It handles Redfish connections, monitors host status (power, health), and performs low-level actions like setting boot devices and powering the host on/off. It exposes the host's state (Available, Provisioning, Provisioned, Error, etc.).
• Beskar7Machine Controller: Represents the infrastructure for a specific Cluster API Machine. It finds an available PhysicalHost, claims it, configures its boot (ISO URL, kernel parameters for specific OS families), monitors the host's provisioning progress, and updates the Machine object with the providerID and readiness status once the host is provisioned.
• Beskar7Cluster Controller: Represents the infrastructure for a Cluster API Cluster. It is responsible for coordinating cluster-level infrastructure, potentially managing load balancers or setting the ControlPlaneEndpoint based on the provisioned control plane Beskar7Machine resources.

• Go (version 1.25 or later required)
• Docker (for envtest)
• controller-gen (make install-controller-gen)
• kustomize (v4 or later for make deploy)

• A running Kubernetes cluster (e.g., kind, minikube, or a remote cluster) with kubectl configured
• Kubernetes 1.31+
• Helm 3.2.0+ (for Helm installation method)
• Cluster API v1.4.0+ (REQUIRED) - See installation below
• cert-manager (REQUIRED) - See installation below

⚠️ IMPORTANT: Beskar7 is a Cluster API Infrastructure Provider and requires Cluster API core components to be installed first.

Option 1: Using clusterctl (Recommended)

# Install clusterctl
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.10.0/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/

# Initialize Cluster API
clusterctl init

Option 2: Manual Installation

# Install CAPI core components
kubectl apply -f https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.10.0/cluster-api-components.yaml

# Install bootstrap provider (kubeadm)
kubectl apply -f https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.10.0/bootstrap-components.yaml

# Install control plane provider (kubeadm)
kubectl apply -f https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.10.0/control-plane-components.yaml

# Wait for components to be ready
kubectl wait --for=condition=Available --timeout=300s deployment/capi-controller-manager -n capi-system
kubectl wait --for=condition=Available --timeout=300s deployment/capi-kubeadm-bootstrap-controller-manager -n capi-kubeadm-bootstrap-system
kubectl wait --for=condition=Available --timeout=300s deployment/capi-kubeadm-control-plane-controller-manager -n capi-kubeadm-control-plane-system

Verify CAPI installation:

kubectl get pods -n capi-system
kubectl get pods -n capi-kubeadm-bootstrap-system
kubectl get pods -n capi-kubeadm-control-plane-system

Beskar7 requires cert-manager to be installed in your cluster to manage webhook TLS certificates. Install cert-manager and its CRDs before deploying Beskar7:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.crds.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml

Wait for all cert-manager pods to be running:

kubectl wait --for=condition=Available --timeout=300s deployment/cert-manager -n cert-manager
kubectl wait --for=condition=Available --timeout=300s deployment/cert-manager-webhook -n cert-manager
kubectl wait --for=condition=Available --timeout=300s deployment/cert-manager-cainjector -n cert-manager

1. Clone the repository:

   git clone https://github.com/wrkode/beskar7.git
   cd beskar7 

2. Install Development Tools:

   make install-controller-gen

3. Build and Push Container Image (Required for deployment): You need to push the manager image to a container registry accessible by your Kubernetes cluster.

   # Login to GitHub Container Registry (or your chosen registry)
   # export CR_PAT=YOUR_GITHUB_PAT # Use a PAT with write:packages scope
   # echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
   
   # Build and push the image (uses values from Makefile: ghcr.io/wrkode/beskar7/beskar7:${VERSION})
   make docker-build docker-push 

   (Note: If using a different registry/repo/tag, override Makefile variables: make docker-push IMG=my-registry/my-repo:my-tag)

4. Generate Code & Manifests (If you made code changes):

   make manifests

5. Build the Manager (Local Binary - Optional):

   make build

6. Run Tests:

   make test

📝 Note for Repository Maintainers: The Helm chart repository is automatically published to GitHub Pages via the helm-publish.yml workflow when a new tag is pushed. However, GitHub Pages must be manually enabled in the repository settings:

1. Go to Settings → Pages
2. Under Build and deployment, set Source to "Deploy from a branch"
3. Select branch: gh-pages, folder: / (root)
4. Click Save

After enabling, wait 1-2 minutes for GitHub Pages to deploy. The workflow will then automatically update the Helm repository on every new release.

helm repo add beskar7 https://wrkode.github.io/beskar7
helm repo update

# Install with default values
helm install beskar7 beskar7/beskar7 --namespace beskar7-system --create-namespace

# Install with custom values
helm install beskar7 beskar7/beskar7 -f values.yaml --namespace beskar7-system --create-namespace

# Wait for deployment to be ready
kubectl wait --for=condition=available --timeout=600s deployment/beskar7-controller-manager -n beskar7-system

This provides more control if you need to customize the deployment.

1. Build and push the manager image as described in "Getting Started" step 3.
2. Install CRDs:

   make install

3. Apply Base Manifests using Kustomize: Navigate to the directory containing the checked-out code.

   # Apply the default configuration (ensure IMG in Makefile is correct or customize)
   kustomize build config/default | kubectl apply -f -

   Alternatively, create your own Kustomize overlay pointing to config/default and set the image there.

Each GitHub release will include a beskar7-manifests-$(VERSION).yaml file. This bundle contains all necessary CRDs, RBAC, and the Deployment for the controller manager, pre-configured with the correct image for that release.

Important: You must install cert-manager and its CRDs before applying the Beskar7 manifest bundle. See the "Install cert-manager (Required)" section above.

1. Download the release manifest (e.g., beskar7-manifests-${VERSION}.yaml) from the GitHub Releases page.
2. Apply the manifest to your cluster:

   kubectl apply -f beskar7-manifests-${VERSION}.yaml

   This will create the beskar7-system namespace and all required Beskar7 components.

First, create a Kubernetes Secret containing the username and password for your Redfish BMC.

apiVersion: v1
kind: Secret
metadata:
  name: my-bmc-credentials
  namespace: default # Or your target namespace
stringData:
  username: "your-bmc-username"
  password: "your-bmc-password"

kubectl apply -f redfish-credentials-secret.yaml

This resource tells Beskar7 about a physical server it can manage.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: PhysicalHost
metadata:
  name: server-01
  namespace: default
spec:
  redfishConnection:
    address: "https://192.168.1.123" # Replace with your BMC IP/hostname
    credentialsSecretRef: "my-bmc-credentials"
    # insecureSkipVerify: true # Optional: use for self-signed certs, not recommended for production

kubectl apply -f physicalhost.yaml

After a short while, the PhysicalHost should transition to an Available state if the connection is successful:

kubectl get physicalhost server-01 -o wide

If the PhysicalHost doesn't reach Available state, see the Troubleshooting Guide for common issues and solutions.

Beskar7 supports four provisioning modes. Choose the one that fits your infrastructure:

Use this when you have an ISO with OS and configuration pre-built.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: Beskar7Machine
metadata:
  name: node-01
  namespace: default
spec:
  osFamily: "kairos"  # kairos, flatcar, or LeapMicro
  imageURL: "http://example.com/my-kairos-prebaked.iso"
  provisioningMode: "PreBakedISO"
  bootMode: "UEFI"  # UEFI (recommended) or Legacy

Use this with a generic ISO and external configuration URL.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: Beskar7Machine
metadata:
  name: node-02
  namespace: default
spec:
  osFamily: "kairos"  # kairos, flatcar, or LeapMicro
  imageURL: "https://github.com/kairos-io/kairos/releases/download/v2.8.1/kairos-alpine-v2.8.1-amd64.iso"
  provisioningMode: "RemoteConfig"
  configURL: "https://your-server.com/kairos-config.yaml"  # Required for RemoteConfig
  bootMode: "UEFI"

Configuration URL Parameters by OS:

• Kairos: config_url=<ConfigURL>
• Flatcar: flatcar.ignition.config.url=<ConfigURL>
• Leap Micro: combustion.path=<ConfigURL>

Use this with existing PXE infrastructure.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: Beskar7Machine
metadata:
  name: node-03
  namespace: default
spec:
  osFamily: "flatcar"
  imageURL: "http://pxe-server.example.com/flatcar.iso"  # Reference
  provisioningMode: "PXE"
  bootMode: "UEFI"

Prerequisites: DHCP, TFTP, and PXE infrastructure must be configured. See PXE Setup Guide.

Use this with iPXE infrastructure for faster, HTTP-based boot.

apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: Beskar7Machine
metadata:
  name: node-04
  namespace: default
spec:
  osFamily: "kairos"
  imageURL: "http://ipxe-server.example.com/boot.ipxe"  # iPXE script URL
  provisioningMode: "iPXE"
  bootMode: "UEFI"

Prerequisites: DHCP and HTTP server with iPXE scripts. See iPXE Setup Guide.

For complete cluster deployments with multiple nodes, see the examples/ directory:

• Minimal Test Cluster - Single-node testing
• Complete Cluster - Multi-node with HA
• PXE Provisioning - Full PXE cluster
• iPXE Provisioning - Full iPXE cluster
• Examples README - Overview of all examples

Beskar7 supports any Redfish-compliant BMC with automatic vendor detection:

• Dell Technologies (iDRAC9+) - Full support with automatic BIOS attribute handling
• HPE (iLO 5+) - Full support with UEFI Target Boot Override
• Lenovo (XCC) - Full support with intelligent BIOS fallback
• Supermicro (BMC) - Good support, X12+ series recommended

Beskar7 supports the following immutable OS families:

Note: Traditional Linux distributions (Ubuntu, RHEL, CentOS, etc.) are not currently supported. Only immutable, cloud-native OS families with built-in provisioning mechanisms are supported.

For detailed compatibility information, hardware-specific workarounds, and testing procedures, see the Hardware Compatibility Matrix.

For production deployments, review:

• Deployment Best Practices - Security, scaling, and operational guidance
• Troubleshooting Guide - Common issues and vendor-specific solutions
• Metrics Documentation - Monitoring and observability setup

Contributions are welcome! For information about contributing to Beskar7, see the issue tracker at https://github.com/wrkode/beskar7/issues.

For detailed information about the project's current status and future plans, please see the GitHub Issues and GitHub Projects pages.

Before running the tests, you need to download the required CRDs and set up envtest assets. Unit tests and controller tests run without real hardware; integration and emulation tests can be run with build tags.

# Download test CRDs (once)
./hack/download-test-crds.sh

# Set up envtest assets (Kubernetes API server binaries)
export KUBEBUILDER_ASSETS=$(go run sigs.k8s.io/controller-runtime/tools/setup-envtest@latest use 1.31.x -p path)

# Run unit and controller tests
go test ./controllers/... -v -ginkgo.v --timeout=10m
go test ./internal/... -v --timeout=10m

# Run integration tests (envtest) — excludes emulation unless tagged
go test -tags=integration ./test/integration/... -v --timeout=30m

# Optional: Run hardware emulation tests (no real hardware required)
# Note: The emulation tests use a mock Redfish server and skip TLS verification.
go test -tags=integration ./test/emulation/... -v --timeout=30m

The test setup is designed to be portable and work across different systems. All required CRDs are downloaded locally and referenced from the repository, ensuring consistent test behavior across different environments.

helm uninstall beskar7 --namespace beskar7-system

1. Undeploy the controller

   make undeploy

2. Uninstall CRDs

   make uninstall

helm upgrade beskar7 beskar7/beskar7 --namespace beskar7-system

• kairos - Cloud-native, immutable OS (recommended)
• flatcar - Container-optimized Linux
• LeapMicro - openSUSE Leap Micro

• PhysicalHost - Represents a bare-metal server
• Beskar7Machine - CAPI Machine infrastructure
• Beskar7Cluster - CAPI Cluster infrastructure
• Beskar7MachineTemplate - Template for machine configs

• 📖 Complete Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📚 Examples

• ✅ PXE/iPXE Support: Full network boot provisioning modes
• ✅ Boot Mode Control: UEFI and Legacy BIOS support
• ✅ Enhanced Testing: All skipped tests fixed and passing
• ✅ Documentation: Complete alignment with implementation
• ✅ OS Support: Focused on proven immutable OS families (kairos, flatcar, LeapMicro)
• ✅ Hardware Matching: Label-based host selection implemented

See CHANGELOG.md for complete release notes and breaking changes.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.