GCP Cloud CLI (gcloud) Kurulum ve Yapılandırma Rehberi

Google Cloud ile ciddi işler yapmak istiyorsanız, web konsolunda tıklamak yerine komut satırından yönetim yapabilmek hem hız hem de tekrarlanabilirlik açısından size çok büyük avantaj sağlar. gcloud CLI, GCP ekosisteminin tam merkezinde duran araç ve bir kez kurulum ile yapılandırmayı doğru yaparsanız, günlük operasyonlarınız inanılmaz derecede kolaylaşıyor. Bu yazıda sıfırdan kurulumdan başlayıp, çoklu proje yönetimine, servis hesabı kimlik doğrulamasına kadar gerçek dünyada kullanacağınız her şeyi ele alacağız.

gcloud CLI Nedir ve Neden Kullanmalısınız?

gcloud, Google Cloud SDK’nın bir parçası olarak gelen komut satırı aracıdır. Compute Engine, GKE, Cloud Storage, IAM, Cloud SQL ve daha onlarca GCP servisini bu tek araçla yönetebilirsiniz. Web konsoluna kıyasla birkaç kritik avantajı var:

• Otomasyon: Bash script’leri içine gömebilir, CI/CD pipeline’larında kullanabilirsiniz
• Tekrarlanabilirlik: Aynı komutu farklı ortamlarda çalıştırarak tutarlı sonuçlar alırsınız
• Hız: 10 VM’yi tek komutla başlatabilirsiniz, web konsolunda teker teker tıklamak zorunda kalmazsınız
• Audit: Komut geçmişiniz var, ne yaptığınızı takip edebilirsiniz

Kurulum

Linux’ta Kurulum

Linux’ta iki farklı yöntem var. Ben production ortamlarında paket yöneticisi yöntemini tercih ediyorum çünkü güncellemeler otomatik geliyor.

Debian/Ubuntu için:

# Google Cloud SDK repo'sunu ekle
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | 
  sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# GPG anahtarını indir
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | 
  sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# Paket listesini güncelle ve kur
sudo apt-get update && sudo apt-get install google-cloud-cli

RHEL/CentOS için:

# Repo dosyasını oluştur
sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el8-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

# Kur
sudo dnf install google-cloud-cli

macOS’ta Kurulum

macOS kullanıcıları için Homebrew en temiz yol:

brew install --cask google-cloud-sdk

# Shell'inize source ekleyin (.zshrc veya .bash_profile)
source "$(brew --prefix)/share/google-cloud-sdk/path.zsh.inc"
source "$(brew --prefix)/share/google-cloud-sdk/completion.zsh.inc"

Windows’ta Kurulum

Windows’ta resmi installer’ı indirip çalıştırabilirsiniz ya da PowerShell üzerinden kurabilirsiniz. Ama dürüst olmak gerekirse, Windows’ta GCP işi yapıyorsanız WSL2 + Ubuntu kurulumu çok daha sağlıklı bir deneyim sunuyor. Production script’leriniz Linux ortamında çalışacaksa, geliştirme ortamınızın da Linux olması mantıklı.

Kurulum Doğrulama

# Versiyon kontrolü
gcloud version

# Bileşen listesi
gcloud components list

Kurulum başarılıysa gcloud version size SDK versiyonunu ve Python versiyonunu gösterir. Eğer command not found hatası alırsanız, PATH ayarlarınıza ~/google-cloud-sdk/bin eklemeniz gerekiyor.

İlk Kimlik Doğrulama ve Yapılandırma

Kullanıcı Hesabıyla Giriş

# Tarayıcı üzerinden OAuth2 akışı başlatır
gcloud auth login

# Headless ortamlarda (sunucu, CI/CD) bu parametreyi kullanın
gcloud auth login --no-launch-browser

Bu komut size bir URL verir. Tarayıcınızda bu URL’e gidin, Google hesabınızla giriş yapın ve gelen kodu terminale yapıştırın. Lokal makinenizde geliştirme yapıyorsanız --no-launch-browser olmadan da çalışır, tarayıcı otomatik açılır.

İlk init Yapılandırması

Yeni bir kurulumda gcloud init komutunu çalıştırmanızı öneririm. Bu interaktif sihirbaz sizi temel yapılandırmadan geçirir:

gcloud init

Sihirbaz şunları sorar:

• Hangi Google hesabını kullanmak istiyorsunuz?
• Hangi projeyi varsayılan proje olarak ayarlamak istiyorsunuz?
• Varsayılan compute bölgesi ve zone’u ne olsun?

