Kompletny przewodnik po Cloud Run: od zera do środowiska produkcyjnego – demonstracja

1. Wprowadzenie

To ćwiczenie przedstawia podstawowe informacje o tym, jak zacząć korzystać z Cloud Run. Dowiesz się, jak korzystać z dodatkowych funkcji, w tym dostępu do VPC, usługi Secret Manager i pakietu ADK dla agentów AI hostowanych w Cloud Run.

Czego się nauczysz

Wdrażanie obrazu nginx
Wdrażanie z kodu źródłowego
Wycofywanie wdrożenia
Wyświetlanie podglądu wdrożenia
Korzystanie z narzędzia serwera MCP Developer Knowledge
Używanie usługi Secret Manager z Cloud Run
Łączenie się z wewnętrzną usługą Cloud Run w sieci VPC
Wdrażanie agenta ADK w Cloud Run

Czego potrzebujesz

przeglądarka, np. Chrome;
projekt Google Cloud z włączonymi płatnościami;

Tworzenie projektu Google Cloud

W konsoli Google Cloud na stronie selektora projektu wybierz lub utwórz projekt w chmurze Google.
Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie są włączone płatności.

Uruchamianie Cloud Shell

Cloud Shell to środowisko wiersza poleceń działające w Google Cloud, które zawiera niezbędne narzędzia.

Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud.
Po połączeniu z Cloud Shell sprawdź uwierzytelnianie:
```
gcloud auth list
```
Sprawdź, czy projekt jest skonfigurowany:
```
gcloud config get project
```

Jeśli projekt nie jest ustawiony zgodnie z oczekiwaniami, ustaw go:

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

Ustawianie zmiennych środowiskowych

W tym ćwiczeniu z programowania używamy tej zmiennej środowiskowej.

Najpierw ustaw region.

export REGION=<YOUR_REGION>

Następnie potwierdź PROJECT_ID i REGION.

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

2. Wdrażanie z obrazu

W tej sekcji wdrożysz standardowy obraz nginx bezpośrednio z Docker Hub. Skonfigurujesz go tak, aby był dostępny publicznie, a port kontenera ustawisz na 80.

Wdróż usługę nginx:

   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION

Po zakończeniu wdrażania w wyniku polecenia pojawi się adres URL usługi. Otwórz ten adres URL w przeglądarce, aby wyświetlić stronę „Welcome to nginx!”.

3. Wdrażanie ze źródła

mkdir color-app && cd $_

Utwórz plik o nazwie requirements.txt z tą zawartością:

Flask>=2.0.0
gunicorn>=20.0.0

Utwórz plik o nazwie main.py z tą zawartością:

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)

Teraz uruchom to polecenie.

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

4. Wycofywanie zmian i linki do podglądu

W tej sekcji wprowadzisz błąd i dowiesz się, jak wycofać zmiany do poprzedniej wersji podczas sprawdzania poprawki.

Najpierw zapisz nazwę wersji, która obecnie obsługuje ruch, ponieważ nie zawiera ona błędu.

GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')

W pliku main.py aplikacji color-app wyszukaj ciąg znaków „ROLLBACK DEMO” i zmień ten wiersz na:

<p>background color: <strong>gray</strong></p>

Teraz ponownie uruchom gcloud run deploy. Sprawdź, jak były używane poprzednie konfiguracje.

Po wdrożeniu błędu możesz wrócić do źródła, wprowadzić zmianę lub cofnąć zmiany w git, a następnie skompilować projekt, wywołać nową kompilację itp. Jednak po drodze możesz popełnić błąd.

Bezpieczniejszym sposobem jest wycofanie zmian.

Aby wycofać zmiany do poprzedniej wersji, uruchom to polecenie:

gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Teraz możesz wdrożyć nową wersję, która nie będzie otrzymywać ruchu.

Teraz napraw błąd, zmieniając tekst z powrotem na darkseagreen

<p>background color: <strong>darkseagreen</strong></p>

