בקשת אישור

במאמר הזה מוסבר איך לבקש אישור באמצעות שירות רשות האישורים (CAS).

כדי ליצור תקשורת מאובטחת ואמינה ב-Google Distributed Cloud (GDC)‎ עם air gap, צריך לבקש אישור עם או בלי ACME מ-Certificate Authority Service.

המסמך הזה מיועד למשתמשים בקבוצת מפעילי האפליקציות, כמו מפתחי אפליקציות או מדעני נתונים, שמנהלים את מחזורי החיים של האישורים בפרויקט שלהם. מידע נוסף מופיע במאמר קהלים למסמכי תיעוד של GDC עם air gap.

לפני שמתחילים

כדי לבקש אישור, צריך לבקש את ההרשאות הנדרשות ולהכין את הסביבה.

בקשת תפקידים ב-IAM

כדי ליצור, להציג ולמחוק בקשות לאישורים, צריך לבקש מהאדמין של הארגון ב-IAM להקצות לכם את התפקיד מבקש אישורים של שירות CA (certificate-authority-service-certificate-requester) במרחב השמות של הפרויקט של רשות האישורים.

הכנת הסביבה

בקשת אישור באמצעות רשות אישורים (CA) עם מצב ACME מופעל

אם רשות האישורים מתארחת במצב ACME, היא מפיקה את כתובת ה-URL של שרת ACME בסטטוס שלה אחרי שהיא מוכנה.

אוספים את כתובת ה-URL של שרת ה-CA ACME מסביבת Distributed Cloud:

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

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CA_NAME: השם של ה-CA, שיכול להיות רשות אישורים ברמה הבסיסית או רשות אישורים משנית
  • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש

בקשת אישור באמצעות רשות אישורים (CA) כשמצב ACME מושבת

כדי ליצור בקשת אישור כשמצב ACME מושבת, צריך ליצור משאב CertificateRequest ולהחיל אותו על המכונה של Distributed Cloud air-gapped. יש שתי דרכים לעשות את זה:

  • יוצרים CertificateResource וכוללים CSR במשאב.
  • יוצרים CertificateResource באמצעות מפתח פרטי שנוצר אוטומטית ב-GDC, ומספקים את הגדרות האישור כערכים בהתאמה אישית.

בקשת אישור באמצעות CSR

  1. יוצרים משאב CertificateRequest ושומרים אותו כקובץ YAML בשם cert-request.yaml. משתמשים במפתח הפרטי כדי ליצור בקשה לחתימה על אישור (CSR) ומוסיפים אותה למשאב.

    אפשר גם להנפיק את האישור עם קבוצה מוגדרת מראש של פרמטרים מסוג X.509, על ידי הזנת שם התבנית בשדה 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

    מחליפים את המשתנים הבאים:

    משתנה תיאור
    CERT_REQ_NAME השם של המשאב CertificateRequest
    USER_PROJECT_NAMESPACE שם מרחב השמות שבו נמצא פרויקט המשתמש
    CA_NAME שם ה-CA, שיכול להיות CA ברמה הבסיסית (root) או ברמת המשנה (sub)
    CSR בקשת החתימה על האישור (CSR) לחתימה באמצעות רשות האישורים (CA)
    SECRET_NAME השם של Kubernetes Secret שמכיל את המפתח הפרטי ואת אישור ה-CA החתום

    מחליפים את המשתנים האופציונליים הבאים:

    משתנה תיאור
    TEMPLATE_NAME שם תבנית האישור המוגדרת מראש שבה רוצים להשתמש. כאן תוכלו למצוא רשימה של תבניות זמינות ופרטים על התנגשויות.
    VALIDITY_START_TIME הזמן שבו האישור נחשב לתקף. הערך הזה צריך להיות בפורמט YYYY-MM-DDTHH:MM:SSZ (לדוגמה, 2025-10-19T21:45:30Z). אם לא מגדירים את הערך, האישור תקף מיד אחרי ההנפקה.
    VALIDITY_END_TIME השעה שבה פג תוקף האישור. הערך הזה צריך להיות בפורמט YYYY-MM-DDTHH:MM:SSZ (לדוגמה, 2026-01-17T18:25:40Z). אם לא מגדירים את הערך, תוקף האישור יפוג 90 יום אחרי שעת ההתחלה שלו.
    SUBJECT_OVERRIDE נושא מותאם אישית לשימוש באישור שהונפק, שמחליף את פרטי הנושא ב-CSR. צריך לספק את הערך הזה כנושא X.509 גולמי, בקידוד ASN.1 DER.

  2. מחילים את המשאב בהתאמה אישית על המכונה של Distributed Cloud:

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

    מחליפים את MANAGEMENT_API_SERVER_KUBECONFIG בנתיב לקובץ kubeconfig של שרת Management API.

  3. מוודאים שהבקשה לאישור מוכנה:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
    • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש
    • ‫CERT_REQ_NAME השם של המשאב ב-CertificateRequest

    הפלט אמור להיראות כך:

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

  4. משיגים את שם הסוד של האישור:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
    • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש
    • ‫CERT_REQ_NAME השם של המשאב ב-CertificateRequest

    הפלט מציג את SECRET_NAME שמכיל את האישור החתום:

    test-jwk-1

