Application Design Center ile uygulamaları hızlıca dağıtma

1. Giriş

Bu codelab'de, Google Cloud Application Design Center (ADC)'ı kullanarak tam yığınlı bir uygulamayı nasıl dağıtacağınızı öğreneceksiniz. Vue 3 ön ucu, FastAPI arka ucu ve uygulama verilerini barındıran bir MCP sunucusu içeren "The Cymbal London Concierge" uygulamasını dağıtacaksınız.

ADC, uygulama mimarinizi görsel olarak tanımlamanıza ve tek bir birim olarak dağıtmanıza olanak tanır. Bağımlılıkları ve bağlantıları otomatik olarak yönetir.

Yapacaklarınız

Application Design Center'ı ayarlayın.
Uygulama bileşenlerini görsel olarak birleştirin.
Uygulama mimarisini dağıtın.
Çalışan uygulamayı doğrulayın.
Uygulamanın Uygulama Merkezi'ne kaydedildiğini doğrulayın.
Uygulama İzleme'de uygulama metriklerini, izlerini ve günlüklerini doğrulayın.

İhtiyacınız olanlar

Chrome gibi bir web tarayıcısı
Faturalandırmanın etkin olduğu bir Google Cloud projesi.

Bu codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştiriciye yöneliktir.

Tahmini Süre: 45 dakika Tahmini Maliyet: 2 ABD dolarından az

2. Kurulum

Proje ayarlama

Google Cloud projesi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
```
gcloud auth list
```
Projenizin yapılandırıldığını onaylayın:
```
gcloud config get project
```

Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

3. Application Design Center'ı ayarlama

Uygulamanızı oluşturmadan önce ADC'de çalışma alanınızı ayarlamanız gerekir.

Google Cloud Console'da Application Design Center'ı arayıp bu merkeze gidin.
Bu projede ADC'yi ilk kez kullanıyorsanız bir kurulum ekranı görürsünüz.
Kuruluma git'i tıklayın.

Application Design Center'ı ayarlama

Gerekli API'ler etkinleştirilmemişse bunları etkinleştirmeniz istenir. Devam etmek için Etkinleştir'i tıklayın.

API'leri etkinleştir

4. ADC özelliklerini keşfetme

Bu görevde, ADC'nin temel bileşenleri olan Alanlar, Kataloglar ve Şablonlar hakkında bilgi edineceksiniz.

ADC Spaces

Alan, şablon oluşturmak ve uygulamaları dağıtmak için kullanılan bir yerdir. Her alan bir Google Cloud projesine aittir. ADC, ilk kurulum sırasında varsayılan bir alan oluşturur ancak daha sonra farklı bölgelerde başka alanlar oluşturabilirsiniz.

Alanlarınızı terminal üzerinden görüntülemek için aşağıdaki adımları uygulayın:

Cloud Shell araç çubuğunda Open Editor'ı (Düzenleyiciyi Aç) tıklayın veya terminali kullanın.
Aşağıdaki komutu çalıştırın:

gcloud alpha design-center spaces list \
--project="your PROJECT ID" \
--location=us-central1

Bölge için varsayılan alanın mevcut olduğunu belirten aşağıdaki gibi bir çıkış görmeniz gerekir.

createTime: '20XXXX-XX-XXT09:19:29.456016967Z'
displayName: default-space
enableGcpSharedTemplates: true
name: projects/your-project-id/locations/us-central1/spaces/default-space

5. Şablonu birleştirme

Bu adımda, Platform Ekibi mühendisi rolünü üstleneceksiniz. Amacınız, kuruluşunuzdaki aracı uygulamaları için yeniden kullanılabilir, güvenli ve uyumlu bir şablon oluşturmaktır. Bu şablondan dağıtılan tüm uygulamaların şirketinizin bulut politikalarına uygun olmasını sağlamak için bileşenler ekleyip kısıtlamaları yapılandıracaksınız.

1. Yeni tasarım oluşturma

ADC konsolunda Templates > Create Template'i (Şablonlar > Şablon Oluştur) tıklayın.
Şablonunuza simple-3-tier-agentic-app adını verin. Bu şablon, Cymbal London Concierge uygulamasını ve benzer uygulamaları dağıtmak için kullanılacaktır.

2. Veri MCP sunucusunu ekleme

Bu bileşen, veritabanı etkileşimlerini ve Vector Search'ü yönetir.

