תחילת העבודה עם Cloud Endpoints ל-Managed Instance Group ‏ (MIG) עם ESPv2

במדריך הזה נסביר איך להגדיר ולפרוס API לדוגמה ואת Extensible Service Proxy V2 ‏ (ESPv2) שפועל בקונטיינרים מוכנים מראש של Docker בקבוצות מופעי מכונה מנוהלים (MIG) .

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

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

מטרות

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

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

עלויות

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

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

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

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

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

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

  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. חשוב לרשום את מזהה הפרויקט כי תצטרכו אותו בהמשך.

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

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

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

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

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

מורידים את קוד הדוגמה למחשב המקומי.

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

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

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

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

OpenAPI 2.0

כדי להגדיר נקודות קצה באמצעות מפרט OpenAPI 2.0, אפשר להשתמש בקובץ openapi.yaml שזמין בספרייה endpoints/getting-started של קוד הדוגמה שהורדתם.

התוכן של מפרט 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

כדי להגדיר את Endpoints באמצעות מפרט OpenAPI 3.x, אפשר להחליף את התוכן של הקובץ openapi.yaml שזמין בספרייה endpoints/getting-started של קוד הדוגמה שהורדתם:

  1. פותחים את הקובץ openapi.yaml בכלי לעריכת טקסט ומחליפים את התוכן שלו בתוכן הבא: 
    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:
        - 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"
  2. שומרים את התוכן החדש של openapi.yaml.

במדריך הזה נעשה שימוש בתוסף ספציפי ל-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 Backend

יצירת תבנית של הגדרות מכונה

יוצרים תבנית שתשמש ליצירת קבוצה של מכונות וירטואליות. כל מופע שנוצר מהתבנית מפעיל ESPv2 ושרת אפליקציות של קצה עורפי.

  1. נכנסים לדף Instance templates במסוף Google Cloud .

    כניסה לדף Instance templates

  2. לוחצים על Create instance template.

  3. בשדה Name (שם), מזינים load-balancing-espv2-template.

  4. בקטע Machine configuration, מגדירים את סוג המכונה לערך e2-micro.

  5. בקטע Boot disk, מגדירים את Image ל-Container Optimized OS stable version.

  6. בקטע Firewall, בוחרים באפשרות Allow HTTP traffic.

  7. לוחצים על Management, security, disks, networking, sole tenancy כדי להציג את ההגדרות המתקדמות.

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

    sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=echo \
  --net=esp_net \
  gcr.io/google-samples/echo-python:1.0
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=echo:8080

    הסקריפט מקבל, מתקין ומפעיל את שרת האפליקציות של echo ואת שרת ה-proxy של ESPv2 בזמן הפעלת המופע.

  9. לוחצים על יצירה.

צריך לחכות עד שהתבנית תיווצר לפני שממשיכים.

יצירת קבוצה אזורית של מופעי מכונה מנוהלים

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

  1. נכנסים לדף Instance groups במסוף Google Cloud .

    כניסה לדף Instance groups

  2. לוחצים על יצירת קבוצת מופעים.

  3. בשדה Name (שם), מזינים load-balancing-espv2-group.

  4. בקטע מיקום, בוחרים באפשרות מספר אזורים.

  5. בקטע Region, בוחרים באפשרות us-central1.

  6. לוחצים על התפריט הנפתח Configure zones (הגדרת אזורים) כדי להציג את האפשרות Zones (אזורים). בוחרים את האזורים הבאים:

    • us-central1-b
    • us-central1-c
    • us-central1-f

  7. בקטע תבנית של הגדרות מכונה, בוחרים באפשרות load-balancing-espv2-template.

  8. בקטע שינוי גודל אוטומטי, בוחרים באפשרות ללא שינוי גודל אוטומטי.

  9. מגדירים את מספר המופעים ל-3.

  10. בקטע Instance redistribution, בוחרים באפשרות On.

  11. בקטעים תיקון אוטומטי ובדיקת תקינות, בוחרים באפשרות ללא בדיקת תקינות.

  12. לוחצים על יצירה. תועברו בחזרה לדף קבוצות מופעים.

יצירת מאזן עומסים

בקטע הזה מוסבר איך ליצור מאזן עומסים (LB) גלובלי שמפנה תנועת HTTP לקבוצת המופעים.

מאזן העומסים הזה משתמש בקצה קדמי כדי לקבל תעבורת נתונים נכנסת ובק-אנד כדי להפיץ את תעבורת הנתונים הזו למכונות תקינות. מאזן העומסים מורכב מכמה רכיבים, ולכן המשימה הזו מחולקת לכמה חלקים:

  • הגדרת הקצה העורפי
  • הגדרות הקצה הקדמי
  • בדיקה וסיום

משלימים את כל השלבים ליצירת מאזן העומסים.

  1. נכנסים לדף Create a load balancer במסוף Google Cloud .

    מעבר אל יצירת מאזן עומסים

  2. בקטע Application Load Balancer (HTTP/S), לוחצים על Start configuration.

  3. בקטע Internet facing or internal only, בוחרים באפשרות From Internet to my VMs. לאחר מכן, לוחצים על המשך.

  4. בשדה Name של מאזן העומסים, מזינים espv2-load-balancer.

