Meminta sertifikat

Dokumen ini menjelaskan langkah-langkah untuk meminta sertifikat menggunakan Certificate Authority Service (CAS).

Untuk membangun kepercayaan dan mengamankan komunikasi dalam Google Distributed Cloud (GDC) air-gapped Anda, minta sertifikat yang mengaktifkan atau menonaktifkan ACME dari Certificate Authority Service.

Dokumen ini ditujukan untuk audiens dalam grup operator aplikasi, seperti developer aplikasi atau ilmuwan data, yang mengelola siklus proses sertifikat dalam project mereka. Untuk mengetahui informasi selengkapnya, lihat Audiens untuk dokumentasi GDC air-gapped.

Sebelum memulai

Sebelum dapat meminta sertifikat, Anda harus meminta izin yang diperlukan dan menyiapkan lingkungan.

Meminta peran IAM

Untuk membuat, melihat, dan menghapus permintaan sertifikat, hubungi Admin IAM Organisasi Anda untuk memberi Anda peran CA Service Certificate Requester (certificate-authority-service-certificate-requester) di namespace project certificate authority.

Menyiapkan lingkungan Anda

Meminta sertifikat menggunakan CA dengan mode ACME diaktifkan

Jika certificate authority dihosting dalam mode ACME, certificate authority akan menampilkan URL server ACME dalam statusnya setelah siap.

Kumpulkan URL server ACME CA dari lingkungan Distributed Cloud Anda:

kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'

Ganti kode berikut:

  • CA_NAME: nama CA, yang dapat berupa CA root atau sub-CA
  • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada

Meminta sertifikat menggunakan CA dengan mode ACME dinonaktifkan

Untuk membuat permintaan sertifikat dengan mode ACME dinonaktifkan, Anda harus membuat dan menerapkan resource CertificateRequest ke instance Distributed Cloud air-gapped Anda. Ada dua cara untuk melakukannya:

  • Buat CertificateResource dan sertakan CSR dalam resource.
  • Buat CertificateResource menggunakan kunci pribadi yang dibuat otomatis oleh GDC dan berikan konfigurasi sertifikat sebagai nilai kustom.

Meminta sertifikat menggunakan CSR

  1. Buat resource CertificateRequest dan simpan sebagai file YAML bernama cert-request.yaml. Gunakan kunci pribadi Anda untuk membuat Certificate Signing Request (CSR) dan tambahkan ke resource Anda.

    Secara opsional, Anda dapat menerbitkan sertifikat dengan kumpulan parameter X.509 yang telah dikonfigurasi sebelumnya dengan memasukkan nama template ke dalam kolom certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  csr: CSR
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Ganti variabel berikut:

    Variabel Deskripsi
    CERT_REQ_NAME nama resource CertificateRequest
    USER_PROJECT_NAMESPACE nama namespace tempat project pengguna berada
    CA_NAME nama CA, yang dapat berupa CA root atau sub-CA
    CSR Certificate Signing Request yang akan ditandatangani menggunakan CA
    SECRET_NAME nama Secret Kubernetes yang menyimpan kunci pribadi dan sertifikat CA yang ditandatangani

    Ganti variabel opsional berikut:

    Variabel Deskripsi
    TEMPLATE_NAME nama template sertifikat yang telah ditentukan sebelumnya yang ingin Anda gunakan. Untuk mengetahui daftar template yang tersedia dan detail terkait konflik, lihat Template sertifikat yang telah ditentukan sebelumnya.
    VALIDITY_START_TIME waktu mulai sertifikat dianggap valid. Nilai ini harus dalam format YYYY-MM-DDTHH:MM:SSZ (misalnya, 2025-10-19T21:45:30Z). Jika tidak ditetapkan, sertifikat akan langsung berlaku setelah diterbitkan.
    VALIDITY_END_TIME waktu saat sertifikat berakhir masa berlakunya. Nilai ini harus dalam format YYYY-MM-DDTHH:MM:SSZ (misalnya, 2026-01-17T18:25:40Z). Jika tidak ditetapkan, sertifikat akan berakhir masa berlakunya 90 hari setelah waktu mulainya.
    SUBJECT_OVERRIDE subjek kustom yang akan digunakan dalam sertifikat yang diterbitkan, yang menggantikan informasi subjek dalam CSR. Berikan nilai ini sebagai subjek X.509 mentah yang dienkode ASN.1 DER.

  2. Terapkan resource kustom ke instance Distributed Cloud Anda:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Ganti MANAGEMENT_API_SERVER_KUBECONFIG dengan jalur ke file kubeconfig server Management API.

  3. Verifikasi kesiapan permintaan sertifikat:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Ganti kode berikut:

    • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
    • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada
    • CERT_REQ_NAME nama resource CertificateRequest

    Outputnya mirip dengan hal berikut ini:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Dapatkan nama secret sertifikat:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Ganti kode berikut:

    • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
    • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada
    • CERT_REQ_NAME nama resource CertificateRequest

    Output akan menampilkan SECRET_NAME yang berisi sertifikat yang ditandatangani:

    test-jwk-1

