Cleura on Backend Engineering Strategy Tools

Gardener on Cleura

Tue, 16 Jun 2026 00:00:00 +0000

Getting hands-on with Gardener on Cleura — a European OpenStack cloud — ahead of using it professionally. The focus is on the networking and traffic ingress side: how does a Gardener shoot cluster on OpenStack expose services, what does the LoadBalancer path actually look like, and when does ingress apply versus when it does not.

The test application is a Minecraft server with Velocity proxy — useful precisely because it is raw TCP rather than HTTP, which forces the full LoadBalancer path rather than an ingress shortcut.

→ Gardener on Cleura — technical notes

Steps

1 — Shoot cluster

Provision a Gardener shoot cluster on Cleura. Cleura wraps Gardener behind their own REST API — gardenctl and the Gardener Terraform provider require the garden cluster kubeconfig, which Cleura does not expose. Cluster lifecycle goes through their REST API instead.

→ Provisioning via Cleura REST API
→ Cleura docs issue #533 — IaC and gardenctl access

2 — Minecraft via standard LoadBalancer

Deploy itzg/minecraft-server as a StatefulSet with a plain LoadBalancer service for TCP 25565 — the direct Octavia path, no Gateway involved. Gets the server running quickly and confirms TCP exposure works on Cleura independently.

Internet
 |
TCP 25565
 |
Octavia LB (direct LoadBalancer service)
 |
Minecraft Pod (itzg/minecraft-server)
 |
PVC (Cinder)

Manifests: stateful_set.yaml · service.yaml

Apply directly from this repo:

kubectl apply -k "https://github.com/Backend-Engineering-Strategy-Tools/site//static/scripts/mc?ref=main"

Check the rollout and grab the external IP:

kubectl get all -l app=mc-example

kubectl get svc mc-example \
 -o jsonpath='{.status.loadBalancer.ingress[0].ip}:{.spec.ports[0].port}'

2.5 — Migrate to Helm chart

Swap the raw manifests for the itzg/minecraft-server-charts Helm chart — actively maintained, covers server type, persistence, RCON, backups, and extra ports (BlueMap, Dynmap). The raw YAML stays useful as a reference for the underlying shape.

Manifests: values.yaml

helm repo add minecraft-server-charts https://itzg.github.io/minecraft-server-charts/
helm upgrade --install mc minecraft-server-charts/minecraft \
 -f https://backend-engineering-strategy-tools.github.io/site/scripts/mc-helm/values.yaml

Check the rollout and grab the external IP:

kubectl get all -l app.kubernetes.io/instance=mc

kubectl get svc mc-example -o jsonpath='{.status.loadBalancer.ingress[0].ip}:{.spec.ports[0].port}'

3 — Envoy Gateway

Deploy Envoy Gateway into the shoot cluster — the CNCF implementation of the Kubernetes Gateway API. The NGINX Ingress Controller is deprecated; Gateway API is the forward path with a standardised spec for both HTTP and TCP.

Envoy Gateway exposes a single LoadBalancer service via Octavia. Everything routes through it.

4 — HTTPRoute, certificates, and BlueMap

Deploy BlueMap — a Minecraft mod that renders the world as a live 3D web map served over HTTP. Route it through the Gateway with a HTTPRoute and wire cert-manager to provision a Let’s Encrypt certificate.

A real HTTP service with a real use, not a throwaway test page. Validates the full HTTP + TLS path before touching the game server.

5 — Migrate to TCPRoute

Migrate the TCP service to a TCPRoute through Envoy Gateway. TCPRoute is in the Gateway API experimental channel — this step validates that a single Gateway handles both HTTP and raw TCP.

Internet
 |
Octavia LB (one Gateway LoadBalancer)
 |
Envoy Gateway
 |
+------------------------------+------------------------------+
| |
HTTPRoute → BlueMap TCPRoute → Minecraft

6 — Velocity (if needed)

Add Velocity as a TCP proxy in front of the Minecraft server if multi-server routing becomes relevant — lobby, modded, survival as separate backends. Skip if a single server is enough.

→ Minecraft project

