Google Cloud'da Cron Job Scheduler ve OIDC Rehberi

Google Cloud Scheduler bir HTTP adresini, Pub/Sub konusunu veya App Engine hedefini belirlediğiniz takvime göre çağırır. Uygulama kodunu Scheduler içinde çalıştırmazsınız; zamanlayıcı isteği gönderir, hedef hizmet işi yürütür. Bu nedenle doğru cron ifadesi kadar hedefin kimlik doğrulaması ve yanıt davranışı da kurulumun parçasıdır.

Bu rehberde mevcut, kimlik doğrulaması isteyen bir Cloud Run servisini İstanbul saatine göre tetikleyeceksiniz. gcloud komutları Google Cloud Shell veya Bash içindir. Servis oluşturmayı tamamladıysanız servis adı, bölge ve proje kimliğiniz yeterlidir. Temel zamanlama kavramları için cron job rehberini, alanların anlamı için crontab sözdizimini kullanabilirsiniz.

HTTP, Pub/Sub ve Cloud Run Job Arasında Seçim

İstek geldiğinde kısa bir işlem tamamlayan servis için HTTP hedefi kullanın. İşin teslimiyle yürütmesini ayırmak ve tüketiciyle ölçeklemek istiyorsanız Pub/Sub uygundur. Uzun süren toplu işlem için Cloud Run job değerlendirin. Bir Cloud Run servisine HTTP isteği göndermek ile Cloud Run job başlatma API'sini çağırmak aynı kurulum değildir.

Cloud Run servisine erişimde genellikle OIDC kimlik belirteci kullanılır. Google API adreslerine yapılan çağrılarda ise OAuth erişim belirteci gerekir. Örneğin run.googleapis.com üzerinden job başlatırken bu farkı dikkate alın. Hedefi herkese açmak yerine çağıran kimliğe yalnız gerekli kaynağın yetkisini verin. Resmi HTTP hedef kimlik doğrulama belgesi iki belirteç türünü ve gerekli rolleri açıklar.

Aynı iş yükünü başka bulutta işletiyorsanız zamanlama ve kimlik modelini doğrudan kopyalamayın. Azure Functions Timer Trigger kurulumu ile AWS EventBridge Scheduler ve Lambda görevleri, Cloud Scheduler'daki OIDC ve beş alanlı ifade kararlarını sağlayıcının kendi yapılandırmasıyla karşılaştırmanıza yardımcı olur.

Adım Adım Proje, Servis Hesabı ve IAM

1. Faturalandırması açık projenizi seçin. Cloud Scheduler API'yi etkinleştirin. Kullanıcınızda API etkinleştirme, Scheduler görevi oluşturma ve hedef IAM politikasını düzenleme izinlerinin bulunmasını sağlayın.
2. Aşağıdaki değişkenlerde proje kimliğini, servis adını ve bölgeyi değiştirin. Örnek, önceden dağıtılmış rapor-api servisini kullanır; boş projede servis oluşturmaz. Servisiniz POST /tasks/report yolunu karşılamalıdır.
3. Yalnız zamanlayıcı için scheduler-invoker servis hesabını oluşturun. Bu hesap işin bulunduğu projeye ait olmalıdır. Cloud Scheduler tarafından yönetilen service agent hesabını işin çağıran hesabı olarak seçmeyin.
4. Cloud Run Invoker rolünü yalnız hedef servis üzerinde verin. Kurulumu yapan kimliğin bu servis hesabında iam.serviceAccounts.actAs yetkisi bulunmalıdır; gerekirse yöneticinizden hesap üzerinde Service Account User rolünü isteyin.
5. Cloud Run servisinin dağıtımının sağlıklı olduğunu ve görev yolunun başarılı yanıt verdiğini uygulama günlüklerinden doğrulayın. Scheduler ayarları bozuk bir uygulama dağıtımını düzeltmez.

# Bash / Google Cloud Shell
PROJECT_ID="projenizin-kimligi"
REGION="europe-west1"
SERVICE="rapor-api"
gcloud config set project "$PROJECT_ID"
gcloud services enable cloudscheduler.googleapis.com run.googleapis.com

