本頁面的部分或所有資訊可能不適用於 S3NS 的 Cloud de Confiance。詳情請參閱「與 Google Cloud 的差異」。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定私人服務存取權

本文說明如何使用私人服務存取權，設定 Cloud SQL 執行個體的私人 IP 連線。

事前準備

Cloud SQL 必須為用於私人 IP 連線的每個虛擬私有雲網路，啟用私人服務存取。

啟用必要的 API

在 Cloud SQL 執行個體所在的專案中，啟用 Service Networking API (servicenetworking.googleapis.com) 和 Compute Engine API (compute.googleapis.com)。

如果您使用 Shared VPC 網路，則也必須在 Shared VPC 主機專案中啟用這些 API。

您可以使用下列指令啟用 API：

gcloud services enable servicenetworking.googleapis.com compute.googleapis.com --project=PROJECT_ID

將 PROJECT_ID 替換為專案 ID (或 Shared VPC 主機專案 ID)。

如果未啟用 Service Networking API，當您建立使用私人 IP 位址的 Cloud SQL 執行個體時，作業會失敗並顯示 SERVICE_NETWORKING_NOT_ENABLED 錯誤。

必要角色和權限

如要取得建立及管理私人服務連線所需的權限，請要求管理員在託管 Cloud SQL 執行個體的專案中，授予您Compute 網路管理員 (roles/compute.networkAdmin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立及管理私人服務連線所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

必須具備下列權限，才能建立及管理私人服務連線：

compute.addresses.create
compute.addresses.list
compute.globalAddresses.create
compute.globalAddresses.createInternal
compute.globalAddresses.list
compute.networks.list
compute.networks.use
servicenetworking.services.addPeering
serviceusage.services.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如果您使用 Shared VPC 網路，也必須將 Compute 網路管理員 (roles/compute.networkAdmin) 角色授予 Shared VPC 主機專案中的使用者。

為 Cloud SQL 設定私人服務連線

私人服務存取設定程序分為兩個部分：

選取現有 IP 位址範圍，或分配新的 IP 位址範圍。

如果您在 Cloud de Confiance 控制台中建立 Cloud SQL 執行個體，也可以選擇讓 Google 為您分配 IP 位址範圍。在這種情況下，Google 會自動分配前置長度為 /24 的 IP 範圍，並以「default-ip-range」命名。

如果您打算在多個區域或不同資料庫類型中建立 Cloud SQL 執行個體，則每個區域或資料庫類型都必須有至少 /24 範圍的可用 IP 位址。包括 Filestore 或 Memorystore 等其他應用程式。如果是新區域或資料庫類型，Cloud SQL 必須有可用的 /24 範圍。
建立從虛擬私有雲網路到基礎服務供應商網路的私人服務連線。

如要瞭解網路和應用程式環境需求，以及私人服務存取權所需的 IAM 權限，請參閱「私人 IP 連線需求」。

分配 IP 位址範圍

控制台

前往 Cloud de Confiance 控制台的「VPC Networks」(虛擬私有雲網路) 頁面。

前往「VPC networks」(虛擬私有雲網路)
選取要使用的虛擬私有雲網路。
選取「私人服務連線」分頁標籤。
選取「分配的服務 IP 範圍」分頁標籤。
按一下「分配 IP 範圍」。
在分配範圍的「名稱」中，指定 google-managed-services-VPC_NETWORK_NAME，其中 VPC_NETWORK_NAME 是您要連線的虛擬私有雲網路名稱 (例如 google-managed-services-default)。「說明」為選填。
選取「Custom」(自訂) 選項，然後以 CIDR 標記法輸入要分配的 IP 位址範圍。
按一下 [Allocate] (分配)，建立已分配範圍。

gcloud

執行下列其中一個步驟：

如要指定位址範圍和前置字元長度 (子網路遮罩)，請使用 addresses 和 prefix-length 旗標。舉例來說，如要分配 CIDR 區塊 192.168.0.0/16，請將位址指定為 192.168.0.0，並將前置長度指定為 16。

    gcloud compute addresses create google-managed-services-VPC_NETWORK_NAME \
       --global \
       --purpose=VPC_PEERING \
       --addresses=192.168.0.0 \
       --prefix-length=16 \
       --network=projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

如要僅指定前置字串長度 (子網路遮罩)，請使用 prefix-length 旗標。如果省略位址範圍， Cloud de Confiance會自動選取虛擬私有雲網路中未使用的位址範圍。以下範例會選取前置字串長度為 16 位元的未使用 IP 位址範圍。

  gcloud compute addresses create google-managed-services-VPC_NETWORK_NAME \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --network=projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME

將 VPC_NETWORK_NAME 替換為虛擬私有雲網路名稱，例如 my-vpc-network。

以下範例會分配 IP 範圍，允許虛擬私有雲網路 my-vpc-network 中的資源使用私人 IP 連線至 Cloud SQL 執行個體。

  gcloud compute addresses create google-managed-services-my-vpc-network \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --network=projects/myprojectid/global/networks/myvpcnetwork \
    --project=my-project

Terraform

如要分配 IP 位址範圍，請使用 Terraform 資源。

resource "google_compute_global_address" "private_ip_address" {
  name          = "private-ip-address"
  purpose       = "VPC_PEERING"
  address_type  = "INTERNAL"
  prefix_length = 16
  network       = google_compute_network.peering_network.id
}

套用變更

如要在 Cloud de Confiance 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

啟動 Cloud Shell。
設定要套用 Terraform 設定的預設 Cloud de Confiance 專案。

每個專案只需執行這個指令一次，而且可以在任何目錄中執行。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您正在按照教學課程操作，可以複製每個章節或步驟中的程式碼範例。

將程式碼範例複製到新建立的 main.tf 中。

您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。
請檢查並修改範例參數，然後套用至您的環境。
儲存變更。
初始化 Terraform。每個目錄只需執行一次這項操作。
```
terraform init
```
如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：
```
terraform init -upgrade
```

套用變更

查看設定，並確認 Terraform 即將建立或更新的資源符合您的預期：
```
terraform plan
```
視需要修正設定。
執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：
```
terraform apply
```
等待 Terraform 顯示「Apply complete!」訊息。
開啟 Cloud de Confiance 專案即可查看結果。在 Cloud de Confiance 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

執行下列指令，並在提示中輸入 yes，移除先前使用 Terraform 設定套用的資源：

terraform destroy

建立私人連線

控制台

前往 Cloud de Confiance 控制台的「VPC Networks」(虛擬私有雲網路) 頁面。

前往虛擬私有雲網路
選取要使用的虛擬私有雲網路。
選取 [Private service connection] (私人服務連線) 分頁標籤。
選取「Private connections to services」(私人服務連線) 分頁標籤。
按一下「建立連線」，在您的網路與服務生產者之間建立私人連線。
在「Assigned allocation」(指派的分配) 部分，選取一或多個其他服務生產者未使用的現有分配範圍。
按一下 [Connect] (連線) 建立連線。

gcloud

為專案中的虛擬私有雲網路建立私人服務存取連線。

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=google-managed-services-VPC_NETWORK_NAME \
--network=VPC_NETWORK_NAME \
--project=PROJECT_ID

這個指令會啟動長時間執行的 Cloud SQL 執行個體作業，並傳回作業 ID。

確認作業是否已經成功完成。

gcloud services vpc-peerings operations describe \
--name=OPERATION_ID

您可以在建立私人連線時指定多個分配範圍，舉例來說，如果範圍已用盡，您可以指派額外的分配範圍。服務會按照您指定的順序，使用所有提供範圍內的 IP 位址。

Terraform

如要建立私人連線，請使用 Terraform 資源。

resource "google_service_networking_connection" "default" {
  network                 = google_compute_network.peering_network.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_address.name]
}