Add Component (Bileşen Ekle) > Cloud Run (Service)'i (Cloud Run (Hizmet)) tıklayın. Bu bileşeni tıkladığınızda sağ üst köşede bileşen kimliği görürsünüz. cloud-run-1 biçiminde olacaktır. Daha sonra kod görünümünde (sonraki bölümlerde ele alınacaktır) düzenleyerek data-mcp-server olarak değiştirebiliriz ancak şimdilik olduğu gibi bırakalım.
Hizmet Adı'nı girin: data-mcp-server.
Gelişmiş ayarları göster bölümünde Üyeler'i allUsers olarak ayarlayın. (Not: Üretim ortamında bunu kısıtlamanız gerekir ancak Codelab'in basitliği için burada kullanıyoruz.)
Gelişmiş ayarları göster bölümünde VPC ERİŞİMİ'ni ayarlayın, Çıkış'ı PRIVATE_RANGES_ONLY olarak ayarlayın.
İsteğe bağlı olarak, Gelişmiş ayarları göster bölümünde Prometheus Sidecar'ı etkinleştir seçeneğinin işaretini kaldırın.
Kaydet'i tıklayın.

3. Temsilci arka ucunu ekleme

Bu, ajan davranışını düzenleyen FastAPI uygulamasıdır.

Add Component (Bileşen Ekle) > Cloud Run (Service)'i (Cloud Run (Hizmet)) tıklayın.
agent-backend olarak adlandırın.
Gelişmiş alanları göster bölümünde Hizmet hesabı oluştur'u işaretleyin ve Hizmet Hesabı Proje Rolleri bölümünde aşağıdaki rolleri tek tek ekleyin:
- roles/monitoring.metricWriter
- roles/logging.logWriter
- roles/cloudtrace.agent
- roles/telemetry.writer
- roles/serviceusage.serviceUsageConsumer. Bu roller, aracının Cloud Monitoring, Cloud Logging ve Cloud Trace'i kullanmasına olanak tanır. Uygunluk Yapılandırması: Platform ekibi, gerekli rolleri açıkça listeleyerek en az ayrıcalık ilkesini uygular.
Gelişmiş ayarları göster bölümünde Üyeler'i allUsers olarak ayarlayın.
Gelişmiş ayarları göster bölümünde VPC ERİŞİMİ'ni ayarlayın, Çıkış'ı PRIVATE_RANGES_ONLY olarak ayarlayın.
İsteğe bağlı olarak, Gelişmiş ayarları göster bölümünde Prometheus Sidecar'ı etkinleştir seçeneğinin işaretini kaldırın.
agent-backend öğesinden data-mcp-server öğesine bağlantı sürükleyerek agent-backend öğesini data-mcp-server öğesine bağlayın.
Kaydet'i tıklayın.

4. Ön ucu ekleme

Kullanıcı arabirimi

Add Component (Bileşen Ekle) > Cloud Run (Service)'i (Cloud Run (Hizmet)) tıklayın.
Hizmet Adı'nı girin: frontend.
Gelişmiş ayarları göster bölümünde Hizmet Hesabı Oluştur'un işaretini kaldırın.
Gelişmiş ayarları göster bölümünde Giriş'i INGRESS_TRAFFIC_INTERNAL_LOADBALANCER olarak ayarlayın. Uygunluk Yapılandırması: Ön uç kapsayıcısına doğrudan herkese açık erişim engellenir ve trafik, yük dengeleyiciden geçmeye zorlanır.
Gelişmiş ayarları göster bölümünde Üyeler'i şu şekilde ayarlayın: allUsers.
İsteğe bağlı olarak, Gelişmiş ayarları göster bölümünde Prometheus Sidecar'ı etkinleştir seçeneğinin işaretini kaldırın.
Kaydet'i tıklayın.
frontend öğesinden agent-backend öğesine bağlantı sürükleyerek frontend öğesini agent-backend öğesine bağlayın.

5. Vertex AI bileşeni ekleme

Add Component (Bileşen Ekle) > Vertex AI'ı tıklayın.
vertex-ai olarak adlandırın.
vertex-ai öğesinden agent-backend ve data-mcp-server öğelerine iki bağlantı sürükleyerek agent-backend ve data-mcp-server öğelerine bağlayın. aiplatform.user rolleri, Vertex AI bileşenine bağlı oldukları için agent-backend ve data-mcp-server hizmet hesaplarına atanmış olur.

6. Global yük dengeleyiciyi ekleme

Yük dengeleyici, ön ucunuzu herkese açık internete sunar. ADC'de bu, arka uç ve ön uç bileşenlerine ayrılır.

C. Yük dengeleyici arka ucunu ekleme

**Add Component > Global Cloud Load Balancing (Backend)'i (Bileşen Ekle > Global Cloud Load Balancing (Arka Uç)) tıklayın.
galb-backend olarak adlandırın.
Bağlantı Ekle'yi tıklayın ve frontend'ye bağlayın.

B. Yük dengeleyici ön ucunu ekleme