הגדרת הקצה העורפי

  1. בחלונית הימנית של הדף Create global external Application Load Balancer (יצירת איזון עומסים חיצוני גלובלי לאפליקציות), לוחצים על Backend configuration (הגדרת קצה עורפי).
  2. לוחצים על Create or select backend services & backend buckets כדי לפתוח תפריט נפתח. לוחצים על שירות לקצה העורפי ואז על יצירת שירות לקצה העורפי.
  3. בחלון החדש, בשדה Name (שם) של אפליקציית ה-Backend, מזינים espv2-backend.
  4. מגדירים את Instance group ל-load-balancing-espv2-group.
  5. מגדירים את ניוד מספרים לערך 80. ההגדרה הזו מאפשרת תעבורת HTTP בין מאזן העומסים לקבוצת המופעים.
  6. בקטע מצב איזון, בוחרים באפשרות ניצול.
  7. לוחצים על סיום כדי ליצור את העורף.

  8. יוצרים את בדיקת התקינות לקצה העורפי של מאזן העומסים:

    1. בקטע Health check (בדיקת תקינות), בוחרים באפשרות Create a health check (יצירת בדיקת תקינות) או באפשרות Create another health check (יצירת בדיקת תקינות נוספת) מהתפריט הנפתח. חלון חדש נפתח.
    2. בחלון החדש, בשדה שם, מזינים espv2-load-balancer-check.
    3. מגדירים את Protocol ל-HTTP.
    4. בשדה Port, מזינים 80.
    5. במדריך הזה, מגדירים את נתיב הבקשה ל-/healthz, שהוא נתיב שה-ESPv2 מוגדר להגיב לו.

    6. מגדירים את קריטריוני הבריאות הבאים:

      1. מגדירים את מרווח הבדיקה ל-3 שניות. הערך הזה מגדיר את משך הזמן מתחילת בקשה לבדיקת תקינות (probe) אחת ועד לתחילת הבקשה לבדיקת תקינות (probe) הבאה.
      2. מגדירים את הזמן הקצוב לתפוגה ל-3 שניות. ההגדרה הזו מגדירה את משך הזמן שבו Google Cloud ממתין לתגובה לבקשה לבדיקת תקינות (probe). הערך שלו חייב להיות קטן ממרווח הבדיקה או שווה לו.
      3. מגדירים את הסף הבריא ל-2 הצלחות רצופות. הערך הזה מגדיר את מספר הבדיקות הרצופות שצריכות להצליח כדי שהמופע ייחשב תקין.
      4. מגדירים את Unhealthy Threshold ל-2 consecutive failures. ההגדרה הזו מגדירה את מספר הבדיקות הרצופות שצריכות להיכשל כדי שהמופע ייחשב כלא תקין.

    7. לוחצים על שמירה והמשך כדי ליצור את בדיקת תקינות.

  9. לוחצים על Create כדי ליצור את שירות לקצה העורפי.

הגדרות הקצה הקדמי

  1. בחלונית שמימין בדף Create global external Application Load Balancer (יצירת איזון עומסים חיצוני גלובלי לאפליקציות), לוחצים על Frontend configuration (הגדרת חזית האפליקציה).
  2. בדף Frontend configuration, בשדה Name, מזינים את הערך espv2-ipv4-frontend.
  3. מגדירים את Protocol ל-HTTP.
  4. מגדירים את Port ל-80.
  5. לוחצים על סיום כדי ליצור את חזית האתר.

בדיקה וסיום

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

    1. בחלונית הימנית של הדף Create global external Application Load Balancer (יצירת מאזן עומסים גלובלי חיצוני של אפליקציות), לוחצים על Review and finalize (בדיקה וסיום).

    2. בדף Review and finalize, בודקים את הגדרות הקצה העורפי הבאות:

      • השירות לקצה העורפי הוא espv2-backend.
      • פרוטוקול נקודת הקצה הוא HTTP.
      • בדיקת התקינות היא espv2-load-balancer-check.
      • קבוצת המופעים היא load-balancing-espv2-group.

    3. באותו דף, מוודאים שFrontend משתמש בכתובת IP עם פרוטוקול של HTTP.

  2. בחלונית הימנית של הדף Create global external Application Load Balancer (יצירת איזון עומסים חיצוני גלובלי של אפליקציות), לוחצים על Create (יצירה) כדי לסיים את יצירת איזון העומסים.

    יכול להיות שתצטרכו להמתין כמה דקות עד שמאזן העומסים ייווצר.

  3. אחרי שיוצרים את מאזן העומסים, מאתרים את כתובת ה-IP בדף Load Balancer.

    כניסה לדף Load Balancer

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

אחרי ש-API לדוגמה ו-ESPv2 פועלים בקצה העורפי שנפרס, אפשר לשלוח בקשות אל ה-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..."

שליחת הבקשה

‫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!

הגדרת 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

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

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

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

    לדף Endpoints Services


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

    כניסה לדף Logs Explorer

הסרת המשאבים

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

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

    gcloud auth login

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

    gcloud projects list

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

    gcloud config set project [YOUR_PROJECT_ID]

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

    gcloud endpoints services list

  5. מוחקים את השירות מניהול השירותים. מחליפים את SERVICE_NAME בשם השירות שרוצים להסיר.

    gcloud endpoints services delete SERVICE_NAME

    הפעלת הפקודה gcloud endpoints services delete לא מוחקת באופן מיידי את השירות המנוהל. השירות לניהול שירותים משבית את השירות המנוהל למשך 30 יום, כדי שיהיה לכם זמן לשחזר אותו אם תצטרכו. אחרי 30 יום, כלי ניהול השירותים מוחק את השירות המנוהל באופן סופי.

  6. עוברים לדף Load Balancer.

    כניסה לדף Load Balancer

    מחיקת מאזן עומסים espv2-load-balancer עם שירות קצה עורפי espv2-backend ובדיקת תקינות espv2-load-balancer-check.

  7. עוברים לדף Instance Groups.

    כניסה לדף Instance Groups

    מחיקת load-balancing-espv2-group

  8. עוברים לדף Instance Template.

    כניסה לדף Instance Templates

    מוחקים את load-balancing-espv2-template.

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