Tích hợp PSC SWP của Agent Engine (ADK)

1. Giới thiệu

Giao diện Private Service Connect là một tài nguyên cho phép mạng Đám mây riêng ảo (VPC) của nhà sản xuất bắt đầu kết nối với nhiều đích đến trong mạng VPC của người dùng. Mạng nhà sản xuất và mạng người tiêu dùng có thể nằm trong các dự án và tổ chức khác nhau.

Nếu một tệp đính kèm mạng chấp nhận kết nối từ một giao diện Kết nối dịch vụ riêng tư, thì Google Cloud sẽ phân bổ cho giao diện đó một địa chỉ IP từ mạng con của người dùng do tệp đính kèm mạng chỉ định. Các mạng lưới người tiêu dùng và nhà sản xuất được kết nối và có thể giao tiếp bằng cách sử dụng địa chỉ IP nội bộ.

Mối kết nối giữa một tệp đính kèm mạng và một giao diện Private Service Connect tương tự như mối kết nối giữa một điểm cuối Private Service Connect và một tệp đính kèm dịch vụ, nhưng có 2 điểm khác biệt chính:

• Tệp đính kèm mạng cho phép mạng nhà sản xuất bắt đầu kết nối với mạng người tiêu dùng (đầu ra của dịch vụ được quản lý), trong khi điểm cuối cho phép mạng người tiêu dùng bắt đầu kết nối với mạng nhà sản xuất (đầu vào của dịch vụ được quản lý).
• Kết nối giao diện Private Service Connect là kết nối bắc cầu. Điều này có nghĩa là mạng nhà sản xuất có thể giao tiếp với các mạng khác được kết nối với mạng người tiêu dùng.

Những điểm cần lưu ý về khả năng tiếp cận PSC-Interface của Vertex AI

• PSC-Interface có khả năng định tuyến lưu lượng truy cập đến VPC hoặc các đích đến tại chỗ mà mạng VPC đã tìm hiểu.
• Để giới hạn phạm vi tiếp cận từ tệp đính kèm mạng mà Agent Engine sử dụng đối với mạng VPC, việc triển khai các quy tắc tường lửa xuất là phương pháp hay nhất.
• Để giới hạn phạm vi lưu lượng truy cập xuất mạng bắt nguồn từ mạng con đính kèm mạng của Agent Engine, bạn nên triển khai một quy tắc tường lửa xuất VPC. Quy tắc này sẽ cho phép lưu lượng truy cập từ Agent Engine đến SWP một cách rõ ràng, đồng thời từ chối tất cả lưu lượng truy cập đi ra khác.

Những điểm cần lưu ý về VPC-SC của Vertex AI PSC-Interface

• Bạn phải cung cấp khả năng kết nối lưu lượng truy cập Internet đi ra trong VPC của khách hàng để Giao diện PSC của Agent Engine hoạt động, ngay cả khi bạn bật VPC Service Controls.

Secure Web Proxy

Secure Web Proxy là một dịch vụ được quản lý, dựa trên đám mây, giúp bạn kiểm soát và bảo mật lưu lượng truy cập đi (HTTP/HTTPS) một cách chi tiết. SWP đóng vai trò là một cổng trung tâm, cho phép bạn thực thi các chính sách bảo mật đối với các kết nối được bắt đầu từ Agent Engine được triển khai bằng Giao diện PSC đến các tài nguyên VPC, chẳng hạn như máy ảo, GKE, Internet và môi trường nhiều đám mây.

Vấn đề được giải quyết

• Ngăn chặn hành vi đánh cắp dữ liệu: Chặn hoạt động tải lên trái phép hoặc liên lạc với các trang web độc hại.
• Thực thi việc tuân thủ: Đảm bảo lưu lượng truy cập đi tuân thủ các chính sách bảo mật và xử lý dữ liệu của tổ chức bạn.
• Giảm chi phí vận hành: Là một dịch vụ được quản lý toàn diện, Secure Web Proxy giúp bạn không cần triển khai, mở rộng quy mô hoặc duy trì các máy ảo proxy của riêng mình.
• Cung cấp khả năng hiển thị sâu: Cho phép kiểm tra lưu lượng truy cập được mã hoá bằng Bảo mật tầng truyền tải (TLS) để phát hiện các mối đe doạ ẩn.

Để biết thêm thông tin, hãy tham khảo các tài nguyên sau:

Triển khai một tác nhân | AI tạo sinh trên Vertex AI | Google Cloud

Thiết lập giao diện Private Service Connect cho các tài nguyên Vertex AI | Google Cloud

Sản phẩm bạn sẽ tạo ra

Trong hướng dẫn này, bạn sẽ tạo một Agent Engine toàn diện được triển khai bằng Giao diện Private Service Connect (PSC) tích hợp với SWP để thực hiện những việc sau bằng cách sử dụng các thư viện ADK:

• Triển khai tính năng kết nối ngang hàng DNS trong Agent Engine để phân giải Tên miền đủ điều kiện của SWP được dùng trong cấu hình proxy.
• Cho phép kết nối đến một trang web công khai (https://api.frankfurter.app/) thông qua một Secure Web Proxy được triển khai trong VPC của người tiêu dùng bằng địa chỉ RFC1918.
• Cho phép lưu lượng truy cập từ Mạng con đính kèm mạng đến SWP trong khi từ chối mọi lưu lượng truy cập khác.

Hình 1

Lưu ý: Hướng dẫn này cung cấp các bước định cấu hình và xác thực dựa trên cấu trúc liên kết minh hoạ. Hãy sửa đổi quy trình nếu cần để đáp ứng các yêu cầu của tổ chức.

Kiến thức bạn sẽ học được

• Cách tạo thiết bị lưu trữ mạng
• Cách nhà sản xuất có thể sử dụng tệp đính kèm mạng để tạo giao diện PSC
• Cách thiết lập giao tiếp từ nhà sản xuất đến người tiêu dùng bằng cách sử dụng tính năng DNS Peering
• Cách triển khai và sử dụng SWP cho lưu lượng truy cập Internet
• Cách xác định các quy tắc về tường lửa xuất để giảm khả năng tiếp cận mạng của Agent Engine

Bạn cần có

Dự án trên Google Cloud

Quyền IAM

• Quản trị viên mạng máy tính (roles/compute.networkAdmin)
• Quản trị viên thực thể Compute (roles/compute.instanceAdmin)
• Quản trị viên bảo mật điện toán (roles/compute.securityAdmin)
• Quản trị viên DNS (roles/dns.admin)
• Người dùng đường hầm được bảo mật bằng IAP (roles/iap.tunnelResourceAccessor)
• Quản trị viên ghi nhật ký (roles/logging.admin)
• Quản trị viên Notebook (roles/notebooks.admin)
• Quản trị viên IAM dự án (roles/resourcemanager.projectIamAdmin)
• Quản trị viên tài khoản dịch vụ (roles/iam.serviceAccountAdmin)
• Quản trị viên sử dụng dịch vụ (roles/serviceusage.serviceUsageAdmin)

2. Trước khi bắt đầu

Cập nhật dự án để hỗ trợ hướng dẫn

Hướng dẫn này sử dụng $variables để hỗ trợ việc triển khai cấu hình gcloud trong Cloud Shell.

Trong Cloud Shell, hãy thực hiện các bước sau:

gcloud config set project [YOUR-PROJECT-NAME]
projectid=YOUR-PROJECT-NAME
echo $projectid

Bật API

Trong Cloud Shell, hãy thực hiện các bước sau:

gcloud services enable "compute.googleapis.com"
gcloud services enable "aiplatform.googleapis.com"
gcloud services enable "dns.googleapis.com"
gcloud services enable "notebooks.googleapis.com"
gcloud services enable "storage.googleapis.com"
gcloud services enable "iap.googleapis.com"
gcloud services enable "networksecurity.googleapis.com"
gcloud services enable "networkservices.googleapis.com"
gcloud services enable "cloudresourcemanager.googleapis.com"

Xác minh rằng bạn đã bật các API thành công

gcloud services list --enabled

3. Thiết lập người tiêu dùng

Tạo VPC người tiêu dùng

VPC này nằm trong một dự án của khách hàng. Các tài nguyên sau đây sẽ được tạo trong VPC này

• Mạng con dành cho người tiêu dùng
• Mạng con đính kèm mạng
• Chỉ mạng con proxy
• Quy tắc tường lửa
• Cloud DNS

Trong Cloud Shell, hãy thực hiện các bước sau:

gcloud compute networks create consumer-vpc --project=$projectid --subnet-mode=custom

Tạo mạng con của người tiêu dùng

Trong Cloud Shell, hãy tạo mạng con cho SWP:

gcloud compute networks subnets create swp-subnet --project=$projectid --range=10.10.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Tạo mạng con Đính kèm mạng Kết nối dịch vụ riêng tư

Trong Cloud Shell, hãy tạo mạng con cho PSC Network Attachment:

gcloud compute networks subnets create intf-subnet --project=$projectid --range=192.168.10.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

Tạo mạng con proxy theo khu vực

Trong Cloud Shell, hãy tạo mạng con chỉ dành cho proxy cần thiết cho các sản phẩm dựa trên Envoy như Secure Web Proxy và Trình cân bằng tải ứng dụng nội bộ/bên ngoài theo khu vực. Bạn phải đặt cờ –purpose thành REGIONAL_MANAGED_PROXY:

gcloud compute networks subnets create proxy-subnet \
  --purpose=REGIONAL_MANAGED_PROXY \
  --role=ACTIVE \
  --region=us-central1 \
  --network=consumer-vpc \
  --range=100.100.10.0/26

Tạo mạng con sổ ghi chú

Trong Cloud Shell, hãy tạo mạng con cho thực thể sổ tay:

gcloud compute networks subnets create notebook-subnet --project=$projectid --range=192.168.20.0/28 --network=consumer-vpc --region=us-central1 --enable-private-ip-google-access

4. Tạo Secure Web Proxy

Chế độ rõ ràng của Secure Web Proxy (hoặc Chế độ định tuyến proxy rõ ràng) là một phương thức triển khai mà các khối lượng công việc của máy khách phải được định cấu hình rõ ràng để sử dụng địa chỉ IP nội bộ hoặc Tên miền đủ điều kiện và cổng của SWP làm proxy chuyển tiếp.

Chính sách này sẽ chứa các quy tắc chi phối lưu lượng truy cập thông qua Secure web proxy dựa trên kết quả khớp phiên, host() == 'api.frankfurter.app' và kết quả khớp ứng dụng request.method == 'GET'

Trong các bước bên dưới, hãy nhớ sửa đổi YOUR-PROJECT-ID thành mã dự án của bạn

Trong Cloud Shell, hãy tạo một tệp policy.yaml:

cat > policy.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy 
description: "My basic SWP policy" 
EOF

Trong Cloud Shell, hãy nhập chính sách:

gcloud network-security gateway-security-policies import my-swp-policy \
    --source=policy.yaml \
    --location=us-central1

Tạo quy tắc Secure Web Proxy

Xác định các quy tắc trong chính sách để chỉ định lưu lượng truy cập được phép hoặc bị từ chối. Các quy tắc được đánh giá dựa trên mức độ ưu tiên.

Trong Cloud Shell, hãy tạo một tệp rule.yaml để cho phép truy cập vào điểm cuối internet mà công cụ tác nhân sử dụng, api.frankfurter.app:

cat > rule.yaml << EOF
name: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-example"
description: "Allow frankfurter API"
enabled: true
priority: 10
basicProfile: ALLOW
sessionMatcher: "host() == 'api.frankfurter.app'"
EOF

Lưu ý: Nếu bạn không bật tính năng kiểm tra TLS, thì trình so khớp ứng dụng request.method == 'GET' sẽ chỉ so khớp lưu lượng truy cập HTTP chứ không so khớp lưu lượng truy cập HTTPS

Trong Cloud Shell, hãy tạo quy tắc chính sách bảo mật:

gcloud network-security gateway-security-policies rules import allow-example \
    --source=rule.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

Tạo quy tắc Secure Web Proxy

Bạn phải tạo thực thể SWP được triển khai ở chế độ định tuyến rõ ràng để Agent Engine phải chỉ định địa chỉ IP hoặc FQDN của SWP trong cấu hình proxy ADK, như được xác định trong tệp YAML của cổng. Cấu hình này cũng liên kết thực thể với chính sách, mạng và mạng con tương ứng.

Trong Cloud Shell, hãy tạo một tệp gateway.yaml dùng để triển khai SWP.

Nhớ lưu tệp YAML sau khi cập nhật các biến sau bằng thông tin chi tiết về môi trường của bạn: PROJECT_ID, REGION, NETWORK_NAME và PROXY_ONLY_SUBNET_NAME. Cổng 8888 được chỉ định là cổng đường hầm bên ngoài được liên kết với cấu hình proxy trong Agent Engine.

cat > gateway.yaml << EOF
name: "projects/$projectid/locations/us-central1/gateways/my-swp-instance"
type: SECURE_WEB_GATEWAY
ports: [8888]
addresses: ["10.10.10.5"]
gatewaySecurityPolicy: "projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy"
network: "projects/$projectid/global/networks/consumer-vpc"
subnetwork: "projects/$projectid/regions/us-central1/subnetworks/swp-subnet"
routingMode: EXPLICIT_ROUTING_MODE
EOF

Trong Cloud Shell, hãy nhập cổng:

gcloud network-services gateways import my-swp-instance \
    --source=gateway.yaml \
    --location=us-central1

5. Thiết bị mạng Private Service Connect

Tệp đính kèm mạng là tài nguyên theo khu vực, đại diện cho phía người dùng của một giao diện Private Service Connect. Bạn liên kết một mạng con duy nhất với một tệp đính kèm mạng và nhà sản xuất sẽ chỉ định IP cho giao diện Private Service Connect từ mạng con đó. Mạng con phải nằm trong cùng khu vực với thiết bị đính kèm mạng. Thiết bị đính kèm mạng phải ở cùng khu vực với dịch vụ nhà sản xuất.

Tạo tệp đính kèm mạng

Trong Cloud Shell, hãy tạo tệp đính kèm mạng.

gcloud compute network-attachments create psc-network-attachment \
    --region=us-central1 \
    --connection-preference=ACCEPT_AUTOMATIC \
    --subnets=intf-subnet

Liệt kê các tệp đính kèm mạng

Trong Cloud Shell, hãy liệt kê các tệp đính kèm mạng.

gcloud compute network-attachments list

Mô tả các tệp đính kèm mạng

Trong Cloud Shell, hãy mô tả network attachment.

gcloud compute network-attachments describe psc-network-attachment --region=us-central1

Ghi lại tên Tệp đính kèm mạng PSC, psc-network-attachment, mà nhà sản xuất sẽ sử dụng khi tạo Giao diện Private Service Connect.

Để xem URL của Network Attachment (Tệp đính kèm mạng) PSC trong Cloud Console, hãy chuyển đến:

Network Services → Private Service Connect → Network Attachment → psc-network-attachment

6. Vùng DNS riêng

Bạn sẽ tạo một Cloud DNS Zone cho demo.com và điền sẵn một bản ghi A trỏ đến địa chỉ IP của SWP. Sau đó, tính năng kết nối ngang DNS sẽ được triển khai trong Agent Engine, cho phép truy cập vào các bản ghi DNS của người dùng.

Trong Cloud Shell, hãy thực hiện các bước sau để tạo một bản minh hoạ tên DNS demo.com.

gcloud dns --project=$projectid managed-zones create private-dns-codelab --description="" --dns-name="demo.com." --visibility="private" --networks="https://compute.googleapis.com/compute/v1/projects/$projectid/global/networks/consumer-vpc"

Lấy và lưu trữ Địa chỉ IP của SWP được dùng cho bản ghi A của DNS.

Trong Cloud Shell, hãy thực hiện thao tác mô tả đối với swp, my-swp-instance:

gcloud network-services gateways describe my-swp-instance --location=us-central1

Trong Cloud Shell, hãy tạo bản ghi cho SWP, swp.demo.com, nhớ cập nhật địa chỉ IP dựa trên đầu ra của môi trường.

gcloud dns --project=$projectid record-sets create swp.demo.com. --zone="private-dns-codelab" --type="A" --ttl="300" --rrdatas="10.10.10.5"

Cấu hình tường lửa

Tạo một quy tắc Cloud Firewall để cho phép truy cập từ Giao diện PSC

Trong phần sau, hãy tạo một quy tắc tường lửa cho phép lưu lượng truy cập bắt nguồn từ quyền truy cập PSC Network Attachment vào mạng con SWP trong VPC của người dùng. Để tăng cường bảo mật, bạn có thể chỉ định Địa chỉ IP SWP làm đích đến duy nhất.

Trong Cloud Shell, hãy tạo quy tắc tường lửa xuất cho phép truy cập từ tệp đính kèm mạng vào SWP:

gcloud compute firewall-rules create allow-access-to-swp \
    --network=consumer-vpc \
    --action=ALLOW \
    --rules=ALL \
    --direction=EGRESS \
    --priority=1000 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="10.10.10.5/32" \
    --enable-logging

Trong Cloud Shell, hãy tạo quy tắc tường lửa xuất cảnh từ chối tất cả lưu lượng truy cập từ tệp đính kèm mạng:

gcloud compute firewall-rules create deny-all \
    --network=consumer-vpc \
    --action=DENY \
    --rules=ALL \
    --direction=EGRESS \
    --priority=65534 \
    --source-ranges="192.168.10.0/28" \
    --destination-ranges="0.0.0.0/0" \
    --enable-logging

7. Tạo Chính sách tường lửa cho Mạng VPC để đảm bảo Thông tin tình báo về mối đe doạ:

Trong phần sau, hãy tạo một chính sách tường lửa cho phép bạn tận dụng danh sách mối đe doạ do Google quản lý để chặn các trang web độc hại đã biết trước khi lưu lượng truy cập được SWP nhận.

Trong Cloud Shell, hãy tạo chính sách tường lửa chung:

gcloud compute network-firewall-policies create psc-secure-policy \
    --global \
    --description="Policy to protect VPC with Threat Intelligence"

Trong Cloud Shell, hãy liên kết Chính sách với VPC của bạn:

gcloud compute network-firewall-policies associations create \
    --firewall-policy=psc-secure-policy \
    --network=consumer-vpc \
    --name=psc-swp-association \
    --global-firewall-policy

Trong Cloud Shell, hãy thêm các Quy tắc thông tin tình báo về mối đe doạ:

Các quy tắc này sẽ loại bỏ lưu lượng truy cập đến từ những đối tượng xấu đã biết trước khi bắt đầu lưu lượng truy cập từ Agent. Trong ví dụ này, chúng tôi đã thêm các quy tắc để Chặn nút thoát Tor (Đầu ra) và Chặn các IP độc hại đã biết (Đầu ra), Chặn các proxy ẩn danh đã biết(Đầu ra), Chặn các công cụ khai thác tiền mã hoá để ngăn chặn việc sử dụng tài nguyên trái phép (Đầu ra),

gcloud compute network-firewall-policies rules create 100 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-tor-exit-nodes \
    --layer4-configs=all \
    --enable-logging \
    --description="Block anonymous Tor traffic" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 110 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-known-malicious-ips \
    --layer4-configs=all \
    --enable-logging \
    --description="Block known botnets and malware sources" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 120 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-anon-proxies \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Known Anonymous Proxies" \
    --global-firewall-policy

gcloud compute network-firewall-policies rules create 130 \
    --firewall-policy=psc-secure-policy \
    --action=deny \
    --direction=EGRESS \
    --dest-threat-intelligence=iplist-crypto-miners \
    --layer4-configs=all \
    --enable-logging \
    --description="Block Crypto Miners (Prevent unauthorized resource usage)" \
    --global-firewall-policy

8. Tạo sổ tay Jupyter

Phần sau đây sẽ hướng dẫn bạn cách tạo một Sổ tay Jupyter. Sổ tay này sẽ được dùng để triển khai Agent Engine nhắm đến một proxy rõ ràng cho Internet Egress.

Tạo tài khoản dịch vụ do người dùng quản lý

Trong phần sau, bạn sẽ tạo một tài khoản dịch vụ được liên kết với phiên bản Vertex AI Workbench dùng trong hướng dẫn này.

Trong hướng dẫn này, tài khoản dịch vụ sẽ có các vai trò sau:

• Quản trị viên Bộ nhớ
• Người dùng Vertex AI
• Quản trị viên Artifact Registry
• Người dùng tài khoản dịch vụ IAM

Trong Cloud Shell, hãy tạo tài khoản dịch vụ.

gcloud iam service-accounts create notebook-sa \
    --display-name="notebook-sa"

Trong Cloud Shell, hãy cập nhật tài khoản dịch vụ bằng vai trò Quản trị viên bộ nhớ.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/storage.admin"

Trong Cloud Shell, hãy cập nhật tài khoản dịch vụ bằng vai trò Người dùng Vertex AI.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/aiplatform.user"

Trong Cloud Shell, hãy cập nhật tài khoản dịch vụ bằng vai trò Quản trị viên Artifact Registry.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" --role="roles/artifactregistry.admin"

Trong Cloud Shell, hãy cho phép tài khoản dịch vụ sổ tay sử dụng tài khoản dịch vụ mặc định của Compute Engine.

gcloud iam service-accounts add-iam-policy-binding \
    $(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')[e-mail] \
    --member="serviceAccount:notebook-sa@$projectid.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountUser"

9. Tạo một phiên bản Vertex AI Workbench

Trong phần sau, hãy tạo một thực thể Vertex AI Workbench kết hợp tài khoản dịch vụ đã tạo trước đó, notebook-sa.

Tạo thực thể ứng dụng khách riêng tư trong Cloud Shell.

gcloud workbench instances create workbench-tutorial --vm-image-project=cloud-notebooks-managed --vm-image-family=workbench-instances --machine-type=n1-standard-4 --location=us-central1-a --subnet-region=us-central1 --subnet=notebook-subnet --disable-public-ip --shielded-secure-boot=true --shielded-integrity-monitoring=true --shielded-vtpm=true --service-account-email=notebook-sa@$projectid.iam.gserviceaccount.com     

Thêm một quy tắc khác vào Secure Web Proxy hiện có để chuyển tiếp lưu lượng truy cập từ thực thể sổ tay này:

Trong Cloud Shell, hãy tạo tệp rule-notebook.yaml bằng trình chỉnh sửa văn bản, nhớ cập nhật YAML bằng mã dự án của bạn

cat > rule-notebook.yaml << EOF
name: projects/$projectid/locations/us-central1/gatewaySecurityPolicies/my-swp-policy/rules/allow-notebook-subnet
description: Allow Internet access for notebook subnet
enabled: true
priority: 2
basicProfile: ALLOW
sessionMatcher: inIpRange(source.ip,'192.168.20.2')
EOF

Trong Cloud Shell, hãy tạo quy tắc chính sách bảo mật:

gcloud network-security gateway-security-policies rules import allow-notebook-subnet \
    --source=rule-notebook.yaml \
    --location=us-central1 \
    --gateway-security-policy=my-swp-policy

10. Cập nhật tác nhân dịch vụ Vertex AI

Vertex AI thay mặt bạn thực hiện các thao tác như lấy Địa chỉ IP từ mạng con PSC Network Attachment (Tệp đính kèm mạng PSC) dùng để tạo Giao diện PSC. Để làm như vậy, Vertex AI sử dụng một tác nhân dịch vụ (được liệt kê bên dưới) yêu cầu quyền Quản trị viên mạng:

service-$[e-mail]

Lưu ý: Trước khi cập nhật quyền của tác nhân dịch vụ, hãy chuyển đến Vertex AI trong bảng điều khiển Cloud để đảm bảo Vertex AI API đã được bật.

Trong Cloud Shell, hãy lấy số dự án của bạn.

gcloud projects describe $projectid | grep projectNumber

Trong Cloud Shell, hãy đặt số dự án của bạn.

projectnumber=YOUR-PROJECT-NUMBER

Trong Cloud Shell, hãy tạo một tài khoản dịch vụ cho Nền tảng Trí tuệ nhân tạo. Bỏ qua bước này nếu bạn đã có tài khoản dịch vụ trong dự án của mình.

gcloud beta services identity create --service=aiplatform.googleapis.com --project=$projectnumber

Trong Cloud Shell, hãy cập nhật tài khoản đơn vị hỗ trợ dịch vụ bằng vai trò compute.networkAdmin.

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$[e-mail]" --role="roles/compute.networkAdmin"

Trong Cloud Shell, hãy cập nhật tài khoản tác nhân dịch vụ bằng vai trò dns.peer

gcloud projects add-iam-policy-binding $projectid --member="serviceAccount:service-$[e-mail]" --role="roles/dns.peer"

Cập nhật tài khoản dịch vụ mặc định

Cấp cho tài khoản dịch vụ mặc định của bạn quyền truy cập vào Vertex AI. Xin lưu ý rằng có thể mất một thời gian để thay đổi về quyền truy cập có hiệu lực.

Trong Cloud Shell, hãy cập nhật tài khoản dịch vụ mặc định bằng vai trò aiplatform.user

gcloud projects add-iam-policy-binding $projectid \
  --member="serviceAccount:$[e-mail]" \
    --role="roles/aiplatform.user"

11. Triển khai Agent Engine

Lưu ý: Chúng ta sẽ sử dụng bảng điều khiển GCP và sổ tay JupyterLab để hoàn thành các tác vụ trong phần này

Trong phần sau, bạn sẽ tạo một sổ tay thực hiện các nhiệm vụ sau:

• Sử dụng Frankfurter API (https://api.frankfurter.app/) để lấy dữ liệu về tỷ giá hối đoái
• Tham chiếu đến một proxy rõ ràng (proxy_server) nhắm đến SWP trong vpc của người tiêu dùng bằng cách sử dụng FQDN swp.demo.com
• Xác định dnsPeeringConfigs "domain": "demo.com."

Chạy quy trình huấn luyện trong phiên bản Vertex AI Workbench.

• Trong bảng điều khiển Cloud, hãy chuyển đến Vertex AI → Workbench
• Bên cạnh tên phiên bản Vertex AI Workbench (workbench-tutorial), hãy nhấp vào Open JupyterLab (Mở JupyterLab). Phiên bản Vertex AI Workbench của bạn sẽ mở ra trong JupyterLab.
• Chọn File > New > Notebook
• Chọn Kernel > Python 3

Cài đặt các thư viện Python cần thiết: Cài đặt các thư viện cần thiết cho Agent Engine, bao gồm pyyaml, google-cloud-aiplatform, cloudpickle, google-cloud-api-keys và langchain-google-vertexai.

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy ô sau đây, chỉ định địa chỉ IP của SWP

!pip install --proxy http://10.10.10.5:8888 --upgrade google-cloud-aiplatform[agent_engines,adk]

Xác định các biến sau đây dựa trên môi trường của bạn trong đoạn mã sau:

• PROJECT_ID
• BUCKET_NAME
• AGENT_NAME

Trong phòng thí nghiệm này, bạn sẽ sử dụng các biến BUCKET_NAME và AGENT_NAME để khởi tạo và định cấu hình vùng lưu trữ có sẵn trên toàn cầu

Trong phần sau, PROXY_SERVER được xác định, ví dụ: swp.demo.com yêu cầu kết nối ngang hàng DNS để phân giải tên. Trong cấu hình, AGENT_PEER_DOMAIN được triển khai dưới dạng demo.com. tương ứng với vùng DNS riêng tư được tạo ở bước trước trong AGENT_PEER_NETWORK, consumer-vpc.

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau:

# --- Fundamental Project Configuration ---
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "us-central1" # e.g., "us-central1"
BUCKET_NAME = "YOUR_BUCKET_NAME" # A GCS bucket in the same location

# --- Agent Configuration ---
AGENT_NAME = "YOUR_AGENT_NAME"
MODEL = "gemini-2.5-flash" # Or another suitable model

# --- Network and Proxy Configuration ---
# The agent will call the Frankfurter API via this proxy
PROXY_SERVER = "http://swp.demo.com:8888"

# --- Deployment Configuration (PSC & DNS Peering) ---
# This should be a pre-existing Network Attachment
NETWORK_ATTACHMENT_NAME = f"projects/{PROJECT_ID}/regions/{LOCATION}/networkAttachments/psc-network-attachment"
# Optional DNS Peering config
AGENT_PEER_DOMAIN = "demo.com."
AGENT_PEER_NETWORK = "consumer-vpc"

# --- Initialize Vertex AI SDK ---
import vertexai
STAGING_BUCKET = f"gs://{BUCKET_NAME}"

vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

print(f"Vertex AI SDK initialized for project {PROJECT_ID} in {LOCATION}.")

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau.

!adk create $AGENT_NAME --model=$MODEL --project=$PROJECT_ID --region=$LOCATION

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy lệnh sau để tạo biến proxy tương ứng với FQDN và cổng của SWP.

import os
os.environ["PROXY_SERVER_URL"] = "http://swp.demo.com:8888"

Ô mã sau đây minh hoạ cấu hình tường minh của proxy cho Agent Engine để truy cập vào API điểm cuối internet api.frankfurter.app bằng cách chỉ định SWP, sử dụng PROXY_SERVER_TO_USE ánh xạ đến os.environ["PROXY_SERVER_URL"].

import requests
# Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
) 
response.raise_for_status() 
print(response.json()) 
except requests.exceptions.RequestException as e: print(f"An error occurred: {e}")

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau đây để xác định việc triển khai công cụ cho API nhắm mục tiêu trao đổi tiền tệ frankfurther.app.

%%writefile $AGENT_NAME/agent.py
from google.adk.agents.llm_agent import Agent
import os
import requests


# Get Proxy Server URL
# This is the VM's FQDN to reach the proxy vm in the consumers network
if "PROXY_SERVER_URL" not in os.environ:
    raise ValueError("Missing required environment variable: PROXY_SERVER_URL is not set.")
PROXY_SERVER_TO_USE = os.environ["PROXY_SERVER_URL"]

# Mock tool implementation
def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    # Use the globally defined proxy server URL
    proxies = {
       "http": PROXY_SERVER_TO_USE,
       "https": PROXY_SERVER_TO_USE,
    }
    
    try:
        response = requests.get(
            f"https://api.frankfurter.app/{currency_date}",
            params={"from": currency_from, "to": currency_to},
            proxies=proxies,
        )
        response.raise_for_status()  # Raise an error for bad responses
        return response.json()
    except Exception as e:
        return f"An unexpected error occurred: {e}"

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description="Provides the currency exchange rates between two currencies",
    instruction="You are a helpful assistant that provides the currency exchange rates between two currencies. Use the 'get_exchange_rate' tool for this purpose.",
    tools=[get_exchange_rate],
)

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau.

# 1. Set your variables
CURRENCY_DATE="latest"
CURRENCY_FROM="USD"
CURRENCY_TO="EUR"
PROXY_SERVER="http://swp.demo.com:8888"

# 2. Run the curl command
!curl -x "$PROXY_SERVER" "https://api.frankfurter.app/$CURRENCY_DATE?from=$CURRENCY_FROM&to=$CURRENCY_TO"

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy lệnh sau để gọi cấu hình giao diện psc mà Agent Engine dùng, ngoài việc kết nối DNS ngang hàng.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {
    "requirements": [
        "google-cloud-aiplatform[agent_engines,adk]",
        "requests",
    ],
    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau.

import json
import os

CONFIG_FILE_PATH = os.path.join(AGENT_NAME, ".agent_engine_config.json")
# Create your config as a Python dictionary ---
config_data = {

    "psc_interface_config": {
        "network_attachment": NETWORK_ATTACHMENT_NAME,
        "dns_peering_configs": [
            {
                "domain": AGENT_PEER_DOMAIN,
                "target_project": PROJECT_ID,
                "target_network": AGENT_PEER_NETWORK,
            },
        ],
    },
}

# Write the dictionary to a JSON file ---
os.makedirs(AGENT_NAME, exist_ok=True) # Ensure the directory exists
with open(CONFIG_FILE_PATH, 'w') as f:
    json.dump(config_data, f, indent=4)

print(f"Successfully created {CONFIG_FILE_PATH} with your variables.")

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau.

%%writefile $AGENT_NAME/.env

GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=1


PROXY_SERVER_URL=http://swp.demo.com:8888

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy đoạn mã sau để tạo Agent.

!adk deploy agent_engine $AGENT_NAME --staging_bucket=$STAGING_BUCKET --env_file=$AGENT_NAME/.env --agent_engine_config_file=$AGENT_NAME/.agent_engine_config.json --display_name=$AGENT_NAME

Mã công cụ suy luận sẽ được tạo khi bạn thực thi ô. Đối với bước tiếp theo, bạn sẽ cần mã nhận dạng đã tạo, đó là 3235268984265768960 trong ví dụ này.

✅ Created agent engine: projects/9315891080/locations/us-central1/reasoningEngines/3235268984265768960

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau, nhớ cập nhật bằng Số dự án và mã nhận dạng suy luận Agent Engine từ đầu ra trước đó:

from vertexai import agent_engines
remote_app = agent_engines.get("projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENTER_YOUR_ID")

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy nội dung sau.

def print_event_nicely_with_thoughts(event):
    """
    Parses and prints streaming query events, including thoughts.
    """
    try:
        content = event.get('content', {})
        role = content.get('role')
        parts = content.get('parts', [{}])

        if not parts:
            print("...")
            return

        part = parts[0] # Get the first part

        # Event 1: Model is thinking (calling a tool or just text)
        if role == 'model':

            # Check for and print any explicit 'thought' text
            if 'thought' in part:
                print(f"🧠 Thought: {part['thought']}")

            # Check for a function call
            if 'function_call' in part:
                # If we haven't *already* printed an explicit thought,
                # print a generic one.
                if 'thought' not in part:
                    print("🧠 Thinking... (decided to use a tool)")

                call = part['function_call']
                print(f"   🔧 Tool Call: {call.get('name')}()")
                print(f"      Args: {call.get('args')}")

            # Check for the final text answer
            elif 'text' in part:
                text = part.get('text', '')
                print(f"\n💬 Model: {text}")

        # Event 2: The tool returns its result
        elif role == 'user' and 'function_response' in part:
            resp = part['function_response']
            print(f"⚙️ Tool Response (from {resp.get('name')}):")
            print(f"   Output: {resp.get('response')}")

        # Other event types (like progress messages)
        else:
            print("...") # Show progress for other events

    except Exception as e:
        print(f"Error processing event: {e}")
        # print(f"Raw event: {event}") # Uncomment to debug



for event in remote_app.stream_query(
    user_id="u_456",
    # session_id=remote_session["id"],
    message="Provide USD to INR conversion rate",
):
    print_event_nicely_with_thoughts(event)

Ví dụ về một lần thực thi thành công giúp xác thực khả năng kết nối với API điểm cuối công khai api.frankfurther.app thông qua SWP dựa trên tỷ giá chuyển đổi từ USD sang INR.

12. Xác thực giao diện PSC

Bạn cũng có thể xem các IP đính kèm mạng mà Agent Engine sử dụng bằng cách chuyển đến phần sau:

Network Services (Dịch vụ mạng) → Private Service Connect (Kết nối dịch vụ riêng tư) → Network Attachment (Tệp đính kèm mạng) → psc-network-attachment

Chọn dự án người thuê nhà (tên dự án kết thúc bằng -tp)

Trường được đánh dấu biểu thị địa chỉ IP mà Agent Engine sử dụng từ PSC Network Attachment.

13. SWP – Xác thực Cloud Logging

Bạn có thể xem Cloud Logging để xác thực lưu lượng truy cập Internet do SWP thực hiện, hãy chuyển đến phần sau:

Giám sát → Trình khám phá nhật ký

Chèn truy vấn: resource.type=" networkservices.googleapis.com/Gateway" rồi nhấp vào Chạy truy vấn. Dưới đây là ví dụ xác nhận điểm cuối đích, api.frankfurter.app.

Ví dụ sau đây về Cloud Logging xác thực những nội dung sau:

Destination_range: Địa chỉ IP giao diện PSC của Agent Engine

Source_range: Mạng con chỉ dành cho proxy Dest_ip: Địa chỉ IP của Secure Web Proxy

Hãy nhớ thay đổi project_id cho truy vấn ghi nhật ký trên đám mây.

logName:("projects/project_id/logs/compute.googleapis.com%2Ffirewall") AND jsonPayload.rule_details.reference:("network:consumer-vpc/firewall:allow-access-to-swp")

{
  "insertId": "1j9ym95fmu8g6o",
  "jsonPayload": {
    "vpc": {
      "project_id": "XXXXXXXXXXXXX",
      "subnetwork_name": "intf-subnet",
      "vpc_name": "consumer-vpc"
    },
    "rule_details": {
      "destination_range": [
        "10.10.10.5/32"
      ],
      "reference": "network:consumer-vpc/firewall:allow-access-to-swp",
      "priority": 1000,
      "source_range": [
        "192.168.10.0/28"
      ],
      "direction": "EGRESS",
      "ip_port_info": [
        {
          "ip_protocol": "ALL"
        }
      ],
      "action": "ALLOW"
    },
    "disposition": "ALLOWED",
    "remote_instance": {
      "region": "us-central1"
    },
    "remote_vpc": {
      "vpc_name": "consumer-vpc",
      "project_id": "XXXXXXXXXXXXXXX",
      "subnetwork_name": "swp-subnet"
    },
    "connection": {
      "src_ip": "192.168.10.2",
      "src_port": 48640,
      "dest_port": 8888,
      "dest_ip": "10.10.10.5",
      "protocol": 6
    }
  },
  "resource": {
    "type": "gce_subnetwork",
    "labels": {
      "subnetwork_id": "7147084067647653041",
      "project_id": "XXXXXXXXXXXXXX",
      "location": "us-central1",
      "subnetwork_name": "intf-subnet"
    }
  },
  "timestamp": "2025-12-30T12:51:36.628538815Z",
  "logName": "projects/dec30-run1-agent/logs/compute.googleapis.com%2Ffirewall",
  "receiveTimestamp": "2025-12-30T12:51:40.846652708Z"
}

14. Dọn dẹp

Trong sổ tay JupyterLab, hãy tạo một ô mới và chạy lệnh sau để kích hoạt việc xoá việc triển khai Agent Engine.

Đảm bảo rằng bạn đang cập nhật "project number" và "reasoningEngines token"

import requests
token = !gcloud auth application-default print-access-token
ENDPOINT = "https://us-central1-aiplatform.googleapis.com"
response = requests.delete(
    f"{ENDPOINT}/v1beta1/projects/218166745590/locations/us-central1/reasoningEngines/3086854705725308928",
    params={"force": "true"},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {token[0]}"
    },
)
print(response.text)

Trong Cloud Shell, hãy xoá các thành phần hướng dẫn.

Lưu ý: Bạn có thể xoá PSC Network Attachment và mạng con sau khi Vertex AI Pipeline không được sử dụng trong ít nhất một giờ.

gcloud workbench instances delete workbench-tutorial --project=$projectid --location=us-central1-a

gcloud network-security gateway-security-policies rules delete allow-notebook-subnet \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies rules delete allow-example \
    --gateway-security-policy=my-swp-policy \
    --location=us-central1

gcloud network-security gateway-security-policies delete my-swp-policy \
    --location=us-central1
gcloud network-services gateways delete my-swp-instance\
    --location=us-central1

gcloud dns record-sets delete swp.demo.com --zone=private-dns-codelab  --type=A

gcloud dns managed-zones delete private-dns-codelab


gcloud compute network-attachments delete psc-network-attachment --region=us-central1 --quiet

export ROUTER_NAME=$(gcloud compute routers list --regions=us-central1 \
    --filter="name ~ swg-autogen-router" --format="value(name)")


 gcloud compute routers nats delete swg-autogen-nat --router=$ROUTER_NAME --region=us-central1 --quiet 

gcloud compute routers delete $ROUTER_NAME --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet rfc1918-subnet1 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet swp-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet intf-subnet --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet proxy-subnet
 --region=us-central1 --quiet

gcloud compute networks subnets delete intf-subnet notebook-subnet
--region=us-central1 --quiet

gcloud compute networks delete consumer-vpc --quiet

15. Xin chúc mừng

Xin chúc mừng! Bạn đã định cấu hình và xác thực thành công Agent Engine được triển khai bằng Giao diện Private Service Connect, với lưu lượng truy cập Internet đi ra được thực hiện thông qua một proxy tường minh.

Bạn đã tạo cơ sở hạ tầng người dùng và thêm một tệp đính kèm mạng cho phép nhà sản xuất tạo một máy ảo có nhiều NIC để kết nối thông tin liên lạc giữa người dùng và nhà sản xuất. Bạn đã tìm hiểu cách tạo một proxy rõ ràng và DNS peering cho phép kết nối Internet.

Cosmopup cho rằng các hướng dẫn rất hữu ích!!

Tiếp theo là gì?

Tài liệu đọc thêm và video

• Tổng quan về Private Service Connect

• Giới thiệu về giao diện Private Service Connect | VPC | Google Cloud

Tài liệu tham khảo

• Thông tin tổng quan về quyền truy cập vào mạng Vertex AI | Google Cloud
• Giới thiệu về việc truy cập các dịch vụ Vertex AI thông qua giao diện Private Service Connect | Google Cloud
• Sử dụng giao diện Private Service Connect với Vertex AI Agent Engine
• Thiết lập giao diện Private Service Connect cho các tài nguyên Vertex AI | Google Cloud