Kunci enkripsi yang dikelola pelanggan (Customer-Managed Encryption Key/CMEK)

Secara default, Gemini Data Analytics mengenkripsi konten pelanggan dalam penyimpanan. Gemini Data Analytics menangani enkripsi untuk Anda tanpa tindakan tambahan dari Anda. Opsi ini disebut Enkripsi default Google.

Jika ingin mengontrol kunci enkripsi, Anda dapat menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) di Cloud KMS dengan layanan yang terintegrasi dengan CMEK, termasuk Gemini Data Analytics. Dengan menggunakan kunci Cloud KMS, Anda dapat mengontrol tingkat perlindungan, lokasi, jadwal rotasi, izin penggunaan dan akses, serta batasan kriptografisnya. Dengan Cloud KMS, Anda juga dapat melihat log audit dan mengontrol siklus proses kunci. Bukan Google yang memiliki dan mengelola kunci enkripsi kunci (KEK) simetris yang melindungi data Anda. Andalah yang mengontrol dan mengelola kunci ini di Cloud KMS.

Setelah Anda menyiapkan resource dengan CMEK, pengalaman mengakses resource Gemini Data Analytics akan serupa dengan menggunakan enkripsi default Google. Untuk mengetahui informasi selengkapnya tentang opsi enkripsi, lihat Kunci enkripsi yang dikelola pelanggan (CMEK).

Halaman ini menjelaskan cara menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) untuk melindungi data yang digunakan oleh Conversational Analytics API. Conversational Analytics API adalah produk dalam layanan Gemini Data Analytics (geminidataanalytics.googleapis.com).

CMEK untuk resource Conversational Analytics API

Saat Anda mengonfigurasi CMEK untuk resource Conversational Analytics API, kunci Cloud KMS yang ditentukan akan mengenkripsi data sensitif dalam penyimpanan. Anda dapat mengonfigurasi CMEK untuk resource DataAgent dan Conversation secara independen.

CMEK untuk Conversational Analytics API hanya tersedia di lokasi regional dan multi-regional, bukan di lokasi global. Untuk mengetahui lokasi yang didukung oleh setiap sumber data, lihat Lokasi data yang didukung.

Yang dilindungi oleh CMEK

CMEK untuk Conversational Analytics API melindungi data dalam penyimpanan berikut:

  • Untuk resource DataAgent, semua konten inti pelanggan dalam kolom data_analytics_agent dilindungi. Konten ini mencakup kolom staging_context, published_context, dan last_published_context, serta kolom system_instruction dan example_queries.
  • Untuk resource Conversation, semua data histori pesan dan status dilindungi.

Data berikut tidak dienkripsi dengan kunci CMEK pelanggan. Sebagai gantinya, data ini dilindungi oleh enkripsi default Google:

  • Untuk resource DataAgent, enkripsi default Google melindungi kolom metadata seperti name, display_name, description, labels, create_time, update_time, delete_time, purge_time, dan kms_key.
  • Untuk resource Conversation, enkripsi default Google melindungi kolom metadata seperti name, agents, labels, create_time, last_used_time, dan kms_key.

Batasan

CMEK untuk Conversational Analytics API memiliki batasan berikut:

  • CMEK harus dikonfigurasi saat resource dibuat. Label ini tidak dapat ditambahkan atau diubah pada resource yang ada.
  • Kebijakan organisasi CMEK tidak didukung.
  • Lokasi kunci Cloud KMS yang diperlukan bergantung pada jenis dan lokasi resource. Di satu region, kunci harus berada di region yang sama dengan resource. Di multi-region us atau eu, lokasi kunci untuk resource DataAgent dan Conversation berbeda. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.
  • Region global tidak didukung.
  • Anda hanya dapat menggunakan satu CMEK per project per region untuk semua resource Conversation dalam project dan region tersebut.

Persyaratan lokasi utama

Lokasi kunci Cloud KMS yang diperlukan bergantung pada jenis resource yang Anda lindungi dan lokasi resource tersebut:

Lokasi resource Lokasi kunci untuk DataAgent resource Lokasi kunci untuk Conversation resource
us multi-region us us-central1
eu multi-region europe europe-west1
Satu region, seperti us-east4 Region yang sama dengan resource Region yang sama dengan resource