gcloud iam service-accounts create scheduler-invoker \
  --display-name="Scheduler HTTP cagirici"

SA="scheduler-invoker@$PROJECT_ID.iam.gserviceaccount.com"
gcloud run services add-iam-policy-binding "$SERVICE" \
  --region="$REGION" \
  --member="serviceAccount:$SA" \
  --role=roles/run.invoker

SERVICE_URL=$(gcloud run services describe "$SERVICE" \
  --region="$REGION" --format='value(status.url)')
echo "$SERVICE_URL"

URL değerinin dolu olduğunu kontrol edin. Kimlik doğrulaması isteyen servisin izinlerini bu aşamada değiştirmeyin. Cloud Run uygulamasının kendi kaynak erişiminde kullandığı yürütme hesabıyla Scheduler çağıran hesabını ayrı tutun. Çağırıcıya veritabanı veya depolama yetkisi vermek, yalnız HTTP isteği göndermek için gerekli değildir.

OIDC ile HTTP Görevi Oluşturma ve Test

Aşağıdaki komut, her gün İstanbul saatiyle 03:00'te POST isteği gönderir. OIDC audience, belirtecin hangi hizmet için düzenlendiğini belirtir; Cloud Run için temel servis URL'sini kullanın. İstek yolunu URI içinde bırakırken audience değerine görev yolu veya sorgu parametresi eklemeyin. Örnekteki JSON gövdesini uygulamanızın beklediği alanlarla değiştirin.

gcloud scheduler jobs create http gunluk-rapor \
  --location="$REGION" \
  --schedule="0 3 * * *" \
  --time-zone="Europe/Istanbul" \
  --uri="$SERVICE_URL/tasks/report" \
  --http-method=POST \
  --headers="Content-Type=application/json" \
  --message-body='{"job":"gunluk-rapor"}' \
  --oidc-service-account-email="$SA" \
  --oidc-token-audience="$SERVICE_URL" \
  --attempt-deadline=180s \
  --max-retry-attempts=3 \
  --min-backoff=10s \
  --max-backoff=60s

gcloud scheduler jobs run gunluk-rapor --location="$REGION"
gcloud scheduler jobs describe gunluk-rapor --location="$REGION"

Manuel çalıştırma komutunun dönmesi işin bittiğini göstermez. Scheduler yürütme kaydında hedef yanıtını, Cloud Run günlüğünde uygulama sonucunu kontrol edin. Test raporunun gerçekten oluştuğunu veya beklenen kaydın güncellendiğini doğrulayın. Console ile çalışıyorsanız Create job ekranında aynı sıralamayla bölge, Frequency, Timezone, HTTP URL, POST, OIDC hesabı ve audience girin.

Bir görevi güncellemeden önce mevcut yapılandırmasını kaydedin. İşlem artık gerekmiyorsa jobs pause ile duraklatın; yeniden açmak için jobs resume kullanın. Bölgeyi komutlarda açık yazmak yanlış konumdaki görevi arama sorununu önler. Bayrakların açıklamaları gcloud HTTP görev başvurusunda bulunur.

Beş Alanlı Cron ve Saat Dilimi Tuzakları

Cloud Scheduler sırasıyla dakika, saat, ayın günü, ay ve haftanın günü alanlarını kullanır. AWS'deki yıl alanını veya Azure örneklerindeki saniyeyi eklemeyin. Haftanın gününde SUN–SAT adları okunaklıdır. Cron ifade oluşturucu ile temel ifadeyi hazırlayıp seçtiğiniz saat dilimiyle birlikte kontrol edebilirsiniz.

Ayın günü ile haftanın gününü birlikte kısıtlarsanız alanlar VEYA mantığıyla değerlendirilir. Örneğin 0 9 1 * MON yalnız ayın ilk pazartesisi değildir; ayın birinde ve her pazartesi çalışır. Böyle özel takvim kurallarını uygulamada kontrol edin. Yaz saati geçişlerinin olduğu bölgelerde yerel saat tekrarlanabilir veya atlanabilir; sabit ritim için UTC düşünün. Cron biçimi ve saat dilimi belgesi bu ayrıntıları açıklar.

