Полное руководство по Cloud Run: от нуля до демонстрации в производственной среде.

1. Введение

Этот практический урок познакомит вас с основами работы с Cloud Run. Вы узнаете, как использовать дополнительные функции, включая доступ к VPC, Secret Manager и ADK для агентов ИИ, размещенных на Cloud Run.

Что вы узнаете

  • Разверните образ nginx
  • Развертывайте из исходного кода.
  • Откат развертывания
  • Предварительный просмотр развертывания
  • Используйте инструмент сервера знаний разработчика MCP.
  • Используйте менеджер секретов с Cloud Run.
  • Подключитесь к внутренней службе Cloud Run в VPC.
  • Разверните агент ADK в Cloud Run.

Что вам понадобится

  • Веб-браузер, например Chrome.
  • Проект Google Cloud с включенной функцией выставления счетов.

Создайте проект в Google Cloud.

  1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
  2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.

  1. В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» .
  2. После подключения к Cloud Shell подтвердите свою аутентификацию: 
    gcloud auth list
  3. Убедитесь, что ваш проект настроен: 
    gcloud config get project
  4. Если параметры вашего проекта заданы не так, как ожидалось, настройте их следующим образом: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Установка переменных среды

В этом практическом задании используется следующая переменная среды.

Сначала укажите свой регион.

export REGION=<YOUR_REGION>

Далее подтвердите свой PROJECT_ID и REGION.

echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"

2. Развертывание из образа

В этом разделе вы развернете стандартный образ nginx непосредственно из Docker Hub. Вы настроите его для публичного доступа и установите порт контейнера на 80.

  1. Разверните службу nginx: 
   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION
  1. После завершения развертывания в выводе команды будет указан URL-адрес сервиса. Откройте этот URL-адрес в браузере, чтобы увидеть страницу «Добро пожаловать в nginx!».

3. Развертывание из исходного кода 

mkdir color-app && cd $_

Создайте файл с именем requirements.txt со следующим содержимым:

Flask>=2.0.0
gunicorn>=20.0.0

Создайте файл с именем main.py со следующим содержимым:

import os
from flask import Flask, render_template_string

app = Flask(__name__)

TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
    <title>Cloud Run Traffic Revisions</title>
    <style>
        body {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 50vh;
            background-color: darkseagreen;
            font-family: sans-serif;
        }
        .content {
            background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
            padding: 2em;
            border-radius: 8px;
            text-align: center;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="content">
	  <!-- ROLLBACK DEMO: change this text to "gray" -->
        <p>background color: <strong>darkseagreen</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    
    return render_template_string(TEMPLATE)

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(debug=True, host='0.0.0.0', port=port)

Теперь выполните следующую команду. 

gcloud run deploy \
 --allow-unauthenticated
 --region $REGION

4. Ссылки для отката и предварительного просмотра

В этом разделе вы обнаружите ошибку и узнаете, как откатиться к предыдущей версии, пока будете искать способ её исправить.

  1. Сначала вам нужно записать название той версии, которая в данный момент обрабатывает трафик, поскольку в ней ошибка отсутствует. 
GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')
  1. В файле main.py приложения color-app найдите строку "ROLLBACK DEMO" и измените её на следующую: 
<p>background color: <strong>gray</strong></p>
  1. Теперь повторно запустите gcloud run deploy . Обратите внимание, как были использованы ваши предыдущие конфигурации.

Теперь, когда вы обнаружили ошибку, вы можете вернуться к исходному коду, внести изменения или выполнить команду `git revert`, а затем выполнить сборку, запустить новую сборку и т. д. Однако существует вероятность, что в процессе вы можете допустить ошибку.

Более безопасный способ — это откат изменений.

  1. Чтобы вернуться к предыдущей версии, выполните следующую команду: 
gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Теперь вы можете развернуть новую версию, которая не будет получать никакого трафика.

  1. Теперь исправьте ошибку, вернув текст обратно на darkseagreen 
<p>background color: <strong>darkseagreen</strong></p>
  1. И разверните его, чтобы проверить исправление. Обратите внимание, что он не будет получать никакого трафика, поскольку 100% трафика привязано к GOOD_REVISION. 
gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION
  1. Проверьте развертывание.

Вы заметите, что URL-адрес немного отличается. Перейдя по нему, вы увидите исправление ошибки в этом развертывании.

  1. Перенаправить трафик на последнюю версию.

Теперь вам нужно будет вернуть трафик к последней версии. 

gcloud run services update-traffic color-app \
  --to-latest \
  --region=$REGION

и удалите тег ревизии. 

gcloud run services update-traffic color-app \
  --remove-tags=bugfix \
  --region=$REGION

Более подробную информацию об откатах можно найти в документации .

5. Сервер MCP для разработчиков знаний

Сервер Knowledge MCP для разработчиков предоставляет инструментам разработки на основе ИИ возможность поиска в официальной документации Google для разработчиков и получения информации о продуктах Google, таких как Firebase, Google Cloud, Android, Maps и других. Подключая ваше ИИ-приложение напрямую к нашей официальной библиотеке документации, вы гарантируете, что получаемый код и рекомендации будут актуальными и основанными на авторитетном контексте.

Для предоставления вашему ИИ-агенту доступа к серверу Developer Knowledge MCP вам потребуется следовать инструкциям по установке .

После установки вы можете задавать своему ИИ-агенту вопросы о последних функциях, описанных в документации, которые могли стать доступны после окончания срока обучения вашей модели.

Например, если вы посмотрите примечания к выпуску Cloud Run , то увидите запись от 24 февраля 2026 года о том, как "Развернуть высокодоступную многорегиональную службу Cloud Run с автоматическим переключением на резервный сервер и восстановлением работоспособности для внешнего трафика, используя функцию проверки работоспособности службы Cloud Run (предварительная версия)".

Теперь вы можете попросить своего ИИ-агента: «Расскажите мне подробнее о новой функции Cloud Run для автоматического переключения при сбоях в нескольких регионах».

6. Использование Secret Manager

В Cloud Run существует 3 способа раскрыть секреты:

  1. В качестве переменной окружения (фиксируется версией, загруженной во время развертывания).
  2. Смонтирован как файловый том (постоянно обновляется до последней версии).
  3. Используйте клиентские библиотеки Secret Manager в своем коде.

В этом разделе вы предоставите доступ к секретному ключу в качестве переменной среды, используя выделенную учетную запись службы.

  1. Создайте новый секрет с именем 'my-secret': 
gcloud secrets create my-secret --replication-policy="automatic"
  1. Добавьте секретное значение в качестве новой версии: 
echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-
  1. Создайте отдельный сервисный аккаунт для приложения color-app: 
gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"
  1. Предоставьте выделенной служебной учетной записи доступ к секрету.
   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"
  1. Повторите развертывание. Теперь у сервиса будет доступ к переменной среды MY_SECRET: 
gcloud run deploy color-app \
     --source . \
     --update-secrets=MY_SECRET=my-secret:latest \
     --service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --region=$REGION

7. Подключитесь к VPC

В этом разделе вы настроите следующую архитектуру:

  • закрытая серверная часть, недоступная из общедоступного интернета
  • публичный интерфейс, взаимодействующий с бэкэндом через прямой исходящий трафик VPC.

В этом примере будет использоваться сеть и подсеть по умолчанию.

Предварительное условие: Убедитесь, что в вашей подсети включен частный доступ Google, чтобы VPC мог направлять внутренние запросы к сервисам Cloud Run. 

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access
  1. Создайте папку для этого раздела. 
mkdir ../vpc-demo
cd ../vpc-demo
  1. создать частный бэкэнд-сервис 
mkdir backend
touch backend/app.js
touch backend/package.json

В файл backend/app.js добавьте следующее: 

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from the Private Backend!');
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Private backend listening on port ${port}`);
});

В файл backend/package.json добавьте следующее: 

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Разверните приватный бэкэнд с внутренним доступом: 
   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated
  1. Запишите URL-адрес бэкэнда. Позже вы предоставите этот URL-адрес фронтенд-приложению. 
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"
  1. Создайте фронтенд-приложение. 
mkdir frontend
touch frontend/app.js
touch frontend/package.json

В файл frontend/app.js добавьте следующее: 

const http = require('http');

const server = http.createServer(async (req, res) => {
  const backendUrl = process.env.BACKEND_URL;
  
  if (!backendUrl) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    return res.end('Error: BACKEND_URL environment variable is missing.');
  }

  try {
    // Fetch the OIDC token from the Metadata server
    const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
      headers: { 'Metadata-Flavor': 'Google' }
    });

    if (!tokenResponse.ok) {
      throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
    }
    const token = await tokenResponse.text();

    // Ping the backend with the token
    const response = await fetch(backendUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const text = await response.text();

    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Public frontend listening on port ${port}`);
});
  1. В файл frontend/package.json добавьте следующее: 
{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}
  1. Создайте отдельный сервисный аккаунт для фронтенд-сервиса: 
  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"
  1. Предоставьте ему роль Cloud Run Invoker. 