**Add Component > Global Cloud Load Balancing (Frontend)'i (Bileşen Ekle > Global Cloud Load Balancing (Ön Uç)) tıklayın.
galb-frontend olarak adlandırın.
Bağlantı Ekle'yi tıklayın ve galb-backend'ye bağlayın.
galb-frontend öğesinden galb-backend öğesine bağlantı sürükleyerek galb-frontend öğesini galb-backend öğesine bağlayın.

Uygulama Şablonu

Katalog, uygulama şablonlarını farklı alanlarda paylaşmanıza olanak tanıyarak mimari yönetimine imkan verir. Katalog, platform ekibi tarafından oluşturulan ve paylaşım için onaylanan şablonların merkezi deposu olarak işlev görür. Alanlar arasında katalog paylaşmak, ortak projelerde tekrarlanan çabaları önler ve başlangıç sürelerini kısaltır.

Şimdi şablonunuzu kataloga ekleyin:

Kataloglar sekmesini tıklayın.
Şablon Ekle'yi tıklayın ve simple-3-tier-agentic-app şablonunu seçin.
Kataloga ekle'yi tıklayın.

Şablonları üç yerde bulabilirsiniz: Google Şablonları (önceden tanımlanmış desenler), Paylaşılan Şablonlar (kuruluşunuzda paylaşılanlar) ve Şablonlar (alanınızdaki özel planlar).

6. Uygulamayı dağıtma

Şimdi, bu şablonu cymbal-london-concierge uygulamasını dağıtmak için kullanmak isteyen bir uygulama geliştirici rolünü oynama zamanı.

ADC konsolunda, Templates (Şablonlar) sekmesinde şablonu yeniden açın ve Configure app (Uygulamayı yapılandır) düğmesini tıklayın.
Yeni uygulama oluştur'u tıklayın.
Uygulamayı yapılandırın:
- Uygulama Adı: cymbal-london-concierge
- Dağıtım projesi: Proje kimliğiniz
- Bölge: us-central1
- Giriş Özellikleri>Ortam: Development
- Giriş Özellikleri>Önem Derecesi: Low
Uygulama Oluştur'u tıklayın.Üretim dağıtımı için Ortam olarak "Üretim", Kritiklik olarak da "Yüksek"i seçersiniz. Bunlar, SRE'lerinizin ve operasyon ekibinizin ortaya çıkan sorunlar üzerinde çalışmayı sıralamasına ve önceliklendirmesine yardımcı olacak etiketlerdir.
Bu işlem, uygulama şablonuyla birlikte dağıtım ayrıntıları sayfasını açmalıdır. Bu yalnızca bir şablon olduğundan, uygulamamıza özgü yapılandırmayı eklememiz gerekir.
Ön ucu yapılandıralım. Ön uç bileşenini tıklayın.
1. Kapsayıcılar > Kapsayıcıyı Düzenle'yi tıklayın.
2. Genel kapsayıcı resmini, uygulamamızda kullanmak istediğimiz resimle değiştirmemiz gerekir.
3. Container Image'i şu şekilde ayarlayın: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
4. http1 bağlantı noktasını 80 olarak ayarlayın.
5. Aşağıdaki ortam değişkenlerini ayarlayın:
  - API_BASE_URL: module.cloud-run-2.service_uri (cloud-run-2, aracı arka uç bileşeninin adı olmalıdır. Aksi takdirde, bileşenin gerçek adıyla değiştirin.)
