# Ubuntu'ya K3s nasıl kurulur: Traefik ve HTTPS ile tek düğümlü Kubernetes

> K3s'i resmi betikle Ubuntu'ya kurun, kubectl'i kendi kullanıcınızla kullanın, test uygulamasını Traefik ve Let's Encrypt ile yayınlayın, yedekleyip yükseltin.

Zorluk: Orta\
Denendiği sistemler: Ubuntu 24.04 LTS, Ubuntu 26.04 LTS

K3s, tek bir ikili dosya olarak paketlenmiş, hafif ve tam uyumlu bir Kubernetes dağıtımıdır. containerd'yi, Flannel ağını, CoreDNS'i, local-path depolama sağlayıcısını, ServiceLB yük dengeleyicisini ve Traefik ingress denetleyicisini birlikte getirir; bu sayede tek bir sunucu gerçek bir Kubernetes kümesi çalıştırmaya yeter. Bu rehber K3s'i bir Ubuntu LTS sunucusuna **resmi kurulum betiğiyle** (önce indirip okuyarak) kurar, yönetici kullanıcınız için `kubectl` ayarlar, bir test uygulamasını Traefik üzerinden yayınlar, cert-manager ile Let's Encrypt sertifikaları ekler; yedekleme, yükseltme ve kaldırma konularını da ele alır.

## Ön koşullar

- **Ubuntu 26.04 LTS** veya **Ubuntu 24.04 LTS** çalıştıran bir sunucu. SUSE'nin v1.36 için K3s destek matrisi Ubuntu 26.04, 24.04 ve 22.04'ü doğrular. Debian bu matrikste yer almaz; K3s belgeleri K3s'in çoğu modern Linux sisteminde çalışması gerektiğini söyler ve Debian için kurulum notları verir, ancak bu rehber yalnızca doğrulanmış Ubuntu sürümlerini esas alır.
- `sudo` yetkisi ve SSH anahtarıyla girişi olan, root olmayan bir kullanıcı; [Yeni bir Linux sunucusunu güvenli hale getirin](/guides/secure-a-new-linux-server) ve [SSH anahtarlarını ayarlayın](/guides/ssh-keys) rehberlerindeki gibi.
- Sunucu için benzersiz bir ana makine adı (K3s her düğümde bunu ister).
- Boş 80 ve 443 portları. Traefik bu portları ServiceLB üzerinden alır; bu nedenle aynı makinede Caddy, Nginx veya başka bir web sunucusu çalıştırmayın.
- HTTPS bölümü için: sunucuyu gösteren bir A kaydına sahip `hello.example.com` gibi bir alan adı.
- Docker gerekmez: K3s kendi konteyner çalışma ortamını getirir.

| Kaynak | En düşük (resmi) | Önerilen başlangıç |
|---|---|---|
| CPU | Sunucu düğümü başına 2 çekirdek | Öğrenmek için 2 vCPU, gerçek iş yükleri için 4 vCPU |
| Bellek | Sunucu düğümü başına 2 GB | 4 GB veya daha fazlası |
| Disk | SSD önerilir; veri deposu yoğun yazma yapar | 40 GB SSD |

En düşük değerler K3s gereksinimler sayfasından alınmıştır. Sağ sütun temkinli bir başlangıç noktasıdır; resmi veya ölçülmüş bir değer değildir. İş yüklerinizin ihtiyacını bunun üzerine ekleyin.

## Adım 1 — Yalnızca K3s'in ihtiyaç duyduğu portları açın