PROJECT_ID=$(gcloud config get project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/run.invoker"
  1. Теперь развернем публичный интерфейс, используя Direct VPC Egress. Мы устанавливаем параметр '–vpc-egress=all-traffic', чтобы принудительно направлять исходящий запрос в VPC: 
   gcloud run deploy public-frontend \
     --source ./frontend \
     --region $REGION \
     --allow-unauthenticated \
     --network default \
     --subnet default \
     --vpc-egress all-traffic \
    --service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --set-env-vars BACKEND_URL=$BACKEND_URL
  1. Проверьте услуги.
  • Протестируйте фронтенд: выполните команду curl для получения общедоступного URL-адреса фронтенда. Должен быть успешный обмен данными с бэкендом и возврат ответа. 
     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL
  • Проверка бэкэнда (прямая): Попробуйте выполнить команду curl для доступа к URL-адресу бэкэнда напрямую с вашего локального компьютера (через общедоступный интернет). Должна возникнуть ошибка 404, поскольку входящий трафик ограничен «внутренним» доступом и требуется аутентификация. 
  curl $BACKEND_URL

8. Разверните агент ADK.

В этом разделе вы узнаете, как Python buildpack поддерживает определение точки входа по умолчанию для Agent Development Kit (ADK).

Вам необходимо создать следующую структуру папок: 

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt
  1. Создайте структуру папок. 
mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt
  1. Добавьте следующее содержимое в файл my_agent/__init.py__ : 
from . import agent
  1. Добавьте следующее содержимое в файл my_agent/agent.py : 
from google.adk import Agent

root_agent = Agent(
    name="demo_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful assistant for a Cloud Run demo."
)
  1. Добавьте следующее содержимое в файл requirements.txt : 
google-adk
  1. Создайте для агента выделенную учетную запись службы: 
  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"
  1. Предоставьте учетной записи службы роль пользователя Vertex AI: 
PROJECT_ID=$(gcloud config get-value project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"
  1. Разверните агент ADK.

Развертывание необходимо выполнить в регионе, где доступен API Gemini. В данном примере это регион us-west1 . 

gcloud run deploy my-adk-agent-demo \
   --source . \
   --region us-west1 \
   --allow-unauthenticated \
   --service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
   --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
  1. Сверните конечную точку

Вы можете убедиться, что агент мгновенно доступен в виде готового к использованию API.

Запишите URL-адрес службы Cloud Run в переменную окружения. 

AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
  --region us-west1 \
  --format 'value(status.url)')

Создайте сессию с агентом. 

curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

Спросите, что такое Cloud Run, и отфильтруйте ответ, чтобы отображалось только то, что говорит агент. 

curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
   \"appName\": \"my_agent\",
   \"userId\": \"u_123\",
   \"sessionId\": \"s_123\",
   \"newMessage\": { 
        \"role\": \"user\", 
        \"parts\": [{ \"text\": \"What is Cloud Run?\" 
    }]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"

И вы должны увидеть что-то подобное следующему: 

Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...

9. Уборка

Чтобы избежать постоянных списаний средств с вашего аккаунта Google Cloud, вы можете либо удалить весь проект (показано ниже), либо удалить отдельные ресурсы, созданные в ходе этого практического занятия.

Удалите сервисы nginx, color-app, private-backend и public-frontend. 

gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet

Удалите агент ADK (примечание: в этом примере он развернут в регионе us-west1). 

gcloud run services delete my-adk-agent-demo --region us-west1 --quiet

Удалите секрет, хранящийся в Secret Manager: 

gcloud secrets delete my-secret --quiet

Удалите учетную запись службы приложения Color. 

gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Удалите учетную запись службы агента ADK. 

gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

(Необязательно) Удалить проект

Если вы создали новый проект специально для этого практического занятия, вы можете удалить весь проект целиком, чтобы все ресурсы были удалены одновременно: 

# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID

10. Поздравляем!

Вы завершили практическое занятие. Вы ознакомились с основами работы с Cloud Run.

Что вы узнали

  • Разверните образ nginx
  • Развертывайте из исходного кода.
  • Откат развертывания
  • Предварительный просмотр развертывания
  • Используйте инструмент сервера знаний разработчика MCP.
  • Используйте менеджер секретов с Cloud Run.
  • Подключитесь к внутренней службе Cloud Run в VPC.
  • Разверните агент ADK в Cloud Run.