7 — Plugin pipeline

A colleague is building a Minecraft plugin. The goal is a Dagger pipeline with GitHub Actions — the same build running locally and in CI, covering the JVM toolchain and packaging steps.

8 — AI

Something with NPC behaviour, a bot, or plugin-side automation. Low priority, high fun.

IaC gap

Cleura does not expose the garden cluster kubeconfig. That one limitation closes off the entire Gardener tooling ecosystem: gardenctl requires it, the Gardener Terraform provider requires it, and any Crossplane provider built on the Gardener API would require it too. There is no HCL path here.

What remains is Cleura’s own REST API — which is fine for interactive use but falls short the moment you want to drive cluster lifecycle from a pipeline. A bash script wrapping curl and jq works, and that is what cleura-shoot.sh does, but it is a workaround rather than a solution. No state, no plan, no diff — just imperative API calls.

Options if this needs to graduate beyond a script:

Crossplane provider-http — can wrap the REST API declaratively, but has no native polling or deletion hooks, so the reconciliation story is awkward
Custom Terraform provider — full plan/apply semantics, but requires writing a Go provider from scratch
Pulumi dynamic provider — similar effort, Python or TypeScript

A feature request for gardenctl access or a native IaC provider has been filed with Cleura (→ cleura/docs#533). Until something changes there, the bash script is as good as it gets.

Status

Step	Status
1 — Shoot cluster on Cleura	done
2 — Minecraft via LoadBalancer (itzg)	planned
2.5 — Migrate to Helm chart	planned
3 — Envoy Gateway	planned
4 — HTTPRoute + cert-manager + BlueMap	planned
5 — Migrate to TCPRoute	planned
6 — Velocity	planned
7 — Plugin pipeline (Dagger)	planned
8 — AI	planned

Building this out — notes will expand as each step lands.

Gardener on Cleura

Tue, 16 Jun 2026 00:00:00 +0000

Gardener is a Kubernetes-as-a-Service framework that runs on Kubernetes and manages the lifecycle of other clusters declaratively. Rather than managing control planes by hand, Gardener treats clusters as a resource — defined, created, upgraded, and deleted via the Gardener API.

Concepts

Gardener uses three layers:

Layer	What it is
Garden cluster	Runs Gardener itself — the management control plane
Seed cluster	Hosts the control planes of shoot clusters (as pods)
Shoot cluster	The cluster you actually use — nodes run on the target cloud

The shoot cluster’s API server does not run on the shoot nodes. It runs as a pod inside the seed cluster. From the outside it behaves like any other Kubernetes cluster; internally the control plane is isolated from the data plane.

Shoot clusters are defined as Shoot resources applied to the garden cluster:

apiVersion: core.gardener.cloud/v1beta1
kind: Shoot
metadata:
 name: my-cluster
 namespace: garden-my-project
spec:
 cloudProfileName: openstack
 region: sto2
 provider:
 type: openstack
 workers:
 - name: worker-pool
 machine:
 type: l2.c2r4
 minimum: 1
 maximum: 3
 kubernetes:
 version: "1.30"
 networking:
 type: calico
 pods: 100.128.0.0/11
 nodes: 10.250.0.0/16
 services: 100.112.0.0/13

Shoot cluster on Cleura

Cleura is a European OpenStack provider. Gardener provisions shoot nodes as OpenStack VMs via the OpenStack machine controller.

Key integrations:

Component	Implementation
Node provisioning	OpenStack VMs via Gardener machine controller
Load balancers	Octavia via cloud-controller-manager
Block storage	Cinder via CSI driver
DNS	Manual or external-dns
CNI	Calico (default) or configurable

Gardener on Cleura does not provide an ingress controller or API gateway — these are brought in separately.

Networking

Gardener manages the cluster network configuration as part of the shoot spec. Pod, node, and service CIDRs are defined at cluster creation and must not overlap with the OpenStack network.

On Cleura, nodes get OpenStack floating IPs for egress. Pod-to-pod traffic stays within the cluster overlay network (Calico by default). Traffic entering from outside the cluster goes through a LoadBalancer service — either directly for raw TCP, or via a gateway controller for HTTP.

Ingress — classic vs Gateway API

The classic Kubernetes Ingress resource is HTTP-only, has no TCP support, and its feature set varies across implementations via non-standard annotations. The NGINX Ingress Controller — the most widely used implementation — is deprecated; NGINX now focuses on their Gateway API implementation instead.

The Kubernetes Gateway API is the forward path — a set of CRDs (Gateway, HTTPRoute, TCPRoute, TLSRoute) with a standardized spec and first-class support for both HTTP and TCP.

Resource	Protocol	API	Status
`Ingress`	HTTP only	Kubernetes	Stable, legacy
`HTTPRoute`	HTTP/HTTPS	Gateway API	Stable
`TCPRoute`	Raw TCP	Gateway API	Experimental
`TLSRoute`	TLS passthrough	Gateway API	Experimental

Envoy Gateway

Envoy Gateway is the CNCF implementation of the Kubernetes Gateway API using Envoy as the data plane. It supports HTTPRoute, TCPRoute, and TLSRoute through a single Gateway resource — one entry point, both protocols.

Octavia LB ← one LoadBalancer service per Gateway listener
 |
Envoy Gateway pod
 |
+------------------+------------------+
| |
HTTPRoute → ClusterIP pods TCPRoute → ClusterIP pods

Envoy Gateway is deployed into the shoot cluster and exposes a LoadBalancer service via Octavia, the same as any other service. The Gateway API resources then declare what routes through it.

TCPRoute — declaring TCP services

TCPRoute attaches to a Gateway listener and routes raw TCP traffic to a backend service. This is how a non-HTTP workload (e.g. a game server, a database proxy, a custom protocol service) gets exposed through the Gateway API rather than a standalone LoadBalancer service.

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
 name: my-tcp-service
 namespace: my-app
spec:
 parentRefs:
 - name: my-gateway
 sectionName: tcp-listener
 rules:
 - backendRefs:
 - name: my-service
 port: 1234

The corresponding Gateway listener:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: my-gateway
 namespace: my-app
spec:
 gatewayClassName: envoy-gateway
 listeners:
 - name: tcp-listener
 protocol: TCP
 port: 1234
 - name: http-listener
 protocol: HTTP
 port: 80

One Gateway, both protocols declared explicitly. The TCPRoute API is in the experimental channel and requires opting in when installing Envoy Gateway.

HTTPRoute — HTTP services

HTTPRoute handles HTTP and HTTPS traffic with routing by hostname, path, header, or method — without annotations.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: my-http-service
 namespace: my-app
spec:
 parentRefs:
 - name: my-gateway
 sectionName: http-listener
 hostnames:
 - my-app.example.com
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /
 backendRefs:
 - name: my-service
 port: 8080

LoadBalancer — direct TCP via Octavia

For cases where a TCPRoute is not appropriate (or the Gateway API experimental channel is not enabled), a LoadBalancer service provisions an Octavia LB directly:

apiVersion: v1
kind: Service
metadata:
 name: my-tcp-service
 namespace: my-app
spec:
 type: LoadBalancer
 selector:
 app: my-app
 ports:
 - port: 1234
 targetPort: 1234
 protocol: TCP

Annotations control Octavia behaviour — timeouts, health check parameters, internal vs external. These are provider-specific and not standardised across OpenStack deployments.

Storage

Cinder block volumes are available via the CSI driver. A PersistentVolumeClaim provisions a Cinder volume automatically using the cluster’s default storage class.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
 name: my-data
spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 20Gi

Cinder volumes are ReadWriteOnce — they attach to a single node. For stateful workloads, use StatefulSet rather than Deployment to get stable volume binding across pod restarts.

Provisioning a shoot cluster on Cleura

Cleura wraps Gardener behind their own REST API at rest.cleura.cloud. The garden cluster kubeconfig is not exposed — gardenctl does not work directly. Cluster lifecycle is managed through HTTP calls.

Authentication

Every call requires a token obtained once per session:

curl -s -X POST https://rest.cleura.cloud/auth/v1/tokens \
 -H "Content-Type: application/json" \
 -d '{"auth": {"login": "you@example.com", "password": "yourpass"}}' \
 | jq '{token: .token}'

Pass X-AUTH-LOGIN and X-AUTH-TOKEN headers on all subsequent calls.

Bootstrap (once per project/region)

Before creating any clusters, the project must be bootstrapped — this wires up the OpenStack credentials that Gardener uses to provision nodes:

curl -X POST \
 https://rest.cleura.cloud/gardener/v1/public/secret/kna1/{projectId}/bootstrap \
 -H "X-AUTH-LOGIN: ..." -H "X-AUTH-TOKEN: ..."

Safe to call repeatedly; idempotent.

Create a shoot cluster

curl -X POST \
 https://rest.cleura.cloud/gardener/v1/public/shoot/kna1/{projectId} \
 -H "X-AUTH-LOGIN: ..." -H "X-AUTH-TOKEN: ..." \
 -H "Content-Type: application/json" \
 -d '{
 "shoot": {
 "name": "my-cluster",
 "kubernetes": {"version": "1.31.0"},
 "provider": {
 "infrastructureConfig": {"floatingPoolName": "ext-net"},
 "workers": [{
 "name": "default",
 "machine": {
 "type": "4C-8GB-50GB",
 "image": {"name": "ubuntu", "version": "22.4.20230301"}
 },
 "minimum": 1,
 "maximum": 3,
 "volume": {"size": "50Gi"}
 }]
 }
 }
 }'

