Uygulama Barındırma arka uçlarını yapılandırma ve yönetme

App Hosting, kullanım kolaylığı ve düşük bakım maliyeti için tasarlanmıştır. Varsayılan ayarlar, çoğu kullanım alanı için optimize edilmiştir. Aynı zamanda, App Hosting, belirli ihtiyaçlarınız için arka uçları yönetip yapılandırmanıza yönelik araçlar sunar. Bu kılavuzda söz konusu araçlar ve süreçler açıklanmaktadır.

Ortam değişkenlerini ayarlama ve güncelleme

Bazen derleme işlemi için ek yapılandırma gerekebilir. App Hosting, Firebase konsolu ve alternatif olarak apphosting.yaml üzerinden projeniz için bu tür verileri depolamak ve almak üzere ortam yapılandırması sunar.

Başlamanın en hızlı yolu, Firebase konsolunda ortam değişkenlerini ayarlamaktır. Gizli parametreleri depolamanız ve bunlara erişmeniz, yalnızca derleme veya çalışma zamanında kullanılabilen değişkenler ayarlamanız ya da ortam değişkenlerini birden fazla ortamda paylaşmanız gerekiyorsa apphosting.yaml simgesini kullanın. Hem konsol hem de apphosting.<env>.yaml ile farklı ortamlar için farklı değerler ayarlayabilirsiniz.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Değişkenleri güncelleme

Firebase konsolunda veya apphosting.yaml kullanarak ortam değişkenleri ekleyebilir, düzenleyebilir ya da silebilirsiniz:

• Firebase konsolu:

  1. Firebase konsolunda Hosting ve sunucusuz > App Hosting'ya gidin.

  2. View Backend > Settings > Environment'a (Arka Uç Görüntüsü > Ayarlar > Ortam) gidin.

  3. Ortam değişkenleri ekleme, düzenleme veya silme

• apphosting.yaml:

  Dosyayı manuel olarak oluşturma ve düzenleme hakkında bilgi edinin.

Değişiklikleriniz yalnızca bir sonraki dağıtımınızda geçerli olur ve mevcut dağıtımı etkilemez. Değişkenlerinizi kaydedip daha sonra dağıtın veya kaydedip yeni bir dağıtım oluşturun.

Değişken kullanılabilirliğini ayarlama

Firebase konsolunda oluşturulan ortam değişkenleri hem derleme süresi hem de çalışma zamanında kullanılabilir. Bu, availability özelliğiyle kapsamı daraltmadığınız sürece apphosting.yaml içinde tanımlanan değişkenler için de varsayılan koşuldur. apphosting.yaml'da (ancak konsolda değil) bir ortam değişkeninin yalnızca derleme ortamında veya yalnızca çalışma zamanı ortamında kullanılabilir olmasını kısıtlayabilirsiniz.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Next.js uygulamalarında, tarayıcıda bir değişkene erişmek için NEXT_PUBLIC_ önekini dotenv dosyanızda kullandığınız şekilde kullanabilirsiniz.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Next.js için dotenv dosyaları

Next.js uygulamalarında, dotenv dosyaları App Hosting ile çalışır.

Bir arka uç oluştururken veya güncellerken dotenv dosyanızdaki ortam değişkenlerini Firebase konsoluna aktarabilirsiniz. Bunun için dotenv dosyasının tüm içeriğini kopyalayıp Ortam Değişkenleri Ayarları'ndaki "Yeni ekle" formunun ilk "Anahtar" alanına yapıştırın.

Bu şekilde kopyalanan tüm ortam değişkenleri, giriş aşağıdaki gibi bir biçime sahip olduğu sürece her birinin ayrı ayrı girilmesine gerek kalmadan forma düzgün bir şekilde biçimlendirilmelidir:

KEY1=value1
KEY2=value2
KEY3=value3

Herhangi bir çerçeveyle karmaşık veya ayrıntılı ortam değişkeni kontrolü için apphosting.yaml kullanmanızı öneririz.

Otomatik olarak doldurulan ortam değişkenleri

App Hosting tarafından otomatik olarak doldurulan ortam değişkenleri vardır. Bunlar arasında Google Cloud tarafından doldurulanlar ve kurulum sırasında arka uçta appId ayarlandığında Firebase'e özgü ortam değişkenleri yer alır:

• FIREBASE_CONFIG: (derleme ve çalışma zamanı ortamlarında kullanılabilir) Aşağıdaki Firebase proje yapılandırma bilgilerini sağlar:

  {
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
    "projectId": 'PROJECT_ID'
  }
  

  Bu yapılandırma, Firebase Admin SDK'sını herhangi bir bağımsız değişken olmadan başlattığınızda otomatik olarak uygulanır.

