תחילת העבודה עם Cloud Endpoints for Kubernetes באמצעות ESP

במדריך הזה נסביר איך להגדיר ולפרוס API לדוגמה ואת Extensible Service Proxy ‏ (ESP) לאשכול Kubernetes שלא נמצא ב- Google Cloud. אם רוצים להשתמש ב-Google Kubernetes Engine‏ (GKE), אפשר להיעזר במאמר תחילת העבודה עם Endpoints ב-GKE.

ממשק ה-API לדוגמה מתואר באמצעות מפרט OpenAPI. במדריך מוסבר גם איך ליצור מפתח API כדי לשלוח בקשות ל-API.

במדריך הזה נעשה שימוש בקובצי אימג' של קונטיינרים שנבנו מראש של קוד לדוגמה ושל ESP, שמאוחסנים ב-Artifact Registry. אם אתם לא מכירים את המושג 'מאגרי תגים', תוכלו לקרוא מידע נוסף במאמרים הבאים:

סקירה כללית של Cloud Endpoints זמינה במאמרים מידע על Endpoints וארכיטקטורת Endpoints.

מטרות

במהלך העבודה עם המדריך, תוכלו להשתמש ברשימת המשימות הכללית הבאה. כדי לשלוח בקשות ל-API בהצלחה, צריך לבצע את כל המשימות בחלק 1.

חלק 1

  1. מגדירים Google Cloud פרויקט. לפני שמתחילים
  2. מתקינים ומגדירים את התוכנה שמשמשת במדריך. מידע נוסף זמין במאמר בנושא התקנה והגדרה של תוכנה נדרשת.
  3. אפשר גם להוריד את הקוד לדוגמה. קבלת קוד לדוגמה
  4. מורידים את קובץ ההגדרות של Kubernetes. איך מקבלים קובץ תצורה של Kubernetes
  5. מגדירים את הקובץ openapi.yaml, שמשמש להגדרת Endpoints. איך מגדירים נקודות קצה
  6. פורסים את ההגדרה של Endpoints כדי ליצור שירות Cloud Endpoints. איך פורסים את ההגדרה של נקודות הקצה
  7. יוצרים פרטי כניסה לשירות Endpoints. מידע נוסף זמין במאמר יצירת פרטי כניסה לשירות.
  8. פורסים את ה-API ואת ESP באשכול. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
  9. קבלת כתובת ה-IP החיצונית של השירות. איך מקבלים את כתובת ה-IP החיצונית
  10. שליחת בקשה ל-API באמצעות כתובת IP. איך שולחים בקשה באמצעות כתובת IP
  11. מעקב אחר פעילות ב-API. מידע נוסף מופיע במאמר בנושא מעקב אחר פעילות של API.

חלק 2

  1. הגדרת רשומת DNS עבור ה-API לדוגמה. מידע נוסף מופיע במאמר בנושא הגדרת DNS לנקודות קצה.
  2. שולחים בקשה ל-API באמצעות שם הדומיין. איך שולחים בקשה באמצעות FQDN

ניקוי

כשמסיימים, כדאי לעיין בקטע ניקוי כדי להימנע מחיובים בחשבון Google Cloud .

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

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

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.

התקנה והגדרה של תוכנה נדרשת

במדריך הזה מוסבר איך להתקין את Google Cloud CLI כדי להשתמש ב-ה-CLI של gcloud לניהול הפרויקט. משתמשים ב-kubectl, ממשק שורת פקודה, כדי להריץ פקודות באשכולות Kubernetes. צריך גם דרך לבדוק את ה-API.

אם כבר התקנתם את התוכנה הנדרשת, אתם יכולים להמשיך לשלב הבא.