Resource DataAgent di multi-region disimpan di multi-region yang ditentukan dalam nama resource, sehingga kunci harus berada di multi-region Cloud KMS yang cocok. Untuk multi-region us, lokasi Cloud KMS juga us. Untuk multi-region eu, lokasi Cloud KMS adalah europe, karena Cloud KMS tidak memiliki lokasi eu. Untuk mengetahui informasi selengkapnya, lihat Lokasi Cloud KMS.

Resource Conversation di multi-region disimpan di region tertentu dalam multi-region tersebut: us-central1 untuk us, dan europe-west1 untuk eu. Kunci harus berada di region tersebut. Misalnya, untuk melindungi resource Conversation yang bernama projects/PROJECT_ID/locations/us/conversations/CONVERSATION_ID, gunakan kunci di lokasi us-central1.

Sebelum memulai

Sebelum Anda dapat menggunakan CMEK dengan Conversational Analytics API, selesaikan langkah-langkah berikut:

  1. Aktifkan API yang diperlukan dalam konsol Google Cloud atau Google Cloud CLI.

    Konsol

    Aktifkan API berikut di konsol Google Cloud untuk project Google Cloud Anda.

    Mengaktifkan Gemini Data Analytics API

    Mengaktifkan Gemini for Google Cloud API

    Mengaktifkan Cloud Key Management Service API

    gcloud

    Dengan Google Cloud CLI, jalankan perintah gcloud services enable berikut untuk mengaktifkan Gemini Data Analytics API, Gemini for Google Cloud API, dan Cloud Key Management Service API:

    gcloud services enable geminidataanalytics.googleapis.com --project=project_id
gcloud services enable cloudaicompanion.googleapis.com --project=project_id
gcloud services enable cloudkms.googleapis.com --project=project_id

    Dalam contoh perintah gcloud CLI sebelumnya, ganti project_id dengan project ID Google Cloud Anda.

  2. Buat key ring dan kunci Cloud KMS di lokasi yang diperlukan untuk resource Conversational Analytics API Anda, seperti yang dijelaskan dalam Persyaratan lokasi kunci. Untuk mengetahui informasi selengkapnya, lihat Membuat kunci.

  3. Buat agen layanan yang dikelola Google, yang juga dikenal sebagai akun layanan per produk per project (P4SA), jika belum ada. Agen layanan ini diperlukan untuk mengizinkan layanan yang terlibat dalam melindungi resource Conversational Analytics API Anda dengan CMEK untuk mengakses kunci Cloud KMS Anda.

    Jalankan perintah gcloud berikut untuk membuat agen layanan: 

    gcloud beta services identity create --service=geminidataanalytics.googleapis.com --project PROJECT_ID
gcloud beta services identity create --service=cloudaicompanion.googleapis.com --project PROJECT_ID
    Ganti PROJECT_ID dengan project ID Google Cloud Anda.

  4. Berikan peran Cloud KMS CryptoKey Encrypter/Decrypter (roles/cloudkms.cryptoKeyEncrypterDecrypter) di Identity and Access Management (IAM) kepada kedua agen layanan yang Anda buat di langkah sebelumnya agar layanan Gemini Data Analytics dapat menggunakan kunci Cloud KMS Anda untuk mengenkripsi dan mendekripsi data Conversational Analytics API Anda. Jika Anda menggunakan lebih dari satu kunci—misalnya, kunci terpisah untuk resource DataAgent dan Conversation di multi-region us atau eu—berikan peran pada setiap kunci.

    Berikan izin ke agen layanan Gemini Data Analytics:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Berikan izin ke agen layanan Gemini for Google Cloud API:

    gcloud kms keys add-iam-policy-binding KEY_NAME \
  --location KEY_LOCATION \
  --keyring KEY_RING_NAME \
  --member
serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudaicompanion. \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project KMS_PROJECT_ID

    Dalam contoh kode sebelumnya, ganti nilai contoh sebagai berikut:

    • KEY_NAME: Nama kunci Cloud KMS Anda.
    • KEY_LOCATION: Region key ring Anda (misalnya, us-east4).
    • KEY_RING_NAME: Nama key ring Anda.
    • PROJECT_NUMBER: Nomor project Google Cloud Anda tempat Anda membuat resource API.
    • KMS_PROJECT_ID: Project ID tempat kunci dibuat. Project ini dapat sama dengan project tempat Anda membuat resource API.