• FIREBASE_WEBAPP_CONFIG: (yalnızca derleme ortamında kullanılabilir) Aşağıdaki Firebase proje yapılandırma bilgilerini sağlar:

  {
    "apiKey": 'API_KEY',
    "appId": 'APP_ID',
    "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
    "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
    "messagingSenderId": 'PROJECT_NUMBER',
    "projectId": 'PROJECT_ID',
    "storageBucket": 'PROJECT_ID.firebasestorage.app',
  }
  

  Firebase JS SDK'sı, derleme sırasında bu FIREBASE_WEBAPP_CONFIG ortam değişkenini postinstall komut dosyasında otomatik olarak kontrol eder. Böylece, istemci SDK'sını herhangi bir bağımsız değişken olmadan da başlatabilirsiniz.

SDK'ları başlatmak için bu ortam değişkenlerini kullanma hakkında daha fazla bilgi edinmek için Firebase Admin SDK'sını ve web SDK'larını otomatik olarak başlatma başlıklı makaleyi inceleyin.

Gerçek Firebase yapılandırmanızdaki değerlerin, projenizde sağladığınız belirli kaynaklara karşılık geleceğini unutmayın.

Değişken hiyerarşisi

Firebase App Hosting, değişkenlerinizi kaynağına göre öncelik sırasına göre uygular. Örneğin, Firebase konsolunda ayarlanan değerler her zaman apphosting.yaml ve dotenv dosyalarında ayarlanan değerleri geçersiz kılar veya bu değerlere göre öncelikli olur.

Öncelik sırasının tamamı şu şekildedir:

1. Firebase konsolu → konsolda ayarlanan değişkenler
2. apphosting.<env>.yaml → apphosting.staging.yaml gibi ortama özel bir YAML dosyasında belirtilen değişkenler (bkz. Birden fazla ortam dağıtma)
3. apphosting.yaml → apphosting.yaml dosyasında belirtilen değişkenler
4. Firebase sistemi → firebase_config json veya firebase_webapp_config için değerler içeren Firebase tarafından ayarlanan değişkenlerin yanı sıra SSR uygulamaları için ana makine adlarını ve bağlantı noktalarını ayarlayan ortam değişkenleri (bundle.yaml içinde App Hosting bağdaştırıcıları tarafından ayarlanır)

Ayrılmış adlar ve sınırlamalar

Cloud Run kapsayıcı çalışma zamanı sözleşmesinde tanımlanan ortam değişkenleri ayrılmıştır ve ayarlanamaz.

Ortam tarafından sağlanan ve otomatik olarak ayarlananlar dışındaki ortam değişkenleri, gelecekteki çalışma zamanı sürümlerinde değişebilir. En iyi uygulama olarak, açıkça ayarlamadığınız ortam değişkenlerine güvenmemenizi veya bunları değiştirmemenizi ve çakışmaları önlemek için ortam değişkenlerine benzersiz bir anahtarla önek eklemenizi öneririz.

Bazı ortam değişkeni anahtarları dahili kullanım için ayrılmıştır. Yapılandırma dosyalarınızda aşağıdaki anahtarlardan hiçbirini kullanmayın:

• Boş dizeler ("")
• "=" içeren anahtarlar
• X_FIREBASE_, X_GOOGLE_ veya CLOUD_RUN_ ile başlayan anahtarlar
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• Yinelenen Anahtarlar

Oluşturma ve düzenleme apphosting.yaml

Gizli diziler veya eşzamanlılık, CPU ve bellek sınırları gibi çalışma zamanı ayarları gibi gelişmiş yapılandırma için uygulamanızın kök dizininde apphosting.yaml dosyasını oluşturup düzenlemeniz gerekir. Bu dosya, Cloud Secret Manager ile yönetilen gizli anahtarlara yapılan referansları destekler. Bu nedenle, kaynak kontrolüne güvenle eklenebilir.

apphosting.yaml oluşturmak için aşağıdaki komutu çalıştırın:

firebase init apphosting

Bu işlem, örnek (yorumlanmış) yapılandırmayla temel bir başlangıç apphosting.yaml dosyası oluşturur. Düzenlemeden sonra, arka uçtaki Cloud Run hizmetinin ayarlarını, bazı ortam değişkenlerini ve Cloud Secret Manager tarafından yönetilen sırlarla ilgili bazı referansları içeren tipik bir apphosting.yaml dosyası aşağıdaki gibi görünebilir:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

Bu kılavuzun geri kalanında, bu örnek ayarlar hakkında daha fazla bilgi ve bağlam sağlanmaktadır.

Cloud Run hizmet ayarlarını yapılandırma

apphosting.yaml ayarlarıyla Cloud Run hizmetinizin nasıl sağlanacağını yapılandırabilirsiniz. Cloud Run hizmeti için kullanılabilen ayarlar runConfig nesnesinde sağlanır:

• cpu: Her yayın örneği için kullanılan CPU sayısı (varsayılan 0).
• memoryMiB: Her sunum örneği için ayrılan bellek miktarı (MiB cinsinden) (varsayılan değer 512'dir)
• maxInstances – Aynı anda çalıştırılacak maksimum kapsayıcı sayısı (varsayılan olarak 100'dür ve kota tarafından yönetilir)
• minInstances: Her zaman etkin tutulacak kapsayıcı sayısı (varsayılan değer 0'dır).
• concurrency: Her yayınlama örneğinin alabileceği maksimum istek sayısı (varsayılan 80).

cpu ve memoryMiB arasındaki önemli ilişkiye dikkat edin. Bellek, 128 ile 32.768 arasında herhangi bir tam sayı değerine ayarlanabilir ancak bellek sınırının artırılması, CPU sınırlarının artırılmasını gerektirebilir:

• 4 GB'tan fazla için en az 2 CPU gerekir.
• 8 GiB'den fazla için en az 4 CPU gerekir.
• 16 GiB'den fazla için en az 6 CPU gerekir.
• 24 GB'tan fazla için en az 8 CPU gerekir.

Benzer şekilde, cpu değeri eşzamanlılık ayarlarını etkiler. 1 CPU'dan daha düşük bir değer ayarlarsanız eşzamanlılığı 1 olarak ayarlamanız gerekir ve CPU yalnızca istek işleme sırasında ayrılır.

Derleme ve çalıştırma komut dosyalarını geçersiz kılma

App Hosting, algılanan çerçeveye göre uygulamanızın derleme ve başlatma komutunu çıkarır. Özel bir derleme veya başlatma komutu kullanmak istiyorsanız App Hosting'nın varsayılanlarını apphosting.yaml'da geçersiz kılabilirsiniz.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

Derleme komutunu geçersiz kılma, diğer tüm derleme komutlarından önceliklidir. Bu işlem, uygulamanızı çerçeve bağdaştırıcılarının dışında bırakır ve App Hosting tarafından sağlanan çerçeveye özgü tüm optimizasyonları devre dışı bırakır. Uygulama özellikleriniz adaptörler tarafından iyi desteklenmediğinde kullanmak için idealdir. Derleme komutunuzu değiştirmek ancak sağladığımız bağdaştırıcıları kullanmaya devam etmek istiyorsanız App Hosting çerçeve bağdaştırıcıları bölümünde açıklandığı gibi derleme komut dosyanızı package.json olarak ayarlayın.

Uygulamanızı başlatmak için kullanmak istediğiniz belirli bir komut, App Hosting ile çıkarılan komuttan farklı olduğunda çalıştırma komutunu geçersiz kılma özelliğini kullanın.

Derleme çıkışını yapılandırma

App Hosting, çerçeve tarafından belirtilen kullanılmayan çıkış dosyalarını silerek uygulama dağıtımlarınızı varsayılan olarak optimize eder. Uygulama dağıtım boyutunuzu daha fazla optimize etmek veya varsayılan optimizasyonları yoksaymak istiyorsanız bu ayarı apphosting.yaml bölümünde geçersiz kılabilirsiniz.

outputFiles:
  serverApp:
    include: [dist, server.js]

include parametresi, uygulamanızı dağıtmak için gerekli olan, uygulama kök dizinine göre dizin ve dosya listesini alır. Tüm dosyaların saklandığından emin olmak istiyorsanız include'u [.] olarak ayarlayın. Bu durumda tüm dosyalar dağıtılır.

Gizli parametreleri depolama ve bunlara erişme

API anahtarları gibi hassas bilgiler, sır olarak saklanmalıdır. Hassas bilgilerin kaynak kontrolüne işlenmesini önlemek için apphosting.yaml içindeki sırları referans olarak kullanabilirsiniz.

secret türündeki parametreler, Cloud Secret Manager'da depolanan bir değere sahip dize parametrelerini temsil eder. Değeri doğrudan türetmek yerine, gizli parametreler Cloud Secret Manager'da var olup olmadığını kontrol eder ve değerleri kullanıma sunma sırasında yükler.

  -   variable: API_KEY
      secret: myApiKeySecret

Cloud Secret Manager'daki gizli anahtarların birden fazla sürümü olabilir. Varsayılan olarak, canlı arka uçunuzda kullanılabilen gizli parametrenin değeri, arka uç oluşturulduğu sırada gizlinin mevcut olan en son sürümüne sabitlenir. Parametrelerin sürüm oluşturma ve yaşam döngüsü yönetimiyle ilgili gereksinimleriniz varsa Cloud Secret Manager ile belirli sürümlere sabitleyebilirsiniz. Örneğin, 5. sürüme sabitlemek için:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

FirebaseCLI komutuyla firebase apphosting:secrets:set sır oluşturabilirsiniz ve gerekli izinleri eklemeniz istenir. Bu akış, gizli referansı apphosting.yaml'ya otomatik olarak ekleme seçeneği sunar.

Cloud Secret Manager işlevlerinin tümünü kullanmak için Cloud Secret Manager konsolunu kullanabilirsiniz. Bunu yaparsanız App Hosting arka uçunuza Firebase KSA komutuyla firebase apphosting:secrets:grantaccess izin vermeniz gerekir.

VPC erişimini yapılandırma

App Hosting arka ucunuz bir Sanal Özel Bulut (VPC) ağına bağlanabilir. Daha fazla bilgi ve örnek için Firebase App Hosting'ı bir VPC ağına bağlama başlıklı makaleyi inceleyin.

Erişimi yapılandırmak için apphosting.yaml dosyanızdaki vpcAccess eşlemesini kullanın. Tam nitelikli bir ağ/bağlayıcı adı veya kimlik kullanın. Kimliklerin kullanılması, farklı bağlayıcılar/ağlar içeren hazırlama ve üretim ortamları arasında taşınabilirliğe olanak tanır.

Doğrudan VPC Çıkış Yapılandırması (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

Sunucusuz Bağlayıcı Yapılandırması (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Arka uçları yönetme

App Hosting arka uçlarının temel yönetimi için komutlar Firebase konsolunda ve Firebase CLI'da sağlanır. Bu bölümde, arka uç oluşturma ve silme gibi daha yaygın yönetim görevlerinden bazıları açıklanmaktadır.

Arka uç oluşturma

App Hosting Arka uç, web uygulamanızı oluşturmak ve çalıştırmak için App Hosting tarafından oluşturulan yönetilen kaynaklar topluluğudur.

Firebase Console: Hosting ve Sunucusuz > App Hosting'e gidin ve Arka uç oluştur'u tıklayın (bu, Firebase projenizdeki ilk arka uçsa Başlayın'ı tıklayın).

Firebase KSA: (v13.15.4 veya sonraki sürümler) Arka uç oluşturmak için yerel proje dizininizin kökünden aşağıdaki komutu çalıştırın ve bağımsız değişken olarak proje kimliğinizi girin:

firebase apphosting:backends:create --project PROJECT_ID

Hem konsol hem de CLI için istemleri uygulayarak bir bölge seçin, GitHub bağlantısı oluşturun ve şu temel dağıtım ayarlarını yapılandırın:

• Uygulamanızın kök dizinini ayarlayın (varsayılan olarak /)

  Bu genellikle package.json dosyanızın bulunduğu yerdir.

• Canlı dalı ayarlama

  Bu, GitHub deponuzun canlı URL'nize dağıtılan dalıdır. Genellikle özellik dallarının veya geliştirme dallarının birleştirildiği daldır.

• Otomatik kullanıma sunma işlemlerini kabul etme veya reddetme

  Otomatik kullanıma sunma varsayılan olarak etkindir. Arka uç oluşturma işlemi tamamlandıktan sonra uygulamanızın hemen App Hosting'ya dağıtılmasını seçebilirsiniz.

• Arka uçunuza bir ad atayın.

• Çalışma zamanı ortamınızı seçin. Varsayılan olarak, önerilen en yeni Node.js sürümü sizin için önceden seçilir.

  • Otomatik temel görüntü güncellemelerini (ABIU) yapılandırın. ABIU varsayılan olarak etkindir ve temel ortamınıza güvenlik yamalarını otomatik olarak uygular. Çalışma zamanınız için "Belirtilmedi"yi seçerek ABIU'yu devre dışı bırakabilirsiniz.

Arka uç silin

Bir arka ucu tamamen kaldırmak için önce Firebase konsolunu veya Firebase CLI'yı kullanarak arka ucu silin. Ardından, diğer arka uçlar veya Firebase projenizin diğer yönleri tarafından kullanılabilecek kaynakları silmemeye özen göstererek ilgili öğeleri manuel olarak kaldırın.

Firebase konsolu: Ayarlar menüsünden Arka ucu sil'i seçin.

Firebase KSA: (v13.15.4 veya sonraki sürümler)

1. App Hosting arka ucunu silmek için aşağıdaki komutu çalıştırın. Bu işlem, arka uçunuzdaki tüm alanları devre dışı bırakır ve ilişkili Cloud Run hizmetini siler:

   firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID
   

2. (İsteğe bağlı) Artifact Registry için Google Cloud konsol sekmesinde, "firebaseapphosting-images" bölümünde arka uçunuzun resmini silin.

3. Cloud Secret Manager'da, gizli adında "apphosting" geçen tüm sırları silin. Bu sırların diğer arka uçlar veya Firebase projenizin diğer yönleri tarafından kullanılmadığından emin olmak için özel dikkat gösterin.