建立私有連線時，系統會將 servicenetworking.serviceAgent 角色授予 service-HOST_PROJECT_NUMBER@service-networking.s3ns-system.iam.gserviceaccount.com 格式的服務帳戶，因為帳戶是即時佈建。

如果看到專案的 compute.globalAddresses.list 權限或 compute.projects.get 權限錯誤，請執行下列 gcloud 指令：

gcloud projects add-iam-policy-binding HOST_PROJECT_NAME \
    --member=serviceAccount:service-HOST_PROJECT_NUMBER@service-networking.s3ns-system.iam.gserviceaccount.com \
    --role=roles/servicenetworking.serviceAgent

使用私人服務存取權，為私人 IP 設定執行個體

您可以為新執行個體和現有執行個體設定私人服務連線。

為新執行個體設定私人 IP

控制台

前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

前往「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面
點選「建立執行個體」。
在「自訂執行個體」部分，展開「顯示設定選項」。
展開「連線」。
選取「私人 IP」。
選取「私人服務連線 (PSA)」。
下拉式選單會顯示專案中可用的虛擬私有雲網路。如果您的專案是Shared VPC的服務專案，系統也會顯示主專案的虛擬私有雲網路。
選取要使用的虛擬私有雲網路。

如果看到訊息，指出您需要設定私人服務連線，請按照下列步驟操作：