Bu ayarları sonradan da değiştirebilirsiniz ama baştan doğru yapmak her komutta --project ve --region parametresi yazmaktan kurtarır.

Yapılandırma Profilleri (Configurations)

Bu kısım çoğu kişinin atladığı ama gerçek dünyada hayat kurtaran bir özellik. Farklı GCP projeleri, farklı hesaplar veya farklı ortamlar (dev, staging, prod) için ayrı yapılandırma profilleri oluşturabilirsiniz.

Yeni Profil Oluşturma

# Production profili oluştur
gcloud config configurations create production

# Development profili oluştur
gcloud config configurations create development

# Mevcut profilleri listele
gcloud config configurations list

Profil Ayarlarını Yapma

# Production profilini aktif et
gcloud config configurations activate production

# Bu profile ait ayarları yap
gcloud config set account [email protected]
gcloud config set project my-production-project
gcloud config set compute/region europe-west1
gcloud config set compute/zone europe-west1-b

# Development profiline geç
gcloud config configurations activate development
gcloud config set account [email protected]
gcloud config set project my-dev-project
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

Profil Doğrulama

# Aktif yapılandırmayı göster
gcloud config list

# Tüm profillerin detaylarını gör
gcloud config configurations describe production

Gerçek dünya senaryosu olarak düşünün: Sabah prod ortamında bir incident inceliyorsunuz, öğleden sonra dev ortamında yeni bir özellik test ediyorsunuz. Sadece gcloud config configurations activate production veya gcloud config configurations activate development diyerek context switch yapıyorsunuz. Yanlış projeye komut gönderme riskini minimize ediyorsunuz.

Servis Hesabı Kimlik Doğrulama

CI/CD pipeline’larında, cronjob’larda veya uygulama sunucularında kişisel Google hesabınızı kullanmak yerine servis hesabı kullanmalısınız. Bu hem güvenlik hem de best practice açısından doğru yaklaşım.

Servis Hesabı Key Dosyasıyla Authentication

# Servis hesabı key dosyasını kullanarak giriş yap
gcloud auth activate-service-account 
  --key-file=/path/to/service-account-key.json

# Hangi hesabın aktif olduğunu kontrol et
gcloud auth list

Application Default Credentials (ADC)

Eğer GCP üzerinde çalışan uygulamalar geliştiriyorsanız veya Terraform, Pulumi gibi araçlar kullanıyorsanız, ADC yapılandırması gerekiyor:

# Kullanıcı hesabıyla ADC ayarla (geliştirme ortamı için)
gcloud auth application-default login

# Servis hesabıyla ADC ayarla (production için)
gcloud auth application-default login 
  [email protected]

ADC, SDK’nın kimlik bilgilerini otomatik bulmasını sağlar. Kodunuzda explicit olarak credential dosyası belirtmeniz gerekmez, bu da taşınabilirlik açısından büyük avantaj.

Temel Komutlar ve Yapı

gcloud komutları şu yapıyı takip eder: gcloud [GROUP] [SUBGROUP] [COMMAND] [FLAGS] [POSITIONAL ARGS]

Örneğin gcloud compute instances list komutunda:

• compute: Servis grubu
• instances: Alt grup
• list: Komut

Sık Kullanılan Grup ve Komutlar

# Proje listesi
gcloud projects list

# Aktif projeyi değiştir
gcloud config set project PROJECT_ID

# Compute Engine VM'lerini listele
gcloud compute instances list

# Tüm bölgelerdeki VM'leri göster
gcloud compute instances list --filter="status=RUNNING"

# GKE cluster listesi
gcloud container clusters list

# Cloud Storage bucket'larını listele
gcloud storage buckets list

Yardım Sistemi

gcloud‘un yardım sistemi oldukça güçlü. Herhangi bir komut için detaylı yardım alabilirsiniz:

# Genel yardım
gcloud help

# Belirli bir komut için yardım
gcloud compute instances create --help

# Interaktif yardım (daha okunaklı)
gcloud help compute instances create

Bileşen Yönetimi

gcloud temel kurulumla gelir ama bazı ek bileşenleri sonradan kurmanız gerekebilir.

# Tüm bileşenleri listele
gcloud components list

# Yeni bileşen kur (kubectl örneği)
gcloud components install kubectl

# gke-gcloud-auth-plugin kur (GKE için gerekli)
gcloud components install gke-gcloud-auth-plugin

# Tüm bileşenleri güncelle
gcloud components update

# Belirli bir bileşeni kaldır
gcloud components remove COMPONENT_ID

