با مرکز طراحی برنامه، برنامه‌ها را به سرعت مستقر کنید

۱. مقدمه

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه یک برنامه فول‌استک را با استفاده از مرکز طراحی برنامه ابری گوگل (ADC) مستقر کنید. شما برنامه "The Cymbal London Concierge" را مستقر خواهید کرد که شامل یک رابط کاربری Vue 3، یک رابط کاربری FastAPI و یک سرور MCP است که داده‌های برنامه را در خود نگه می‌دارد.

ADC به شما امکان می‌دهد معماری برنامه خود را به صورت بصری تعریف کنید و آن را به عنوان یک واحد واحد مستقر کنید و وابستگی‌ها و اتصالات را به طور خودکار مدیریت کنید.

کاری که انجام خواهید داد

• راه اندازی مرکز طراحی اپلیکیشن
• اجزای برنامه را به صورت بصری مونتاژ کنید.
• معماری برنامه را مستقر کنید.
• برنامه در حال اجرا را تأیید کنید.
• تأیید کنید که برنامه در App Hub ثبت شده است.
• معیارهای برنامه، ردیابی‌ها و گزارش‌ها را در نظارت بر برنامه تأیید کنید.

آنچه نیاز دارید

• یک مرورگر وب مانند کروم .
• یک پروژه گوگل کلود با قابلیت پرداخت.

این آزمایشگاه کد برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است.

مدت زمان تخمینی: ۴۵ دقیقه هزینه تخمینی: کمتر از ۲ دلار آمریکا

۲. راه‌اندازی

راه‌اندازی پروژه

ایجاد یک پروژه ابری گوگل

1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید:

   gcloud auth list
   

3. تأیید کنید که پروژه شما پیکربندی شده است:

   gcloud config get project
   

4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید:

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

۳. مرکز طراحی اپلیکیشن راه‌اندازی کنید

قبل از اینکه بتوانید برنامه خود را مونتاژ کنید، باید فضای کاری خود را در ADC تنظیم کنید.

1. در کنسول گوگل کلود، عبارت Application Design Center را جستجو کنید و به آن بروید.
2. اگر این اولین بار است که از ADC در این پروژه استفاده می‌کنید، یک صفحه تنظیمات مشاهده خواهید کرد.
3. روی رفتن به تنظیمات کلیک کنید.

4. اگر API های مورد نیاز از قبل فعال نشده باشند، از شما خواسته می‌شود که آنها را فعال کنید. برای ادامه، روی فعال کردن کلیک کنید.

۴. بررسی ویژگی‌های ADC

در این تمرین، اجزای اصلی ADC را یاد می‌گیرید: فضاها، کاتالوگ‌ها و قالب‌ها.

فضاهای ADC

یک فضا (Space) مکانی برای ایجاد قالب‌ها و استقرار برنامه‌ها است. هر فضا متعلق به یک پروژه Google Cloud است. ADC در طول راه‌اندازی اولیه یک فضای پیش‌فرض ایجاد می‌کند، اما شما می‌توانید بعداً فضاهای دیگری را در مناطق مختلف ایجاد کنید.

برای مشاهده فضاهای خود از طریق ترمینال، مراحل زیر را انجام دهید:

1. روی «باز کردن ویرایشگر» در نوار ابزار Cloud Shell کلیک کنید یا از ترمینال استفاده کنید.
2. دستور زیر را اجرا کنید:

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

شما باید خروجی‌ای شبیه به این ببینید که نشان می‌دهد فضای پیش‌فرض برای منطقه وجود دارد.

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

۵. الگو را مونتاژ کنید

در این مرحله، شما نقش مهندس تیم پلتفرم را بر عهده خواهید گرفت. هدف شما ایجاد یک الگوی قابل استفاده مجدد، امن و سازگار برای برنامه‌های عامل در سازمانتان است. شما اجزا را اضافه کرده و محدودیت‌هایی را پیکربندی خواهید کرد تا اطمینان حاصل شود که هر برنامه‌ای که از این الگو مستقر می‌شود، با سیاست‌های ابری شرکت شما مطابقت دارد.

۱. یک طرح جدید ایجاد کنید

1. در کنسول ADC، روی Templates > Create Template کلیک کنید.
2. نام الگوی خود را simple-3-tier-agentic-app بگذارید، زیرا این الگو برای استقرار برنامه Cymbal London Concierge و سایر برنامه‌های مشابه استفاده خواهد شد.

۲. سرور Data MCP را اضافه کنید

این کامپوننت تعاملات پایگاه داده و جستجوی برداری را مدیریت می‌کند.

