Containers

Containers nedir?

Workers, V8 isolate’i içinde JavaScript ve Wasm çalıştırır. Dosya sistemi yoktur, süreç başlatamaz, CPU süresi sınırlıdır. Bu sınırların dışına çıkan işler vardır: ffmpeg ile video dönüştürmek, ImageMagick kullanmak, bir Python veri bilimi kütüphanesini çalıştırmak, kendi derlediğin bir C ikilisini koşturmak.

Containers tam bu boşluğu doldurur. Cloudflare’in kendi tanımı:

“Run code written in any programming language, built for any runtime, as part of apps built on Workers.” — “Deploy your container image to Region:Earth without worrying about managing infrastructure - just define your Worker and wrangler deploy.”

Ürün sayfasındaki slogan durumu iyi özetliyor: “Run containers globally with one command. No Kubernetes, no regions.”

Nasıl çalışır?

Image nasıl yayına gider

wrangler deploy çalıştığında, image alanı bir Dockerfile yolunu gösteriyorsa Wrangler image’ı yerelde Docker ile derler ve Cloudflare’in R2 destekli registry’sine gönderir. Kimlik doğrulama otomatiktir. Sonraki deploy’larda yalnızca değişen katmanlar gönderilir.

Image linux/amd64 mimarisinde olmalıdır — Apple Silicon Mac’te varsayılan derleme arm64 üretir ve çalışmaz.

Worker’dan container’a yönlendirme

İstek → Worker → Durable Object → Container instance

Container sınıfı DurableObject’i genişletir. Bu, üç şeyi beraberinde getirir: this.ctx.storage (container yeniden başlasa da kalıcı SQLite), alarmlar, ve RPC. Ayrıca wrangler.jsonc içinde new_sqlite_classes kullanmayı zorunlu kılar.

Instance başlatılırken image’ı önceden çekilmiş en yakın konum seçilir. Bir kez başladıktan sonra, istek nereden gelirse gelsin aynı instance’a yönlendirilir.

Uyku ve kapanma

Varsayılan sleepAfter = "10m". Kapanma sırası resmî olarak şöyle:

1. Ana sürece SIGTERM gönderilir
2. Sürecin çıkması için 15 dakikaya kadar beklenir
3. Hâlâ çalışıyorsa SIGKILL gönderilir

Yaşam döngüsü kancaları: onStart(), onStop(), onActivityExpired(), onError().

Disk

Bu, Containers’ta en çok yanlış anlaşılan konudur:

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Başka bir dil veya runtime gerektiren işler (Go, Rust, Python, Java, .NET)
• CLI araçları: ffmpeg, ImageMagick, pandoc, LaTeX
• Gerçek dosya sistemi gerektiren kütüphaneler
• Paralel CPU çekirdeği veya GB ölçeğinde bellek isteyen hesaplama
• Elinde zaten bir Docker image’ı olan mevcut uygulamalar

Uygun olmadığı işler

• Ücretsiz plan. Containers yalnızca Workers Paid’de var.
• Gecikmeye duyarlı, yüksek frekanslı küçük işler. 1–3 saniyelik cold start karşısında Worker isolate’i ~0 ms’de başlar.
• Kalıcı yerel disk gerektiren işler. Disk geçicidir.
• Otomatik ölçeklenen stateless servisler. Autoscaling henüz yok; sabit N instance ve getRandom ile idare edilir.
• Son kullanıcıdan ham TCP/UDP. Tüm trafik Worker’dan HTTP olarak geçer.
• 4 vCPU / 12 GiB bellek / 20 GB diskten büyük işler. Sert tavan; üstü için Cloudflare ile görüşmek gerekir.
• Garantili çalışma süresi. Instance’ın belirli bir süre ayakta kalacağı garanti edilmez.
• iptables veya kernel modülü gerektiren işler. Desteklenmiyor.
• GPU iş yükleri. Ürün sayfasında “coming soon” olarak geçiyor, kullanılabilir olduğu doğrulanamadı.

Somut örnekler

1. Statik ön yüz + container arka uç

{
  "name": "uygulama",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-31",
  "assets": { "directory": "./dist", "binding": "ASSETS" },
  "containers": [
    { "class_name": "ArkaUc", "image": "./Dockerfile", "max_instances": 3, "instance_type": "basic" }
  ],
  "durable_objects": { "bindings": [{ "class_name": "ArkaUc", "name": "ARKA_UC" }] },
  "migrations": [{ "new_sqlite_classes": ["ArkaUc"], "tag": "v1" }]
}