בקשת אישור באמצעות מפתח שנוצר אוטומטית

  1. יוצרים משאב CertificateRequest ושומרים אותו כקובץ YAML בשם cert-request.yaml. ממלאים את הערכים שנבחרו לאישור.

    אפשר גם להנפיק את האישור עם קבוצה מוגדרת מראש של פרמטרים מסוג X.509, על ידי הזנת שם התבנית בשדה 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

    מחליפים את המשתנים הבאים:

    משתנה תיאור
    CERT_REQ_NAME השם של המשאב CertificateRequest
    USER_PROJECT_NAMESPACE שם מרחב השמות שבו נמצא פרויקט המשתמש
    CA_NAME שם ה-CA, שיכול להיות CA ברמה הבסיסית (root) או ברמת המשנה (sub)
    SECRET_NAME השם של Kubernetes Secret שמכיל את המפתח הפרטי ואת אישור ה-CA החתום

    מחליפים את המשתנים האופציונליים הבאים. צריך לכלול לפחות אחד מהשדות מהבלוק spec.certificateConfig.subjectConfig של המשאב CertificateRequest:

    משתנה תיאור
    COMMON_NAME השם הנפוץ של האישור
    ORGANIZATION הארגון שיופיע באישור
    LOCALITY היישוב של האישור
    STATE מדינה (State) או מחוז שיופיעו באישור
    COUNTRY המדינה שבה הונפק האישור
    DNS_NAMES רשימה של dNSName subjectAltNames שצריך להגדיר באישור
    IP_ADDRESS רשימה של ipAddress subjectAltNames שצריך להגדיר באישור
    RFC822_NAMES רשימה של rfc822Name subjectAltNames שצריך להגדיר באישור
    URIS רשימה של uniformResourceIdentifier subjectAltNames שצריך להגדיר באישור
    TEMPLATE_NAME שם תבנית האישור המוגדרת מראש שבה רוצים להשתמש. כאן תוכלו למצוא רשימה של תבניות זמינות ופרטים על התנגשויות.
    VALIDITY_START_TIME הזמן שבו האישור נחשב לתקף. הערך הזה צריך להיות בפורמט YYYY-MM-DDTHH:MM:SSZ (לדוגמה, 2025-10-19T21:45:30Z). אם לא מגדירים את הערך, האישור תקף מיד אחרי ההנפקה.
    VALIDITY_END_TIME השעה שבה פג תוקף האישור. הערך הזה צריך להיות בפורמט YYYY-MM-DDTHH:MM:SSZ (לדוגמה, 2026-01-17T18:25:40Z). אם לא מגדירים את הערך, תוקף האישור יפוג 90 יום אחרי שעת ההתחלה שלו.
    SUBJECT_OVERRIDE נושא מותאם אישית לשימוש באישור שהונפק, שמחליף את פרטי הנושא ב-CSR. צריך לספק את הערך הזה כנושא X.509 גולמי, בקידוד ASN.1 DER.

  2. מחילים את המשאב בהתאמה אישית על המכונה של Distributed Cloud:

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

    מחליפים את MANAGEMENT_API_SERVER_KUBECONFIG בנתיב לקובץ kubeconfig של שרת Management API.

  3. מוודאים שהבקשה לאישור מוכנה:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
    • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש
    • ‫CERT_REQ_NAME השם של המשאב ב-CertificateRequest

    הפלט אמור להיראות כך:

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

  4. משיגים את שם הסוד של האישור:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
    • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש
    • ‫CERT_REQ_NAME: השם של המשאב ב-CertificateRequest

    הפלט מציג את SECRET_NAME שמכיל את האישור החתום:

    test-jwk-1

