From 4ca85a3856a098de04680cacd0ca22f74839e457 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Thu, 12 Feb 2026 18:13:45 +0300 Subject: [PATCH 1/5] docs(install): add generic Kubernetes deployment guide for v1 Add documentation for deploying Cozystack on k3s, kubeadm, RKE2, and other non-Talos Kubernetes distributions using the isp-full-generic bundle. Update the install index to include the new Generic Kubernetes section alongside the existing Talos methods. Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- .../en/docs/v1/install/kubernetes/_index.md | 22 +- .../en/docs/v1/install/kubernetes/generic.md | 516 ++++++++++++++++++ 2 files changed, 532 insertions(+), 6 deletions(-) create mode 100644 content/en/docs/v1/install/kubernetes/generic.md diff --git a/content/en/docs/v1/install/kubernetes/_index.md b/content/en/docs/v1/install/kubernetes/_index.md index fc326aec..c4b4998a 100644 --- a/content/en/docs/v1/install/kubernetes/_index.md +++ b/content/en/docs/v1/install/kubernetes/_index.md @@ -1,7 +1,7 @@ --- -title: "Installing and Configuring Kubernetes Cluster on Talos Linux" +title: "Installing and Configuring Kubernetes Cluster" linkTitle: "2. Install Kubernetes" -description: "Step 2: Installing and configuring a Kubernetes cluster on Talos Linux nodes, ready for Cozystack installation." +description: "Step 2: Installing and configuring a Kubernetes cluster ready for Cozystack installation." weight: 20 aliases: - /docs/v1/operations/talos/configuration @@ -10,24 +10,34 @@ aliases: --- -**The second step** in deploying a Cozystack cluster is to install and configure a Kubernetes cluster on Talos Linux nodes. -A prerequisite to this step is having [installed Talos Linux]({{% ref "/docs/v1/install/talos" %}}). +**The second step** in deploying a Cozystack cluster is to install and configure a Kubernetes cluster. The result is a Kubernetes cluster installed, configured, and ready to install Cozystack. If this is your first time installing Cozystack, [start with the Cozystack tutorial]({{% ref "/docs/v1/getting-started" %}}). ## Installation Options +### Talos Linux (Recommended) + +For production deployments, Cozystack recommends [Talos Linux]({{% ref "/docs/v1/guides/talos" %}}) as the underlying operating system. +A prerequisite to using these methods is having [installed Talos Linux]({{% ref "/docs/v1/install/talos" %}}). + There are several methods to configure Talos nodes and bootstrap a Kubernetes cluster: - **Recommended**: [using Talm]({{% ref "./talm" %}}), a declarative CLI tool, which has ready presets for Cozystack and uses the power of Talos API under the hood. - [Using `talos-bootstrap`]({{% ref "./talos-bootstrap" %}}), an interactive script for bootstrapping Kubernetes clusters on Talos OS. -- [Using talosctl]({{% ref "./talosctl" %}}), a specialized command line tool for managing Talos. +- [Using talosctl]({{% ref "./talosctl" %}}), a specialized command-line tool for managing Talos. - [Air-gapped installation]({{% ref "./air-gapped" %}}) is possible with Talm or talosctl. +### Generic Kubernetes + +Cozystack can also be deployed on other Kubernetes distributions: + +- [Generic Kubernetes]({{% ref "./generic" %}}) — deploy Cozystack on k3s, kubeadm, RKE2, or other distributions. + If you encounter problems with installation, refer to the [Troubleshooting section]({{% ref "./troubleshooting" %}}). ## Further Steps -- After installing and configuring Kubernetes on top of Talos Linux nodes, you will have a Kubernetes cluster ready to +- After installing and configuring a Kubernetes cluster, you will have it ready to [install and configure Cozystack]({{% ref "/docs/v1/install/cozystack" %}}). diff --git a/content/en/docs/v1/install/kubernetes/generic.md b/content/en/docs/v1/install/kubernetes/generic.md new file mode 100644 index 00000000..aa7f9585 --- /dev/null +++ b/content/en/docs/v1/install/kubernetes/generic.md @@ -0,0 +1,516 @@ +--- +title: "Deploying Cozystack on Generic Kubernetes" +linkTitle: "Generic Kubernetes" +description: "How to deploy Cozystack on k3s, kubeadm, RKE2, or other Kubernetes distributions without Talos Linux" +weight: 50 +--- + +This guide explains how to deploy Cozystack on generic Kubernetes distributions such as k3s, kubeadm, or RKE2. +While Talos Linux remains the recommended platform for production deployments, Cozystack supports deployment on other Kubernetes distributions using the `isp-full-generic` bundle. + +## When to Use Generic Kubernetes + +Consider using generic Kubernetes instead of Talos Linux when: + +- You have an existing Kubernetes cluster you want to enhance with Cozystack +- Your infrastructure doesn't support Talos Linux (certain cloud providers, embedded systems) +- You need specific Linux features or packages not available in Talos + +For new production deployments, [Talos Linux]({{% ref "/docs/v1/guides/talos" %}}) is recommended due to its security and operational benefits. + +## Prerequisites + +### Supported Distributions + +Cozystack has been tested on: + +- **k3s** v1.32+ (recommended for single-node and edge deployments) +- **kubeadm** v1.28+ +- **RKE2** v1.28+ + +### Host Requirements + +- **Operating System**: Ubuntu 22.04+ or Debian 12+ (kernel 5.x+ with systemd) +- **Architecture**: amd64 or arm64 +- **Hardware**: See [hardware requirements]({{% ref "/docs/v1/install/hardware-requirements" %}}) + +### Required Packages + +Install the following packages on all nodes: + +```bash +apt-get update +apt-get install -y nfs-common open-iscsi multipath-tools +``` + +### Required Services + +Enable and start required services: + +```bash +systemctl enable --now iscsid +systemctl enable --now multipathd +``` + +## Sysctl Configuration + +{{% alert color="warning" %}} +:warning: **Critical**: The sysctl settings below are mandatory for Cozystack to function properly. +Without these settings, Kubernetes components will fail due to insufficient inotify watches. +{{% /alert %}} + +Create `/etc/sysctl.d/99-cozystack.conf` with the following content: + +```ini +# Inotify limits (critical for Cozystack) +fs.inotify.max_user_watches = 524288 +fs.inotify.max_user_instances = 8192 +fs.inotify.max_queued_events = 65536 + +# Filesystem limits +fs.file-max = 2097152 +fs.aio-max-nr = 1048576 + +# Network forwarding (required for Kubernetes) +net.ipv4.ip_forward = 1 +net.ipv4.conf.all.forwarding = 1 +net.bridge.bridge-nf-call-iptables = 1 +net.bridge.bridge-nf-call-ip6tables = 1 + +# VM tuning +vm.swappiness = 1 +``` + +Apply the settings: + +```bash +sysctl --system +``` + +## Kubernetes Configuration + +Cozystack manages its own networking (Cilium/KubeOVN), storage (LINSTOR), and ingress (NGINX). +Your Kubernetes distribution must be configured to **not** install these components. + +### Required Configuration + +| Component | Requirement | +| ----------- | ------------- | +| CNI | **Disabled** — Cozystack deploys Cilium or KubeOVN | +| Ingress Controller | **Disabled** — Cozystack deploys NGINX | +| Storage Provisioner | **Disabled** — Cozystack deploys LINSTOR | +| kube-proxy | **Disabled** — Cilium replaces it | +| Cluster Domain | Must be `cozy.local` | + +### k3s Configuration + +When installing k3s, use the following flags: + +```bash +curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server \ + --disable=traefik \ + --disable=servicelb \ + --disable=local-storage \ + --disable=metrics-server \ + --disable-network-policy \ + --disable-kube-proxy \ + --flannel-backend=none \ + --cluster-domain=cozy.local \ + --tls-san= \ + --kubelet-arg=max-pods=220" sh - +``` + +Replace `` with your node's IP address. + +### kubeadm Configuration + +Create a kubeadm configuration file: + +```yaml +apiVersion: kubeadm.k8s.io/v1beta3 +kind: ClusterConfiguration +networking: + podSubnet: "10.244.0.0/16" + serviceSubnet: "10.96.0.0/16" + dnsDomain: "cozy.local" +--- +apiVersion: kubeproxy.config.k8s.io/v1alpha1 +kind: KubeProxyConfiguration +mode: "none" # Cilium will replace kube-proxy +``` + +Initialize the cluster without the default CNI: + +```bash +kubeadm init --config kubeadm-config.yaml --skip-phases=addon/kube-proxy +``` + +### RKE2 Configuration + +Create `/etc/rancher/rke2/config.yaml`: + +```yaml +cni: none +disable: + - rke2-ingress-nginx + - rke2-metrics-server +cluster-domain: cozy.local +disable-kube-proxy: true +``` + +## Installing Cozystack + +### 1. Apply CRDs + +Download and apply Custom Resource Definitions: + +```bash +kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-crds.yaml +``` + +### 2. Create Namespace + +```bash +kubectl create namespace cozy-system +``` + +### 3. Create ConfigMap + +Create `cozystack-config.yaml` with your cluster configuration. + +{{% alert color="warning" %}} +:warning: **Important**: The `ipv4-pod-cidr` and `ipv4-svc-cidr` values **must match** your Kubernetes cluster configuration. +Different distributions use different defaults: +- **k3s**: `10.42.0.0/16` (pods), `10.43.0.0/16` (services) +- **kubeadm**: `10.244.0.0/16` (pods), `10.96.0.0/16` (services) +- **RKE2**: `10.42.0.0/16` (pods), `10.43.0.0/16` (services) +{{% /alert %}} + +Example for **k3s** (adjust CIDRs for other distributions): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: cozystack + namespace: cozy-system +data: + root-host: "example.com" + api-server-endpoint: "https://:6443" + ipv4-pod-cidr: "10.42.0.0/16" + ipv4-pod-gateway: "10.42.0.1" + ipv4-svc-cidr: "10.43.0.0/16" + ipv4-join-cidr: "100.64.0.0/16" +``` + +Adjust the values: + +| Field | Description | +| ------- | ------------- | +| `root-host` | Your domain for Cozystack services | +| `api-server-endpoint` | Kubernetes API endpoint URL | +| `ipv4-pod-cidr` | Pod network CIDR (must match your k8s config) | +| `ipv4-svc-cidr` | Service network CIDR (must match your k8s config) | +| `ipv4-join-cidr` | Network for nested cluster communication | + +Apply the ConfigMap: + +```bash +kubectl apply -f cozystack-config.yaml +``` + +### 4. Create Operator Configuration + +The generic operator manifest reads the Kubernetes API server address from a ConfigMap. +You **must** create this ConfigMap before deploying the operator, otherwise the operator pod will fail to start. + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: cozystack-operator-config + namespace: cozy-system +data: + KUBERNETES_SERVICE_HOST: "" + KUBERNETES_SERVICE_PORT: "6443" +``` + +Replace `` with the IP address of your Kubernetes API server (the same address used in `api-server-endpoint` above, without the `https://` prefix and port). + +Apply it: + +```bash +kubectl apply -f cozystack-operator-config.yaml +``` + +### 5. Deploy Cozystack Operator + +Apply the generic operator manifest: + +```bash +kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml +``` + +### 6. Create Platform Package + +After the operator starts and reconciles the `PackageSource`, create a `Package` resource to trigger the platform installation: + +```yaml +apiVersion: cozystack.io/v1alpha1 +kind: Package +metadata: + name: cozystack.cozystack-platform +spec: + variant: isp-full-generic +``` + +Apply it: + +```bash +kubectl apply -f cozystack-platform-package.yaml +``` + +{{% alert color="info" %}} +The Package name **must** match the PackageSource name (`cozystack.cozystack-platform`). +You can verify available PackageSources with `kubectl get packagesource`. +{{% /alert %}} + +### 7. Monitor Installation + +Watch the installation progress: + +```bash +kubectl logs -n cozy-system deploy/cozystack-operator -f +``` + +Check HelmRelease status: + +```bash +kubectl get hr -A +``` + +{{% alert color="info" %}} +During initial deployment, HelmReleases may show errors such as `ExternalArtifact not found` or `dependency is not ready` for the first few minutes while Cilium and other core components are being reconciled. This is expected — wait a few minutes and check again. +{{% /alert %}} + +You can verify that Cilium has been deployed and nodes are networked by waiting for them to become Ready: + +```bash +kubectl wait --for=condition=Ready nodes --all --timeout=300s +``` + +## Example: Ansible Playbook + +Below is a minimal Ansible playbook for preparing nodes and deploying Cozystack. + +### Node Preparation Playbook + +```yaml +--- +- name: Prepare nodes for Cozystack + hosts: all + become: true + tasks: + - name: Install required packages + ansible.builtin.apt: + name: + - nfs-common + - open-iscsi + - multipath-tools + state: present + update_cache: true + + - name: Configure sysctl for Cozystack + ansible.posix.sysctl: + name: "{{ item.name }}" + value: "{{ item.value }}" + sysctl_set: true + state: present + reload: true + loop: + - { name: fs.inotify.max_user_watches, value: "524288" } + - { name: fs.inotify.max_user_instances, value: "8192" } + - { name: fs.inotify.max_queued_events, value: "65536" } + - { name: fs.file-max, value: "2097152" } + - { name: fs.aio-max-nr, value: "1048576" } + - { name: net.ipv4.ip_forward, value: "1" } + - { name: net.ipv4.conf.all.forwarding, value: "1" } + - { name: net.bridge.bridge-nf-call-iptables, value: "1" } + - { name: net.bridge.bridge-nf-call-ip6tables, value: "1" } + - { name: vm.swappiness, value: "1" } + + - name: Enable iscsid service + ansible.builtin.systemd: + name: iscsid + enabled: true + state: started + + - name: Enable multipathd service + ansible.builtin.systemd: + name: multipathd + enabled: true + state: started +``` + +### Cozystack Deployment Playbook + +This example uses k3s default CIDRs. Adjust for kubeadm (`10.244.0.0/16`, `10.96.0.0/16`) or your custom configuration. + +```yaml +--- +- name: Deploy Cozystack + hosts: localhost + connection: local + vars: + cozystack_root_host: "example.com" + cozystack_api_endpoint: "https://10.0.0.1:6443" + # k3s defaults - adjust for kubeadm (10.244.0.0/16, 10.96.0.0/16) + cozystack_pod_cidr: "10.42.0.0/16" + cozystack_svc_cidr: "10.43.0.0/16" + tasks: + - name: Apply Cozystack CRDs + ansible.builtin.command: + cmd: kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-crds.yaml + changed_when: true + + - name: Create cozy-system namespace + kubernetes.core.k8s: + state: present + definition: + apiVersion: v1 + kind: Namespace + metadata: + name: cozy-system + + - name: Create Cozystack ConfigMap + kubernetes.core.k8s: + state: present + definition: + apiVersion: v1 + kind: ConfigMap + metadata: + name: cozystack + namespace: cozy-system + data: + root-host: "{{ cozystack_root_host }}" + api-server-endpoint: "{{ cozystack_api_endpoint }}" + ipv4-pod-cidr: "{{ cozystack_pod_cidr }}" + ipv4-pod-gateway: "{{ cozystack_pod_cidr | ansible.utils.ipaddr('1') | ansible.utils.ipaddr('address') }}" + ipv4-svc-cidr: "{{ cozystack_svc_cidr }}" + ipv4-join-cidr: "100.64.0.0/16" + + - name: Create Cozystack operator config + kubernetes.core.k8s: + state: present + definition: + apiVersion: v1 + kind: ConfigMap + metadata: + name: cozystack-operator-config + namespace: cozy-system + data: + KUBERNETES_SERVICE_HOST: "{{ cozystack_api_endpoint | urlsplit('hostname') }}" + KUBERNETES_SERVICE_PORT: "{{ cozystack_api_endpoint | urlsplit('port') | default('6443', true) }}" + + - name: Apply Cozystack operator + ansible.builtin.command: + cmd: kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml + changed_when: true + + - name: Wait for PackageSource to be ready + kubernetes.core.k8s_info: + api_version: cozystack.io/v1alpha1 + kind: PackageSource + name: cozystack.cozystack-platform + register: pkg_source + until: > + pkg_source.resources | length > 0 and + ( + pkg_source.resources[0].status.conditions + | selectattr('type', 'equalto', 'Ready') + | map(attribute='status') + | first + | default('False') + ) == "True" + retries: 30 + delay: 10 + + - name: Create Platform Package + kubernetes.core.k8s: + state: present + definition: + apiVersion: cozystack.io/v1alpha1 + kind: Package + metadata: + name: cozystack.cozystack-platform + spec: + variant: isp-full-generic +``` + +## Troubleshooting + +### linstor-scheduler Image Tag Invalid + +**Symptom**: `InvalidImageName` error for linstor-scheduler pod. + +**Cause**: k3s version format (e.g., `v1.35.0+k3s1`) contains `+` which is invalid in Docker image tags. + +**Solution**: This is fixed in Cozystack v1.0.0+. Ensure you're using the latest release. + +### KubeOVN Not Scheduling + +**Symptom**: ovn-central pods stuck in Pending state. + +**Cause**: KubeOVN uses Helm `lookup` to find control-plane nodes, which may fail on fresh clusters. + +**Solution**: Ensure your Platform Package includes explicit `MASTER_NODES` configuration: + +```yaml +spec: + components: + networking: + values: + kube-ovn: + MASTER_NODES: "" +``` + +### Cilium Cannot Reach API Server + +**Symptom**: Cilium pods in CrashLoopBackOff with API connection errors. + +**Cause**: Single-node clusters or non-standard API endpoints require explicit configuration. + +**Solution**: Verify your ConfigMap includes correct `api-server-endpoint` and ensure the Platform Package has: + +```yaml +spec: + components: + networking: + values: + cilium: + k8sServiceHost: "" + k8sServicePort: "6443" +``` + +### Inotify Limit Errors + +**Symptom**: Pods failing with "too many open files" or inotify errors. + +**Cause**: Default Linux inotify limits are too low for Kubernetes. + +**Solution**: Apply sysctl settings from the [Sysctl Configuration](#sysctl-configuration) section and reboot the node. + +## Further Steps + +After Cozystack installation completes: + +1. [Configure storage with LINSTOR]({{% ref "/docs/v1/getting-started/install-cozystack#3-configure-storage" %}}) +2. [Set up the root tenant]({{% ref "/docs/v1/getting-started/install-cozystack#51-setup-root-tenant-services" %}}) +3. [Deploy your first application]({{% ref "/docs/v1/applications" %}}) + +## References + +- [PR #1939: Non-Talos Kubernetes Support](https://github.com/cozystack/cozystack/pull/1939) +- [Issue #1950: Complete non-Talos Support](https://github.com/cozystack/cozystack/issues/1950) +- [k3s Documentation](https://docs.k3s.io/) +- [kubeadm Documentation](https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/) From 81cc88ea37a6e2d85f8223f6ae9598de8a218d5e Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Thu, 12 Feb 2026 18:27:31 +0300 Subject: [PATCH 2/5] fix(docs): remove ConfigMap steps, use Package-based config flow Align with cozystack/cozystack#2010: the operator manifest now includes cozystack-operator-config ConfigMap with REPLACE_ME placeholder. All platform configuration (networking CIDRs, publishing host) moves into the Package resource spec.components. Also add br_netfilter kernel module loading as prerequisite for bridge netfilter sysctl settings. Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- .../en/docs/v1/install/kubernetes/generic.md | 188 +++++++----------- 1 file changed, 71 insertions(+), 117 deletions(-) diff --git a/content/en/docs/v1/install/kubernetes/generic.md b/content/en/docs/v1/install/kubernetes/generic.md index aa7f9585..b3d19812 100644 --- a/content/en/docs/v1/install/kubernetes/generic.md +++ b/content/en/docs/v1/install/kubernetes/generic.md @@ -43,6 +43,15 @@ apt-get update apt-get install -y nfs-common open-iscsi multipath-tools ``` +### Required Kernel Modules + +Load the `br_netfilter` module (required for bridge netfilter sysctl settings): + +```bash +modprobe br_netfilter +echo "br_netfilter" > /etc/modules-load.d/br_netfilter.conf +``` + ### Required Services Enable and start required services: @@ -168,19 +177,28 @@ Download and apply Custom Resource Definitions: kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-crds.yaml ``` -### 2. Create Namespace +### 2. Deploy Cozystack Operator + +Download the generic operator manifest, replace the API server address placeholder, and apply: ```bash -kubectl create namespace cozy-system +curl -fsSL https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml \ + | sed 's/REPLACE_ME//' \ + | kubectl apply -f - ``` -### 3. Create ConfigMap +Replace `` with the IP address of your Kubernetes API server (IP only, without protocol or port). + +The manifest includes the operator deployment, the `cozystack-operator-config` ConfigMap with the API server address, and the `PackageSource` resource. + +### 3. Create Platform Package -Create `cozystack-config.yaml` with your cluster configuration. +After the operator starts and reconciles the `PackageSource`, create a `Package` resource to trigger the platform installation. {{% alert color="warning" %}} -:warning: **Important**: The `ipv4-pod-cidr` and `ipv4-svc-cidr` values **must match** your Kubernetes cluster configuration. +:warning: **Important**: The `podCIDR` and `serviceCIDR` values **must match** your Kubernetes cluster configuration. Different distributions use different defaults: + - **k3s**: `10.42.0.0/16` (pods), `10.43.0.0/16` (services) - **kubeadm**: `10.244.0.0/16` (pods), `10.96.0.0/16` (services) - **RKE2**: `10.42.0.0/16` (pods), `10.43.0.0/16` (services) @@ -188,82 +206,37 @@ Different distributions use different defaults: Example for **k3s** (adjust CIDRs for other distributions): -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cozystack - namespace: cozy-system -data: - root-host: "example.com" - api-server-endpoint: "https://:6443" - ipv4-pod-cidr: "10.42.0.0/16" - ipv4-pod-gateway: "10.42.0.1" - ipv4-svc-cidr: "10.43.0.0/16" - ipv4-join-cidr: "100.64.0.0/16" -``` - -Adjust the values: - -| Field | Description | -| ------- | ------------- | -| `root-host` | Your domain for Cozystack services | -| `api-server-endpoint` | Kubernetes API endpoint URL | -| `ipv4-pod-cidr` | Pod network CIDR (must match your k8s config) | -| `ipv4-svc-cidr` | Service network CIDR (must match your k8s config) | -| `ipv4-join-cidr` | Network for nested cluster communication | - -Apply the ConfigMap: - -```bash -kubectl apply -f cozystack-config.yaml -``` - -### 4. Create Operator Configuration - -The generic operator manifest reads the Kubernetes API server address from a ConfigMap. -You **must** create this ConfigMap before deploying the operator, otherwise the operator pod will fail to start. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: cozystack-operator-config - namespace: cozy-system -data: - KUBERNETES_SERVICE_HOST: "" - KUBERNETES_SERVICE_PORT: "6443" -``` - -Replace `` with the IP address of your Kubernetes API server (the same address used in `api-server-endpoint` above, without the `https://` prefix and port). - -Apply it: - -```bash -kubectl apply -f cozystack-operator-config.yaml -``` - -### 5. Deploy Cozystack Operator - -Apply the generic operator manifest: - -```bash -kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml -``` - -### 6. Create Platform Package - -After the operator starts and reconciles the `PackageSource`, create a `Package` resource to trigger the platform installation: - ```yaml apiVersion: cozystack.io/v1alpha1 kind: Package metadata: name: cozystack.cozystack-platform + # Package is cluster-scoped — no namespace needed spec: variant: isp-full-generic + components: + platform: + values: + publishing: + host: "example.com" + apiServerEndpoint: "https://:6443" + networking: + podCIDR: "10.42.0.0/16" + podGateway: "10.42.0.1" + serviceCIDR: "10.43.0.0/16" + joinCIDR: "100.64.0.0/16" ``` +Adjust the values: + +| Field | Description | +| ------- | ------------- | +| `publishing.host` | Your domain for Cozystack services | +| `publishing.apiServerEndpoint` | Kubernetes API endpoint URL | +| `networking.podCIDR` | Pod network CIDR (must match your k8s config) | +| `networking.serviceCIDR` | Service network CIDR (must match your k8s config) | +| `networking.joinCIDR` | Network for nested cluster communication | + Apply it: ```bash @@ -275,7 +248,7 @@ The Package name **must** match the PackageSource name (`cozystack.cozystack-pla You can verify available PackageSources with `kubectl get packagesource`. {{% /alert %}} -### 7. Monitor Installation +### 4. Monitor Installation Watch the installation progress: @@ -311,6 +284,11 @@ Below is a minimal Ansible playbook for preparing nodes and deploying Cozystack. hosts: all become: true tasks: + - name: Load br_netfilter module + community.general.modprobe: + name: br_netfilter + persistent: present + - name: Install required packages ansible.builtin.apt: name: @@ -363,7 +341,8 @@ This example uses k3s default CIDRs. Adjust for kubeadm (`10.244.0.0/16`, `10.96 connection: local vars: cozystack_root_host: "example.com" - cozystack_api_endpoint: "https://10.0.0.1:6443" + cozystack_api_host: "10.0.0.1" + cozystack_api_port: "6443" # k3s defaults - adjust for kubeadm (10.244.0.0/16, 10.96.0.0/16) cozystack_pod_cidr: "10.42.0.0/16" cozystack_svc_cidr: "10.43.0.0/16" @@ -373,48 +352,12 @@ This example uses k3s default CIDRs. Adjust for kubeadm (`10.244.0.0/16`, `10.96 cmd: kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-crds.yaml changed_when: true - - name: Create cozy-system namespace - kubernetes.core.k8s: - state: present - definition: - apiVersion: v1 - kind: Namespace - metadata: - name: cozy-system - - - name: Create Cozystack ConfigMap - kubernetes.core.k8s: - state: present - definition: - apiVersion: v1 - kind: ConfigMap - metadata: - name: cozystack - namespace: cozy-system - data: - root-host: "{{ cozystack_root_host }}" - api-server-endpoint: "{{ cozystack_api_endpoint }}" - ipv4-pod-cidr: "{{ cozystack_pod_cidr }}" - ipv4-pod-gateway: "{{ cozystack_pod_cidr | ansible.utils.ipaddr('1') | ansible.utils.ipaddr('address') }}" - ipv4-svc-cidr: "{{ cozystack_svc_cidr }}" - ipv4-join-cidr: "100.64.0.0/16" - - - name: Create Cozystack operator config - kubernetes.core.k8s: - state: present - definition: - apiVersion: v1 - kind: ConfigMap - metadata: - name: cozystack-operator-config - namespace: cozy-system - data: - KUBERNETES_SERVICE_HOST: "{{ cozystack_api_endpoint | urlsplit('hostname') }}" - KUBERNETES_SERVICE_PORT: "{{ cozystack_api_endpoint | urlsplit('port') | default('6443', true) }}" - - - name: Apply Cozystack operator - ansible.builtin.command: - cmd: kubectl apply -f https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml + - name: Download and apply Cozystack operator manifest + ansible.builtin.shell: + cmd: > + curl -fsSL https://github.com/cozystack/cozystack/releases/latest/download/cozystack-operator-generic.yaml + | sed 's/REPLACE_ME/{{ cozystack_api_host }}/' + | kubectl apply -f - changed_when: true - name: Wait for PackageSource to be ready @@ -445,6 +388,17 @@ This example uses k3s default CIDRs. Adjust for kubeadm (`10.244.0.0/16`, `10.96 name: cozystack.cozystack-platform spec: variant: isp-full-generic + components: + platform: + values: + publishing: + host: "{{ cozystack_root_host }}" + apiServerEndpoint: "https://{{ cozystack_api_host }}:{{ cozystack_api_port }}" + networking: + podCIDR: "{{ cozystack_pod_cidr }}" + podGateway: "{{ cozystack_pod_cidr | ansible.utils.ipaddr('1') | ansible.utils.ipaddr('address') }}" + serviceCIDR: "{{ cozystack_svc_cidr }}" + joinCIDR: "100.64.0.0/16" ``` ## Troubleshooting @@ -480,7 +434,7 @@ spec: **Cause**: Single-node clusters or non-standard API endpoints require explicit configuration. -**Solution**: Verify your ConfigMap includes correct `api-server-endpoint` and ensure the Platform Package has: +**Solution**: Verify your Platform Package includes correct API server settings: ```yaml spec: From d460b7d5adb02a3ec62cd6d9a1cfebafad3f02ec Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Thu, 12 Feb 2026 19:40:35 +0300 Subject: [PATCH 3/5] fix(docs): add podGateway to values table, Ansible deps, fix wording - Add missing podGateway field to Package values description table - Add ansible-galaxy collection install for required collections - Fix awkward "you will have it ready to" phrasing in _index.md Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- content/en/docs/v1/install/kubernetes/_index.md | 2 +- content/en/docs/v1/install/kubernetes/generic.md | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/content/en/docs/v1/install/kubernetes/_index.md b/content/en/docs/v1/install/kubernetes/_index.md index c4b4998a..d1b87d7f 100644 --- a/content/en/docs/v1/install/kubernetes/_index.md +++ b/content/en/docs/v1/install/kubernetes/_index.md @@ -39,5 +39,5 @@ If you encounter problems with installation, refer to the [Troubleshooting secti ## Further Steps -- After installing and configuring a Kubernetes cluster, you will have it ready to +- After installing and configuring a Kubernetes cluster, you are ready to [install and configure Cozystack]({{% ref "/docs/v1/install/cozystack" %}}). diff --git a/content/en/docs/v1/install/kubernetes/generic.md b/content/en/docs/v1/install/kubernetes/generic.md index b3d19812..a5aacc90 100644 --- a/content/en/docs/v1/install/kubernetes/generic.md +++ b/content/en/docs/v1/install/kubernetes/generic.md @@ -234,6 +234,7 @@ Adjust the values: | `publishing.host` | Your domain for Cozystack services | | `publishing.apiServerEndpoint` | Kubernetes API endpoint URL | | `networking.podCIDR` | Pod network CIDR (must match your k8s config) | +| `networking.podGateway` | First IP in pod CIDR (e.g., `10.42.0.1` for `10.42.0.0/16`) | | `networking.serviceCIDR` | Service network CIDR (must match your k8s config) | | `networking.joinCIDR` | Network for nested cluster communication | @@ -276,6 +277,12 @@ kubectl wait --for=condition=Ready nodes --all --timeout=300s Below is a minimal Ansible playbook for preparing nodes and deploying Cozystack. +Install the required Ansible collections first: + +```bash +ansible-galaxy collection install ansible.posix community.general kubernetes.core ansible.utils +``` + ### Node Preparation Playbook ```yaml From 4a2f1bae40d57ab848d0dfaa777db9b52e32a5bd Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Thu, 12 Feb 2026 19:46:55 +0300 Subject: [PATCH 4/5] fix(docs): add kubeadm CNI warning Warn users not to install a CNI plugin after kubeadm init since Cozystack deploys Cilium automatically. Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- content/en/docs/v1/install/kubernetes/generic.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/v1/install/kubernetes/generic.md b/content/en/docs/v1/install/kubernetes/generic.md index a5aacc90..74ed0edd 100644 --- a/content/en/docs/v1/install/kubernetes/generic.md +++ b/content/en/docs/v1/install/kubernetes/generic.md @@ -154,6 +154,8 @@ Initialize the cluster without the default CNI: kubeadm init --config kubeadm-config.yaml --skip-phases=addon/kube-proxy ``` +Do not install a CNI plugin after `kubeadm init` — Cozystack will deploy Cilium automatically. + ### RKE2 Configuration Create `/etc/rancher/rke2/config.yaml`: From 1edc4b4cd93e49c650f0daa5e15d0b322c8fb291 Mon Sep 17 00:00:00 2001 From: Aleksei Sviridkin Date: Sun, 15 Feb 2026 03:33:31 +0300 Subject: [PATCH 5/5] fix(docs): use tabs for distribution configs, fix CNI description Wrap k3s/kubeadm/RKE2 configuration sections in Hugo tabs shortcode for cleaner presentation. Update CNI note to mention both Kube-OVN and Cilium per reviewer feedback. Co-Authored-By: Claude Signed-off-by: Aleksei Sviridkin --- content/en/docs/v1/install/kubernetes/generic.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/en/docs/v1/install/kubernetes/generic.md b/content/en/docs/v1/install/kubernetes/generic.md index 74ed0edd..d3b0b941 100644 --- a/content/en/docs/v1/install/kubernetes/generic.md +++ b/content/en/docs/v1/install/kubernetes/generic.md @@ -111,7 +111,8 @@ Your Kubernetes distribution must be configured to **not** install these compone | kube-proxy | **Disabled** — Cilium replaces it | | Cluster Domain | Must be `cozy.local` | -### k3s Configuration +{{< tabs name="kubernetes_distributions" >}} +{{% tab name="k3s" %}} When installing k3s, use the following flags: @@ -131,7 +132,8 @@ curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server \ Replace `` with your node's IP address. -### kubeadm Configuration +{{% /tab %}} +{{% tab name="kubeadm" %}} Create a kubeadm configuration file: @@ -154,9 +156,10 @@ Initialize the cluster without the default CNI: kubeadm init --config kubeadm-config.yaml --skip-phases=addon/kube-proxy ``` -Do not install a CNI plugin after `kubeadm init` — Cozystack will deploy Cilium automatically. +Do not install a CNI plugin after `kubeadm init` — Cozystack will deploy Kube-OVN and Cilium automatically. -### RKE2 Configuration +{{% /tab %}} +{{% tab name="RKE2" %}} Create `/etc/rancher/rke2/config.yaml`: @@ -169,6 +172,9 @@ cluster-domain: cozy.local disable-kube-proxy: true ``` +{{% /tab %}} +{{< /tabs >}} + ## Installing Cozystack ### 1. Apply CRDs