mirror of
https://github.com/outbackdingo/talos-cloud-controller-manager.git
synced 2026-01-27 10:20:27 +00:00
docs: split readme file
Update installation instructions. Add controllers explanations. Signed-off-by: Serge Logvinov <serge.logvinov@sinextra.dev>
This commit is contained in:
Serge Logvinov
103
README.md
103
README.md
@@ -13,38 +13,26 @@ If you have multiple cloud controllers installed in a single cluster, it's possi
|
||||
|
||||
Talos CCM tries to solve these issues and helps you to launch multiple CCMs in one cluster.
|
||||
|
||||
## Features
|
||||
## Controllers
|
||||
|
||||
### Node initialize
|
||||
Support controllers:
|
||||
|
||||
Talos CCM receives the metadata from the Talos platform resource and applies labels to the nodes during the initialization process.
|
||||
* cloud-node
|
||||
* Updates node resource with cloud metadata
|
||||
* Assigns labels and taints based on cloud metadata and configuration
|
||||
* cloud-node-lifecycle
|
||||
* Cleans up node resource when cloud instance is deleted.
|
||||
* node-ipam
|
||||
* Manages the allocation and assignment of CIDR addresses to pods across the nodes in a Kubernetes cluster.
|
||||
* csr-approval
|
||||
* Automatically approves Certificate Signing Requests (CSRs) for kubelet server certificates.
|
||||
|
||||
Well-Known [labels](https://kubernetes.io/docs/reference/labels-annotations-taints/):
|
||||
* topology.kubernetes.io/region
|
||||
* topology.kubernetes.io/zone
|
||||
* node.kubernetes.io/instance-type
|
||||
|
||||
Talos specific labels:
|
||||
* node.cloudprovider.kubernetes.io/clustername - talos cluster name
|
||||
* node.cloudprovider.kubernetes.io/platform - name of platform
|
||||
* node.cloudprovider.kubernetes.io/lifecycle - spot instance type
|
||||
|
||||
Node specs:
|
||||
* providerID magic string
|
||||
* InternalIP and ExternalIP addresses
|
||||
|
||||
### Node certificate approval
|
||||
|
||||
Talos CCM is responsible for validating a node's certificate signing request (CSR) and approving it.
|
||||
When a node wants to join a cluster, it generates a CSR, which includes its identity and other relevant information.
|
||||
It checks if the CSR is properly formatted, contains all the required information, and matches the node's identity.
|
||||
|
||||
By validating and approving node CSRs, Talos CCM plays a crucial role in maintaining the security and integrity of the cluster by ensuring that only trusted and authorized nodes are allowed to have signed kubelet certificate.
|
||||
|
||||
The kubelet certificate is used to secure the communication between the kubelet and other components in the cluster, such as the Kubernetes control plane. It ensures that the communication is encrypted and authenticated and preventing a man-in-the-middle (MITM) attack.
|
||||
Read more about cloud [controllers](docs/controllers.md).
|
||||
|
||||
## Example
|
||||
|
||||
Kubernetes node resource:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Node
|
||||
@@ -73,68 +61,7 @@ status:
|
||||
|
||||
## Install
|
||||
|
||||
We need to set the `--cloud-provider=external` flag for each node.
|
||||
|
||||
To allow CCM approves/signs the [kubelet certificate signing request](https://kubernetes.io/docs/reference/access-authn-authz/certificate-signing-requests/#kubernetes-signers) set the flag `--rotate-server-certificates=true`.
|
||||
|
||||
### Prepare control-plane
|
||||
|
||||
On the control-plane you need to allow [API access feature](https://www.talos.dev/v1.2/reference/configuration/#featuresconfig):
|
||||
|
||||
```yaml
|
||||
machine:
|
||||
kubelet:
|
||||
extraArgs:
|
||||
cloud-provider: external
|
||||
rotate-server-certificates: true
|
||||
features:
|
||||
kubernetesTalosAPIAccess:
|
||||
enabled: true
|
||||
allowedRoles:
|
||||
- os:reader
|
||||
allowedKubernetesNamespaces:
|
||||
- kube-system
|
||||
```
|
||||
|
||||
### Prepare worker nodes
|
||||
|
||||
```yaml
|
||||
machine:
|
||||
kubelet:
|
||||
extraArgs:
|
||||
cloud-provider: external
|
||||
rotate-server-certificates: true
|
||||
```
|
||||
|
||||
### Method 1: talos machine config
|
||||
|
||||
```yaml
|
||||
cluster:
|
||||
externalCloudProvider:
|
||||
enabled: true
|
||||
manifests:
|
||||
- https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager.yml
|
||||
```
|
||||
|
||||
### Method 2: kubectl
|
||||
|
||||
Latest release:
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager.yml
|
||||
```
|
||||
|
||||
Latest stable version (edge):
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager-edge.yml
|
||||
```
|
||||
|
||||
### Method 3: helm chart
|
||||
|
||||
```shell
|
||||
helm upgrade -i -n kube-system talos-cloud-controller-manager oci://ghcr.io/siderolabs/charts/talos-cloud-controller-manager
|
||||
```
|
||||
See [Install](docs/install.md) for installation instructions.
|
||||
|
||||
## Community
|
||||
|
||||
|
||||
93
docs/controllers.md
Normal file
93
docs/controllers.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Talos CCM Controllers
|
||||
|
||||
Talos CCM is a set of controllers that manage cloud resources in a Kubernetes cluster.
|
||||
To check the default state of the controllers, run the following command:
|
||||
|
||||
```shell
|
||||
docker run --rm -ti ghcr.io/siderolabs/talos-cloud-controller-manager:edge --help | grep -A 2 'controllers'
|
||||
|
||||
--controllers strings A list of controllers to enable. '*' enables all on-by-default controllers, 'foo' enables the controller named 'foo', '-foo' disables the controller named 'foo'.
|
||||
All controllers: cloud-node-controller, cloud-node-lifecycle-controller, node-ipam-controller, node-route-controller, service-lb-controller
|
||||
Disabled-by-default controllers: node-ipam-controller, node-lifecycle-controller (default [*])
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
* [cloud-node](#cloud-node)
|
||||
* [cloud-node-lifecycle](#cloud-node-lifecycle)
|
||||
* [route](#route)
|
||||
* [service](#service)
|
||||
* [nodeipam](#node-ipam)
|
||||
* [csr-approval](#node-certificate-approval)
|
||||
|
||||
## Cloud node
|
||||
|
||||
Enabled by default.
|
||||
|
||||
Detects new instances launched in the cloud and registers them as nodes in the Kubernetes cluster.
|
||||
Assigns labels and taints based on cloud metadata and configuration.
|
||||
See [configuration options](config.md) for more details.
|
||||
|
||||
Well-Known [labels](https://kubernetes.io/docs/reference/labels-annotations-taints/):
|
||||
* topology.kubernetes.io/region
|
||||
* topology.kubernetes.io/zone
|
||||
* node.kubernetes.io/instance-type
|
||||
|
||||
Talos specific labels:
|
||||
* node.cloudprovider.kubernetes.io/clustername - talos cluster name
|
||||
* node.cloudprovider.kubernetes.io/platform - name of platform
|
||||
* node.cloudprovider.kubernetes.io/lifecycle - spot instance type
|
||||
|
||||
Node specs:
|
||||
* providerID magic string
|
||||
* InternalIP and ExternalIP addresses
|
||||
|
||||
## Cloud node lifecycle
|
||||
|
||||
Disabled by default.
|
||||
|
||||
Currently, it make sense only for GCP cloud.
|
||||
GCP spot instances change their IP address when they are evicted. CCM catches this event and remove the node resource from the cluster. After instance recreation, the node will initialize again and join the cluster.
|
||||
|
||||
## Route
|
||||
|
||||
Is not implemented yet.
|
||||
|
||||
## Service
|
||||
|
||||
Is not implemented yet.
|
||||
|
||||
## Node IPAM
|
||||
|
||||
Disabled by default.
|
||||
|
||||
Node IPAM is responsible for managing the allocation and assignment of CIDR addresses to pods across the nodes in a Kubernetes cluster. It ensures that IP addresses are efficiently distributed without conflicts, supporting scalable and flexible networking within the cluster.
|
||||
|
||||
Pod CIDR allocation is based on the node CIDR range, which is defined by the `--node-cidr-mask-size-ipv4` and `--node-cidr-mask-size-ipv6` flags. The node CIDR range is divided into smaller subnets, which are then assigned to nodes in the cluster.
|
||||
The CIDR allocator type can be set to `CloudAllocator` or `RangeAllocator`.
|
||||
|
||||
* RangeAllocator - is the default Kubernetes CIDR allocator.
|
||||
* CloudAllocator - is a custom CIDR allocator that uses Talos metadata to allocate CIDR ranges to nodes.
|
||||
|
||||
This controller solves the IPv6 CIDR allocation problem in Kubernetes in hybrid environments.
|
||||
Each node can have a different IPv6 CIDR range, which is not possible with the default Kubernetes CIDR allocator.
|
||||
|
||||
In hybrid environments, the Cloud Controller Manager (CCM) can utilize cloud provider-specific metadata to determine the IPv6 subnet assigned to each node.
|
||||
By doing so, it allocates a unique pod CIDR range for each node based on its specific IPv6 subnet.
|
||||
This ensures seamless integration of Kubernetes networking with the existing cloud infrastructure, enabling each node to have a distinct IPv6 CIDR range that suits its environment.
|
||||
|
||||
Recommended arguments for the controller:
|
||||
|
||||
```shell
|
||||
--allocate-node-cidrs --node-cidr-mask-size-ipv4=24 --node-cidr-mask-size-ipv6=80 --cidr-allocator-type=CloudAllocator
|
||||
```
|
||||
|
||||
## Node certificate approval
|
||||
|
||||
Talos CCM is responsible for validating a node's certificate signing request (CSR) and approving it.
|
||||
When a node wants to join a cluster, it generates a CSR, which includes its identity and other relevant information.
|
||||
It checks if the CSR is properly formatted, contains all the required information, and matches the node's identity.
|
||||
|
||||
By validating and approving node CSRs, Talos CCM plays a crucial role in maintaining the security and integrity of the cluster by ensuring that only trusted and authorized nodes are allowed to have signed kubelet certificate.
|
||||
|
||||
The kubelet certificate is used to secure the communication between the kubelet and other components in the cluster, such as the Kubernetes control plane. It ensures that the communication is encrypted and authenticated and preventing a man-in-the-middle (MITM) attack.
|
||||
61
docs/install.md
Normal file
61
docs/install.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Install
|
||||
|
||||
## Prepare nodes
|
||||
|
||||
We need to set the `--cloud-provider=external` kubelet flag for each node.
|
||||
|
||||
```yaml
|
||||
# Talos machine config
|
||||
machine:
|
||||
kubelet:
|
||||
extraArgs:
|
||||
cloud-provider: external
|
||||
```
|
||||
|
||||
On the control-plane you need to allow [API access feature](https://www.talos.dev/v1.2/reference/configuration/#featuresconfig):
|
||||
|
||||
```yaml
|
||||
# Talos machine config
|
||||
machine:
|
||||
features:
|
||||
kubernetesTalosAPIAccess:
|
||||
enabled: true
|
||||
allowedRoles:
|
||||
- os:reader
|
||||
allowedKubernetesNamespaces:
|
||||
- kube-system
|
||||
```
|
||||
|
||||
## Install Talos Cloud Controller Manager
|
||||
|
||||
### Method 1: talos machine config
|
||||
|
||||
```yaml
|
||||
cluster:
|
||||
externalCloudProvider:
|
||||
enabled: true
|
||||
manifests:
|
||||
- https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager.yml
|
||||
```
|
||||
|
||||
### Method 2: kubectl
|
||||
|
||||
Latest release:
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager.yml
|
||||
```
|
||||
|
||||
Latest stable version (edge):
|
||||
|
||||
```shell
|
||||
kubectl apply -f https://raw.githubusercontent.com/siderolabs/talos-cloud-controller-manager/main/docs/deploy/cloud-controller-manager-edge.yml
|
||||
```
|
||||
|
||||
### Method 3: helm chart
|
||||
|
||||
Helm chart documentation can be found [here](../charts/talos-cloud-controller-manager/README.md)
|
||||
|
||||
```shell
|
||||
helm upgrade -i -n kube-system talos-cloud-controller-manager oci://ghcr.io/siderolabs/charts/talos-cloud-controller-manager
|
||||
```
|
||||
Reference in New Issue
Block a user