Automated Installation with Ansible

The cozystack.installer Ansible collection automates the full deployment pipeline: OS preparation, k3s cluster bootstrap, and Cozystack installation. It is suited for deploying Cozystack on bare-metal servers or VMs running a standard Linux distribution.

When to Use Ansible

Consider this approach when:

• You want a fully automated, repeatable deployment from bare OS to a running Cozystack
• You are deploying on generic Linux (Ubuntu, Debian, RHEL, Rocky, openSUSE) rather than Talos Linux
• You want to manage multiple nodes with a single inventory file

For manual installation steps without Ansible, see the Generic Kubernetes guide.

Prerequisites

Controller Machine

• Python >= 3.9
• Ansible >= 2.15

Target Nodes

• Operating System: Ubuntu/Debian, RHEL 8+/CentOS Stream 8+/Rocky/Alma, or openSUSE/SLE
• Architecture: amd64 or arm64
• SSH access with passwordless sudo
• See hardware requirements for CPU, RAM, and disk sizing

Installation

1. Install the Ansible Collection

ansible-galaxy collection install git+https://github.com/cozystack/ansible-cozystack.git

Install required dependency collections. The requirements.yml file is not included in the packaged collection, so download it from the repository:

curl --silent --location --output /tmp/requirements.yml \
  https://raw.githubusercontent.com/cozystack/ansible-cozystack/main/requirements.yml
ansible-galaxy collection install --requirements-file /tmp/requirements.yml

This installs the following dependencies:

• ansible.posix, community.general, kubernetes.core — from Ansible Galaxy
• k3s.orchestration — k3s deployment collection, installed from Git

2. Create an Inventory

Create an inventory.yml file. The internal (private) IP of each node must be used as the host key, because KubeOVN validates host IPs through NODE_IPS. The public IP (if different) goes in ansible_host.

cluster:
  children:
    server:
      hosts:
        10.0.0.10:
          ansible_host: 203.0.113.10
    agent:
      hosts:
        10.0.0.11:
          ansible_host: 203.0.113.11
        10.0.0.12:
          ansible_host: 203.0.113.12

  vars:
    ansible_port: 22
    ansible_user: ubuntu

    # k3s settings — check https://github.com/k3s-io/k3s/releases for available versions
    k3s_version: v1.35.0+k3s3
    token: "CHANGE_ME"  # REPLACE with a strong random secret
    api_endpoint: "10.0.0.10"
    cluster_context: my-cluster

    # Cozystack settings
    cozystack_api_server_host: "10.0.0.10"
    cozystack_root_host: "cozy.example.com"
    cozystack_platform_variant: "isp-full-generic"
    # cozystack_k3s_extra_args: "--tls-san=203.0.113.10"  # add public IP if nodes are behind NAT

cozystack_chart_version: "1.0.0-rc.2"

3. Create a Playbook

Create a site.yml file that chains OS preparation, k3s deployment, and Cozystack installation.

The collection repository includes example prepare playbooks for each supported OS family in the examples/ directory. Copy the one matching your target OS into your project directory, then reference it as a local file:

• Ubuntu / Debian
• RHEL / Rocky / Alma
• openSUSE / SLE

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-ubuntu.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-rhel.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

- name: Prepare nodes
  ansible.builtin.import_playbook: prepare-suse.yml

- name: Deploy k3s cluster
  ansible.builtin.import_playbook: k3s.orchestration.site

- name: Install Cozystack
  ansible.builtin.import_playbook: cozystack.installer.site

4. Run the Playbook

ansible-playbook --inventory inventory.yml site.yml

The playbook performs the following steps automatically:

1. Prepare nodes — installs required packages (nfs-common, open-iscsi, multipath-tools), configures sysctl, enables storage services
2. Deploy k3s — bootstraps a k3s cluster with Cozystack-compatible settings (disables built-in Traefik, ServiceLB, kube-proxy, Flannel; sets cluster-domain=cozy.local)
3. Install Cozystack — installs Helm and the helm-diff plugin (used for idempotent upgrades), deploys the cozy-installer chart, waits for the operator and CRDs, then creates the Platform Package

Configuration Reference

Core Variables

Networking

Advanced

Prepare Playbook Variables

The example prepare playbooks (copied from the examples/ directory) support additional variables:

Verification

After the playbook completes, verify the deployment from the first server node:

# Check operator
kubectl get deployment cozystack-operator --namespace cozy-system

# Check Platform Package
kubectl get packages.cozystack.io cozystack.cozystack-platform

# Check all pods
kubectl get pods --all-namespaces

Idempotency

The playbook is idempotent — running it again will not re-apply resources that haven’t changed. The Platform Package is only applied when a diff is detected via kubectl diff.