Melindungi resource dengan CMEK

Bagian ini menunjukkan cara melindungi resource DataAgent atau Conversation baru dengan CMEK menggunakan REST API untuk menentukan kunci Cloud KMS di kolom kms_key selama pembuatan resource.

Anda hanya dapat mengaktifkan CMEK saat membuat resource DataAgent atau Conversation.

Lokasi kunci Cloud KMS yang diperlukan bergantung pada jenis dan lokasi resource yang dilindunginya. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.

Melindungi resource DataAgent dengan CMEK

Untuk melindungi resource DataAgent baru dengan CMEK, tentukan kunci Cloud KMS di kolom kms_key saat Anda membuat agen data.

Python SDK

Contoh berikut menunjukkan cara menentukan kunci Cloud KMS saat Anda membuat resource DataAgent dengan Python SDK. Untuk contoh permintaan create lengkap, lihat Membangun agen data menggunakan Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_data_agent = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

data_agent = geminidataanalytics.DataAgent()
data_agent.data_analytics_agent.published_context = published_context
data_agent.kms_key = kms_key_data_agent

Pada contoh sebelumnya, ganti nilai sebagai berikut:

  • BILLING_PROJECT_ID: : Project ID penagihan Anda.
  • KEY_RING_NAME: Nama key ring Cloud KMS Anda.
  • KEY_NAME: Nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Project ID tempat kunci dibuat. Jika dibiarkan kosong, billing_project akan digunakan.
  • LOCATION: Lokasi agen data—misalnya, us, eu, atau us-east4.
  • KEY_LOCATION: Lokasi key ring Anda. Untuk multi-region eu, gunakan europe. Untuk semua lokasi lainnya, gunakan lokasi yang sama dengan LOCATION. Jika dibiarkan kosong, setelan ini akan ditetapkan secara default ke lokasi agen data, yang berfungsi untuk semua lokasi kecuali multi-region eu.

HTTP

Contoh berikut menunjukkan cara menentukan kunci Cloud KMS dalam isi permintaan saat Anda membuat resource DataAgent dengan HTTP dan Python. Untuk contoh permintaan create lengkap, lihat Membangun agen data menggunakan HTTP dan Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the data agent
key_location = "KEY_LOCATION" # Location of your key ring

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      "description": "This is the description of data_agent_1.",
      # If using CMEK, include the kms_key field.
      "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}",
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": looker_data_source,
              "system_instruction": system_instruction,
          }
      }
  }

Pada contoh sebelumnya, ganti nilai sebagai berikut:

  • KEY_RING_NAME: Nama key ring Cloud KMS Anda.
  • KEY_NAME: Nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Project ID tempat kunci dibuat.
  • LOCATION: Lokasi agen data—misalnya, us, eu, atau us-east4.
  • KEY_LOCATION: Lokasi key ring Anda. Untuk multi-region eu, gunakan europe. Untuk semua lokasi lainnya, gunakan lokasi yang sama dengan agen data.

Melindungi resource Conversation dengan CMEK

Untuk melindungi resource Conversation baru dengan CMEK, tentukan kunci Cloud KMS di kolom kms_key saat Anda membuat percakapan.

Python SDK

Contoh berikut menunjukkan cara menentukan kunci Cloud KMS saat Anda membuat resource Conversation dengan Python SDK. Untuk contoh permintaan create lengkap, lihat Membangun agen data menggunakan Python SDK.

# Define the KMS key.
billing_project = "BILLING_PROJECT_ID"
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

if key_project == "":
  key_project = billing_project
if key_location == "":
  key_location = location

kms_key_conversation = f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"