Yeniden Deneme ve Tekrar İşlemeyi Önleme

Cloud Scheduler en az bir kez teslim yaklaşımıyla çalışır; nadiren aynı planlanan iş birden fazla kez gelebilir. HTTP hedefiniz aynı dönem için ikinci kez rapor veya ödeme üretmemelidir. İş adı ile planlanan zamandan bir işlem anahtarı çıkarın, bu anahtarı veritabanında benzersiz saklayın. Cloud Scheduler genel bakışı teslim modelini açıklar.

Yeniden denemelerin varsayılan olarak açık olduğunu varsaymayın; örnekte üç deneme isteği açıkça ayarlanmıştır. HTTP hedefinde başarılı kabul için 2xx yanıt kullanın. Yanıt süresi dolduğunda hedefteki işlem devam ediyor olabilir; timeout sonrası yeniden gelen istek bu yüzden de çoğalabilir. İş uzun sürüyorsa kalıcı kuyruğa yazdıktan sonra 202 dönün, kuyruktaki gerçek tamamlanmayı ayrıca izleyin. Bellekte arka plan işi başlatıp hemen başarı dönmek güvenilir bir teslim kaydı değildir.

İki Uygulanabilir Senaryo

Her Gece Stok Mutabakatı

Günlük 03:00 göreviyle mağaza ve depo kayıtlarını karşılaştırın. Önce fark raporu üretin; otomatik düzeltmeyi ayrı bir yetki ve işlem olarak ele alın. Eksik sayfa veya dış API hatasında kısmi sonucu tamamlandı olarak işaretlemeyin. Son başarılı çalışma dönemini kaydederek ertesi gün hangi dönemin eksik olduğunu bulun.

Pub/Sub ile Saatlik Rapor Talebi

Saat başı bir mesaj yayınlayıp rapor tüketicisini bağımsız çalıştırabilirsiniz. Önce konu oluşturun, tüketici aboneliğini bağlayın, sonra zamanlamayı açın. Mesajın yayınlanması raporun tamamlandığı anlamına gelmez. Tüketici hata kayıtlarını ve bekleyen mesajları ayrıca izleyin; aşağıdaki komutlar yalnız konu ve zamanlamayı oluşturur.

gcloud pubsub topics create rapor-talepleri
gcloud scheduler jobs create pubsub saatlik-rapor \
  --location="$REGION" \
  --schedule="0 * * * *" \
  --time-zone="Europe/Istanbul" \
  --topic=rapor-talepleri \
  --message-body='{"job":"saatlik-rapor"}'

Sık Hatalar ve Çözümleri

401 ve URL_ERROR-ERROR_AUTHENTICATION

Belirteç eksik veya geçersiz olabilir. OIDC hesabını, audience değerini ve hedefin beklediği kimlik doğrulama türünü kontrol edin. Cloud Run'da temel servis URL'sini audience olarak kullanın. Google API çağrısına OIDC gönderiyorsanız OAuth gereksinimini değerlendirin.

403 ve URL_ERROR-ERROR_OTHER

Hedefte çağırıcı hesabın Invoker rolünü inceleyin. Cloud Scheduler service agent üzerindeki roles/cloudscheduler.serviceAgent rolünün kaldırılmadığını da doğrulayın. Ayrıca ingress ve kuruluş ağ politikalarını kontrol edin; yalnız IAM rolü eklemek bütün erişim engellerini çözmez.

URL_ERROR-ERROR_NOT_FOUND

404 yanıtında servis URL'sini ve /tasks/report yolunu uygulama yönlendirmeleriyle karşılaştırın. Cloud Run servisinin adresiyle eski Cloud Functions adresini karıştırmayın. Scheduler bölgesiyle hedef adresindeki bilgileri birbirinden bağımsız doğrulayın.

URL_ERROR-ERROR_DNS

Alan adı çözülemiyor olabilir. Yazım hatasını, DNS kaydını ve özel hedef erişim koşullarını inceleyin. Yerel ağdaki herhangi bir sunucunun Cloud Scheduler tarafından doğrudan erişilebilir olduğunu varsaymayın.