Poll until ready

curl https://rest.cleura.cloud/gardener/v1/public/shoot/kna1/{projectId}/my-cluster \
 -H "X-AUTH-LOGIN: ..." -H "X-AUTH-TOKEN: ..." \
 | jq '.lastOperation | {state, description, progress}'

Poll until lastOperation.state == "Succeeded". Takes roughly 10–15 minutes on first provision.

Fetch kubeconfig

The Cleura docs reference two kubeconfig paths — GET /kubeconfig (lowercase) and POST /Kubeconfig (uppercase, different casing). Neither worked reliably in practice. The endpoint that actually returns a kubeconfig is:

curl -s -X POST \
 https://rest.cleura.cloud/gardener/v1/public/shoot/kna1/{projectId}/my-cluster/adminkubeconfig \
 -H "X-AUTH-LOGIN: ..." -H "X-AUTH-TOKEN: ..." \
 -H "Content-Type: application/json" \
 -d '{"config": {"expirationSeconds": 3600}}' \
 | jq -r > my-cluster-kubeconfig.yaml

The expirationSeconds field controls credential lifetime. A bug report has been filed with Cleura about the endpoint inconsistency — the adminkubeconfig path is not documented.

Path	Method	Documented	Works
`/kubeconfig`	GET	yes	unclear
`/Kubeconfig`	POST	yes	unclear
`/adminkubeconfig`	POST	no	yes

→ Cleura docs issue #534 — kubeconfig endpoint inconsistencies in Gardener REST API

Script

A bash script wrapping the full workflow (list, create, wait, kubeconfig, delete) is available: cleura-shoot.sh

export CLEURA_LOGIN="you@example.com"
export CLEURA_PASSWORD="yourpass"

./cleura-shoot.sh list
./cleura-shoot.sh create my-cluster
./cleura-shoot.sh wait my-cluster
./cleura-shoot.sh kubeconfig my-cluster
./cleura-shoot.sh delete my-cluster

IaC options

No native Terraform provider exists for Cleura’s Gardener REST API. The Gardener Terraform provider (registry.terraform.io/providers/gardener/gardener) requires the garden cluster kubeconfig, which Cleura does not expose. Options:

Approach	Notes
Bash + curl	Minimal deps — just `curl` and `jq`
Crossplane `provider-http`	Declarative, Kubernetes-native, reconciliation loop
Custom Terraform provider	Full `plan`/`apply` semantics — requires Go provider development
Pulumi custom dynamic provider	Python/TypeScript, similar effort to custom Terraform provider