Create a Kluster

This guide explains how to create a Kluster and its first workerpool, then connect to it with kubectl.

Prerequisites

A Public Cloud project. See First Project if you don't have one yet.
kubectl installed on your computer.
For Terraform and API: an Infomaniak API token with the user_info, accounts and Public Cloud scopes.

Choose your options

When creating a Kluster, you need to choose:

Region

Where the Kluster runs: dc3-a or dc4-a.

Pack

The type of control plane:

shared: the control plane runs on infrastructure shared with other customers. Only one shared Kluster is allowed per project.
dedicated_4, dedicated_8 or dedicated_16: the control plane runs on dedicated resources, with a highly available etcd datastore. Up to four per project.

The list of packs and their prices is available with GET /1/public_clouds/kaas/packs (see the API tab below).

Kubernetes version

The minor version of Kubernetes, for example 1.35. The available versions are listed with GET /1/public_clouds/kaas/versions. The Kluster can later be upgraded one minor version at a time. Downgrades are not possible.

Each workerpool also needs:

Flavor: The instance flavor of the nodes, for example a2-ram4-disk50-perf1.
Availability zone: The availability zone where the nodes are created, for example dc3-a-04. To spread your nodes across zones, create one workerpool per zone.
Minimum and maximum number of nodes: If both values are equal, the workerpool has a fixed size. If the maximum is greater than the minimum, autoscaling is enabled: nodes are added or removed depending on the load.

Create the Kluster and its workerpool

Manager Terraform API

Log in to the Infomaniak Manager and open your Public Cloud.
Select your project, then open the Kubernetes section.
Click Create a Kluster.
Choose a name, the region, the pack and the Kubernetes version.
Confirm the creation. The Kluster takes 10 to 20 minutes to be ready.

Once the Kluster is ready, add a workerpool:

Open your Kluster and go to the Workerpools tab.
Click Add a workerpool.
Choose a name, the flavor, the availability zone and the minimum and maximum number of nodes.
Confirm. The nodes join the Kluster after 5 to 10 minutes.

The Kluster and its workerpools can be managed as code with the Infomaniak Terraform / OpenTofu provider.

You need the ID of your Public Cloud and of your project. Retrieve them with your API token:

export INFOMANIAK_TOKEN=xxxxxxxxxxxx

# Public Cloud ID
account_id=$(curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" https://api.infomaniak.com/2/profile | jq '.data.preferences.account.current_account_id')
curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" "https://api.infomaniak.com/1/public_clouds?account_id=$account_id" | jq '.data[] | {"name": .customer_name, "cloud_id": .id}'

# Project ID
public_cloud_id=1234  # use the ID retrieved above
curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" "https://api.infomaniak.com/1/public_clouds/$public_cloud_id/projects" | jq '.data[] | {"name": .name, "project_id": .public_cloud_project_id}'

Create a main.tf file:

terraform {
  required_providers {
    infomaniak = {
      source  = "Infomaniak/infomaniak"
      version = "~> 1.4"
    }
  }
}

# The token is read from the INFOMANIAK_TOKEN environment variable
provider "infomaniak" {}

resource "infomaniak_kaas" "kluster" {
  public_cloud_id         = 1234
  public_cloud_project_id = 5678

  name               = "my-kluster"
  pack_name          = "shared"
  kubernetes_version = "1.35"
  region             = "dc3-a"
}

resource "infomaniak_kaas_instance_pool" "workers" {
  public_cloud_id         = infomaniak_kaas.kluster.public_cloud_id
  public_cloud_project_id = infomaniak_kaas.kluster.public_cloud_project_id
  kaas_id                 = infomaniak_kaas.kluster.id

  name              = "workers"
  flavor_name       = "a2-ram4-disk50-perf1"
  availability_zone = "dc3-a-04"
  min_instances     = 2
  max_instances     = 2

  # Optional Kubernetes node labels: keys need a prefix, values can't be empty
  labels = {
    "node-role.kubernetes.io/worker" = "true"
  }
}

output "kubeconfig" {
  value     = infomaniak_kaas.kluster.kubeconfig
  sensitive = true
}

Apply the configuration:

terraform init
terraform apply

The creation takes about 20 minutes: 10 to 15 minutes for the Kluster, then 5 to 10 minutes for the workerpool.

Export the kubeconfig to a file:

terraform output -raw kubeconfig > kubeconfig.yaml

More examples (OIDC, IP filtering, audit logs) are available in the provider repository.

The Kluster can also be managed with the Infomaniak API. All requests need an API token, and the ID of your Public Cloud and project (see the Terraform tab to retrieve them).

export INFOMANIAK_TOKEN=xxxxxxxxxxxx
export PUBLIC_CLOUD_ID=1234
export PROJECT_ID=5678
API=https://api.infomaniak.com/1/public_clouds

List the available packs and Kubernetes versions:

curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" "$API/kaas/packs" | jq
curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" "$API/kaas/versions" | jq

Create the Kluster, using the kaas_pack_id of the chosen pack:

curl -s -X POST \
  -H "Authorization: Bearer $INFOMANIAK_TOKEN" \
  -H "Content-Type: application/json" \
  "$API/$PUBLIC_CLOUD_ID/projects/$PROJECT_ID/kaas" \
  -d '{
        "name": "my-kluster",
        "kaas_pack_id": 1,
        "region": "dc3-a",
        "kubernetes_version": "1.35"
      }' | jq .data