504 veya Yeni Çalışmanın Başlamaması

Önceki istek hâlâ sürüyor veya yanıt bekleniyor olabilir. Hedef günlüğünde bitiş zamanını bulun, görev deadline değerini işlem süresiyle karşılaştırın. Uzun işi kuyruğa ayırın. Hata kodlarının ayrıntıları resmi sorun giderme belgesindedir.

cronjob.com.tr ile HTTP Tabanlı Alternatif

IAM ile korunan Cloud Run adresini yalnız bir özel header ekleyerek çağırmanız yeterli olmaz. Harici zamanlayıcı kullanacaksanız herkese ağ erişimi açık, uygulama seviyesinde gizli token doğrulayan ayrı bir HTTPS uç noktası hazırlayın. Bu tercih uygun değilse OIDC kullanan Cloud Scheduler düzenini koruyun.

Örnekte Flask uygulamanıza ayrı bir yol eklenir; CRON_HTTP_TOKEN ortamda tutulur. Panelde URL olarak https://ornek.com/tasks/cron-http, metot olarak POST, header olarak X-Cron-Token ve aynı gizli değeri girin. Zamanlamayı 0 3 * * * ve saat dilimini Europe/Istanbul seçin. Tokenı URL'ye veya yanıta yazmayın.

# Mevcut Flask uygulamasına ekleyin.
import hmac
import os
from flask import request

@app.post("/tasks/cron-http")
def cron_http():
    expected = os.environ["CRON_HTTP_TOKEN"]
    supplied = request.headers.get("X-Cron-Token", "")
    if not expected or not hmac.compare_digest(expected, supplied):
        return "Unauthorized", 401
    # İşinizi çalıştırın veya kalıcı kuyruğa yazın.
    return "Erisim dogrulandi", 200

Cron ifadeli işlerde yanıt bekleme sınırı 290 saniyedir; hazır bir dakikalık aralıkta 55, iki dakikada 115 saniyedir. Bağlantı hatası olmadan HTTP 200–399 başarı sayılır. Ardışık hata eşiği varsayılan üçtür; erişim sorunu ve düzelme e-postaları gönderilir, aynı işte bildirimler arasında en az 60 dakika bulunur. Kayıtlar yedi gün saklanır. Uygulamanız 202 döndürüyorsa kabul edilen işin son sonucunu kendi kayıtlarınızdan takip edin.

Sıkça Sorulan Sorular (SSS)

Cloud Scheduler saniyelik cron destekler mi?

Unix-cron zamanlaması beş alanlıdır ve dakika alanıyla başlar. Saniye alanı eklemeyin; daha sık işleme ihtiyacını uygulama veya kuyruk mimarisinde değerlendirin.

Cloud Run için hangi çağırma rolü gerekir?

Scheduler çağıran servis hesabına hedef servis üzerinde roles/run.invoker verin. Bu hesap ile Cloud Scheduler tarafından yönetilen service agent farklı kimliklerdir.

Cloud Scheduler API kapatılırsa kaçırılan işler ne olur?

Resmi belgeye göre API yeniden etkinleştirildiğinde arada çalışamayan görevler sonraki takvim saatini beklemeden çalışır. Her geçmiş dönemin uygulamada eksiksiz işlendiğini ayrıca kontrol edin.

Başarılı HTTP yanıtı bütün işin bittiğini gösterir mi?

Yalnız hedefiniz yanıtı iş tamamlandıktan sonra veriyorsa bunu gösterebilir. Kuyruğa kabul için 202 dönüyorsanız tüketicinin tamamlanma kaydını ayrıca izlemelisiniz.

Cloud Scheduler kullanmak tamamen ücretsiz midir?

Scheduler görevleriyle birlikte hedef hizmet, günlük ve mesajlaşma maliyetlerini değerlendirin. Güncel ücretsiz kullanım koşullarını proje ve hesap bazında resmi fiyatlandırmadan kontrol edin.

İlgili Rehberler