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

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.

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.

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):

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:

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:

sudo sh k3s-install.sh

Servisi ve kümeyi kontrol edin:

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:

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:

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:

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:

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:

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):

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:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: traefik

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:

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

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.

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:

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.

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:

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.

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

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 rehberinde karşılaştırın.
• Yalnızca birkaç konteynere ihtiyacınız varsa Docker ile Portainer daha basit bir seçenektir.
• Kümeler için boyutlandırılmış sunuculara 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 okuyun.