i wdrożyć go, aby zweryfikować poprawkę. Pamiętaj, że nie będzie ona otrzymywać żadnego ruchu, ponieważ 100% ruchu jest przypisane do wersji GOOD_REVISION.

gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION

Sprawdzanie wdrożenia

Zauważysz, że adres URL jest nieco inny. Gdy ją otworzysz, zobaczysz poprawkę błędu w tym wdrożeniu.

Przekieruj ruch z powrotem do najnowszej wersji.

Teraz przywrócisz ruch do najnowszej wersji.

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

i usuń tag wersji.

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

Więcej informacji o operacjach przywracania znajdziesz w dokumentacji.

5. Serwer MCP w Developer Knowledge

Serwer MCP z wiedzą dla deweloperów umożliwia narzędziom deweloperskim opartym na AI wyszukiwanie oficjalnej dokumentacji Google dla deweloperów i pobieranie informacji o usługach Google, takich jak Firebase, Google Cloud, Android, Mapy i inne. Dzięki połączeniu aplikacji AI bezpośrednio z naszą oficjalną biblioteką dokumentacji otrzymywany kod i wskazówki są aktualne i oparte na wiarygodnym kontekście.

Postępuj zgodnie z instrukcjami instalacji, aby przyznać agentowi AI dostęp do serwera MCP z wiedzą dla deweloperów.

Po zainstalowaniu możesz zadawać agentowi AI pytania o najnowsze funkcje w dokumentacji, które mogły stać się dostępne po dacie zakończenia trenowania modelu.

Jeśli na przykład zajrzysz do informacji o wersji Cloud Run, zobaczysz, że 24 lutego 2026 roku pojawił się wpis „Wdrażanie wysoce dostępnej usługi Cloud Run w wielu regionach z automatycznym przełączaniem awaryjnym i powrotem po awarii w przypadku ruchu zewnętrznego za pomocą stanu usługi Cloud Run (wersja zapoznawcza)”.

Możesz teraz zapytać agenta AI: „Powiedz mi więcej o tej nowej funkcji Cloud Run do automatycznego przełączania awaryjnego w wielu regionach”.

6. Korzystanie z usługi Secret Manager

Obiekty tajne w Cloud Run możesz udostępniać na 3 sposoby:

Jako zmienna środowiskowa (zablokowana w wersji pobranej w momencie wdrażania).
Podłączone jako wolumin pliku (stale aktualizowany do najnowszej wersji).
Korzystanie w kodzie z bibliotek klienta usługi Secret Manager.

W tej sekcji wyświetlisz obiekt tajny jako zmienną środowiskową za pomocą dedykowanego konta usługi.

Utwórz nowy obiekt tajny o nazwie „my-secret”:

gcloud secrets create my-secret --replication-policy="automatic"

Dodaj wartość obiektu tajnego jako nową wersję:

echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-

Utwórz dedykowane konto usługi dla aplikacji do kolorowania:

gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"

Przyznaj dedykowanemu kontu usługi dostęp do obiektu tajnego.

   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

Wdróż ponownie. Teraz usługa będzie mieć dostęp do zmiennej środowiskowej 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. Połącz z VPC

W tej sekcji skonfigurujesz tę architekturę:

prywatny backend, który nie jest dostępny z publicznego internetu;
publiczny interfejs, który komunikuje się z backendem za pomocą bezpośredniego ruchu wychodzącego VPC;

W tym przykładzie użyjemy sieci i podsieci domyślnej.

Wymaganie wstępne: upewnij się, że w podsieci włączony jest prywatny dostęp do Google, aby VPC mogło kierować wewnętrzne żądania do usług Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access

Utwórz folder dla tej sekcji

mkdir ../vpc-demo
cd ../vpc-demo

utworzyć prywatną usługę backendu,

mkdir backend
touch backend/app.js
touch backend/package.json