import { Container, getRandom } from "@cloudflare/containers";

const INSTANCE_SAYISI = 3;

export class ArkaUc extends Container {
  defaultPort = 8080;
  sleepAfter = "2h";
}

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api")) {
      // Stateless dağıtım: konumdan bağımsız rastgele instance seçer
      const instance = await getRandom(env.ARKA_UC, INSTANCE_SAYISI);
      return instance.fetch(request);
    }
    return env.ASSETS.fetch(request);
  },
};

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /out/sunucu ./sunucu.go

FROM gcr.io/distroless/static-debian12
COPY --from=build /out/sunucu /sunucu
EXPOSE 8080
ENTRYPOINT ["/sunucu"]

2. Oturum başına instance

import { Container } from "@cloudflare/containers";

export class Oturum extends Container {
  defaultPort = 4000;
  sleepAfter = "10m";
}

export default {
  async fetch(request, env) {
    const { pathname } = new URL(request.url);
    if (pathname.startsWith("/oturum/")) {
      // Her oturum kendi container'ına düşer — adres tabanlı, deterministik
      const container = env.OTURUM.getByName(pathname);
      return await container.fetch(request);
    }
    return new Response("Bulunamadı", { status: 404 });
  },
};

3. Egress kilitleme — programlanabilir çıkış

Bu, container’a sır vermeden dış API çağırmanın yoludur.

import { Container, ContainerProxy } from "@cloudflare/containers";
export { ContainerProxy };   // Bu satır olmadan sessizce çalışmaz

export class Isci extends Container {
  interceptHttps = true;
  enableInternet = false;              // varsayılan olarak her şeyi engelle
  allowedHosts = ["api.github.com"];   // yalnızca buna izin ver
}

Isci.outbound = async (request, env, ctx) => {
  const url = new URL(request.url);
  if (url.hostname === "api.github.com") {
    const headers = new Headers(request.headers);
    // Token Worker'da kalır, container onu hiç görmez
    headers.set("Authorization", `Bearer ${env.GITHUB_TOKEN}`);
    return fetch(new Request(request, { headers }));
  }
  return new Response("Engellendi", { status: 403 });
};

enableInternet: false iken yalnızca 80, 443 ve DNS açıktır; DNS sorguları Cloudflare’in sunucularına gider.

4. Zamanlanmış toplu iş

{ "triggers": { "crons": ["*/15 * * * *"] } }

import { Container, getContainer } from "@cloudflare/containers";

export class CronContainer extends Container {
  sleepAfter = "30s";
  onStart() { console.log("container başladı"); }
  onStop()  { console.log("container durdu"); }
}

export default {
  async fetch() {
    return new Response("Bu Worker zamanlanmış container işi çalıştırır.");
  },
  async scheduled(controller, env) {
    const container = getContainer(env.CRON_CONTAINER);
    await container.start({
      envVars: { BASLANGIC: new Date().toISOString() },
    });
  },
};

Cron tetikleyicilerinin duvar saati sınırı 15 dakikadır.

5. WebSocket geçişi

import { Container, getContainer } from "@cloudflare/containers";

export class WsContainer extends Container {
  defaultPort = 8080;
  sleepAfter = "2m";
}

export default {
  async fetch(request, env) {
    return getContainer(env.WS_CONTAINER).fetch(request);
  },
};

Resmî ifade: “WebSocket requests are automatically forwarded to a container using the default fetch method.”

Demo 1: Workers’a sığmayan bir işi container’da çalıştırma

Senaryo: yüklenen bir videodan küçük resim üretmek. ffmpeg gerektirdiği için Workers’ta mümkün değil.

Adım 1 — Kurulum

docker info    # Docker çalışıyor olmalı
npm create cloudflare@latest -- --template=cloudflare/templates/containers-template
cd <proje>

C3 çıktısı ve proje yapısı; containers-template'in oluşturduğu Dockerfile ile wrangler.jsonc görünsün

Adım 2 — Yerelde çalıştır

npx wrangler dev

Terminal — Docker build adımları ve ardından container binding'inin listelenmesi

curl ile localhost:8787 üzerinden container'a istek ve dönen yanıt

Adım 3 — Yayına al

npx wrangler deploy

Terminal — image push adımları, hangi katmanların yeni olduğu ve toplam boyut

Adım 4 — Instance’ları incele