Önemli not: Paket yöneticisi ile kurduysanız (apt, yum), gcloud components update yerine sudo apt-get upgrade google-cloud-cli kullanın. İki yöntemi karıştırmak bazen sorunlara yol açıyor.

Gerçek Dünya Senaryosu: Ortam Kurulum Script’i

Yeni bir takım üyesi katıldığında veya yeni bir geliştirici makinesini hazırlarken kullandığım script’in basitleştirilmiş versiyonu:

#!/bin/bash
# gcp-setup.sh - GCP ortam kurulum scripti

set -euo pipefail

PROJECT_DEV="sirket-dev-123456"
PROJECT_PROD="sirket-prod-654321"
REGION_EU="europe-west1"
REGION_US="us-central1"
SA_KEY_PATH="$HOME/.config/gcloud/service-accounts"

echo "=== GCP CLI Ortam Kurulumu ==="

# Klasörü oluştur
mkdir -p "$SA_KEY_PATH"

# Development profili oluştur
echo "Development profili kuruluyor..."
gcloud config configurations create dev 2>/dev/null || 
  gcloud config configurations activate dev

gcloud config set project "$PROJECT_DEV"
gcloud config set compute/region "$REGION_US"
gcloud config set compute/zone "${REGION_US}-a"

# Production profili oluştur
echo "Production profili kuruluyor..."
gcloud config configurations create prod 2>/dev/null || 
  gcloud config configurations activate prod

gcloud config set project "$PROJECT_PROD"
gcloud config set compute/region "$REGION_EU"
gcloud config set compute/zone "${REGION_EU}-b"

# Development profilini aktif et (güvenli başlangıç noktası)
gcloud config configurations activate dev

echo "=== Kurulum tamamlandi ==="
echo "Aktif profil: $(gcloud config configurations list --filter='is_active=true' --format='value(name)')"
echo "Aktif proje: $(gcloud config get-value project)"

Çıktı Formatlama ve Filtreleme

gcloud komutlarının çıktısını farklı formatlarda alabilirsiniz. Bu özellikle script yazarken veya başka araçlarla entegrasyon yaparken kritik önem taşıyor.

# JSON formatında çıktı al
gcloud compute instances list --format=json

# YAML formatında çıktı al
gcloud compute instances list --format=yaml

# Sadece belirli alanları al
gcloud compute instances list 
  --format="table(name, zone, status, networkInterfaces[0].accessConfigs[0].natIP)"

# Çıktıyı filtrele - sadece RUNNING instance'lar
gcloud compute instances list --filter="status=RUNNING"

# Belirli bir zone'daki instance'lar
gcloud compute instances list 
  --filter="zone:(europe-west1-b)" 
  --format="value(name)"

# Birden fazla filtre birleştirme
gcloud compute instances list 
  --filter="status=RUNNING AND zone:(europe-west1-b)" 
  --format="value(name,networkInterfaces[0].accessConfigs[0].natIP)"

Bu filtreleme özellikleri script’lerde çok işe yarıyor. Örneğin tüm RUNNING instance’ların IP adreslerini toplayıp bir Ansible inventory oluşturmak istiyorsanız, --format="value()" ile düz liste çıktısı alıp doğrudan kullanabilirsiniz.

Impersonation ve Yetki Yönetimi

Özellikle production ortamlarında direkt servis hesabına anahtar vermek yerine impersonation kullanmak daha güvenli:

# Servis hesabını taklit ederek komut çalıştır
gcloud compute instances list 
  --impersonate-service-account=deploy-sa@proje.iam.gserviceaccount.com

# Aktif hesabın rollerini kontrol et
gcloud projects get-iam-policy PROJECT_ID 
  --format="table(bindings.role, bindings.members)"

# Belirli bir hesaba rol ata
gcloud projects add-iam-policy-binding PROJECT_ID 
  --member="serviceAccount:[email protected]" 
  --role="roles/compute.viewer"

Proxy ve Ağ Yapılandırması

Kurumsal ortamlarda proxy arkasından çalışıyorsanız:

# HTTP proxy ayarla
gcloud config set proxy/address 10.0.0.1
gcloud config set proxy/port 8080
gcloud config set proxy/type http

# Kimlik doğrulama gerektiren proxy
gcloud config set proxy/username proxyuser
gcloud config set proxy/password proxypass

# Proxy ayarlarını kaldır
gcloud config unset proxy/address
gcloud config unset proxy/port
gcloud config unset proxy/type

Alternatif olarak standart environment variable’ları da destekleniyor:

export HTTPS_PROXY=http://10.0.0.1:8080
export HTTP_PROXY=http://10.0.0.1:8080

Logging ve Debug

Bir şeyler yanlış gittiğinde ne yapacaksınız?

