metalkast

Appearance

Get started ​

This guide will help you deploying a basic Kubernetes cluster on your bare metal machines.

IMPORTANT

The current setup requires a working DHCP server configured to assign IPs and nameservers to target nodes.

Install kast binary ​

You can install kast binary from source with Go toolchain.

shell
go install github.com/metalkast/metalkast/cmd/kast@latest

Install ipmitool ​

Install ipmitool based on the operating system you're running.

MacOS

shell
brew install ipmitool

Ubuntu

shell
apt-get install -y ipmitool

Prepare manifests ​

To use kast, you'll first need to prepare ClusterAPI and system manifests.

Cluster manifests ​

Create a kustomization layer in manifests/cluster/deployments/<cluster> directory and use the example below as reference for your configuration.

To use metalkast prebuilt Kubernetes cluster images, you can include preconfigured k8s-cluster-version ConfigMap like in the example below. You can find the list of all published releases on Image Releases page.

yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - https://dl.metalkast.io/node-images/k8s-v1.29.1-ubuntu-22.04-20230719-amd64-9a797a0/config.yaml
  - nodes-secrets.yaml
  - nodes.yaml

configMapGenerator:
  - name: metalkast.io/cluster-config
    options:
      annotations:
        config.kubernetes.io/local-config: "true"
    literals:
      - control_plane_hostname=
      - control_plane_ip=

components:
  - https://github.com/metalkast/metalkast//manifests/cluster/base?ref=accb8b1d651a8dda29f4629e29cdb6309aa19bcf
  - https://github.com/metalkast/metalkast//manifests/cluster/components/disable-certificate-verification?ref=accb8b1d651a8dda29f4629e29cdb6309aa19bcf

Configure hosts ​

Create secret(s) with metalkast.io/redfish-urls annotation set to Redfish URLs of the hosts you want to join the cluster and Redfish login credentials. Make sure to include the secrets in cluster's manifests. The example is encrypted with sops.

yaml
apiVersion: v1
kind: Secret
metadata:
    name: redfish-creds-k8s-nodes
    namespace: capi-clusters
    annotations:
        metalkast.io/redfish-urls: |-
            https://192.168.122.101
            https://192.168.122.102
            https://192.168.122.103
stringData:
    username: ENC[AES256_GCM,data:QI0kY2A=,iv:2j+/bN5hlQCkum4eRBRS/bsLhgL0Lpy/A3t4c6OsHVs=,tag:BG2BonEt9HuuASIS7FJSag==,type:str]
    password: ENC[AES256_GCM,data:FYN68wvofxI=,iv:WobUB1qMSqvbho5qZMC3mVztY6vNFVHXTZ9Yr4YqkHo=,tag:YWvLtJJY3fUqm6Wo+lnZMA==,type:str]
type: Opaque
sops:
    kms: []
    gcp_kms: []
    azure_kv: []
    hc_vault: []
    age:
        - recipient: age1dk25phcnxzhkryzn7smn29wa4lhsplgvty3skzddr2w5plsh0ddq04ukv3
          enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA5RHJrUTAzdzhlZWNWM2lr
            dHFSc2o1dE53aTdXRldDcm9iWVdibHRueVJRCncxREpmejFESTB1d1YxQkh5c2Vu
            TUM5bmh4NXd3Yjl1SUVwcUtYYml5ME0KLS0tIG0wMS9SNitoMUkvZ0g5d2dVcWVu
            bG5GWHZkZXBHclZmREpGbjRidjgzaDAKvDAV+HePfd5UcsRm8KyxHkn4YCAJVkFK
            W3Dq8cEOE7yqWww7Uv7RxXbFO+C+3qS7tCjADEShc7cIfk+Z9QTmSg==
            -----END AGE ENCRYPTED FILE-----
    lastmodified: "2024-02-19T19:33:47Z"
    mac: ENC[AES256_GCM,data:u8tyz65Vk2waDWue0g1mR3CHwnuPyx7AY0+Ptu9fg6cYiQT9iAOxQoZXadHcS7zQZiRb829CoubHerF45l60JtoTY7+nj/igki0GYmA43pZTOEsrUL5+8szmq5+KxyAzs6HzPI+6zCSUoiVg++l6SBDOPa0DsESpYM5VkARFlqI=,iv:69CmLCoY4tiASzdoMyoP5Is8deoto7P8pJiJSg0vPLM=,tag:79zTirH+DyAP1Hn9CFq7ww==,type:str]
    pgp: []
    encrypted_regex: ^(data|stringData)$
    version: 3.7.3

Configure system manifests ​

Create a kustomization layer in manifests/system/deployments/<cluster> directory and use the example below are reference for your configuration.

yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

configMapGenerator:
  - name: metalkast.io/system-config
    options:
      annotations:
        config.kubernetes.io/local-config: "true"
    literals:
      - ingress_ip=
      - ingress_domain=


components:
  - https://github.com/metalkast/metalkast//manifests/system/base?ref=accb8b1d651a8dda29f4629e29cdb6309aa19bcf
  - https://github.com/metalkast/metalkast//manifests/system/base/ironic/components/insecure?ref=accb8b1d651a8dda29f4629e29cdb6309aa19bcf
  - https://github.com/metalkast/metalkast//manifests/system/base/cilium/components/issuers/self-signed?ref=accb8b1d651a8dda29f4629e29cdb6309aa19bcf

Generate hosts manifests ​

Generate BareMetalHosts manifests and make sure to include them in cluster's manifests.

shell
kast generate \
  manifests/cluster/deployments/<cluster>/nodes-secrets.yaml \
  manifests/cluster/deployments/<cluster>/nodes.yaml

Bootstrap the cluster ​

Finally, run the bootstrap. This can take up to an hour depending on your hardware.

shell
kast bootstrap \
  manifests/system/deployments/<cluster> \
  manifests/cluster/deployments/<cluster>