W pliku backend/app.js dodaj te informacje:

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}`);
});

W pliku backend/package.json dodaj te informacje:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

Wdróż prywatny backend z ruchem przychodzącym tylko do użytku wewnętrznego:

   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated

Zapisz adres URL backendu. Ten adres URL podasz później w aplikacji frontendowej.

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"

Tworzenie aplikacji frontendowej

mkdir frontend
touch frontend/app.js
touch frontend/package.json

W pliku frontend/app.js dodaj te informacje:

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}`);
});

W pliku frontend/package.json dodaj te informacje:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

Utwórz dedykowane konto usługi dla usługi frontendu:

  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"

przyznaj mu rolę Wywołujący Cloud Run.

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"

Teraz wdróż publiczny frontend za pomocą bezpośredniej sieci VPC w ruchu wychodzącym. Ustawiamy „–vpc-egress=all-traffic”, aby wymusić przekierowanie żądania wychodzącego do sieci 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

Weryfikowanie usług

Testowanie interfejsu: wyślij żądanie curl do publicznego adresu URL interfejsu. Powinien on komunikować się z backendem i zwracać odpowiedź.

     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL

Testowanie backendu (bezpośrednie): spróbuj bezpośrednio wywołać adres URL backendu z komputera lokalnego (publiczny internet). Powinien zwrócić błąd 404, ponieważ dostęp do usługi jest ograniczony do „wewnętrznego” i wymaga uwierzytelniania.

  curl $BACKEND_URL

8. Wdrażanie agenta ADK

W tej sekcji dowiesz się, jak pakiet kompilacyjny Pythona obsługuje domyślne wykrywanie punktu wejścia w przypadku pakietu Agent Development Kit (ADK).

Utworzysz tę strukturę folderów:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt

Tworzenie struktury folderów

mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt

Dodaj do pliku my_agent/__init.py__ te wiersze:

from . import agent

Dodaj do pliku my_agent/agent.py te wiersze:

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."
)

Dodaj do pliku requirements.txt te wiersze:

google-adk

Utwórz dedykowane konto usługi dla agenta:

  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"

Przypisz do konta usługi rolę użytkownika 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"

Wdrażanie agenta ADK

Musisz wdrożyć model w regionie, w którym dostępny jest interfejs Gemini API. W tym przykładzie jest to 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"

Zawiń punkt końcowy

Możesz zobaczyć, jak agent jest natychmiast dostępny jako interfejs API gotowy do wdrożenia w wersji produkcyjnej.

Zapisz adres URL usługi Cloud Run w zmiennej środowiskowej.

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

Utwórz sesję z agentem

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

Zapytaj, czym jest Cloud Run, i odfiltruj odpowiedź, aby wyświetlać tylko to, co mówi agent.

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'])"

Powinien pojawić się ekran podobny do tego:

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. Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud bieżącymi opłatami, możesz usunąć cały projekt (jak pokazano poniżej) lub poszczególne zasoby utworzone w ramach tego laboratorium.

Usuń usługi nginx, color-app, private-backend i 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

Usuń agenta ADK (uwaga: w tym przykładzie jest on wdrożony w regionie us-west1).

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

Usuń klucz tajny przechowywany w usłudze Secret Manager:

gcloud secrets delete my-secret --quiet

Usuwanie konta usługi aplikacji Color

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

Usuwanie konta usługi agenta ADK

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

(Opcjonalnie) Usuwanie projektu

Jeśli na potrzeby tego ćwiczenia z programowania został przez Ciebie utworzony nowy projekt, możesz go usunąć w całości, aby mieć pewność, że wszystkie zasoby zostaną usunięte naraz:

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

10. Gratulacje!

To już koniec tego laboratorium. Poznaliśmy podstawy korzystania z Cloud Run.

Czego się dowiedziałeś

Wdrażanie obrazu nginx
Wdrażanie z kodu źródłowego
Wycofywanie wdrożenia
Wyświetlanie podglądu wdrożenia
Korzystanie z narzędzia serwera MCP Developer Knowledge
Używanie usługi Secret Manager z Cloud Run
Łączenie się z wewnętrzną usługą Cloud Run w sieci VPC
Wdrażanie agenta ADK w Cloud Run