כדי להתקין ולהגדיר את התוכנה הנדרשת:

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

    • משתמשי Linux ו-macOS: במדריך הזה יש דוגמה לשימוש ב-curl, שבדרך כלל מותקן מראש במערכת ההפעלה. אם אין לכם את curl, אתם יכולים להוריד אותו מcurl דף ההורדות והגרסאות.
    • משתמשי Windows: במדריך הזה יש דוגמה לשימוש ב-Invoke-WebRequest, שנתמך ב-PowerShell 3.0 ואילך.
  2. מתקינים ומפעילים את ה-CLI של gcloud.
  3. מעדכנים את ה-CLI של gcloud ומתקינים את רכיבי Endpoints: 
    gcloud components update
  4. מוודאים ש-Google Cloud CLI ‏ (gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud: 
    gcloud auth login
     בכרטיסייה החדשה שנפתחת, בוחרים חשבון.
  5. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט: 
    gcloud config set project YOUR_PROJECT_ID

    מחליפים את YOUR_PROJECT_ID במזהה הפרויקט. אם יש לכם פרויקטים אחרים Google Cloud ואתם רוצים להשתמש ב-gcloudכדי לנהל אותם, תוכלו לקרוא את המאמר בנושא ניהול ההגדרות האישיות של ה-CLI של gcloud.

  6. התקנה של kubectl: 
    gcloud components install kubectl
  7. קבלת פרטי כניסה חדשים של משתמשים לשימוש ב-Application Default Credentials. פרטי הכניסה של המשתמש מאשרים את kubectl. 
    gcloud auth application-default login
  8. בכרטיסייה החדשה שנפתחת, בוחרים חשבון.
  9. מריצים את הפקודה הבאה כדי לוודא שלקוח Kubernetes מוגדר כמו שצריך: 
    kubectl version

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

       Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
     GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
     BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
     Platform:"linux/amd64"}
   Server Version: version.Info{Major:"1", Minor:"7+",
     GitVersion:"v1.7.8-gke.0",
     GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
     BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
     Platform:"linux/amd64"}

הורדת הקוד לדוגמה

אפשר גם להוריד את הקוד לדוגמה. במדריך הזה תפרסו קובץ אימג' של קונטיינר מוכן מראש, כך שלא תצטרכו ליצור קונטיינר מקוד לדוגמה. עם זאת, יכול להיות שתרצו להוריד את קוד הדוגמה, שזמין בכמה שפות, כדי להבין איך ה-API לדוגמה פועל.

כדי להוריד את הקוד לדוגמה:

Java

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd java-docs-samples/endpoints/getting-started
Python

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd python-docs-samples/endpoints/getting-started
Go

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. מוודאים שמשתנה הסביבה GOPATH מוגדר.
  2. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd php-docs-samples/endpoints/getting-started
Ruby

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

כדי לשכפל או להוריד את ה-API לדוגמה:

  1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית: 
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את הקוד לדוגמה: 
    cd nodejs-docs-samples/endpoints/getting-started

קבלת קובץ התצורה של Kubernetes

  1. משכפלים את מאגר GitHub שמכיל את הקבצים yaml שמשמשים במדריך הזה למחשב המקומי:

     git clone https://github.com/googlecloudplatform/endpoints-samples

    אפשרות אחרת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

  2. עוברים לספרייה שמכילה את קובצי ההגדרות:

     cd endpoints-samples/kubernetes

הגדרת נקודות קצה

צריך ליצור מסמך OpenAPI שמבוסס על OpenAPI 2.0 או על OpenAPI 3.x, ומתאר את הסביבה של האפליקציות ואת דרישות האימות. מידע נוסף זמין במאמר גרסאות נתמכות של OpenAPI.

צריך גם להוסיף שדה ספציפי ל-Google שמכיל את כתובת ה-URL של כל אפליקציה, כדי של-ESPv2 יהיה המידע שהוא צריך כדי להפעיל אפליקציה. אם אתם חדשים ב-OpenAPI, תוכלו לקרוא מידע נוסף בסקירה כללית של OpenAPI.

כדי להגדיר נקודות קצה:

  1. יוצרים קובץ טקסט חדש בשם openapi.yaml. לנוחותכם, בדף הזה אנחנו מתייחסים למסמך OpenAPI לפי שם הקובץ הזה, אבל אתם יכולים לתת לו שם אחר אם אתם מעדיפים.
  2. מעתיקים את התוכן של אחד מהקבצים הבאים לקובץ openapi.yaml החדש. אפשר להשתמש ב-OpenAPI 2.0 או ב-OpenAPI 3.x.

    OpenAPI 2.0

    swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"