Tek düğümde internetin yalnızca SSH'ye ve 80 ile 443 portlarındaki Traefik'e ulaşması gerekir. K3s gereksinimlerindeki diğer portlar (agent'lar için 6443, Flannel VXLAN için 8472/udp, kubelet için 10250, etcd için 2379-2380) düğümler arası trafiği taşır. K3s belgeleri ufw'nin kapatılmasını önerir ve açık tutmak isteyenler için kurallar verir. Bu rehber ufw'yi bu kurallarla açık tutar: iki `from` satırı varsayılan pod ağına (10.42.0.0/16) ve servis ağına (10.43.0.0/16) izin verir.

```bash
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable
sudo ufw status verbose
```

`kubectl` komutunu SSH tüneli olmadan kendi bilgisayarınızdan çalıştırmak istiyorsanız API portuna yalnızca kendi adresinizden izin verin (belgelendirme IP'sini kendi adresinizle değiştirin):

```bash
sudo ufw allow from 198.51.100.25 to any port 6443 proto tcp
```

## Adım 2 — Kurulum betiğini indirin ve inceleyin

Resmi kurulum yöntemi `get.k3s.io` adresindeki betiktir. Root olarak ne yapacağını okuyabilmek için önce indirin:

```bash
curl -sfL https://get.k3s.io -o k3s-install.sh
less k3s-install.sh
```

Kısaca betik şunları yapar:

- systemd'yi (veya OpenRC'yi) algılar ve bir sunucu mu yoksa `K3S_URL` ayarlıysa bir agent mı kuracağına karar verir;
- `INSTALL_K3S_VERSION` veya `INSTALL_K3S_CHANNEL` ayarlamadıysanız sürümü `update.k3s.io` üzerindeki `stable` kanalından öğrenir;
- `k3s` ikili dosyasını projenin GitHub sürümlerinden indirir, SHA-256 sağlamasını doğrular ve `/usr/local/bin/k3s` konumuna kurar;
- `kubectl`, `crictl` ve `ctr` komutları henüz yoksa bunlar için sembolik bağlantılar ile `k3s-killall.sh` ve `k3s-uninstall.sh` betiklerini oluşturur;
- `k3s` systemd birimini ve ortam dosyasını `/etc/systemd/system/` altına yazar, ardından servisi etkinleştirip başlatır.

## Adım 3 — K3s'i kurun

İncelediğiniz betiği çalıştırın:

```bash
sudo sh k3s-install.sh
```

> **İpucu**
>
> Resmi tek satırlık karşılığı `curl -sfL https://get.k3s.io | sh -` komutudur. Bir sürüme sabitlemek için `sh` önüne `INSTALL_K3S_VERSION` ekleyin; örneğin Ekim 2026'da stable kanalının gösterdiği `INSTALL_K3S_VERSION=v1.36.5+k3s1`. Güncel değer için `update.k3s.io/v1-release/channels` adresindeki kanal listesine bakın.

Servisi ve kümeyi kontrol edin:

```bash
sudo systemctl status k3s --no-pager
sudo kubectl get nodes
sudo kubectl get pods -A
```

Düğüm yaklaşık bir dakika sonra `Ready` olarak listelenir. `kube-system` içinde `coredns`, `local-path-provisioner`, `metrics-server`, `traefik` ve bir `svclb-traefik` pod'unu `Running`, `helm-install` işlerini ise `Completed` olarak görmelisiniz.

## Adım 4 — kubectl'i yönetici kullanıcınızla kullanın

K3s yönetici kubeconfig dosyasını yalnızca root'un okuyabildiği `/etc/rancher/k3s/k3s.yaml` konumuna yazar. Bu dosya tam cluster-admin yetkisi verir; özgün dosyayı herkese okunabilir yapmak yerine kendi kullanıcınıza özel bir kopya verin:

```bash
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
chmod 600 ~/.kube/config
echo 'export KUBECONFIG=$HOME/.kube/config' >> ~/.bashrc
export KUBECONFIG=$HOME/.kube/config
kubectl get nodes
```

`kubectl get nodes` artık `sudo` olmadan çalışır. K3s her başladığında `k3s.yaml` içindeki sertifikaları yeniler, ancak kopyalar güncellenmez; `kubectl` bir gün yetkisiz olduğunuzu bildirirse dosyayı yeniden kopyalayın.

Kümeyi kendi bilgisayarınızdan kullanmak için `~/.kube/config` dosyasını oraya kopyalayın. En basit güvenli yol, `server: https://127.0.0.1:6443` satırını geçerli tutan bir SSH tünelidir:

```bash
ssh -L 6443:127.0.0.1:6443 user@203.0.113.10
```

Bunun yerine Adım 1'de 6443 portunu IP adresinize açtıysanız `server` alanındaki `127.0.0.1` değerini sunucunun adresiyle değiştirin.

## Adım 5 — Traefik arkasına bir test uygulaması dağıtın

K3s, Traefik'i bir IngressClass ile dağıtır. Adını doğrulayın:

```bash
kubectl get ingressclass
```

`traefik` görmelisiniz. Şimdi bir namespace, bir Nginx deployment'ı, bir servis ve `hello.example.com` için bir ingress içeren bir manifest oluşturun. `nano hello.yaml` ile yeni bir dosya açın ve şunu yapıştırın:

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: hello
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
  namespace: hello
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: web
          image: nginx:stable
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: hello
  namespace: hello
spec:
  selector:
    app: hello
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello
  namespace: hello
spec:
  ingressClassName: traefik
  rules:
    - host: hello.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hello
                port:
                  number: 80
```

Uygulayın ve test edin; önce sunucunun kendisinde bir `Host` başlığıyla, ardından DNS üzerinden:

```bash
kubectl apply -f hello.yaml
kubectl -n hello get pods,svc,ingress
curl -I -H "Host: hello.example.com" http://127.0.0.1
curl -I http://hello.example.com
```

İki istek de `Server: nginx` ile `HTTP/1.1 200 OK` döndürür. Trafik 80 portundaki ServiceLB'den Traefik'e, oradan da `hello` servisine akar.

## Adım 6 — cert-manager ve Let's Encrypt ile HTTPS ekleyin

Traefik TLS sonlandırabilir ama sertifikaya ihtiyaç duyar. Kubernetes içinde sertifika almanın ve yenilemenin yaygın yolu cert-manager'dır. cert-manager belgelerindeki statik manifest ile kurun (Ekim 2026'da kurulum sayfasının gösterdiği sürüm v1.21.2'dir; daha yenisi için sayfayı kontrol edin):

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.2/cert-manager.yaml
kubectl -n cert-manager wait --for=condition=Available deployment --all --timeout=300s
kubectl -n cert-manager get pods
```

`cert-manager`, `cert-manager-cainjector` ve `cert-manager-webhook` pod'ları `Running` olmalıdır. Ardından Let's Encrypt HTTP-01 doğrulamalarını Traefik üzerinden çözen bir ClusterIssuer oluşturun. Kendi e-posta adresinizle `clusterissuer.yaml` olarak kaydedin:

```yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: traefik
```

```bash
kubectl apply -f clusterissuer.yaml
kubectl get clusterissuer
```

cert-manager ACME hesabını kaydettiğinde `READY` değeri `True` olur. Şimdi ingress'e bir annotation ve bir `tls` bölümü ekleyerek sertifika isteyin. Bunu `hello-ingress.yaml` olarak kaydedin:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello
  namespace: hello
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - hello.example.com
      secretName: hello-tls
  rules:
    - host: hello.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: hello
                port:
                  number: 80
```

```bash
kubectl apply -f hello-ingress.yaml
kubectl -n hello get certificate
curl -I https://hello.example.com
```

Bir dakika sonra sertifika `READY True` olarak görünür ve `curl` HTTPS üzerinden başarılı olur.

> **İpucu**
>
> Deneme yaparken ikinci bir ClusterIssuer'ı `https://acme-staging-v02.api.letsencrypt.org/directory` staging adresine yönlendirin. Staging sertifikalarına tarayıcılar güvenmez, ancak istek sınırları çok daha yüksektir.

## Yedekleme ve geri yükleme

Tek bir K3s sunucusu varsayılan olarak gömülü bir SQLite veri deposu kullanır. Durum bilgisi `/var/lib/rancher/k3s/server/db/` içinde durur; `/var/lib/rancher/k3s/server/token` konumundaki sunucu token'ı ise buradaki gizli verileri şifreler. Aynı token olmadan geri yüklenen veri deposu kullanılamaz. Tutarlı bir kopya için K3s'i durdurun (çalışan pod'lar boşaltılmaz ama API kısa bir süre erişilemez olur), ikisini `/etc/rancher/k3s` ile birlikte arşivleyin ve yeniden başlatın:

```bash
sudo mkdir -p /opt/backups
sudo systemctl stop k3s
sudo tar czf /opt/backups/k3s-server-$(date +%F).tar.gz /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s
sudo systemctl start k3s
```

Bu arşiv uygulama verilerinizi değil küme durumunu içerir. Varsayılan `local-path` StorageClass'ın kalıcı volume'ları `/var/lib/rancher/k3s/storage` altında durur; bunların içindeki veritabanlarını kendi döküm araçlarıyla yedekleyin. Manifestlerinizi (`hello.yaml` vb.) Git'te tutun ve her yedeği sunucunun dışına kopyalayın.

Aynı sunucuya geri yüklemek için `INSTALL_K3S_VERSION` ile aynı K3s sürümünü kurun, ardından veri deposunu ve token'ı değiştirin.

> **Tehlike**
>
> Sonraki komutlar mevcut K3s veri deposunu siler. Yalnızca bir yedeği geri yüklemek için kullanın.

```bash
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar xzf /opt/backups/k3s-server-2026-10-09.tar.gz -C /
sudo systemctl start k3s
```

Kurulumu `--cluster-init` ile yaptıysanız K3s, SQLite yerine gömülü etcd kullanır. Bu durumda 00:00 ve 12:00'de kendiliğinden anlık görüntü alır ve son beşini `/var/lib/rancher/k3s/server/db/snapshots` içinde tutar. İstediğiniz an bir tane alabilirsiniz:

```bash
sudo k3s etcd-snapshot save
sudo ls /var/lib/rancher/k3s/server/db/snapshots
```

Bir etcd anlık görüntüsünü geri yüklemek için K3s'i durdurun ve K3s `etcd-snapshot` belgelerinde anlatıldığı gibi `sudo k3s server --cluster-reset --cluster-reset-restore-path=` komutunu anlık görüntünün yoluyla birlikte çalıştırın.

## K3s'i yükseltme

K3s sürüm kanalları yayınlar: `stable` (varsayılan ve üretim için önerilen), `latest` ve `v1.36` gibi her Kubernetes ara sürümü için ayrı bir kanal. Yükseltmek için betiği yeniden indirin ve kurulumda kullandığınız ortam değişkenleri ve seçeneklerle tekrar çalıştırın. `/etc/rancher/k3s/config.yaml` içindeki seçenekler korunur; ancak komut satırında verdiğiniz ve şimdi yazmadığınız her şey kaybolur.

```bash
curl -sfL https://get.k3s.io -o k3s-install.sh
sudo INSTALL_K3S_CHANNEL=stable sh k3s-install.sh
kubectl get nodes
```

`VERSION` sütunu yeni sürümü gösterir. Kubernetes ara sürümlerini atlamayın: `stable` sizden birden fazla ara sürüm ilerideyse sürüm kanalları üzerinden adım adım yükseltin; örneğin `INSTALL_K3S_CHANNEL=v1.36` ile. Önce sürüm notlarını okuyun ve yedek alın. Elle uğraşmadan yükseltme için K3s, bir kanalı izleyen yükseltme planlarını (Plan) uygulayan system-upgrade-controller'ı belgeler.

## K3s'i kaldırma

> **Tehlike**
>
> Kaldırma işlemi tüm pod'ları durdurur; yerel veri deposunu, düğüm yapılandırmasını ve local-path volume'larındaki verileri siler. Önce yedek alın.

```bash
sudo /usr/local/bin/k3s-uninstall.sh
```

## Sorun giderme

### Traefik'in svclb pod'ları Pending durumunda kalıyor, 80 ve 443 portları yanıt vermiyor

ServiceLB, Traefik'i 80 ve 443 ana makine portlarında yayınlar ve pod'ları yalnızca bu portların boş olduğu düğümlerde başlar. Portları büyük olasılıkla başka bir web sunucusu (Caddy, Nginx, Apache) veya Docker'dan bir konteyner tutuyordur. `sudo ss -tlnp | grep -E ':(80|443) '` ile kontrol edin, diğer servisi durdurun ve pod'ların başlamasını bekleyin.

### ufw açıkken pod'lar ad çözemiyor veya servislere ulaşamıyor

Güvenlik duvarı pod ve servis ağlarından gelen trafiği engelliyor. Adım 1'deki `from 10.42.0.0/16` ve `from 10.43.0.0/16` kurallarını ekleyin ya da K3s'in önerisini izleyerek ufw'yi kapatıp sağlayıcınızın ağ güvenlik duvarını kullanın.

### The connection to the server 127.0.0.1:6443 was refused

K3s servisi çalışmıyor veya hâlâ başlıyor. `sudo systemctl status k3s` ile kontrol edin ve logu `sudo journalctl -u k3s -e` ile okuyun. Sık görülen nedenlerden biri `/etc/rancher/k3s/config.yaml` içindeki hatalı bir seçenektir.

### kubectl sunucuda oturum açmanız gerektiğini söylüyor

Kubeconfig kopyanız, K3s'in sonradan yenilediği sertifikaları içeriyor. Adım 4'teki kopyalama komutlarını tekrarlayın.

### Sertifika hiç hazır olmuyor

`kubectl -n hello describe certificate hello-tls` ve `kubectl get challenges -A` komutlarını çalıştırın. Hataların çoğu, henüz sunucuyu göstermeyen DNS kayıtlarından veya 80 portunun engellenmesinden kaynaklanır; çünkü Let's Encrypt'in HTTP-01 doğrulaması Traefik'e düz HTTP üzerinden ulaşmak zorundadır.

## Sonraki adımlar

- Traefik'in bağımsız bir proxy olarak kullanımını [Traefik reverse proxy](/guides/traefik-reverse-proxy) rehberinde karşılaştırın.
- Yalnızca birkaç konteynere ihtiyacınız varsa [Docker ile Portainer](/guides/install-portainer) daha basit bir seçenektir.
- Kümeler için boyutlandırılmış sunuculara [Kubernetes VPS](/kubernetes-vps) sayfasında göz atın.
- Yüksek erişilebilirlik, agent'lar ve yapılandırma seçenekleri için resmi [K3s belgelerini](https://docs.k3s.io/) okuyun.

## Sık sorulan sorular

### K3s'i çalıştırmak için Docker gerekir mi?

Hayır. K3s kendi containerd çalışma ortamını crictl ve ctr araçlarıyla birlikte getirir. Docker aynı sunucuda çalışabilir, ancak 80 ve 443 portlarını paketle gelen Traefik ingress denetleyicisi için boş bırakın.

### Tek düğümlü bir K3s kümesi üretim için yeterli mi?

Tek bir K3s sunucusu eksiksiz bir Kubernetes kümesidir ve küçük iş yükleri için iyi çalışır, ancak tek arıza noktasıdır. Yedeklilik için K3s, gömülü etcd veya harici bir veri deposu ile ek sunucu düğümlerini destekler.

### Tek düğümlü bir K3s sunucusu hangi portlara ihtiyaç duyar?

İnternetten yalnızca SSH ile Traefik için 80 ve 443. 6443 Kubernetes API portudur; kubectl'i uzaktan çalıştıracaksanız yalnızca kendi IP adresinize açın. K3s belgelerindeki diğer portlar düğümler arası trafik içindir.

### K3s kubeconfig dosyası nerede?

K3s yönetici kubeconfig dosyasını yalnızca root'un okuyabildiği /etc/rancher/k3s/k3s.yaml konumuna yazar. Yönetici kullanıcınız için ~/.kube/config konumuna kopyalayın ve K3s sertifikaları yeniledikten sonra yeniden kopyalayın; kopyalar kendiliğinden güncellenmez.

### Paketle gelen Traefik'i kapatabilir miyim?

Evet. Tüm sunucuları --disable=traefik ile başlatın, örneğin /etc/rancher/k3s/config.yaml içinde bir disable girdisiyle; ardından tercih ettiğiniz ingress denetleyicisini kurun.

---

Kaynak: <https://hyperdc.com/tr/guides/tutorials/install-k3s>\
Son güncelleme: 2026-10-09