Meminta sertifikat menggunakan kunci yang dibuat otomatis

  1. Buat resource CertificateRequest dan simpan sebagai file YAML bernama cert-request.yaml. Isi nilai yang dipilih untuk sertifikat.

    Secara opsional, Anda dapat menerbitkan sertifikat dengan kumpulan parameter X.509 yang telah dikonfigurasi sebelumnya dengan memasukkan nama template ke dalam kolom certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  certificateConfig:
    subjectConfig:
      commonName: COMMON_NAME
      organization: ORGANIZATION
      locality: LOCALITY
      state: STATE
      country: COUNTRY
      dnsNames:
      - DNS_NAMES
      ipAddresses:
      - IP_ADDRESSES
      rfc822Names:
      - RFC822NAMES
      uris:
      - URIS
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Ganti variabel berikut:

    Variabel Deskripsi
    CERT_REQ_NAME nama resource CertificateRequest
    USER_PROJECT_NAMESPACE nama namespace tempat project pengguna berada
    CA_NAME nama CA, yang dapat berupa CA root atau sub-CA
    SECRET_NAME nama Secret Kubernetes yang menyimpan kunci pribadi dan sertifikat CA yang ditandatangani

    Ganti variabel opsional berikut. Anda harus menyertakan setidaknya satu kolom dari blok spec.certificateConfig.subjectConfig resource CertificateRequest:

    Variabel Deskripsi
    COMMON_NAME nama umum sertifikat
    ORGANIZATION organisasi yang akan digunakan pada sertifikat
    LOCALITY lokalitas sertifikat
    STATE negara bagian atau provinsi yang akan digunakan pada sertifikat
    COUNTRY negara sertifikat
    DNS_NAMES daftar dNSName subjectAltNames yang akan ditetapkan pada sertifikat
    IP_ADDRESS daftar ipAddress subjectAltNames yang akan ditetapkan pada sertifikat
    RFC822_NAMES daftar rfc822Name subjectAltNames yang akan ditetapkan pada sertifikat
    URIS daftar uniformResourceIdentifier subjectAltNames yang akan ditetapkan pada sertifikat
    TEMPLATE_NAME nama template sertifikat yang telah ditentukan sebelumnya yang ingin Anda gunakan. Untuk mengetahui daftar template yang tersedia dan detail terkait konflik, lihat Template sertifikat yang telah ditentukan sebelumnya.
    VALIDITY_START_TIME waktu mulai sertifikat dianggap valid. Nilai ini harus dalam format YYYY-MM-DDTHH:MM:SSZ (misalnya, 2025-10-19T21:45:30Z). Jika tidak ditetapkan, sertifikat akan langsung berlaku setelah diterbitkan.
    VALIDITY_END_TIME waktu saat sertifikat berakhir masa berlakunya. Nilai ini harus dalam format YYYY-MM-DDTHH:MM:SSZ (misalnya, 2026-01-17T18:25:40Z). Jika tidak ditetapkan, sertifikat akan berakhir masa berlakunya 90 hari setelah waktu mulainya.
    SUBJECT_OVERRIDE subjek kustom yang akan digunakan dalam sertifikat yang diterbitkan, yang menggantikan informasi subjek dalam CSR. Berikan nilai ini sebagai subjek X.509 mentah yang dienkode ASN.1 DER.

  2. Terapkan resource kustom ke instance Distributed Cloud Anda:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Ganti MANAGEMENT_API_SERVER_KUBECONFIG dengan jalur ke file kubeconfig server Management API.

  3. Verifikasi kesiapan permintaan sertifikat:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Ganti kode berikut:

    • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
    • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada
    • CERT_REQ_NAME nama resource CertificateRequest

    Outputnya mirip dengan hal berikut ini:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Dapatkan nama secret sertifikat:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Ganti kode berikut:

    • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
    • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada
    • CERT_REQ_NAME: nama resource CertificateRequest

    Output akan menampilkan SECRET_NAME yang berisi sertifikat yang ditandatangani:

    test-jwk-1