host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"

consumes:
  - "application/json"
produces:
  - "application/json"

schemes:
# Uncomment the next line if you configure SSL for this API.
# - "https"
  - "http"

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
        - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
        -
          description: "Message to echo"
          in: body
          name: message
          required: true
          schema:
            $ref: "#/definitions/echoMessage"
      security:
        - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
        - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      security:
        - api_key: []
          google_jwt: []
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
        - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      security:
        - api_key: []
          google_id_token: []

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"

  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
    # This must match the "aud" field in the JWT. You can add multiple
    # audiences to accept JWTs from multiple clients.
    x-google-audiences: "echo.endpoints.sample.google.com"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.

  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    # Your OAuth2 client's Client ID must be added here. You can add
    # multiple client IDs to accept tokens from multiple clients.
    x-google-audiences: "YOUR_CLIENT_ID"

    ‫OpenAPI 3.x

    openapi: 3.0.4
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
servers:
  - url: "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoint: {}

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      requestBody:
        description: "Message to echo"
        required: true
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/echoMessage"
      responses:
        '200':
          description: "Echo"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/echoMessage"
      security:
        securitySchemes
        - api_key: []

  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      responses:
        '200':
          description: "Authentication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - api_key: []
          google_jwt: []

  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      responses:
        '200':
          description: "Authentication info."
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/authInfoResponse"
      security:
        - api_key: []
          google_id_token: []

components:
  schemas:
    echoMessage:
      type: "object"
      properties:
        message:
          type: "string"
    authInfoResponse:
      properties:
        id:
          type: "string"
        email:
          type: "string"

  securitySchemes:
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

    google_jwt:
      type: "oauth2"
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "jwt-client.endpoints.sample.google.com"
        jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
        audiences: "echo.endpoints.sample.google.com"

    google_id_token:
      type: "oauth2"
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "https://accounts.google.com"
        jwksUri: "https://www.googleapis.com/oauth2/v3/certs"
        audiences:
          - "YOUR_CLIENT_ID"

במדריך הזה נעשה שימוש בתוסף ספציפי ל-Google למפרט OpenAPI, שמאפשר להגדיר את שם השירות. השיטה לציון שם השירות תלויה בגרסה של מפרט OpenAPI שבה אתם משתמשים.

OpenAPI 2.0

משתמשים בשדה host כדי לציין את שם השירות:

host: echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog

כדי להגדיר נקודות קצה:

  1. פותחים את הקובץ openapi.yaml.
  2. בשדה host, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב- Google Cloud .
  3. שומרים את קובץ ה-openapi.yaml.

‫OpenAPI 3.x

משתמשים בשדה url באובייקט servers כדי לציין את שם השירות:

servers:
- url: https://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
  x-google-endpoint: {}

כדי להגדיר נקודות קצה:

  1. פותחים את הקובץ openapi.yaml.
  2. אם בקובץ openapi.yaml יש שדה host, צריך להסיר אותו.
  3. מוסיפים אובייקט servers כמו שמוצג.
  4. בשדה url, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב- Google Cloud .
  5. שומרים את קובץ ה-openapi.yaml.

אחרי שמסיימים את כל שלבי ההגדרה הבאים כך שאפשר לשלוח בקשות ל-API לדוגמה באמצעות כתובת IP, אפשר לעיין במאמר הגדרת DNS של נקודות קצה כדי לקבל מידע על הגדרת echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog כשם הדומיין שמוגדר במלואו (FQDN).

פריסת ההגדרה של נקודות הקצה

כדי לפרוס את ההגדרה של Endpoints, משתמשים בפקודה gcloud endpoints services deploy. הפקודה הזו משתמשת ב-Service Management כדי ליצור שירות מנוהל.

כדי לפרוס את ההגדרה של Endpoints:

  1. מוודאים שאתם נמצאים בספרייה שבה נמצא קובץ ההגדרות openapi.yaml.
  2. מעלים את ההגדרה ויוצרים שירות מנוהל: 
    gcloud endpoints services deploy openapi.yaml