按一下「設定連線」。
在「Allocate an IP range」(分配 IP 範圍) 區段中，選取下列其中一個選項：
- 從下拉式選單中，選取一或多個現有的 IP 範圍，或建立新的 IP 範圍。下拉式選單會顯示先前分配的範圍 (如有)，您也可以選取「分配新的 IP 範圍」，然後輸入新的範圍和名稱。
- 使用網路中自動分配的 IP 範圍。
注意： 您只能為主要執行個體指定位址範圍，無法為唯讀副本或複製執行個體指定。
按一下「繼續」。
點選「建立連線」。
確認您看到以下訊息：Private service connection for network VPC_NETWORK_NAME has been successfully created。

您也可以指定分配的 IP 範圍，供執行個體用於連線。
1. 展開「顯示分配的 IP 範圍選項」。
2. 從下拉式選單中選取 IP 範圍。
選用。如要允許 BigQuery 等其他 Cloud de Confiance by S3NS 服務透過私人 IP 連線存取 Cloud SQL 中的資料並進行查詢，請選取「啟用私人路徑」。
完成執行個體設定。
點選「建立執行個體」。

gcloud

使用私人 IP 位址建立執行個體前，請確認專案已設為私人服務存取權。

執行下列 gcloud CLI 指令，為 Cloud SQL 設定私人服務連線網路：

啟用必要的 API：

gcloud services enable \
    sqladmin.googleapis.com \
    compute.googleapis.com \
    servicenetworking.googleapis.com \
    --project=PROJECT_ID

為虛擬私有雲網路對等互連分配 IP 位址範圍：

gcloud compute addresses create google-managed-services-VPC_NETWORK_NAME \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --network=projects/NETWORK_PROJECT_ID/global/networks/VPC_NETWORK_NAME \
    --project=PROJECT_ID

建立虛擬私有雲網路對接連線：

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=google-managed-services-VPC_NETWORK_NAME \
    --network=VPC_NETWORK_NAME \
    --project=PROJECT_ID

使用任何要求資料之前，請先修改下列項目的值：

INSTANCE_ID：執行個體 ID
PROJECT_ID：專案 ID
NETWORK_PROJECT_ID：虛擬私有雲網路的專案 ID

注意： 如果虛擬私有雲網路是 Shared VPC，則 PROJECT_ID 必須是 Shared VPC 服務專案的 ID，而 NETWORK_PROJECT_ID 必須是 Shared VPC 主專案的 ID。
VPC_NETWORK_NAME：虛擬私有雲網路名稱
RANGE_NAME：選填。如果指定，則會設定分配 IP 範圍的範圍名稱。範圍名稱必須符合RFC-1035，且長度介於 1 至 63 個字元之間。
REGION_NAME：區域名稱

如要指定虛擬私有雲網路名稱，請使用 --network 參數。如要停用公開 IP，請使用 --no-assign-ip 旗標。

此外，您也可以選擇使用 --enable-google-private-path 參數，允許 BigQuery 等其他 Cloud de Confiance 服務存取 Cloud SQL 中的資料，並透過私人 IP 連線查詢這項資料。這個參數僅在下列情況有效：

使用 --no-assign-ip 參數。
您可以使用 --network 參數，指定要用於建立私人連線的虛擬私有雲網路名稱。

如要強制執行例項使用新的網路架構，請使用 --enforce-new-sql-network-architecture 旗標。請確認您已分配足夠的 IP 位址。如果在專案完全升級前，就強制執行新的網路架構，可能會因 IP 位址空間不足，導致執行個體建立失敗。詳情請參閱「將執行個體升級至新網路架構」和「分配 IP 位址範圍」。

gcloud beta sql instances create INSTANCE_ID \
  --project=PROJECT_ID \
  --network=projects/NETWORK_PROJECT_ID/global/networks/VPC_NETWORK_NAME \
  --no-assign-ip \
  --allocated-ip-range-name=RANGE_NAME \
  --enable-google-private-path \
  --enforce-new-sql-network-architecture

Terraform

如要為新執行個體設定私人 IP，請使用下列 Terraform 資源：


resource "google_compute_network" "peering_network" {
  name                    = "private-network"
  auto_create_subnetworks = "false"
}