1. روی افزودن کامپوننت > اجرای ابری (سرویس) کلیک کنید. اگر روی آن کامپوننت کلیک کنید، شناسه کامپوننت را در گوشه بالا سمت راست مشاهده خواهید کرد. این شناسه به شکل cloud-run-1 خواهد بود. می‌توانیم با ویرایش آن در نمای کد (که بعداً مورد بحث قرار خواهد گرفت) آن را به data-mcp-server تغییر دهیم، اما بیایید آن را به همین شکل رها کنیم.
2. نام سرویس را وارد کنید: data-mcp-server .
3. در قسمت «نمایش تنظیمات پیشرفته» ، گزینه « اعضا» را روی allUsers تنظیم کنید. (نکته: در یک محیط عملیاتی، احتمالاً این مورد را محدود می‌کنید، اما ما در اینجا برای سادگی کدنویسی از آن استفاده می‌کنیم.)
4. در قسمت نمایش تنظیمات پیشرفته ، گزینه تنظیم دسترسی به VPC و گزینه خروجی را روی PRIVATE_RANGES_ONLY تنظیم کنید.
5. در صورت تمایل، در قسمت نمایش تنظیمات پیشرفته ، تیک گزینه‌ی «فعال کردن پرومتئوس سایدکار» را بردارید.
6. روی ذخیره کلیک کنید.

۳. افزودن بخش پشتیبانی عامل

این برنامه FastAPI است که رفتار عامل‌محور را هماهنگ می‌کند.

1. روی افزودن کامپوننت > اجرای ابری (سرویس) کلیک کنید.
2. نام آن را agent-backend بگذارید.
3. در قسمت نمایش فیلدهای پیشرفته ، گزینه ایجاد حساب کاربری سرویس (Create Service Account) را علامت بزنید و نقش‌های زیر را یکی یکی در قسمت نقش‌های پروژه حساب کاربری سرویس (Service Account Project Roles) اضافه کنید:
   • roles/monitoring.metricWriter
   • roles/logging.logWriter
   • roles/cloudtrace.agent
   • roles/telemetry.writer
   • roles/serviceusage.serviceUsageConsumer . این نقش‌ها به عامل اجازه می‌دهند تا از Cloud Monitoring، Cloud Logging و Cloud Trace استفاده کند. پیکربندی انطباق: تیم پلتفرم با فهرست کردن صریح نقش‌های مورد نیاز، اصل حداقل امتیاز را اجرا می‌کند.
   
4. در قسمت نمایش تنظیمات پیشرفته ، اعضا را روی allUsers تنظیم کنید.
5. در قسمت نمایش تنظیمات پیشرفته ، گزینه تنظیم دسترسی به VPC و گزینه خروجی را روی PRIVATE_RANGES_ONLY تنظیم کنید.
6. در صورت تمایل، در قسمت نمایش تنظیمات پیشرفته ، تیک گزینه‌ی «فعال کردن پرومتئوس سایدکار» را بردارید.
7. با کشیدن یک اتصال از agent-backend به data-mcp-server ، agent-backend را به data-mcp-server متصل کنید.
8. روی ذخیره کلیک کنید.

۴. ظاهر (Frontend) را اضافه کنید

رابط کاربری جلویی (front-end UI).

1. روی افزودن کامپوننت > اجرای ابری (سرویس) کلیک کنید.
2. نام سرویس را وارد کنید: frontend .
3. در قسمت نمایش تنظیمات پیشرفته ، تیک گزینه ایجاد حساب کاربری سرویس (Create Service Account) را بردارید.
4. در قسمت نمایش تنظیمات پیشرفته ، ورودی را روی INGRESS_TRAFFIC_INTERNAL_LOADBALANCER تنظیم کنید. پیکربندی انطباق: دسترسی عمومی مستقیم به کانتینر frontend مسدود شده است و ترافیک را مجبور به عبور از متعادل‌کننده بار می‌کند.
5. در قسمت نمایش تنظیمات پیشرفته ، اعضا را روی allUsers تنظیم کنید.
6. در صورت تمایل، در قسمت نمایش تنظیمات پیشرفته ، تیک گزینه‌ی «فعال کردن پرومتئوس سایدکار» را بردارید.
7. روی ذخیره کلیک کنید.
8. با کشیدن یک اتصال از frontend به agent-backend ، frontend را به agent-backend متصل کنید.

۵. یک کامپوننت هوش مصنوعی رأسی اضافه کنید