6. Kaydet'i tıklayın.
Aracı arka ucunu yapılandıralım. agent-backend bileşenini tıklayın.
1. Kapsayıcılar > Kapsayıcıyı Düzenle'yi tıklayın.
2. Genel kapsayıcı resmini, uygulamamızda kullanmak istediğimiz resimle değiştirmemiz gerekir.
3. Container Image'i us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1 olarak ayarlayın.
4. Aşağıdaki ortam değişkenlerini ayarlayın:
5. GOOGLE_CLOUD_PROJECT:
6. GOOGLE_CLOUD_LOCATION: us-central1
7. DATA_BACKEND_URL: module.cloud-run-1.service_uri (cloud-run-1 öğesinin veri mcp sunucusu bileşeninin adı olduğundan emin olun, değilse bileşenin gerçek adıyla değiştirin)
8. http1 bağlantı noktasını 8000 olarak ayarlayın.
9. Kaydet'i tıklayın.
Veri MCP sunucusunu yapılandıralım. data-mcp-server bileşenini tıklayın.
1. Kapsayıcılar > Kapsayıcıyı Düzenle'yi tıklayın.
2. Genel kapsayıcı resmini, uygulamamızda kullanmak istediğimiz resimle değiştirmemiz gerekir.
3. Container Image'i us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1 olarak ayarlayın.
4. Aşağıdaki ortam değişkenlerini ayarlayın:
5. GOOGLE_CLOUD_PROJECT:
6. GOOGLE_CLOUD_LOCATION: us-central1
7. DB_TYPE: sqlite
8. EMBEDDING_MODEL: text-embedding-005
9. http1 bağlantı noktasını 8002 olarak ayarlayın.
10. Kaydet'i tıklayın.
Gerçek bir üretim senaryosunda CloudSQL veya AlloyDB gibi bir veritabanı da yapılandırır ve veri mcp sunucusu için veritabanı bağlantı dizesini sağlarsınız. Ancak bu laboratuvarda bellek içi bir veritabanı kullanacağız. Ayrıca mcp sunucusunu ve veritabanını gizli hale getirip yalnızca aracı arka ucundan veya ağ içinden erişilebilir hale getirirsiniz.
Uygulamanın Terraform kodunu görüntülemek için sayfanın üst kısmındaki Code (Kod) düğmesini tıklayın. Ayrıca, uygulamaya ait Terraform kodunu Get Code (Kodu Al) düğmesini tıklayarak indirip kod tabanınızda saklayabilirsiniz.
Uygulamayı dağıtmak için sayfanın sağ üst köşesindeki Dağıt düğmesini tıklayın.
Dağıtım sayfasında, dağıtım ardışık düzeni için bir hizmet hesabı oluşturmanız veya mevcut bir hesabı seçmeniz istenir. Hizmet hesabı oluştur'u (ad otomatik olarak doldurulur) ve ardından Devam'ı tıklayın. Yeni bir hizmet hesabı oluşturmak birkaç saniye sürer.

Hizmet hesabı oluşturma

Hizmet hesabı oluşturulduktan sonra sayfa yenilenir ve hizmet hesabını seçin seçeneğinin yanında bir onay işareti görürsünüz.

Oluşturulan Hizmet Hesabı

Ardından, sayfanın alt kısmındaki Dağıt'ı tıklayın.
Bu işlemin tamamlanması birkaç dakika sürer. Dağıtım tamamlandığında her bileşenin yanında yeşil bir onay işareti görürsünüz. Ayrıca, dağıtımın durumunu kontrol etmek için Günlüklere bağlantı düğmesini tıklayarak bulut derleme günlüklerini açabilirsiniz. Düğmenin görünmesi birkaç dakika sürebilir.

![Deployment Logs](./img/10b_logs.png)

Dağıtımın durumunu görmek veya uygulamayı dağıtırken oluşabilecek hataları incelemek için Cloud Build günlüklerini görüntüleyebilirsiniz. Ayrıca, Google Cloud Console'da Cloud Build'i arayıp Geçmiş'i tıklayarak doğrudan Cloud Build günlüklerine gidebilirsiniz. Uygulamanın dağıtılması yaklaşık 5-8 dakika sürer.

![Cloud Build](./img/10c_cloudbuild.png)

Dağıtım tamamlandığında Dağıtım durumu alanının yanında yeşil bir onay işareti görürsünüz.

![Deployment Complete](./img/11_deployed.png)

7. Uygulamayı doğrulama

Aracının çalışıp çalışmadığını test edelim. Dağıtım ayrıntıları sayfasının outputs (çıkışlar) bölümünde ön uç bileşeninin URL'sini görürsünüz. Bu URL'yi kopyalayıp tarayıcınıza yapıştırın. https değil http kullandığınızdan emin olun. Ayrıca, ön uç http kullandığından tarayıcıda alabileceğiniz uyarıları da kabul edin.

Uygulamayla sohbet edip Londra seyahati için bir seyahat planı oluşturmasını isteyin.

Ön uç

8. Uygulama Merkezi ve uygulama izleme

ADC konsolunda, sayfanın sağ üst köşesindeki Uygulamayı Uygulama Merkezi'nde görüntüle düğmesini tıklayın.

Uygulama Merkezi

Bu işlem, uygulamayı Uygulama Merkezi'nde açar. Uygulama Merkezi, tüm uygulamalarınızı görüntüleyip yönetebileceğiniz merkezi bir yerdir. Bu sayede, kaynak odaklı bir görünümden uygulama odaklı bir görünüme geçiş yapabilirsiniz. ADC kullanarak uygulama oluşturduğunuzda Uygulama Merkezi'nde otomatik olarak bir uygulama oluşturulur. Uygulamayı oluşturan tüm iş yükleri ve hizmetler burada listelenir. Buluttaki kaynakları tek tek kaynaklar olarak görüntülemek yerine, tek bir uygulamanın parçası olarak görüntüleyebilir, böylece yönetimi ve yönetişimi basitleştirebilirsiniz.