From e021236d84528fb90dd0a430d8a886874ceff88b Mon Sep 17 00:00:00 2001 From: Andreas Fritzler Date: Fri, 27 Jun 2025 15:15:55 +0200 Subject: [PATCH] Add documentation for bare metal ccm --- .../kubernetes/cloud-controller-manager.md | 26 ++++++- .../kubernetes/cloud-controller-manager.md | 75 +++++++++++-------- docs/iaas/kubernetes/csi-driver.md | 52 +++++-------- 3 files changed, 87 insertions(+), 66 deletions(-) diff --git a/docs/baremetal/kubernetes/cloud-controller-manager.md b/docs/baremetal/kubernetes/cloud-controller-manager.md index 087090d..14fd487 100644 --- a/docs/baremetal/kubernetes/cloud-controller-manager.md +++ b/docs/baremetal/kubernetes/cloud-controller-manager.md @@ -1 +1,25 @@ -# Cloud Controller Manager (CCM) for IronCore Bare Metal \ No newline at end of file +# 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. diff --git a/docs/iaas/kubernetes/cloud-controller-manager.md b/docs/iaas/kubernetes/cloud-controller-manager.md index 0e11d25..24b3f01 100644 --- a/docs/iaas/kubernetes/cloud-controller-manager.md +++ b/docs/iaas/kubernetes/cloud-controller-manager.md @@ -1,25 +1,29 @@ # Cloud Controller Manager -Cloud-controller-manager (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 in the cloud-provider-ironcore 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 @@ InstanceMetadata returns metadata of a node instance, which includes : ## 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. diff --git a/docs/iaas/kubernetes/csi-driver.md b/docs/iaas/kubernetes/csi-driver.md index 0782186..1402323 100644 --- a/docs/iaas/kubernetes/csi-driver.md +++ b/docs/iaas/kubernetes/csi-driver.md @@ -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