# Verbose mod - ne olduğunu görmek için
gcloud compute instances list --verbosity=debug

# Sadece uyarıları göster
gcloud compute instances list --verbosity=warning

# Log dosyası konumu
# Linux/macOS: ~/.config/gcloud/logs/
# Windows: %APPDATA%gcloudlogs

# Son log dosyasını bul
ls -lt ~/.config/gcloud/logs/ | head -5

Debug modu özellikle API çağrısının tam olarak ne gönderip ne aldığını görmek istediğinizde değerli. Bir servis account’ının yeterli yetkisi var mı, API isteği doğru mu formatlanmış gibi soruları çözmek için --verbosity=debug çıktısı altın değerinde.

Shell Tamamlama (Tab Completion) Kurulumu

Bu küçük ama verimliliğinizi ciddi artıran bir özellik:

# Bash için
gcloud completion bash > /etc/bash_completion.d/gcloud
# veya .bashrc'ye ekle
source "$(gcloud info --format='value(installation.sdk_root)')/completion.bash.inc"

# Zsh için .zshrc'ye ekle
source "$(gcloud info --format='value(installation.sdk_root)')/completion.zsh.inc"

Tamamlamayı aktif ettikten sonra gcloud compute yazıp Tab’a bastığınızda mevcut alt komutları göreceksiniz. gcloud compute instances yazıp Tab’a bastığınızda list, create, delete, start, stop gibi seçenekler gelecek.

Yapılandırma Yedekleme ve Taşıma

Yapılandırmanızı başka bir makineye taşımak veya yedeklemek istiyorsanız:

# Yapılandırma dosyalarının konumu
ls ~/.config/gcloud/configurations/

# Tüm yapılandırmaları yedekle
tar -czf gcloud-config-backup.tar.gz ~/.config/gcloud/configurations/

# Başka bir makineye taşı
scp gcloud-config-backup.tar.gz user@newmachine:~/
ssh user@newmachine "mkdir -p ~/.config/gcloud/configurations && 
  tar -xzf gcloud-config-backup.tar.gz -C /"

Dikkat: ~/.config/gcloud/ dizininde kimlik bilgileri de var. Bu dizini git’e commit etmeyin, paylaşmayın. Backup yaparken şifreli tutun.

Sık Karşılaşılan Sorunlar ve Çözümleri

“quota exceeded” hatası: Genellikle API’ye çok fazla istek atıyorsunuzdur. Script’lerinizde döngü varsa biraz uyku ekleyin: sleep 1

“permission denied” hatası: Aktif hesabın gerekli IAM rolüne sahip olup olmadığını kontrol edin. gcloud auth list ile hangi hesabın aktif olduğunu doğrulayın.

Token süresi dolmuş: gcloud auth login ile yeniden giriş yapın ya da servis hesabı kullanıyorsanız gcloud auth activate-service-account çalıştırın.

“project not found”: Proje ID’sini doğrulayın, proje adıyla proje ID’sini karıştırmak yaygın bir hata. gcloud projects list ile doğru ID’yi alın.

# Token durumunu kontrol et
gcloud auth print-access-token

# Tüm aktif kimlik bilgilerini listele
gcloud auth list

# Belirli bir hesabı revoke et
gcloud auth revoke ACCOUNT_EMAIL

# Tüm credential'ları temizle
gcloud auth revoke --all

Sonuç

gcloud CLI’yı doğru kurup yapılandırmak, GCP ile verimli çalışmanın temel taşı. Özellikle birden fazla proje veya ortamla çalışıyorsanız, yapılandırma profillerini kullanmak hem hız kazandırıyor hem de insan hatası riskini azaltıyor. Servis hesabı authentication ve ADC konusunu iyi anlamak ise uygulama geliştirme ve CI/CD pipeline kurulumunda mutlaka işinize yarayacak.

Buradan sonra gcloud compute, gcloud container, gcloud storage gibi spesifik servis gruplarını keşfetmek mantıklı bir adım. Her servis kendi komut yapısını taşıyor ama temel desen hep aynı. Bir kez alışkanlık edindikten sonra web konsolu sadece görsel doğrulama için kullandığınız bir araç haline geliyor.

Son olarak bir güvenlik hatırlatması: --verbosity=debug çıktılarını, log dosyalarını ve özellikle servis hesabı JSON key’lerini dikkatli yönetin. Bu dosyaların git’e gitmesini engellemek için .gitignore‘unuzu güncel tutun ve mümkün olduğunca Workload Identity Federation veya impersonation gibi keyless authentication yöntemlerini tercih edin.