הצגת רשימה של בקשות לאישורים

משתמשים בפרמטר certificaterequests כדי להציג את כל המשאבים של CertificateRequest:

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

מחליפים את מה שכתוב בשדות הבאים:

  • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
  • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש

הדוגמה הבאה מראה פקודה לדוגמה באמצעות מרחב השמות agtest-project:

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

הפלט הצפוי אמור להיראות כך:

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

מחיקת אישור

כדי למחוק אישור, צריך למחוק את המשאב המותאם אישית התואם של CertificateRequest. הפעולה הזו מסירה את המשאב ממסד הנתונים של CAS.

  1. מוצאים את השם של CertificateRequest שרוצים למחוק. כדי למצוא את השם, אפשר להציג רשימה של בקשות לאישורים.

  2. מוחקים את המשאב CertificateRequest:

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

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫MANAGEMENT_API_SERVER_KUBECONFIG: הנתיב לקובץ kubeconfig של שרת Management API
    • ‫USER_PROJECT_NAMESPACE: השם של מרחב השמות שבו נמצא פרויקט המשתמש
    • ‫CERT_REQ_NAME: השם של המשאב ב-CertificateRequest

מגבלות על בקשות לאישורים וניקוי

כדי לשמור על יציבות המערכת ולמנוע שימוש רב במשאבים, שירות CAS אוכף מגבלות על מספר המשאבים המותאמים אישית של CertificateRequest ומציע תכונה אופציונלית לניקוי אוטומטי.

מכסת הבקשות לאישורים

שירות CAS אוכף מכסה על מספר המשאבים המותאמים אישית של CertificateRequest לכל ארגון, עם מגבלה שמוגדרת כברירת מחדל של 5,000. חריגה מהמגבלה הזו עלולה לפגוע בביצועים של שרת ה-API לניהול ושל CAS.

כשהמספר הכולל של משאבי CertificateRequest מתקרב למכסה (לדוגמה, ב-80% וב-90% מהמגבלה), יופיעו אזהרות בפלט הפקודה כשתיצרו בקשות חדשות. אם תנסו ליצור CertificateRequest אחרי שתגיעו למכסה, הבקשה תידחה. יכול להיות שתופיע הודעת שגיאה דומה לזו:

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

אם נתקלתם בשגיאה הזו, יכול להיות שתצטרכו למחוק משאבי CertificateRequest ישנים או מיותרים. כדי לשנות את המכסה, פנו לחבר בקבוצת מפעילי התשתית בארגון שלכם. הם יכולים לשנות את המכסה לפי ההוראות במדריך ההפעלה PLATAUTH-G2102.

ניקוי אוטומטי

אתם יכולים להפעיל ניקוי אוטומטי כדי למחוק משאבי CertificateRequest שפג תוקפם. התכונה הזו עוזרת לפנות משאבים על ידי הסרה שלהם אחרי תקופת חסד שניתן להגדיר. תקופת החסד מגדירה את משך הזמן שעובר בין תפוגת התוקף של האישור לבין מחיקת המשאב CertificateRequest.

ניקוי אוטומטי מושבת כברירת מחדל. חבר בקבוצת מפעילי התשתית בארגון יכול להפעיל את התכונה הזו ולהגדיר את תקופת החסד לפי ההוראות במדריך ההפעלה PLATAUTH-G2103. התכונה תישאר מושבתת אם תקופת החסד לא מוגדרת או מוגדרת כ-0.