הפקודה gcloud קוראת ל-Service Management API כדי ליצור שירות מנוהל עם השם שציינתם בשדה host או servers.url בקובץ openapi.yaml. שירות ניהול השירותים מגדיר את השירות בהתאם להגדרות בקובץ openapi.yaml. כשמבצעים שינויים ב-openapi.yaml, צריך לפרוס מחדש את הקובץ כדי לעדכן את שירות נקודות הקצה.

במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. אפשר להתעלם בבטחה מהאזהרות לגבי הנתיבים בקובץ openapi.yaml שלא דורשים מפתח API. בסיום הגדרת השירות, Service Management מציג הודעה עם מזהה הגדרת השירות ושם השירות, בדומה להודעה הבאה:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

בדוגמה שלמעלה, 2017-02-13r0 הוא מזהה הגדרת השירות ו-echo-api.endpoints.example-project-12345.cloud.goog הוא שירות ה-Endpoints. מזהה הגדרות השירות מורכב מחותמת תאריך וממספר גרסה. אם תפעילו את הקובץ openapi.yaml שוב באותו יום, מספר הגרסה יוגדל במזהה תצורת השירות. אפשר לראות את הגדרת השירות של Endpoints בדף Endpoints > Services במסוף Google Cloud .

אם מופיעה הודעת שגיאה, אפשר לעיין במאמר בנושא פתרון בעיות בהטמעה של הגדרות Endpoints.

בדיקת השירותים הנדרשים

לפחות, צריך להפעיל את שירותי Google הבאים כדי להשתמש ב-Endpoints וב-ESP:
שם כותרת
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

ברוב המקרים, הפקודה gcloud endpoints services deploy מפעילה את השירותים הנדרשים האלה. עם זאת, הפקודה gcloud מסתיימת בהצלחה אבל לא מפעילה את השירותים הנדרשים בנסיבות הבאות:

  • אם השתמשתם באפליקציה של צד שלישי כמו Terraform ולא כללתם את השירותים האלה.

  • הפריסה של הגדרת ה-Endpoints בוצעה בפרויקטGoogle Cloud קיים שבו השירותים האלה הושבתו באופן מפורש.

כדי לוודא שהשירותים הנדרשים מופעלים, משתמשים בפקודה הבאה:

gcloud services list

אם השירותים הנדרשים לא מופיעים ברשימה, צריך להפעיל אותם:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

צריך גם להפעיל את שירות Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

כדי לדעת מהו ENDPOINTS_SERVICE_NAME, אפשר:

  • אחרי פריסת ההגדרה של Endpoints, נכנסים לדף Endpoints במסוף Cloud. רשימת האפשרויות האפשריות של ENDPOINTS_SERVICE_NAME מוצגת בעמודה שם השירות.

  • ב-OpenAPI, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה host במפרט OpenAPI. ב-gRPC, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה name בהגדרות של נקודות הקצה של gRPC.

מידע נוסף על פקודות gcloud זמין במאמר שירותי gcloud.

יצירת פרטי כניסה לשירות

כדי לספק ניהול של ה-API, גם ESP וגם ESPv2 דורשים את השירותים ב-Service Infrastructure. כדי לקרוא לשירותים האלה, ESP ו-ESPv2 צריכים להשתמש באסימוני גישה. כשפורסים את ESP או ESPv2 בסביבות כמו GKE,‏ Compute Engine או הסביבה הגמישה של App Engine,‏ ESP ו-ESPv2 מקבלים בשבילכם אסימוני גישה דרך שירות המטא-נתונים. Google Cloud Google Cloud

כשפורסים את ESP או ESPv2 בסביבה שאינהGoogle Cloud , כמו שולחן העבודה המקומי, אשכול Kubernetes מקומי או ספק אחר של שירותי ענן, צריך לספק קובץ JSON של חשבון שירות שמכיל מפתח פרטי. ‫ESP ו-ESPv2 משתמשים בחשבון שירות כדי ליצור אסימוני גישה לקריאה לשירותים שהם צריכים כדי לנהל את ה-API שלכם.

אפשר להשתמש במסוף Google Cloud או ב-Google Cloud CLI כדי ליצור את חשבון השירות ואת קובץ המפתח הפרטי:

המסוף

  1. במסוף Google Cloud , פותחים את הדף Service Accounts .

    מעבר לדף 'חשבונות שירות'

  2. לוחצים על Select a project (בחירת פרויקט).
  3. בוחרים את הפרויקט שבו נוצר ה-API ולוחצים על Open.
  4. לוחצים על + יצירת חשבון שירות.
  5. בשדה Service account name, מזינים את השם של חשבון השירות.
  6. לוחצים על יצירה.
  7. לוחצים על Continue.
  8. לוחצים על סיום.
  9. לוחצים על כתובת האימייל של חשבון השירות החדש שנוצר.
  10. לוחצים על Keys.
  11. לוחצים על Add key ואז על Create new key.

  12. לוחצים על יצירה. למחשב שלכם תתבצע הורדה של קובץ JSON עם המפתח.

    חשוב לאחסן את קובץ המפתח באופן מאובטח כי הוא יכול לשמש לצורך אימות כחשבון השירות שלכם. אפשר להעביר את הקובץ לאן שרוצים ולשנות את השם שלו למה שרוצים.

  13. לוחצים על Close.

gcloud

  1. מזינים את הפקודה הבאה כדי להציג את מזהי הפרויקטים שלGoogle Cloud הפרויקטים:

    gcloud projects list

  2. מחליפים את PROJECT_ID בפקודה הבאה כדי להגדיר את פרויקט ברירת המחדל לפרויקט שבו נמצא ה-API:

    gcloud config set project PROJECT_ID

  3. מוודאים ש-Google Cloud CLI ‏ (gcloud) מורשה לגשת לנתונים ולשירותים שלכם ב- Google Cloud:

    gcloud auth login

    אם יש לכם יותר מחשבון אחד, הקפידו לבחור את החשבון שמשויך ל Google Cloud פרויקט שבו ה-API נמצא. אם מריצים את הפקודה gcloud auth list, החשבון שבחרתם מוצג כחשבון הפעיל של הפרויקט.

  4. כדי ליצור חשבון שירות, מריצים את הפקודה הבאה ומחליפים את SERVICE_ACCOUNT_NAME ואת My Service Account בשם ובשם התצוגה שרוצים להשתמש בהם:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"

    הפקודה מקצה כתובת אימייל לחשבון השירות בפורמט הבא:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    כתובת האימייל הזו נדרשת בפקודות הבאות.

  5. יוצרים קובץ מפתח של חשבון שירות:

    gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

מוסיפים את התפקידים הנדרשים ב-IAM:

בקטע הזה מתוארים משאבי ה-IAM שמשמשים את ESP ו-ESPv2, ותפקידי ה-IAM שנדרשים לחשבון השירות המצורף כדי לגשת למשאבים האלה.

הגדרת שירות נקודות קצה

‫ESP ו-ESPv2 קוראים ל-Service Control API, שמשתמש בהגדרות השירות של נקודת הקצה. הגדרת שירות נקודת הקצה היא משאב IAM, ו-ESP ו-ESPv2 צריכים את התפקיד Service Controller כדי לגשת אליו.

תפקיד ה-IAM מוגדר בהגדרות של שירות נקודת הקצה, ולא בפרויקט. יכול להיות שלפרויקט יש כמה הגדרות של שירות נקודות קצה.

משתמשים בפקודה הבאה ב-gcloud כדי להוסיף את התפקיד לחשבון השירות המצורף להגדרת שירות נקודת הקצה.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

כאשר
* SERVICE_NAME הוא שם שירות נקודת הקצה
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com הוא חשבון השירות המצורף.

Cloud Trace

‫ESP ו-ESPv2 קוראים לשירות Cloud Trace כדי לייצא את הנתונים של Trace לפרויקט. הפרויקט הזה נקרא פרויקט המעקב. ב-ESP, פרויקט המעקב והפרויקט שבבעלותו הגדרות השירות של נקודת הקצה הם אותו פרויקט. ב-ESPv2, אפשר לציין את פרויקט המעקב באמצעות הדגל --tracing_project_id, ופרויקט הפריסה מוגדר כברירת מחדל.

כדי להפעיל את Cloud Trace, צריך להקצות ל-ESP ול-ESPv2 את התפקיד Cloud Trace Agent.