conversation = geminidataanalytics.Conversation()
conversation.agents = [f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"]
conversation.kms_key = kms_key_conversation

Pada contoh sebelumnya, ganti nilai sebagai berikut:

  • BILLING_PROJECT_ID: : Project ID penagihan Anda.
  • KEY_RING_NAME: Nama key ring Cloud KMS Anda.
  • KEY_NAME: Nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Project ID tempat kunci dibuat. Jika dibiarkan kosong, billing_project akan digunakan.
  • LOCATION: Lokasi agen percakapan dan data—misalnya, us, eu, atau us-east4.
  • KEY_LOCATION: Lokasi key ring Anda. Untuk multi-region us, gunakan us-central1. Untuk multi-region eu, gunakan europe-west1. Untuk satu region, gunakan region yang sama dengan LOCATION. Jika dibiarkan kosong, setelan ini akan ditetapkan secara default ke lokasi percakapan, yang hanya berfungsi untuk satu region.

HTTP

Contoh berikut menunjukkan cara menentukan kunci Cloud KMS dalam isi permintaan saat Anda membuat resource Conversation dengan HTTP dan Python. Untuk contoh permintaan create lengkap, lihat Membangun agen data menggunakan HTTP dan Python.

# Define the KMS key.
key_ring = "KEY_RING_NAME"
key_name = "KEY_NAME"
key_project = "KMS_PROJECT_ID" # Project where the key was created
location = "LOCATION" # Location of the conversation and data agent
key_location = "KEY_LOCATION" # Location of your key ring

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
    # If using CMEK, include the kms_key field.
    "kms_key": f"projects/{key_project}/locations/{key_location}/keyRings/{key_ring}/cryptoKeys/{key_name}"
}

Pada contoh sebelumnya, ganti nilai sebagai berikut:

  • KEY_RING_NAME: Nama key ring Cloud KMS Anda.
  • KEY_NAME: Nama kunci Cloud KMS Anda.
  • KMS_PROJECT_ID: Project ID tempat kunci dibuat.
  • LOCATION: Lokasi agen percakapan dan data—misalnya, us, eu, atau us-east4.
  • KEY_LOCATION: Lokasi key ring Anda. Untuk multi-region us, gunakan us-central1. Untuk multi-region eu, gunakan europe-west1. Untuk satu region, gunakan region yang sama dengan percakapan.

Pemecahan masalah

Bagian ini membahas masalah umum dan pertimbangan penting saat Anda menggunakan CMEK dengan Conversational Analytics API.

Perubahan status kunci

Jika versi kunci Cloud KMS yang melindungi resource Conversational Analytics API tidak tersedia, Anda akan kehilangan akses ke data yang dienkripsi oleh kunci tersebut. Jika Anda mencoba mengakses data yang dilindungi saat kunci tidak tersedia, seperti dengan membaca konteks resource DataAgent atau mengakses histori Conversation, permintaan akan gagal. Error yang ditampilkan bergantung pada alasan kunci tidak tersedia:

  • Jika versi kunci dinonaktifkan atau dihancurkan, operasi biasanya akan gagal dengan error FAILED_PRECONDITION.
  • Jika peran IAM cloudkms.cryptoKeyEncrypterDecrypter dicabut dari agen layanan gcp-sa-geminidataanalytics atau gcp-sa-cloudaicompanion, operasi biasanya akan gagal dengan error PERMISSION_DENIED atau NOT_FOUND.

Meskipun kunci tidak tersedia, Anda masih dapat melakukan operasi yang tidak memerlukan dekripsi konten, seperti menghapus resource DataAgent atau Conversation.

Untuk memulihkan akses ke data terenkripsi, aktifkan kembali kunci dan pastikan agen layanan memiliki izin IAM yang diperlukan, seperti yang dijelaskan di bagian Sebelum memulai.

Kuota Cloud KMS dan Conversational Analytics API

Saat Anda menggunakan CMEK di Conversational Analytics API, project Anda dapat memakai kuota permintaan kriptografis Cloud KMS. Misalnya, membaca resource DataAgent atau mengakses histori Conversation yang dilindungi oleh CMEK memerlukan Cloud KMS untuk mendekripsi data.

Operasi enkripsi dan dekripsi yang menggunakan kunci CMEK memengaruhi kuota Cloud KMS dengan cara berikut:

  • Untuk kunci software CMEK yang dihasilkan di Cloud KMS, tidak ada kuota Cloud KMS yang digunakan.
  • Untuk kunci eksternal CMEK—terkadang disebut kunci Cloud EKM —operasi enkripsi dan dekripsi akan mengurangi kuota Cloud EKM dalam project yang berisi kunci tersebut.

Untuk informasi selengkapnya, lihat kuota Cloud KMS.

Langkah berikutnya