npx wrangler containers list
npx wrangler containers images list
npx wrangler containers instances

Terminal — container listesi, image listesi ve çalışan instance'lar; instance tipi ve durumu görünsün

Workers & Pages → Containers → Metrics: aktif instance sayısı, bellek ve CPU kullanımı

Adım 5 — Cold start’ı ölç

# Uyuduktan sonraki ilk istek
time curl -s https://<worker>/api/isle > /dev/null
# Hemen ardından ikinci istek
time curl -s https://<worker>/api/isle > /dev/null

İki time çıktısı yan yana — ilk istek 1-3 saniye, ikinci istek milisaniyeler

Demo 2: Egress kilitleme ve container’a sır vermeme

Adım 1 — Container’ı internete kapat

Container içinden curl ile dış siteye erişim denemesi ve engellendiğini gösteren çıktı

Adım 2 — Outbound handler ile tek host’a izin ver

wrangler tail çıktısı — container'dan çıkan isteğin Worker'daki outbound handler'a düştüğü

Container içinden env değişkenlerinin listelenmesi — GITHUB_TOKEN'ın orada olmadığı görünsün

Adım 3 — SSH ile container’a bağlan

npx wrangler containers ssh <INSTANCE_ID>

Terminal — container içindeki kabuk; ls, ps ve df çıktıları (disk boyutunun instance tipiyle uyuştuğu görünsün)

Ölçüm

Fiyatlandırma

Rakamlar 31 Ağustos 2026’da resmî dokümandan doğrulanmıştır.

Resmî ifade: “Containers are billed for every 10ms that they are actively running.”

Egress:

Kritik ayrıntı: bellek ve disk provision edilen kaynağa göre, CPU ise yalnızca aktif kullanıma göre faturalanır. Kasım 2025’te yapılan bir değişiklikle CPU provision değil aktif kullanım üzerinden ücretlendiriliyor.

Limitler

Instance tipleri

dev = lite, standard = standard-1 (geriye dönük uyumluluk için korunuyor).

Özel instance tipi sınırları

1 vCPU’dan az gerektiren işler için önceden tanımlı tipleri (lite, basic) kullan.

Hesap sınırları

Pratik karşılık: eşzamanlı olarak 15.000 lite, 6.000 basic veya 1.500’den fazla standard-1 instance çalıştırabilirsin.

Lisanslama ve hukuki çerçeve

Containers tescilli bir hizmettir; Cloudflare Hizmet Şartları kapsamındadır. Container image’ın ve içindeki kod sana aittir; Cloudflare bunları hizmeti sunmak için işler.

Image’lar Cloudflare’in R2 destekli registry’sinde saklanır. Kendi image’ında bulunan üçüncü taraf yazılımların lisanslarından sen sorumlusun — özellikle ffmpeg gibi patent yükü olabilecek araçlarda buna dikkat et.

Veri konumu: constraints.regions ile bölge, constraints.jurisdiction ile yargı alanı (eu, fedramp) sınırlanabilir. Türkiye için tanımlı bir bölge veya yargı alanı yoktur. Verinin Türkiye’de işlenmesi gerekiyorsa Containers uygun değildir.

Sık yapılan hatalar

new_classes kullanmak. Durable Object new_sqlite_classes ile tanımlanmalı. Resmî ifade: “The Durable Object must use new_sqlite_classes not new_classes.”

Apple Silicon’da arm64 derlemek. Image linux/amd64 olmak zorunda.

Dockerfile’da EXPOSE unutmak. Üretimde gerekmez ama wrangler dev hata verir.

Diske kalıcı veri yazmak. Uyku sonrası her şey sıfırlanır.

İlk deploy’dan hemen sonra test edip “bozuk” demek. Provision birkaç dakika sürer.

export { ContainerProxy } satırını unutmak. Outbound handler sessizce çalışmaz.

SIGTERM’i yakalamamak. Rollout ve host taşımaları aynı kapanma sırasını kullanır; yakalamazsan 15 dakika sonra sert SIGKILL gelir.

Durable Object ile container’ın aynı yerde olduğunu varsaymak. Resmî ifade: “Durable Objects and their associated Container instances are not guaranteed to run in the same location.”

50 GB image deposunu doldurup eski image’ı silmek. Resmî uyarı: “If you delete a container image and then roll back your Worker to a previous version, this version may no longer work.”

wrangler versions upload ile image güncellendiğini sanmak. Yalnızca wrangler deploy image’ı günceller.