ironcore-dev · afritzler · Jun 27, 2025 · Jun 27, 2025
@@ -1 +1,25 @@
-# Cloud Controller Manager (CCM) for IronCore Bare Metal
+# Cloud Controller Manager
+
+[Cloud-Controller-Manager](https://kubernetes.io/docs/concepts/architecture/cloud-controller) (CCM) is the bridge
+between Kubernetes and a cloud-provider. CCM uses the cloud-provider (IronCore Bare Metal API in this case) API to manage these
+resources. We have implemented the [cloud provider interface](https://github.com/kubernetes/cloud-provider/blob/master/cloud.go)
+in the [`cloud-provider-metal`](https://github.com/ironcore-dev/cloud-provider-metal) repository.
+Here's a more detail on how these APIs are implemented in the IronCore bare metal cloud-provider for different objects.
+
+## Node lifecycle
+
+### InstanceExists
+
+`InstanceExists` checks if a node with the given name exists in the cloud provider. In IronCore bare metal a `Node`
+is represented by a `ServerClaim` object. The `InstanceExists` method checks if a `ServerClaim` with the given name exists.
+
+### InstanceShutdown
+
+`InstanceShutdown` checks if a node with the given name is shutdown in the cloud provider. Here, the instane controller
+checks if the `ServerClaim` and the claimed `Server` object are in the `PowerOff` state.
+
+### InstanceMetadata
+
+`InstanceMetadata` retrieves the metadata of a node with the given name. In IronCore bare metal, this method retrieves
+the topology labels from a `Server` object which is claimed by the `ServerClaim` of the node. Additional labels of the
+`Server` object are also added to the node object.
@@ -1,25 +1,29 @@
 # Cloud Controller Manager
 
-<a href="https://kubernetes.io/docs/concepts/architecture/cloud-controller/">Cloud-controller-manager</a> (CCM) is the bridge between Kubernetes and a cloud-provider. CCM is responsible for managing cloud-specific infrastructure resources such as `Routes`, `LoadBalancer` and `Instances`.
-CCM uses the cloud-provider (IronCore in this case) APIs to manage these resources.
-We have implemented the <a href="https://github.com/kubernetes/cloud-provider/blob/master/cloud.go">cloud provider interface</a> in the <a href="https://github.com/ironcore-dev/cloud-provider-ironcore">cloud-provider-ironcore</a> repository. 
-Here's a more detail on how these APIs implemented in IronCore cloud-provider for different objects.
-
+[Cloud-Controller-Manager](https://kubernetes.io/docs/concepts/architecture/cloud-controller) (CCM) is the bridge 
+between Kubernetes and a cloud-provider. CCM is responsible for managing cloud-specific infrastructure resources such 
+as `Routes`, `LoadBalancer` and `Instances`. CCM uses the cloud-provider (IronCore in this case) APIs to manage these 
+resources. We have implemented the [cloud provider interface](https://github.com/kubernetes/cloud-provider/blob/master/cloud.go)
+in the [`cloud-provider-ironcore`](https://github.com/ironcore-dev/cloud-provider-ironcore) repository. 
+Here's a more detail on how these APIs are implemented in the IronCore IaaS cloud-provider for different objects.
 
 ## Node lifecycle
-The Node Controller within the CCM ensures that the Kubernetes cluster has an accurate and up-to-date view of the available nodes and their status, by interacting with cloud-provider's API. This allows Kubernetes to manage workloads effectively and leverage cloud provider resources. 
 
-Below is the detailed explanation on how APIs are implemented by cloud-provider-ironcore for Node instance.
+The Node Controller within the CCM ensures that the Kubernetes cluster has an up-to-date view of the available `Nodes` 
+and their status, by interacting with cloud-provider's API. This allows Kubernetes to manage workloads effectively and 
+leverage cloud provider resources. 
+
+Below is the detailed explanation on how APIs are implemented by `cloud-provider-ironcore` for `Node` instance.
 
-**Instance Exists**
+### Instance Exists
 
-- InstanceExists method checks for the node existence. `Machine` object from IronCore represents the `Node` instance.
+- `InstanceExists` method checks for the node existence. `Machine` object from IronCore represents the `Node` instance.
 
-**Instance Shutdown**
+### Instance Shutdown
 
-- InstanceShutdown checks if the node instance is in shutdown state
+- `InstanceShutdown` checks if the node instance is in shutdown state
 
-**Instance Metadata**
+### Instance Metadata
 
 InstanceMetadata returns metadata of a node instance, which includes :
 
@@ -30,50 +34,57 @@
 
 
 ## Load balancing for Services of type LoadBalancer
-`LoadBalancer` service allows external access to Kubernetes services within a cluster, ensuring traffic is distributed effectively. Within the CCM there is a controller that listens for `Service` objects of type `LoadBalancer`. It then interacts with cloud provider specific APIs to provision, configure, and manage the load balancer. Below is the detailed explanation on how APIs are implemented in IronCore cloud-provider.
 
-**Get LoadBalancer Name**
+`LoadBalancer` service allows external access to Kubernetes services within a cluster, ensuring traffic is distributed 
+effectively. Within the CCM there is a controller that listens for `Service` objects of type `LoadBalancer`. It then 
+interacts with cloud provider specific APIs to provision, configure, and manage the load balancer. Below is the detailed
+explanation on how APIs are implemented in IronCore cloud-provider.
 
-- GetLoadBalancerName return LoadBalancer's name based on the service name
+### GetLoadBalancerName
 
-**Ensure LoadBalancer**
+- `GetLoadBalancerName` return LoadBalancer's name based on the service name
 
-- EnsureLoadBalancer gets the LoadBalancer name based on service name.
-- Checks if IronCore `LoadBalancer` object already exists. If not it gets the `port` and `protocol`,  `ipFamily` information from the service and creates new LoadBalancer object in the Ironcore. 
+### Ensure LoadBalancer
+
+- `EnsureLoadBalancer` gets the LoadBalancer name based on service name.
+- Checks if IronCore `LoadBalancer` object already exists. If not it gets the `port` and `protocol`,  `ipFamily` information from the service and creates a new LoadBalancer object in the Ironcore. 
 - Newly created LoadBalancer will be associated with Network reference provided in cloud configuration.
-- Then `LoadBalancerRouting` object is created with the destination IP information retrieved from the nodes (Note: `LoadBalancerRouting` is internal object to Ironcore). Later this information is used at the Ironcore API level to describe the explicit targets in a pool traffic is routed to.
+- Then `LoadBalancerRouting` object is created with the destination IP information retrieved from the nodes (Note: `LoadBalancerRouting` is internal object to Ironcore). Later, this information is used at the Ironcore API level to describe the explicit targets in a pool traffic is routed to.
 - Ironcore supports two types of LoadBalancer `Public` and `Internal`. If LoadBalancer has to be of type Internal, "service.beta.kubernetes.io/ironcore-load-balancer-internal" annotation needs to be set to true, otherwise it will be considered as public type.
 
-**Update LoadBalancer**
+### Update LoadBalancer
 
-- UpdateLoadBalancer gets the `LoadBalancer` and `LoadBalancerRouting` objects based on service name.
+- `UpdateLoadBalancer` gets the `LoadBalancer` and `LoadBalancerRouting` objects based on service name.
 - If there is any change in the nodes(added/removed), LoadBalancerRouting destinations are updated.
 
 
-**Delete LoadBalancer**
+### Delete LoadBalancer
 
 - EnsureLoadBalancerDeleted gets the LoadBalancer name based on service name, check if it exists and deletes it.
 
 ## Managing Routes
-The Route Controller within the CCM is specifically tasked with creating and maintaining network routes within the cloud provider's infrastructure to enable pods on different nodes to communicate. IronCore cloud-provider implements below interfaces to ensure this functionality.
 
-**Creating Routes**
+The Route Controller within the CCM is specifically tasked with creating and maintaining network routes within the cloud
+provider's infrastructure to enable pods on different nodes to communicate. IronCore cloud-provider implements below 
+interfaces to ensure this functionality.
+
+### Creating Routes
 
 - Create route method retrieve the machine object corresponding to the target node name. 
 - Iterates over all target node addresses and identify the matching network interface using internal IPs.
-- If a matching network interface is found, proceed with finding prefix. If prefix already exist that means route is already present.
-- If the prefix is not found, adds it to the network interface specification.
+- If a matching network interface is found, proceed with finding prefix. If a prefix already exists, that means the route is already present.
+- If the prefix is not found, add it to the network interface specification.
 
-**Deleting Route**
+### Deleting Route
 
-- Delete route method retrieve the machine object corresponding to the target node name. 
+- Delete route method retrieves the machine object corresponding to the target node name. 
 - Then iterates over all target node addresses and identify the matching network interface using internal IPs.
 - If a matching network interface is found, attempt to remove the prefix.
-- Checks for the prefix in the network interface's spec and remove it if present.
+- Check for the prefix in the network interface's spec and remove it if present.
 
-**List Routes**
+### List Routes
 
 - List route method retrieves all the network interfaces matching the given namespace, network, and cluster label.
-- Iterates over each network interface and compile route information based on its prefixes.
+- Iterates over each network interface and compiles route information based on its prefixes.
 - It also verifies that the network interface is associated with a machine reference and retrieves node addresses based on the machine reference name. 
-- Based on all the collected information(Name, DestinationCIDR, TargetNode, TargetNodeAddresses) `Route` list is returned.
+- Based on all the collected information (Name, DestinationCIDR, TargetNode, TargetNodeAddresses) `Route` list is returned.
@@ -47,22 +47,18 @@ explanation of how the APIs are implemented in the IronCore CSI driver for diffe
 
 ### Volume Creation
 
-**CreateVolume**
-
-- CreateVolume method is called when a new PersistentVolumeClaim is created
+- `CreateVolume` method is called when a new `PersistentVolumeClaim` is created
 - Validates the storage class parameters and volume capabilities
-- Creates a new Volume object in IronCore with specified parameters
-- Sets up the volume with appropriate size, access mode, and other configurations
-- Returns a unique volume ID that will be used to identify the volume in subsequent operations
+- Create a new `Volume` object in IronCore with specified parameters
+- Set up the volume with the appropriate size, access mode, and other configurations
+- Returns a unique volume ID that will be used to identify the volume in later operations
 
 ### Volume Deletion
 
-**DeleteVolume**
-
-- DeleteVolume method is called when a PersistentVolume is deleted
-- Retrieves the volume using the volume ID
+- `DeleteVolume` method is called when a `PersistentVolume` is deleted
+- Retrieve the volume using the volume ID
 - Performs cleanup operations if necessary
-- Deletes the Volume object from IronCore
+- Delete the `Volum`e object from IronCore
 - Ensures all associated resources are properly cleaned up
 
 ## Node Operations
@@ -71,21 +67,17 @@ The CSI driver runs as a node plugin on each Kubernetes node to handle volume mo
 
 ### Volume Publishing
 
-**NodePublishVolume**
-
-- NodePublishVolume is called when a volume needs to be mounted on a node
+- `NodePublishVolume` is called when a volume needs to be mounted on a node
 - Validates the volume capabilities and access mode
-- Creates the necessary mount point on the node
+- Create the necessary mount point on the node
 - Mounts the volume using the appropriate filesystem
-- Sets up the required permissions and mount options
+- Set up the required permissions and mount options
 
 ### Volume Unpublishing
 
-**NodeUnpublishVolume**
-
-- NodeUnpublishVolume is called when a volume needs to be unmounted from a node
+- `NodeUnpublishVolume` is called when a volume needs to be unmounted from a node
 - Unmounts the volume from the specified mount point
-- Cleans up any temporary files or directories
+- Clean up any temporary files or directories
 - Ensures the volume is properly detached from the node
 
 ## Controller Operations
@@ -94,30 +86,24 @@ The CSI driver also runs as a controller plugin to manage volume provisioning an
 
 ### Volume Attachment
 
-**ControllerPublishVolume**
-
-- ControllerPublishVolume is called when a volume needs to be attached to a node
+- `ControllerPublishVolume` is called when a volume needs to be attached to a node
 - Validates the node information and volume capabilities
-- Attaches the volume to the specified node
+- Attaches the `Volume` to the specified node
 - Returns the device path that will be used for mounting
 
 ### Volume Detachment
 
-**ControllerUnpublishVolume**
-
-- ControllerUnpublishVolume is called when a volume needs to be detached from a node
+- `ControllerUnpublishVolume` is called when a volume needs to be detached from a node
 - Detaches the volume from the specified node
-- Performs any necessary cleanup operations
+- Perform any necessary cleanup operations
 - Ensures the volume is properly detached before returning
 
 ## Volume Expansion
 
 The CSI driver supports online volume expansion (if allowed by the `StorageClass`), allowing volumes to be resized without downtime.
 
-**ExpandVolume**
-
-- ExpandVolume is called when a volume needs to be resized
+- `ExpandVolume` is called when a volume needs to be resized
 - Validates the new size and volume capabilities
-- Resizes the volume in IronCore
-- Updates the filesystem if necessary
+- Resizes the `Volume` in IronCore
+- Update the filesystem if necessary
 - Returns the new size of the volume