Mencantumkan permintaan sertifikat

Gunakan parameter certificaterequests untuk mencantumkan semua resource CertificateRequest:

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog

Ganti kode berikut:

  • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
  • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada

Berikut adalah contoh perintah menggunakan namespace agtest-project:

kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig  -n agtest-project get certificaterequest.pki.security.gdc.goog

Output yang diharapkan mirip dengan hal berikut ini:

NAME                                               READY   AGE
test-externalca-subca-cert-req-with-csr            True    17h
test-externalca-subca-cert-req-with-csr-override   True    17h

Menghapus sertifikat

Untuk menghapus sertifikat, Anda harus menghapus resource kustom CertificateRequest yang sesuai. Tindakan ini akan menghapus resource dari database CAS.

  1. Temukan nama CertificateRequest yang ingin Anda hapus. Anda dapat mencantumkan permintaan sertifikat untuk membantu menemukan nama.

  2. Hapus resource CertificateRequest:

    kubectl --kubeconfig  MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME

    Ganti kode berikut:

    • MANAGEMENT_API_SERVER_KUBECONFIG: jalur ke file kubeconfig server Management API
    • USER_PROJECT_NAMESPACE: nama namespace tempat project pengguna berada
    • CERT_REQ_NAME: nama resource CertificateRequest

Batas dan pembersihan permintaan sertifikat

Untuk membantu menjaga stabilitas sistem dan mencegah penggunaan resource yang tinggi, CAS menerapkan batas pada jumlah resource kustom CertificateRequest dan menawarkan fitur pembersihan otomatis opsional.

Kuota permintaan sertifikat

CAS menerapkan kuota pada jumlah resource kustom CertificateRequest per organisasi, dengan batas default 5.000. Melebihi batas ini dapat menurunkan performa CAS dan Server Management API.

Saat jumlah total resource CertificateRequest mendekati kuota (misalnya, pada 80% dan 90% batas), Anda akan melihat peringatan dalam output perintah saat membuat permintaan baru. Jika Anda mencoba membuat CertificateRequest setelah kuota tercapai, permintaan akan ditolak. Anda mungkin melihat pesan error yang mirip dengan berikut ini:

Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue

Jika Anda mengalami error ini, Anda mungkin perlu menghapus resource yang lama atau tidak diperlukan.CertificateRequest Untuk menyesuaikan kuota, hubungi anggota grup operator infrastruktur dalam organisasi Anda. Mereka dapat mengganti kuota dengan mengikuti petunjuk dalam runbook PLATAUTH-G2102.

Pembersihan otomatis

Anda dapat mengaktifkan pembersihan otomatis untuk menghapus resource CertificateRequest yang masa berlakunya telah berakhir. Fitur ini membantu mengosongkan resource dengan menghapusnya setelah masa tenggang yang dapat dikonfigurasi. Masa tenggang menentukan jangka waktu antara masa berlaku sertifikat berakhir dan saat resource CertificateRequest dihapus.

Pembersihan otomatis dinonaktifkan secara default. Anggota grup operator infrastruktur dalam organisasi Anda dapat mengaktifkan fitur ini dan mengonfigurasi masa tenggang dengan mengikuti petunjuk dalam runbook PLATAUTH-G2103. Fitur ini akan tetap dinonaktifkan jika masa tenggang tidak ditetapkan atau ditetapkan ke nol.