1. روی افزودن کامپوننت > Vertex AI کلیک کنید.
2. نام آن را vertex-ai .
3. با کشیدن دو اتصال از vertex-ai به ترتیب به agent-backend و data-mcp-server ، آن را به agent-backend و data-mcp-server متصل کنید. نقش‌های aiplatform.user از قبل به حساب‌های سرویس agent-backend و data-mcp-server به دلیل اتصال آنها به کامپوننت vertex AI اختصاص داده شده‌اند.

۶. متعادل‌کننده بار سراسری را اضافه کنید

متعادل‌کننده بار، بخش frontend شما را در معرض اینترنت عمومی قرار می‌دهد. در ADC، این بخش به یک بخش Backend و یک بخش Frontend تقسیم می‌شود.

الف. اضافه کردن Backend متعادل‌کننده بار

1. روی افزودن کامپوننت > متعادل‌سازی بار ابری سراسری (پشتیبان) کلیک کنید.
2. نام آن را galb-backend بگذارید.
3. روی افزودن اتصال کلیک کنید و آن را به frontend متصل کنید.

ب. اضافه کردن رابط کاربری Load Balancer

1. روی افزودن کامپوننت > متعادل‌سازی بار ابری سراسری (ظاهر) کلیک کنید.
2. نام آن را galb-frontend بگذارید.
3. روی افزودن اتصال کلیک کنید و آن را به galb-backend متصل کنید.
4. با کشیدن یک اتصال از galb-frontend به galb-backend ، galb-frontend را به galb-backend متصل کنید.

الگو را در کاتالوگ به اشتراک بگذارید

یک کاتالوگ به شما امکان می‌دهد قالب‌های برنامه را در فضاهای مختلف به اشتراک بگذارید و مدیریت معماری را امکان‌پذیر کنید. یک کاتالوگ به عنوان یک مخزن مرکزی برای قالب‌هایی که توسط تیم پلتفرم ایجاد و برای اشتراک‌گذاری تأیید شده‌اند، عمل می‌کند. اشتراک‌گذاری کاتالوگ‌ها بین فضاها از تلاش‌های تکراری برای پروژه‌های مشترک جلوگیری می‌کند و زمان راه‌اندازی را ساده می‌کند.

حالا، الگوی خود را به کاتالوگ اضافه کنید:

1. روی برگه کاتالوگ‌ها کلیک کنید.
2. روی افزودن قالب‌ها کلیک کنید و قالب simple-3-tier-agentic-app را انتخاب کنید.
3. روی افزودن به کاتالوگ کلیک کنید.

می‌توانید الگوها را در سه مکان پیدا کنید: الگوهای گوگل (الگوهای از پیش تعریف‌شده)، الگوهای اشتراکی (مشترک در سراسر سازمان شما) و الگوها (طرح‌های سفارشی در فضای شما).

۶. برنامه را مستقر کنید

حالا وقت آن رسیده که نقش یک توسعه‌دهنده اپلیکیشن را بازی کنیم که می‌خواهد از این الگو برای استقرار اپلیکیشن cymbal-london-concierge استفاده کند.

1. در کنسول ADC، قالب را در تب Templates دوباره باز کنید و روی دکمه Configure app کلیک کنید.
2. روی ایجاد برنامه جدید کلیک کنید.
3. پیکربندی برنامه:
   • نام برنامه : cymbal-london-concierge
   • پروژه استقرار : شناسه پروژه شما
   • منطقه : us-central1
   • ویژگی‌های ورودی>محیط : Development
   • ویژگی‌های ورودی> سطح بحرانی : Low
4. روی ایجاد برنامه کلیک کنید. برای استقرار در محیط عملیاتی، می‌توانید «تولید» را برای محیط و «بالا» را برای بحرانی بودن انتخاب کنید. این‌ها برچسب‌هایی هستند که به SREها و تیم عملیاتی شما کمک می‌کنند تا کار روی هر مشکلی که رخ می‌دهد را مرتب و اولویت‌بندی کنند.
5. این باید صفحه جزئیات استقرار را با الگوی برنامه باز کند. با توجه به اینکه این فقط یک الگو است، ما هنوز باید پیکربندی خاصی را که مختص برنامه ماست اضافه کنیم.
6. بیایید ظاهر (frontend) را پیکربندی کنیم. روی کامپوننت ظاهر (frontend) کلیک کنید.
   1. روی کانتینرها > ویرایش کانتینر کلیک کنید.
   2. ما باید تصویر کانتینر عمومی را با تصویری که می‌خواهیم برای برنامه خود استفاده کنیم، جایگزین کنیم.
   3. تصویر کانتینر را روی این تنظیم کنید: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/frontend:codelab-c2c6-v1
   4. پورت http1 را روی 80 تنظیم کنید.
   5. متغیرهای محیطی زیر را تنظیم کنید:
      • API_BASE_URL : module.cloud-run-2.service_uri (مطمئن شوید که cloud-run-2 نام کامپوننت backend عامل است، در غیر این صورت آن را با نام واقعی کامپوننت جایگزین کنید)
   6. روی ذخیره کلیک کنید.