משתמשים בפקודה הבאה ב-gcloud כדי להוסיף את התפקיד לחשבון השירות המצורף:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

כאשר
* TRACING_PROJECT_ID הוא מזהה פרויקט המעקב
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com הוא חשבון השירות המצורף. מידע נוסף זמין במאמר מהם תפקידים והרשאות?

מידע נוסף על הפקודות זמין במאמר gcloud iam service-accounts.

פריסת ה-API backend

עד עכשיו פרסתם את מסמך OpenAPI ל-Service Management, אבל עדיין לא פרסתם את הקוד שמשרת את העורף של ה-API. בקטע הזה נסביר איך לפרוס קונטיינרים מוכנים מראש עבור ה-API לדוגמה ו-ESP ל-Kubernetes.

בדיקת ההרשאות הנדרשות

נותנים לחשבון השירות שמשויך לאשכול את ההרשאות הנדרשות:

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member "serviceAccount:SERVICE_ACCOUNT" \
  --role roles/servicemanagement.serviceController

מידע נוסף זמין במאמר מהם תפקידים והרשאות?

העברת פרטי הכניסה לשירות אל ספק ה-ESP

ל-ESP, שפועל בתוך קונטיינר, נדרשת גישה לפרטי הכניסה שמאוחסנים באופן מקומי בקובץ service-account-creds.json. כדי לתת ל-ESP גישה לפרטי הכניסה, יוצרים סוד של Kubernetes ומטמיעים אותו כנפח של Kubernetes.

כדי ליצור את הסוד של Kubernetes ולצרף את אמצעי האחסון:

  1. אם קובץ ה-JSON הורד לספרייה אחרת, צריך לשנות את השם שלו ל-service-account-creds.json ולהעתיק אותו ל-endpoints-samples/k8s. כך השם תואם לאפשרויות שצוינו בקובץ המניפסט של הפריסה esp_echo_http.yaml.

  2. חשוב לוודא שאתם נמצאים בספרייה endpoints-samples/k8s.

  3. יוצרים סוד ב-Kubernetes עם פרטי הכניסה של חשבון השירות:

    kubectl create secret generic service-account-creds \
  --from-file=service-account-creds.json

    אם הפעולה בוצעה בהצלחה, תוצג ההודעה הבאה: secret "service-account-creds" created

קובץ המניפסט של הפריסה שבו אתם משתמשים כדי לפרוס את ה-API ואת ה-ESP ב-Kubernetes כבר מכיל את הנפח הסודי, כמו שמוצג בשני הקטעים הבאים של הקובץ:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds
 
volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

הגדרת שם השירות והפעלת השירות

‫ESP צריך לדעת את שם השירות כדי למצוא את ההגדרה שפרסתם קודם (באמצעות הפקודה gcloud endpoints services deploy).

כדי להגדיר את שם השירות ולהפעיל את השירות:

  1. פותחים את קובץ מניפסט הפריסה, esp_echo_http.yaml, ומחליפים את SERVICE_NAME באפשרויות ההפעלה של ESP בשם השירות. זהו אותו השם שהגדרתם בשדה host או server.url במסמך OpenAPI. לדוגמה:

    "--service=echo-api.endpoints.example-project-12345.cloud.goog"

    containers:
  - name: esp
    image: gcr.io/endpoints-release/endpoints-runtime:1
    args: [
      "--http_port", "8080",
      "--backend", "127.0.0.1:8081",
      "--service", "SERVICE_NAME",
      "--rollout_strategy", "managed",
      "--service_account_key", "/etc/nginx/creds/service-account-creds.json",
    ]

    האפשרות --rollout_strategy=managed" מגדירה את ESP כך שישתמש בהגדרת השירות העדכנית ביותר שנפרסה. אם תבחרו באפשרות הזו, עד 5 דקות אחרי שתפרסו הגדרת שירות חדשה, ESP יזהה את השינוי ויתחיל להשתמש בה באופן אוטומטי. אנחנו ממליצים לציין את האפשרות הזו במקום מזהה תצורה ספציפי לשימוש ב-ESP. מידע על אפשרויות אחרות של ESP שבהן נעשה שימוש מופיע במאמר אפשרויות הפעלה של ESP.

  2. מפעילים את השירות כדי לפרוס את שירות Endpoints ב-Kubernetes:

    kubectl create -f echo.yaml

    אם מופיעה הודעת שגיאה דומה להודעה הבאה:

    The connection to the server localhost:8080 was refused - did you specify the right host or port?

    המשמעות היא ש-kubectl לא מוגדר בצורה נכונה. מידע נוסף מופיע במאמר בנושא הגדרת kubectl.