The response contains the ID of the new Kluster. Wait until its status is Active (GET /kaas/{kaas_id}, 10 to 15 minutes), then use the ID to create a workerpool:

export KAAS_ID=42

curl -s -X POST \
  -H "Authorization: Bearer $INFOMANIAK_TOKEN" \
  -H "Content-Type: application/json" \
  "$API/$PUBLIC_CLOUD_ID/projects/$PROJECT_ID/kaas/$KAAS_ID/instance_pools" \
  -d '{
        "name": "workers",
        "flavor": "a2-ram4-disk50-perf1",
        "availability_zone": "dc3-a-04",
        "minimum_instances": 2,
        "maximum_instances": 2
      }'

Download the kubeconfig:

curl -s -H "Authorization: Bearer $INFOMANIAK_TOKEN" \
  "$API/$PUBLIC_CLOUD_ID/projects/$PROJECT_ID/kaas/$KAAS_ID/kube_config" \
  | jq -r '.data' > kubeconfig.yaml

Other useful endpoints:

Method	Endpoint	Description
`GET`	`/kaas/{kaas_id}`	Get the Kluster and its status
`PATCH`	`/kaas/{kaas_id}`	Rename or upgrade the Kluster
`DELETE`	`/kaas/{kaas_id}`	Delete the Kluster
`PATCH`	`/kaas/{kaas_id}/instance_pools/{pool_id}`	Resize a workerpool
`DELETE`	`/kaas/{kaas_id}/instance_pools/{pool_id}`	Delete a workerpool
`PATCH`	`/kaas/{kaas_id}/apiserver`	Configure OIDC and audit logs
`PUT`	`/kaas/{kaas_id}/ip_filters`	Restrict access to the Kubernetes API

All endpoints are relative to https://api.infomaniak.com/1/public_clouds/{public_cloud_id}/projects/{project_id}.

Connect to the Kluster

Download the kubeconfig file of your Kluster from the Manager (or from the Terraform output or the API), then point kubectl to it:

export KUBECONFIG=$PWD/kubeconfig.yaml
kubectl get nodes

All the nodes of your workerpool should be listed with the Ready status:

NAME                          STATUS   ROLES    AGE   VERSION
pck-xxxxxxx-ppl-xxxxx-aaaaa   Ready    worker   3m    v1.35.x
pck-xxxxxxx-ppl-xxxxx-bbbbb   Ready    worker   3m    v1.35.x

Warning

The kubeconfig gives full administrator access to your Kluster. Keep it secret and consider OIDC authentication to give access to other users.

Tip

You can restrict access to the Kubernetes API to some IP ranges. With Terraform, set ip_filters in the apiserver block of the infomaniak_kaas resource:

apiserver = {
  ip_filters = ["203.0.113.0/24", "2001:db8::/32"]
}

Your Kluster is ready, you can now deploy your first application.