resource "google_compute_global_address" "private_ip_address" {
  name          = "private-ip-address"
  purpose       = "VPC_PEERING"
  address_type  = "INTERNAL"
  prefix_length = 16
  network       = google_compute_network.peering_network.id
}

resource "google_service_networking_connection" "default" {
  network                 = google_compute_network.peering_network.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_address.name]
}

resource "google_sql_database_instance" "instance" {
  name             = "private-ip-sql-instance"
  region           = "us-central1"
  database_version = "MYSQL_8_0"

  depends_on = [google_service_networking_connection.default]

  settings {
    tier = "db-f1-micro"
    ip_configuration {
      ipv4_enabled    = "false"
      private_network = google_compute_network.peering_network.id
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

resource "google_compute_network_peering_routes_config" "peering_routes" {
  peering              = google_service_networking_connection.default.peering
  network              = google_compute_network.peering_network.name
  import_custom_routes = true
  export_custom_routes = true
}


## Uncomment this block after adding a valid DNS suffix

# resource "google_service_networking_peered_dns_domain" "default" {
#   name       = "example-com"
#   network    = google_compute_network.peering_network.name
#   dns_suffix = "example.com."
#   service    = "servicenetworking.googleapis.com"
# }

套用變更

如要在 Cloud de Confiance 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

啟動 Cloud Shell。
設定要套用 Terraform 設定的預設 Cloud de Confiance 專案。

每個專案只需執行這個指令一次，而且可以在任何目錄中執行。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您正在按照教學課程操作，可以複製每個章節或步驟中的程式碼範例。

將程式碼範例複製到新建立的 main.tf 中。

您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。
請檢查並修改範例參數，然後套用至您的環境。
儲存變更。
初始化 Terraform。每個目錄只需執行一次這項操作。
```
terraform init
```
如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：
```
terraform init -upgrade
```

套用變更

查看設定，並確認 Terraform 即將建立或更新的資源符合您的預期：
```
terraform plan
```
視需要修正設定。
執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：
```
terraform apply
```
等待 Terraform 顯示「Apply complete!」訊息。
開啟 Cloud de Confiance 專案即可查看結果。在 Cloud de Confiance 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

刪除變更

如要刪除變更，請按照下列步驟操作：

如要停用防刪除功能，請在 Terraform 設定檔中將 deletion_protection 引數設為 false。
```
deletion_protection =  "false"
```
執行下列指令，並在提示中輸入 yes，套用更新後的 Terraform 設定：
```
terraform apply
```

執行下列指令，並在提示中輸入 yes，移除先前使用 Terraform 設定套用的資源：
```
terraform destroy
```

REST v1

建立具有私人 IP 位址的新執行個體：

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID: 專案 ID
INSTANCE_ID: 執行個體 ID
VPC_NETWORK_NAME: 指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。網路必須已設定私人服務連線。
RANGE_NAME: 選填。如果指定，則會設定分配 IP 範圍的範圍名稱。範圍名稱必須符合 RFC-1035，且長度介於 1 至 63 個字元。
AUTHORIZED_NETWORKS: 如果是公開 IP 連線，請指定可連線至執行個體的授權網路連線。

如果是執行個體使用公開 IP 位址，請將 ipv4Enabled 參數的值設為 true ；如果是執行個體使用私人 IP 位址，請將參數的值設為 false。

如果將 enablePrivatePathForGoogleCloudServices 參數設為 true，則允許其他 Cloud de Confiance by S3NS 服務 (例如 BigQuery) 透過私人 IP 連線存取 Cloud SQL 中的資料，並對這些資料執行查詢。將這個參數設為 false，其他 Cloud de Confiance by S3NS 服務就無法透過私人 IP 連線存取 Cloud SQL 中的資料。

您可以使用 sqlNetworkArchitecture 欄位，強制在建立執行個體時使用新的網路架構，即使專案尚未完全升級也沒問題。如要進一步瞭解新版網路架構及其影響，請參閱「將執行個體升級為新版網路架構」和「分配 IP 位址範圍」。

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

JSON 要求主體：

{
  "name": "INSTANCE_ID",
  "region": "region",
  "databaseVersion": "database-version",
  "settings": {
    "tier": "machine-type",
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  },
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

建立具有私人 IP 位址的新執行個體：

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID: 專案 ID
INSTANCE_ID: 執行個體 ID
VPC_NETWORK_NAME: 指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。網路必須已設定私人服務連線。
RANGE_NAME: 選填。如果指定，則會設定分配 IP 範圍的範圍名稱。範圍名稱必須符合 RFC-1035 ，且長度介於 1 至 63 個字元之間。
AUTHORIZED_NETWORKS: 如果是公開 IP 連線，請指定可連線至執行個體的授權網路連線。

如果是執行個體使用公開 IP 位址，請將 ipv4Enabled 參數的值設為 true ；如果是執行個體使用私人 IP 位址，請將參數的值設為 false。

如果將 enablePrivatePathForGoogleCloudServices 參數設為 true，則允許其他 Cloud de Confiance by S3NS 服務 (例如 BigQuery) 透過私人 IP 連線存取 Cloud SQL 中的資料，並對這些資料執行查詢。如果將這個參數設為 false，其他 Cloud de Confiance by S3NS 服務就無法透過私人 IP 連線存取 Cloud SQL 中的資料。

HTTP 方法和網址：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances

JSON 要求主體：

{
  "name": "INSTANCE_ID",
  "region": "region",
  "databaseVersion": "database-version",
  "settings": {
    "tier": "machine-type",
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  },
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CREATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

為現有執行個體設定私人 IP

將現有 Cloud SQL 執行個體設為使用私人 IP 時，執行個體會重新啟動，導致停機。

如何將現有執行個體設定為使用私人 IP：

控制台

前往 Cloud de Confiance 控制台的「Cloud SQL Instances」(Cloud SQL 執行個體) 頁面。

前往 Cloud SQL 執行個體
點選執行個體名稱，開啟執行個體的「總覽」頁面。
在 Cloud SQL 導覽選單中，選取「連線」。
在「網路」分頁中，勾選「私人 IP」核取方塊。
下拉式選單會顯示專案中的可用網路。
選取要使用的虛擬私有雲網路：

如果看到「必須使用私人服務連線」：

按一下「設定連線」。
在「Allocate an IP range」(分配 IP 範圍) 區段中，選擇下列其中一個選項：
- 從下拉式選單中選取一或多個現有的 IP 範圍，或建立新的 IP 範圍。下拉式選單會列出先前分配的範圍 (如有)，您也可以選取「分配新的 IP 範圍」，然後輸入新的範圍和名稱。
- 使用網路中自動分配的 IP 範圍。
注意： 您只能為主要執行個體指定位址範圍，無法為唯讀副本或複製執行個體指定位址範圍。
按一下「繼續」。
點選「建立連線」。
確認您看到「Private service connection for network VPC_NETWORK_NAME has been successfully created 」(已成功建立網路 VPC_NETWORK_NAME 的私人服務連線) 狀態。

選用。如要允許 BigQuery 等其他 Cloud de Confiance 服務透過私人 IP 連線存取 Cloud SQL 中的資料並進行查詢，請選取「啟用私人路徑」核取方塊。
按一下 [儲存]。

gcloud

確認專案已設定私人服務存取權。

使用 --network 參數更新 Cloud SQL 執行個體，指定所選虛擬私有雲網路的名稱。

如要在新增私人 IP 網路設定時，強制執行個體使用新的網路架構，請使用 --enforce-new-sql-network-architecture 旗標。請確認您在 IP 範圍中分配了足夠的 IP 位址空間。在專案完全升級前，如果使用新的網路架構強制執行功能，可能會因 IP 位址空間不足，導致執行個體建立失敗。

詳情請參閱「將執行個體升級為新版網路架構」和「分配 IP 位址範圍」。

gcloud beta sql instances patch INSTANCE_ID \
--project=PROJECT_ID \
--network=projects/NETWORK_PROJECT_ID/global/networks/VPC_NETWORK_NAME \
--no-assign-ip \
--enable-google-private-path \
--enforce-new-sql-network-architecture

REST v1

建立具有私人 IP 位址的新執行個體：

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID: 專案 ID
INSTANCE_ID: 執行個體 ID
VPC_NETWORK_NAME: 指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。網路必須已設定私人服務連線。
RANGE_NAME: 選填。如果指定，則會設定要分配 IP 範圍的範圍名稱。範圍名稱必須符合 RFC-1035，且長度介於 1 至 63 個字元。
AUTHORIZED_NETWORKS: 如果是公開 IP 連線，請指定可連線至執行個體的授權網路連線。

如果執行個體使用公開 IP 位址，請將 ipv4Enabled 參數的值設為 true；如果執行個體使用私人 IP 位址，請將該參數的值設為 false。

即使專案尚未完全升級，您仍可使用 sqlNetworkArchitecture 欄位，在建立執行個體時強制使用新的網路架構。如要進一步瞭解新版網路架構及其影響，請參閱「將執行個體升級為新版網路架構」和「分配 IP 位址範圍」。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "settings":
  {
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  },
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

REST v1beta4

建立具有私人 IP 位址的新執行個體：

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID: 專案 ID
INSTANCE_ID: 執行個體 ID
VPC_NETWORK_NAME: 指定要用於這個執行個體的虛擬私有雲 (VPC) 網路名稱。網路必須已設定私人服務連線。
RANGE_NAME: 選填。如果指定，則會設定要分配 IP 範圍的範圍名稱。範圍名稱必須符合 RFC-1035 ，且長度介於 1 至 63 個字元之間。
AUTHORIZED_NETWORKS：如果是公開 IP 連線，請指定可連至執行個體的授權網路連線。

如果是執行個體使用公開 IP 位址，請將 ipv4Enabled 參數的值設為 true ；如果是執行個體使用私人 IP 位址，請將參數的值設為 false。

如果將 enablePrivatePathForGoogleCloudServices 參數設為 true，您就能允許 BigQuery 等其他 Cloud de Confiance by S3NS 服務存取 Cloud SQL 中的資料，並透過私人 IP 連線查詢這項資料。如果將這個參數設為 false，其他 Cloud de Confiance by S3NS 服務就無法透過私人 IP 連線存取 Cloud SQL 中的資料。

HTTP 方法和網址：

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID

JSON 要求主體：

{
  "settings":
  {
    "ipConfiguration": {
      "ipv4Enabled": false,
      "privateNetwork": "projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME",
      "allocatedIpRange": "RANGE_NAME"
      "authorizedNetworks": [AUTHORIZED_NETWORKS],
      
      "enablePrivatePathForGoogleCloudServices": true
      
    }
  },
  "sqlNetworkArchitecture": "NEW_NETWORK_ARCHITECTURE"
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

回應

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_ID",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "UPDATE",
  "name": "OPERATION_ID",
  "targetId": "INSTANCE_ID",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

變更私人服務存取權設定

您可以變更私人服務連線的分配位址範圍，而不必修改任何現有的 Cloud SQL 執行個體。如要變更現有 Cloud SQL 執行個體的私人 IP 位址，請按照這些步驟操作。

如要變更分配的位址範圍，請按照下列步驟操作：

控制台

前往 Cloud de Confiance 控制台的「VPC Networks」(虛擬私有雲網路) 頁面。

前往虛擬私有雲網路
選取要使用的虛擬私有雲網路。
選取 [Private service connection] (私人服務連線) 分頁標籤。
選取「分配的服務 IP 範圍」分頁標籤。
選取要刪除的範圍名稱。

注意： 刪除範圍前，請先記下範圍名稱。稍後會用到。
按一下「釋出」。
按一下「Allocate IP range」(分配 IP 範圍)。
建立同名的新範圍和新範圍
名稱很重要，因為私人連線已使用該位址名稱建立。

gcloud services vpc-peerings update \
--network=VPC_NETWORK_NAME \
--ranges=ALLOCATED_RANGES \
--service=servicenetworking.googleapis.com \
--force

變更現有 Cloud SQL 執行個體的私人 IP 位址

如要變更現有 Cloud SQL 執行個體的私人 IP 位址，請將執行個體從原始網路移至臨時虛擬私有雲網路。接著，變更執行個體原始網路的私人服務存取權設定，並將 Cloud SQL 執行個體移回原始網路。

如要移至其他虛擬私有雲網路，請按照下列程序操作，但略過最後一個步驟 (將執行個體移回)。在本例中，TEMPORARY_VPC_NETWORK_NAME 是新的虛擬私有雲網路。此外，請刪除舊的私人連線。刪除的私人連線可能需要幾天，才會從Cloud de Confiance 控制台消失。

如果 Cloud SQL 執行個體託管於 Shared VPC 網路，下列操作說明中使用的 VPC_NETWORK_NAME 變數必須是主專案的虛擬私有雲網路名稱。如要指定使用 Shared VPC 網路的網路，請使用網路的完整網址，例如 projects/HOST_PROJECT/global/networks/NETWORK_NAME。

控制台

前往 Cloud de Confiance 控制台的「VPC Networks」(虛擬私有雲網路) 頁面。

前往虛擬私有雲網路
建立暫時性虛擬私有雲網路。
在臨時虛擬私有雲網路中建立 IP 分配。
在臨時虛擬私有雲網路中建立私人連線。

將 Cloud SQL 執行個體移至臨時虛擬私有雲網路。

gcloud beta sql instances patch INSTANCE_ID \
  --project=PROJECT_ID \
  --network=projects/PROJECT_ID/global/networks/TEMPORARY_VPC_NETWORK_NAME \
  --no-assign-ip

變更原始網路中的私人服務存取權設定，新增分配範圍或刪除現有範圍。

將 Cloud SQL 執行個體移回原始 VPC 網路。

gcloud beta sql instances patch INSTANCE_ID \
  --project=PROJECT_ID \
  --network=projects/PROJECT_ID/global/networks/ORIGINAL_VPC_NETWORK_NAME \
  --no-assign-ip

使用私人 IP 位址連線至執行個體

您可以透過私有服務存取權，從相同虛擬私有雲網路中的 Compute Engine 或 Google Kubernetes Engine 執行個體 (在此定義為內部來源)，或從該網路外部 (外部來源) 連線至 Cloud SQL 執行個體。

從內部來源連線

如要從與 Cloud SQL 執行個體位於相同 Cloud de Confiance 專案的來源連線 (例如在 Compute Engine 資源上執行的 Cloud SQL Auth Proxy)，該資源必須位於與 Cloud SQL 執行個體建立私人服務存取的相同 VPC 網路中。

如要從無伺服器來源 (例如 App Engine 標準環境、Cloud Run 或 Cloud Run 函式) 連線，應用程式或函式會透過無伺服器 VPC 存取直接連線至執行個體，無須使用 Cloud SQL Auth Proxy。

從外部來源連線

如果外部網路 (例如地端部署網路或虛擬私有雲網路) 連線至 Cloud SQL 執行個體所連線的虛擬私有雲網路，則可以使用 Cloud VPN 或 Cloud Interconnect，從外部網路中的用戶端連線至執行個體。

如要允許外部網路連線，請按照下列步驟操作：

請確認您的虛擬私有雲網路已使用 Cloud VPN 通道，或 Dedicated Interconnect 或 Partner Interconnect 的 VLAN 連結，連線至外部網路。
請確認管理 Cloud VPN 通道和 Cloud Interconnect 互連網路連結 (VLAN) 的 Cloud Router 上的邊界閘道通訊協定 (BGP) 工作階段，已從地端部署網路接收特定前置字元 (目的地)。

預設路由 (目的地 0.0.0.0/0) 無法匯入 Cloud SQL 虛擬私有雲網路，因為該網路有自己的本機預設路由。即使 Cloud SQL 對等互連已設為從虛擬私有雲網路匯入自訂路徑，系統仍會使用目的地的本機路徑。
找出私人服務連線產生的對接連線。視服務而定，Private Service Connect 可能會建立一或多個下列對等連線，但不一定會建立所有連線：
- cloudsql-mysql-googleapis-com
- cloudsql-postgres-googleapis-com
- servicenetworking-googleapis-com
更新「所有」對等互連連線，啟用「匯出自訂路由」。
找出 Private Service Connect 使用的分配範圍。
設定 Cloud Router 自訂 advertisement 模式，用於管理 Cloud VPN 通道或 Cloud Interconnect 互連網路連結 (VLAN) 的 BGP 工作階段的 Cloud Router 上的分配範圍。

從 Cloud Shell 連線

Cloud Shell 使用由 Cloud de Confiance by S3NS 管理的 Compute Engine 虛擬機器，且位於虛擬私有雲網路之外。因此，Cloud Shell 和虛擬私有雲網路的私人 IP 位址空間之間沒有連線路徑。

因此，Cloud Shell 不支援連線至只有私人 IP 位址的 Cloud SQL 執行個體。

如要使用私人 IP 連線能力，從外部網路連線至 Cloud SQL 執行個體，請參閱「從虛擬私有雲外部連線至 Cloud SQL 執行個體」。

從非 RFC 1918 IP 位址連線

RFC 1918 指定指派用於內部 (即組織內) 的 IP 位址，且不會在網際網路上轉送。具體來說，這些是：

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

使用私人 IP 位址連至 Cloud SQL 執行個體的連線，會自動獲得 RFC 1918 位址範圍的授權。這樣一來，所有私人用戶端都能存取資料庫，不必透過 Proxy。

如要從非 RFC 1918 IP 位址連線，您必須設定各執行個體的 IP 授權，允許來自非 RFC 1918 IP 位址範圍的流量。

舉例來說，請使用下列 gcloud 指令：

gcloud sql instances patch INSTANCE_NAME \
--authorized-networks=192.88.99.0/24,11.0.0.0/24

根據預設，Cloud SQL 不會從虛擬私有雲網路學習非 RFC 1918 子網路路由。您必須更新 Cloud SQL 的網路對等互連，才能匯出任何非 RFC 1918 路由。

gcloud compute networks peerings update PEERING_CONNECTION \
--network=VPC_NETWORK_NAME \
--export-subnet-routes-with-public-ip \
--project=PROJECT_ID

更改下列內容：

PEERING_CONNECTION 是虛擬私有雲網路與服務生產者網路之間的 Private Service Connect，所產生的對接連線名稱。
VPC_NETWORK_NAME 是您虛擬私有雲網路的名稱。
PROJECT_ID 是虛擬私有雲網路的專案 ID。如果您使用 Shared VPC，請使用主專案 ID。

如要緩解 IP 位址耗盡的問題，可以使用私人使用的公開 IP 位址。

從私人使用的公開 IP 位址連線

如要在私下使用的公開 IP 位址範圍內設定執行個體，請在網路與 Cloud SQL 網路之間的網路對等互連上啟用 export-subnet-routes-with-public-ip。

gcloud compute networks peerings update PEERING_CONNECTION \
--network=VPC_NETWORK_NAME \
--export-subnet-routes-with-public-ip \
--project=PROJECT_ID

更改下列內容：

PEERING_CONNECTION 是虛擬私有雲網路與服務供應商網路之間的私人服務連線，所產生的對接連線名稱。如要查看對等互連連線名稱，請前往「虛擬私有雲網路對等互連」頁面。
VPC_NETWORK_NAME 是您虛擬私有雲網路的名稱。
PROJECT_ID 是虛擬私有雲網路的專案 ID。如果您使用 Shared VPC，請使用主專案 ID。

連線至設有私人使用公開 IP 位址的執行個體

如果執行個體是在私人使用的公開 IP 位址範圍中設定，且您想連線至該執行個體，請在您的網路與 Cloud SQL 網路之間啟用import-subnet-routes-with-public-ip網路對等互連。

gcloud compute networks peerings update PEERING_CONNECTION \
--network=VPC_NETWORK_NAME \
--import-subnet-routes-with-public-ip \
--project=PROJECT_ID

更改下列內容：

PEERING_CONNECTION 是對接連線的名稱，由虛擬私有雲網路和服務供應商網路之間的私人服務連線產生。如要查看對接連線名稱，請前往「虛擬私有雲網路對接」頁面。
VPC_NETWORK_NAME 是您虛擬私有雲網路的名稱。
PROJECT_ID 是虛擬私有雲網路的專案 ID。如果使用 Shared VPC，請提供主專案 ID。

使用寫入端點建立連線

除了私人 IP 位址，您也可以在 SQL 連線字串中使用寫入端點。寫入端點是全域網域名稱服務 (DNS) 名稱，會自動解析為目前主要執行個體的 IP 位址。使用寫入端點，即可避免區域發生故障時，必須進行應用程式連線變更。

如果副本容錯移轉或切換，寫入端點可協助管理執行個體的私人 IP 位址。發生這種情況時，請使用寫入端點連線至做為主要執行個體的執行個體。

Cloud SQL 如何建立寫入端點

如果您為 Cloud de Confiance 專案啟用 Cloud DNS API，然後建立主要 Cloud SQL Enterprise Plus 版本執行個體、升級執行個體的副本，或將執行個體從 Cloud SQL Enterprise 版本升級，Cloud SQL 就會自動產生寫入端點，並指派給執行個體。

如果主要執行個體在切換或容錯移轉程序期間變更，Cloud SQL 會將寫入端點指派給容錯移轉副本，因為這個副本是新的主要執行個體。

詳情請參閱「查看寫入端點」。

為執行個體指派寫入端點

如果沒有為 Cloud de Confiance 專案啟用 Cloud DNS API，然後建立、升級或升級執行個體，Cloud SQL 就不會自動將寫入端點指派給執行個體。

如要讓 Cloud SQL 產生寫入端點並指派給執行個體，請參閱「產生寫入端點」。

疑難排解

如需連線問題的已知問題，請參閱疑難排解，如需自我診斷的相關說明，請參閱排解連線問題。