7. بیایید بخش مدیریت عامل (agent backend) را پیکربندی کنیم. روی کامپوننت agent-backend کلیک کنید.
   1. روی کانتینرها > ویرایش کانتینر کلیک کنید.
   2. ما باید تصویر کانتینر عمومی را با تصویری که می‌خواهیم برای برنامه خود استفاده کنیم، جایگزین کنیم.
   3. تصویر کانتینر را روی us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/agent:codelab-c2c6-v1 تنظیم کنید.
   4. متغیرهای محیطی زیر را تنظیم کنید:
   5. GOOGLE_CLOUD_PROJECT :
   6. GOOGLE_CLOUD_LOCATION : us-central1
   7. DATA_BACKEND_URL : module.cloud-run-1.service_uri (مطمئن شوید که cloud-run-1 نام کامپوننت سرور data mcp است، در غیر این صورت آن را با نام واقعی کامپوننت جایگزین کنید)
   8. پورت http1 را روی 8000 تنظیم کنید.
   9. روی ذخیره کلیک کنید.
8. بیایید سرور data mcp را پیکربندی کنیم. روی کامپوننت data-mcp-server کلیک کنید.
   1. روی کانتینرها > ویرایش کانتینر کلیک کنید.
   2. ما باید تصویر کانتینر عمومی را با تصویری که می‌خواهیم برای برنامه خود استفاده کنیم، جایگزین کنیم.
   3. تصویر کانتینر را روی این تنظیم کنید: us-central1-docker.pkg.dev/o11y-movie-guru/london-travel-agency/data_mcp:codelab-c2c6-v1
   4. متغیرهای محیطی زیر را تنظیم کنید:
   5. GOOGLE_CLOUD_PROJECT :
   6. GOOGLE_CLOUD_LOCATION : us-central1
   7. DB_TYPE : sqlite
   8. EMBEDDING_MODEL : text-embedding-005
   9. پورت http1 را روی 8002 تنظیم کنید.
   10. روی ذخیره کلیک کنید.
   در یک سناریوی تولید واقعی، شما همچنین یک پایگاه داده مانند CloudSQL یا AlloyDB را پیکربندی می‌کنید و رشته اتصال پایگاه داده را برای سرور داده mcp فراهم می‌کنید. اما برای این آزمایش، ما از یک پایگاه داده درون حافظه‌ای استفاده خواهیم کرد. شما همچنین سرور mcp و پایگاه داده را خصوصی می‌کنید و فقط از backend عامل یا از داخل شبکه قابل دسترسی هستند.
9. برای مشاهده کد terraform مربوط به برنامه، روی دکمه Code در بالای صفحه کلیک کنید. همچنین می‌توانید با کلیک روی دکمه Get Code ، کد terraform مربوط به برنامه را دانلود کنید تا در پایگاه کد شما ذخیره شود.
10. برای استقرار برنامه، روی دکمه‌ی Deploy در گوشه‌ی بالا سمت راست صفحه کلیک کنید.
11. صفحه استقرار از شما می‌خواهد که یک حساب کاربری سرویس برای فرآیند استقرار ایجاد کنید یا یک حساب کاربری موجود را انتخاب کنید. روی «ایجاد حساب کاربری سرویس» کلیک کنید (این کار به طور خودکار یک نام را پر می‌کند) و سپس «ادامه » را بزنید. ایجاد یک حساب کاربری سرویس جدید چند ثانیه طول می‌کشد.

12. پس از ایجاد حساب کاربری سرویس، صفحه رفرش می‌شود و گزینه «انتخاب حساب کاربری سرویس» را به همراه یک علامت تیک در کنار آن مشاهده خواهید کرد.

13. سپس در پایین صفحه روی گزینه Deploy کلیک کنید.
14. تکمیل این فرآیند چند دقیقه طول خواهد کشید. پس از اتمام استقرار، یک علامت سبز در کنار هر جزء مشاهده خواهید کرد. همچنین می‌توانید با کلیک بر روی دکمه «پیوند به گزارش‌ها» که گزارش‌های ساخت ابری را باز می‌کند، وضعیت استقرار را بررسی کنید. ممکن است نمایش این دکمه چند دقیقه طول بکشد.

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