מידע נוסף זמין במאמר בנושא פריסת Endpoints ב-Kubernetes.

איך מוצאים את כתובת ה-IP החיצונית של השירות

אם אתם משתמשים ב-Minikube, דלגו אל שליחת בקשה באמצעות כתובת IP.

יכול להיות שיעברו כמה דקות אחרי שתפעילו את השירות במאגר עד שכתובת ה-IP החיצונית תהיה מוכנה.

כדי לראות את כתובת ה-IP החיצונית של השירות:

  1. מריצים את הפקודה הבאה:

    kubectl get service

  2. רושמים את הערך של EXTERNAL-IP. משתמשים בכתובת ה-IP הזו כששולחים בקשה ל-API לדוגמה.

שליחת בקשה באמצעות כתובת IP

אחרי שה-API לדוגמה יפעל באוסף הקונטיינרים, תוכלו לשלוח בקשות ל-API.

יצירת מפתח API והגדרת משתנה סביבה

קוד לדוגמה דורש מפתח API. כדי לפשט את הבקשה, מגדירים משתנה סביבתי למפתח ה-API.

  1. באותו פרויקט שבו השתמשתם עבור ה-API, יוצרים מפתח API בדף 'פרטי כניסה ל-API'. Google Cloud אם רוצים ליצור מפתח API בפרויקט אחר ב- Google Cloud , אפשר לעיין במאמר בנושא הפעלת API בפרויקט Google Cloud .

    לדף Credentials

  2. לוחצים על Create credentials ואז על API key.
  3. מעתיקים את המפתח ללוח.
  4. לוחצים על Close.
  5. במחשב המקומי, מדביקים את מפתח ה-API כדי להקצות אותו למשתנה סביבה:
    • ב-Linux או ב-macOS: export ENDPOINTS_KEY=AIza...
    • ב-Windows PowerShell: ‏ $Env:ENDPOINTS_KEY="AIza..."

שליחת הבקשה אל minikube

הפקודות הבאות משתמשות במשתנה הסביבה ENDPOINTS_KEY שהגדרתם קודם.

‫Linux או Mac OS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

שליחת הבקשה לאשכולות Kubernetes אחרים

‫Linux או Mac OS

משתמשים ב-curl כדי לשלוח בקשת HTTP באמצעות משתנה הסביבה ENDPOINTS_KEY שהגדרתם קודם. מחליפים את IP_ADDRESS בכתובת ה-IP החיצונית של המכונה.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

במהלך curl הקודמים:

  • האפשרות --data מציינת את הנתונים שיישלחו ל-API.
  • האפשרות --header מציינת שהנתונים הם בפורמט JSON.

PowerShell

משתמשים ב-Invoke-WebRequest כדי לשלוח בקשת HTTP באמצעות משתנה הסביבה ENDPOINTS_KEY שהגדרתם קודם. מחליפים את IP_ADDRESS בכתובת ה-IP החיצונית של המופע.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content

בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.

אפליקציה של צד שלישי

אפשר להשתמש באפליקציה של צד שלישי, כמו התוסף Postman לדפדפן Chrome, כדי לשלוח את הבקשה:

  • בוחרים באפשרות POST כפועל ה-HTTP.
  • בכותרת, בוחרים את המפתח content-type ואת הערך application/json.
  • בגוף ההודעה, מזינים את הפרטים הבאים:
    {"message":"hello world"}
  • בכתובת ה-URL, משתמשים במפתח ה-API בפועל ולא במשתנה הסביבה. לדוגמה:
    http://192.0.2.0:80/echo?key=AIza...

ה-API מחזיר את ההודעה ששלחתם ומגיב עם:

{
  "message": "hello world"
}

אם לא קיבלתם תגובה, אפשר להיעזר במאמר בנושא פתרון בעיות שקשורות לתגובות.

הרגע פרסתם ובדקתם API ב-Endpoints!

מעקב אחר פעילות ב-API

כדי לעקוב אחרי פעילות ב-API:

  1. מעיינים בתרשימי הפעילות של ה-API בדף Endpoints ‏ > Services.

    לדף Endpoints Services


    יכול להיות שיחלפו כמה רגעים עד שהבקשה תשתקף בתרשימים.

  2. מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.

    כניסה לדף Logs Explorer

הגדרת DNS לנקודות קצה

מכיוון ששם השירות של Endpoints עבור ה-API נמצא בדומיין .endpoints.YOUR_PROJECT_ID.cloud.goog, אפשר להשתמש בו כשם דומיין מוגדר במלואו (FQDN) על ידי ביצוע שינוי קטן בהגדרות בקובץ openapi.yaml. כך תוכלו לשלוח בקשות ל-API לדוגמה באמצעות echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog במקום כתובת ה-IP.

כדי להגדיר את ה-DNS של Endpoints:

OpenAPI 2.0

  1. פותחים את קובץ התצורה של OpenAPI,‏ openapi.yaml, ומוסיפים את המאפיין x-google-endpoints ברמה העליונה של הקובץ (לא מוזח או מקונן), כמו שמוצג בקטע הקוד הבא: 
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"
  2. במאפיין name, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט.
  3. במאפיין target, מחליפים את IP_ADDRESS בכתובת ה-IP שבה השתמשתם כששלחתם בקשה ל-API לדוגמה.
  4. פורסים את קובץ התצורה המעודכן של OpenAPI ל-Service Management: 
    gcloud endpoints services deploy openapi.yaml

‫OpenAPI 3.x

  1. פותחים את קובץ התצורה של OpenAPI,‏ openapi.yaml, ומוסיפים את המאפיין servers.url ברמה העליונה של הקובץ (לא מוזח או מקונן), כמו שמוצג בקטע הקוד הבא: 
    servers:
  - url: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoint:
      target: "IP_ADDRESS"
  2. במאפיין name, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט.
  3. במאפיין target, מחליפים את IP_ADDRESS בכתובת ה-IP שבה השתמשתם כששלחתם בקשה ל-API לדוגמה.
  4. פורסים את קובץ התצורה המעודכן של OpenAPI ל-Service Management: 
    gcloud endpoints services deploy openapi.yaml

לדוגמה, נניח שבקובץ openapi.yaml מוגדרות ההגדרות הבאות:

OpenAPI 2.0

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

‫OpenAPI 3.x

servers:
  - url: "echo-api.endpoints.example-project-12345.cloud.goog"
    x-google-endpoint:
      target: "192.0.2.1"

כשפורסים את הקובץ openapi.yaml באמצעות הפקודה gcloud שצוינה למעלה, Service Management יוצר רשומת DNS מסוג A‏, echo-api.endpoints.my-project-id.cloud.goog, שמפנה לכתובת ה-IP של היעד, 192.0.2.1. יכול להיות שיחלפו כמה דקות עד שהגדרת ה-DNS החדשה תתעדכן.

הגדרת SSL

פרטים נוספים על הגדרת DNS ו-SSL זמינים במאמר הפעלת SSL לנקודות קצה.

שליחת בקשה ל-FQDN

אחרי שהגדרתם את רשומת ה-DNS עבור ה-API לדוגמה, שולחים אליו בקשה באמצעות ה-FQDN (מחליפים את YOUR_PROJECT_ID במזהה הפרויקט) ומשתנה הסביבה ENDPOINTS_KEY שהוגדר קודם:

  • ב-Linux או ב-macOS: 
    curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • ב-Windows PowerShell: 
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

הסרת המשאבים

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

  • מוחקים את שירות Kubernetes ואת הפריסה:

    kubectl delete -f esp_echo_http.yaml

במאמר מחיקת API ומופעי API מוסבר איך להפסיק את השירותים שבהם נעשה שימוש במדריך הזה.

המאמרים הבאים