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 aracılığıyla ve alternatif olarak apphosting.yaml'da projeniz için bu tür verileri depolayıp almak üzere ortam yapılandırması sunar.

Ortam değişkenlerini konsolda ayarlamak, başlamanın en hızlı yoludur. 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 kullanın. Hem konsol hem de apphosting.<env>.yaml ile farklı ortamlar için farklı değerler ayarlayabilirsiniz.

Firebase konsolu

apphosting.yaml

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

Dikkat: Konsol tabanlı ve dosya tabanlı yapılandırma arasında birkaç temel fark vardır. Bu nedenle, bu bölümü dikkatlice inceleyin. En önemlisi: Konsolda ayarlanan değerler her zaman apphosting.yaml'da ayarlanan değerleri geçersiz kılar veya bu değerlere göre öncelikli olur. Değişken hiyerarşisine bakın.

Değişkenleri güncelleme

Arka uç için Ayarlar sekmesindeki Firebase konsolunda ortam değişkenleri ekleyebilir ve düzenleyebilirsiniz. Arka Uçtaki Görünüm >> Ayarlar >> Ortam'a gidin ve ortam değişkenlerini ekleyin, düzenleyin veya silin.

apphosting.yaml, ortam değişkenlerini eklemek ve düzenlemek için dosyayı manuel olarak oluşturun ve düzenleyin.

Değişiklikleriniz yalnızca bir sonraki kullanıma sunma işleminizde geçerli olur ve mevcut kullanıma sunma işlemini 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 (ancak konsolda değil) ortam değişkenini yalnızca derleme ortamında veya yalnızca çalışma zamanı ortamında kullanılabilir olacak şekilde kısıtlayabilirsiniz.

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

Next.js uygulamalarında, bir değişkene tarayıcıda erişilebilir hale getirmek için NEXT_PUBLIC_ önekini dotenv dosyanızda yaptığınız gibi kullanabilirsiniz.

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

Next.js için dotenv dosyaları

Next.js uygulamalarında, ortam değişkenlerini içeren 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 kullanılmasını öneririz.

Değişken hiyerarşisi

Firebase App Hosting, değişkenlerinizi kaynaklarına göre öncelik sırasına göre uygular. Örneğin, konsolda 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.

İpucu: Firebase konsolunda, dağıtımın ayrıntılarını görüntülemek için belirli bir dağıtımı tıklayabilirsiniz. Dağıtım sırasında kullanılan ortam değişkenlerinin ve kaynaklarının listesini incelemek için dağıtım ayrıntıları panelinin en altındaki Bu derlemedeki ortam değişkenleri'ne gidin.

Öncelik sırasının tamamı aşağıda verilmiştir:

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çindeki App Hosting bağdaştırıcıları tarafından ayarlanır)

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

Geçerli değişken anahtarları büyük harfle başlamalı ve yalnızca büyük harf, rakam ve alt çizgi içermelidir. 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 değişkenler
• X_FIREBASE_ ile başlayan tüm değişkenler
• PORT
• K_SERVICE
• K_REVISION
• K_CONFIGURATION
• Yinelenen anahtarlar

apphosting.yaml oluşturma ve düzenleme

Gizli diziler veya eşzamanlılık, CPU ve bellek sınırları gibi çalışma zamanı ayarları gibi gelişmiş yapılandırmalar 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 sayede, kaynak kontrolüne güvenli bir şekilde 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üzenlendikten sonra, tipik bir apphosting.yaml dosyası, arka uçtaki Cloud Run hizmetinin ayarları, bazı ortam değişkenleri ve Cloud Secret Manager tarafından yönetilen gizli dizilere yapılan bazı referanslarla birlikte 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 sunum örneği için kullanılan CPU sayısı (varsayılan 0).
• memoryMiB – Her sunum örneği için ayrılan bellek miktarı (MiB) (varsayılan 512)
• maxInstances – Aynı anda çalıştırılacak maksimum container 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 sunum örneğinin alabileceği maksimum istek sayısıdır (varsayılan değer 80'dir).

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 GiB'den fazla için en az 2 CPU gerekir
• 8 GB'tan fazla bellek için en az 4 CPU gerekir.
• 16 GiB'den fazla bellek için en az 6 CPU gerekir.
• 24 GiB'den fazla bellek 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 tahsis edilir.

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 apphosting.yaml'deki App Hosting varsayılanlarını 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 kullanılması önerilir. Derleme komutunuzu değiştirmek ancak sağladığımız bağdaştırıcıları kullanmaya devam etmek istiyorsanız App Hosting framework bağdaştırıcıları bölümünde açıklandığı gibi derleme komut dosyanızı package.json içinde ayarlayın.

Uygulamanızı başlatmak için kullanmak istediğiniz belirli bir komut olduğunda ve bu 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 gereken ve uygulama kök dizinine göre olan dizin ve dosyaların listesini alır. Tüm dosyaların saklandığından emin olmak istiyorsanız include değerini [.] olarak ayarlayın. Bu durumda tüm dosyalar dağıtılır.

Gizli parametreleri depolama ve bunlara erişme

API anahtarları gibi hassas bilgiler gizli anahtar 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. Gizli parametreler, değeri doğrudan türetmek yerine 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 bir parametrenin değeri, arka uç oluşturulduğu sırada gizli anahtarın 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

firebase apphosting:secrets:set KSA komutuyla gizli anahtarlar oluşturabilirsiniz. Gerekli izinleri eklemeniz istenir. Bu akış, gizli referansı apphosting.yaml'ya otomatik olarak ekleme seçeneği sunar.

Cloud Secret Manager işlevlerinin tamamını kullanmak için Cloud Secret Manager konsolunu kullanabilirsiniz. Bu işlemi yaparsanız App Hosting arka ucunuza firebase apphosting:secrets:grantaccess CLI komutuyla 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 vpcAccess dosyanızdaki apphosting.yaml eşlemeyi 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ırlık 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 CLI ve Firebase konsolunda 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 HostingArka uçApp Hosting, web uygulamanızı oluşturmak ve çalıştırmak için App Hosting tarafından oluşturulan yönetilen kaynaklar topluluğudur.

Proje sahibi, ilk App Hosting arka uçunu oluşturmalıdır. Bu ilk kurulumdan sonra, App Hosting Yöneticiler ek arka uçlar da oluşturup yönetebilir. Kuruluşunuzun tüm depolarını görmek için GitHub'da Kuruluş Yöneticisi rolüne sahip olduğunuzdan emin olun. Standart üye rolü yalnızca kişisel olarak oluşturduğunuz depoları gösterir. Ayrıntılar için Firebase App Hosting IAM rolleri başlıklı makaleyi inceleyin.

Firebase konsolu: Oluştur menüsünden App Hosting ve ardından Arka uç oluştur'u seçin (Firebase projenizdeki ilk arka uç ise Başlayın'ı seçin).

CLI: (13.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 projectID değerini bağımsız değişken olarak 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 aşağıdaki temel dağıtım ayarlarını yapılandırın:

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

  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.

Arka uç silin

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

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

CLI: (13.15.4 veya sonraki sürümler)

1. App Hosting Backend'i 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 Console sekmesinde, "firebaseapphosting-images" bölümünde arka uç için resmi silin.

3. Cloud Secret Manager'da, gizli anahtar adında "apphosting" geçen tüm gizli anahtarları silin. Bu gizli anahtarları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.