{"id":19838508,"url":"https://github.com/metal-stack/cluster-api-provider-metal-stack","last_synced_at":"2026-02-27T13:15:32.887Z","repository":{"id":261218604,"uuid":"883626285","full_name":"metal-stack/cluster-api-provider-metal-stack","owner":"metal-stack","description":"Controllers implementing the Cluster API for metal-stack. Still work in progress.","archived":false,"fork":false,"pushed_at":"2025-02-21T11:52:36.000Z","size":226,"stargazers_count":1,"open_issues_count":9,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-21T12:33:09.213Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metal-stack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-05T09:49:41.000Z","updated_at":"2025-02-21T11:52:37.000Z","dependencies_parsed_at":"2024-11-05T11:38:33.966Z","dependency_job_id":"a77413dc-1df9-4337-9280-9de99992d33f","html_url":"https://github.com/metal-stack/cluster-api-provider-metal-stack","commit_stats":null,"previous_names":["metal-stack/cluster-api-provider-metal-stack"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fcluster-api-provider-metal-stack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fcluster-api-provider-metal-stack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fcluster-api-provider-metal-stack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metal-stack%2Fcluster-api-provider-metal-stack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metal-stack","download_url":"https://codeload.github.com/metal-stack/cluster-api-provider-metal-stack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241203637,"owners_count":19926829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T12:17:59.808Z","updated_at":"2026-02-27T13:15:32.869Z","avatar_url":"https://github.com/metal-stack.png","language":"Go","readme":"# cluster-api-provider-metal-stack\n\nThe Cluster API provider for metal-stack (CAPMS) implements the declarative management of Kubernetes cluster infrastructure on top of [metal-stack](https://metal-stack.io/) using [Cluster API (CAPI)](https://cluster-api.sigs.k8s.io/).\n\n\u003e [!WARNING]\n\u003e As of now the CAPMS is not yet feature complete and there might be breaking changes in future releases.\n\u003e In case you search for a feature stable alternative consider [Gardener on metal-stack](https://docs.metal-stack.io/stable/installation/deployment/#Gardener-with-metal-stack) instead.\n\u003e For developing this project head to our [DEVELOPMENT.md](/DEVELOPMENT.md).\n\nCurrently, we provide the following custom resources:\n\n- [`MetalStackCluster`](./api/v1alpha1/metalstackcluster_types.go) can be used as [infrastructure cluster](https://cluster-api.sigs.k8s.io/developer/providers/contracts/infra-cluster) and ensures that there is a control plane IP for the cluster.\n- [`MetalStackMachine`](./api/v1alpha1/metalstackmachine_types.go) bridges between [infrastructure machines](https://cluster-api.sigs.k8s.io/developer/providers/contracts/infra-machine) and metal-stack machines.\n- [`MetalStackMachineTemplate`](./api/v1alpha1/metalstackmachinetemplate_types.go) can be used to define reusable machine specifications for `MetalStackMachine` resources.\n- [`MetalStackFirewallDeployment`](./api/v1alpha1/metalstackfirewalldeployment_types.go) can be used to define firewall deployments for a cluster.\n- [`MetalStackFirewallTemplate`](./api/v1alpha1/metalstackfirewalltemplate_types.go) defines the configuration of deployed firewalls.\n\nWe plan to cover more resources in the future:\n\n- Complete Firewall Deployments using the [Firewall Controller Manager](https://github.com/metal-stack/firewall-controller-manager)\n- Improved configuration suggestion of CNIs\n\n\u003e [!note]\n\u003e Currently our infrastructure provider is only tested against the [Cluster API bootstrap provider Kubeadm (CABPK)](https://cluster-api.sigs.k8s.io/tasks/bootstrap/kubeadm-bootstrap/index.html?highlight=kubeadm#cluster-api-bootstrap-provider-kubeadm).\n\u003e While other providers might work, there is no guarantee nor the goal to reach compatibility.\n\n## Getting started\n\n**Prerequisites:**\n\n- Running metal-stack installation. See our [installation](https://docs.metal-stack.io/stable/installation/deployment/) section on how to get started with metal-stack.\n- Operating system images available to metal-stack. See [metal-stack/metal-images](https://github.com/metal-stack/metal-images) for pre-built ones.\n- Management cluster (with network access to the metal-stack infrastructure).\n- CLI metalctl installed for communicating with the metal-api. Installation instructions can be found in the corresponding [repository](https://github.com/metal-stack/metalctl).\n- CLI clusterctl\n\nFirst, add the metal-stack infrastructure provider to your `clusterctl.yaml`:\n\n```yaml\n# ~/.config/cluster-api/clusterctl.yaml\nproviders:\n  - name: \"metal-stack\"\n    url: \"https://github.com/metal-stack/cluster-api-provider-metal-stack/releases/latest/download/infrastructure-components.yaml\"\n    type: InfrastructureProvider\n```\n\nNow, you are able to install the CAPMS into your management cluster:\n\n```bash\n# export the following environment variables\nexport METAL_API_URL=\u003curl\u003e\nexport METAL_API_HMAC=\u003chmac\u003e\nexport METAL_API_HMAC_AUTH_TYPE=\u003cMetal-Admin or Metal-Edit\u003e\nexport EXP_KUBEADM_BOOTSTRAP_FORMAT_IGNITION=true\n\n# initialize the management cluster\nclusterctl init --infrastructure metal-stack\n```\n\n\u003e [!CAUTION]\n\u003e **Manual steps needed:**\n\u003e Due to the early development stage, manual actions are needed for the cluster to operate. Some metal-stack resources need to be created manually.\n\nAllocate a VIP for the control plane.\n\n```bash\nexport CLUSTER_NAME=\u003ccluster-name\u003e\nexport METAL_PARTITION=\u003cpartition\u003e\nexport METAL_PROJECT_ID=\u003cproject-id\u003e\n\nexport CONTROL_PLANE_IP=$(metalctl network ip create --network internet --project $METAL_PROJECT_ID --name \"$CLUSTER_NAME-vip\" --type static -o template --template \"{{ .ipaddress }}\")\n```\n\nFor your first cluster, it is advised to start with our generated template. Ensure that the namespaced cluster name is unique within the metal stack project.\n\n```bash\n# display required environment variables\nclusterctl generate cluster $CLUSTER_NAME --infrastructure metal-stack --list-variables --flavor calico\n\n# set additional environment variables\nexport CONTROL_PLANE_MACHINE_IMAGE=\u003cmachine-image\u003e\nexport CONTROL_PLANE_MACHINE_SIZE=\u003cmachine-size\u003e\nexport WORKER_MACHINE_IMAGE=\u003cmachine-image\u003e\nexport WORKER_MACHINE_SIZE=\u003cmachine-size\u003e\nexport FIREWALL_MACHINE_IMAGE=\u003cmachine-image\u003e\nexport FIREWALL_MACHINE_SIZE=\u003cmachine-size\u003e\n\n# generate manifest\nclusterctl generate cluster $CLUSTER_NAME --kubernetes-version v1.32.9 --infrastructure metal-stack --flavor calico\n```\n\nApply the generated manifest from the `clusterctl` output.\n\n```bash\nkubectl apply -f \u003cmanifest\u003e\n```\n\nThat's it!\n\n## Frequently Asked Questions\n\n### I need to know the Control Plane IP address in advance. Can I provide a static IP address in advance?\n\nYes, simply create a static IP address and set it to `metalstackcluster/$CLUSTER_NAME.spec.controlPlaneIP`.\n\n```bash\nmetalctl network ip create --name $CLUSTER_NAME-vip --project $METAL_PROJECT_ID --type static\n```\n\n### I'd like to have a specific Pod CIDR. How can I achieve this?\n\nWhen generating your cluster, set `POD_CIDR` to your desired value.\n\n```bash\nexport POD_CIDR=[\"10.240.0.0/12\"]\n```\n\n## I'd like to update the firewall and / or its rules. How can I achieve this?\n\nUnfortunately there is no automated way to update firewall deployments or rules yet. You have to manually edit the `MetalStackFirewallDeployment` resource to force it to create a new firewall.\n\n1. Save the firewall machine ID stored in `MetalStackFirewallDeployment.spec.managedResourceRef.name`.\n2. Update the `MetalStackFirewallTemplate` as desired.\n3. Remove `MetalStackFirewallDeployment.spec.managedResourceRef`.\n4. Wait for CAPMS to create the new firewall.\n5. Wait for the new firewall to be in `Phoned Home` state using `metalctl machine list --id \u003cnew-id\u003e`.\n6. Delete the old firewall machine using `metalctl machine delete \u003cold-id\u003e` as soon as possible.\n\nThis leads to a minimized downtime of the cluster as the firewall is not available during the transition.\n\n## Flavors\n\nYou might choose from different cluster template [flavors](https://cluster-api.sigs.k8s.io/clusterctl/commands/generate-cluster.html?highlight=flavor#flavors) to generate manifests with clusterctl. Here is a table describing the available flavors:\n\n| Name      | Description                                                                                                                                                                                                                                                                            | K8s Compatibility |\n| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |\n|           | This is the default flavor without providing the `--flavor` flag. This expects the user to deploy a CNI and a CCM.                                                                                                                                                                     | \u003e= v1.33          |\n| calico    | Installs [calico](https://docs.tigera.io/calico/latest/about/) CNI along with [metal-ccm](https://github.com/metal-stack/metal-ccm). Depends on `ClusterResourceSet` and the [Add-on Provider for Helm](https://github.com/kubernetes-sigs/cluster-api-addon-provider-helm/tree/main). | \u003e= v1.33          |\n| pre-v1.33 | The same as the default flavor but working for K8s versions \u003c v1.33.                                                                                                                                                                                                                   | \u003c v1.33           |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fcluster-api-provider-metal-stack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetal-stack%2Fcluster-api-provider-metal-stack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetal-stack%2Fcluster-api-provider-metal-stack/lists"}