15. شما می‌توانید گزارش‌های ساخت ابری را مشاهده کنید تا وضعیت استقرار یا هرگونه خطایی که ممکن است هنگام استقرار برنامه رخ دهد را مشاهده کنید. همچنین می‌توانید با جستجوی Cloud Build در کنسول Google Cloud و کلیک بر روی History ، مستقیماً به گزارش‌های ساخت ابری بروید. استقرار برنامه حدود ۵ تا ۸ دقیقه طول خواهد کشید.

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

16. پس از اتمام استقرار، یک علامت سبز در کنار فیلد وضعیت استقرار مشاهده خواهید کرد.

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

۷. برنامه را تأیید کنید

بیایید بررسی کنیم که آیا عامل فعال است یا خیر. در بخش خروجی‌های صفحه جزئیات استقرار، آدرس اینترنتی (URL) کامپوننت frontend را مشاهده خواهید کرد. آن آدرس اینترنتی را کپی کرده و در مرورگر خود جایگذاری کنید. مطمئن شوید که از http استفاده می‌کنید و نه https . همچنین هرگونه هشداری را که ممکن است در مرورگر دریافت کنید، زیرا frontend از http استفاده می‌کند، بپذیرید.

با برنامه چت کنید و از آن بخواهید که یک برنامه سفر به لندن ایجاد کند.

۸. هاب برنامه و نظارت بر برنامه

1. در کنسول ADC، روی دکمه‌ی «مشاهده‌ی برنامه در App Hub» در گوشه‌ی بالا سمت راست صفحه کلیک کنید.

2. این کار برنامه را در App Hub باز می‌کند. App Hub یک مکان مرکزی برای مشاهده و مدیریت تمام برنامه‌های شماست و شما را از دیدگاه منبع محور به دیدگاه برنامه محور منتقل می‌کند. ایجاد یک برنامه با استفاده از ADC به طور خودکار یک برنامه را در App Hub ایجاد می‌کند. شما باید تمام حجم کار و سرویس‌هایی را که برنامه را تشکیل می‌دهند، در اینجا مشاهده کنید. به جای مشاهده منابع موجود در ابر به عنوان منابع جداگانه، می‌توانید آنها را به عنوان بخشی از یک برنامه واحد مشاهده کنید که مدیریت و نظارت را ساده می‌کند.

3. روی دکمه‌ی «مشاهده در مشاهده‌پذیری» کلیک کنید. این کار باید برنامه را در کنسول مشاهده‌پذیری باز کند.
4. نمای داشبورد را باز کنید. داشبورد با ارائه معیارهایی مانند 4 سیگنال طلایی: نرخ درخواست، نرخ خطا، تأخیر و اشباع، نمای کلی از عملکرد و سلامت برنامه را به شما ارائه می‌دهد. این نظارت متمرکز بر برنامه برای حفظ قابلیت اطمینان بسیار مهم است. همچنین می‌توانید گزارش‌ها و ردیابی‌های برنامه را مشاهده کنید که به شما امکان می‌دهد سیگنال‌ها را با هم مرتبط کرده و گلوگاه‌ها را مشخص کنید. این امر به ویژه در یک برنامه پیچیده عامل‌محور مانند این مهم است، جایی که پاسخ‌های کند از Vertex AI یا سرور Data MCP می‌تواند تجربه کاربر را خراب کند.

5. کاوش هدایت‌شده : از عامل یک سؤال خاص در برنامه بپرسید (مثلاً "بهترین مکان‌ها برای بازدید در لندن کدامند؟"). سپس، به کنسول Observability برگردید و لیست Traces را مشاهده کنید. trace مربوط به درخواست خود را پیدا کنید. برای مشاهده نمای آبشاری دقیق، روی آن کلیک کنید. توجه کنید که چگونه می‌توانید زمان صرف شده در frontend، backend عامل و تماس‌ها با Vertex AI را مشاهده کنید. این به شما امکان می‌دهد دقیقاً مشخص کنید که تأخیر در کجا ایجاد می‌شود.

۹. تبریک

تبریک! شما یک معماری برنامه سه لایه را با استفاده از ADC مستقر کرده‌اید.

آنچه آموخته‌اید

• چگونه با استفاده از ADC یک معماری ابری را به صورت بصری مونتاژ کنیم.
• نحوه تنظیم ADC و فعال کردن APIها از طریق رابط کاربری.
• نحوه استقرار برنامه‌ها با استفاده از ADC
• نحوه استفاده از App Hub برای مشاهده منابع خود با محوریت برنامه.
• نحوه نظارت بر سلامت برنامه با استفاده از داشبورد مشاهده‌پذیری.

اسناد مرجع

• مستندات ADC
• مستندات مرکز برنامه
• نظارت بر برنامه