שימוש ב-Docker ל-Edge Microgateway

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

בנושא הזה מוסבר איך להריץ את Edge Microgateway בקונטיינר של Docker. השלבים המתוארים בנושא הזה מבוססים על הבנה בסיסית של Docker, פקודות Docker והגדרה והגדרה של Edge Microgateway. למידע נוסף, עיינו במסמכי התיעוד של Docker ו-Edge Microgateway

דרישות מוקדמות

לפני שמפעילים את Edge Microgateway בקונטיינר Docker, צריך לבצע את המשימות הבאות:

  • הגדרה של Edge Microgateway עבור הארגון או הסביבה שלך ב-Apigee:

    edgemicro configure -o your_org -e your_env -u your_username

    לפרטים נוספים על התצורה, אפשר לעיין בחלק 1: הגדרת Edge Microgateway.

  • אחרי שמבצעים את שלבי ההגדרה, מאתרים את קובץ התצורה. מיקום ברירת המחדל הוא כאן:

    $HOME/.edgemicro/your_org-your_env-config.yaml

    כאשר your_org ו-your_env הם הארגון והסביבה שבהם השתמשתם כשהרצתם את הפקודה edgemicro config. תצטרכו את הקובץ הזה כשמפעילים את Edge Microgateway בקונטיינר של Docker.

  • ודאו שיש לכם את פרטי הכניסה והמפתח שהוחזרו כשהרצתם את הפקודה edgemicro config. לדוגמה:

    The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

  • לפני שמפעילים את Edge Microgateway בקונטיינר של Docker, צריך ליצור (או ליצור) את הישויות של Apigee Edge שנדרשות כדי לבצע קריאות לשרת proxy מאומתות ל-API. הישויות האלה כוללות שרת proxy לאימות של Edge Microgateway, מוצר API, מפתח ואפליקציה למפתחים. להוראות מלאות, קראו את המאמר יצירת ישויות ב-Apigee Edge.

מריצים את Edge Micro כקונטיינר של Docker

  1. מורידים את תמונת ה-Docker של Edge Microgateway:

    docker pull gcr.io/apigee-microgateway/edgemicro:latest

  2. לפני שממשיכים לשלבים הבאים, חשוב לוודא שביצעתם את כל השלבים שמפורטים בקטע Prerequis.

  3. מריצים את הפקודה הבאה כדי לבצע קידוד base64 בקובץ התצורה של Edge Microgateway, שנמצא ב-$HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    כאשר your_org ו-your_env הם הארגון והסביבה שבהם השתמשתם כשהרצתם את הפקודה edgemicro config.

    חשוב לזכור להציב סימני סימונים עורפיים (`) מסביב לפקודה. לדוגמה:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. מריצים את Edge Microgateway כקונטיינר. הפקודה מגדירה כמה משתני סביבה שמשמשים את זמן הריצה של הקונטיינר כדי להפעיל את Edge Microgateway:

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL \
gcr.io/apigee-microgateway/edgemicro:latest

    פרמטרים

    פרמטר ‫תיאור
    -P מפרסמים את כל היציאות החשופות למארח. עיינו גם במאמר סקירה על הרצת Docker.
    -p מיפוי מפורש של יציאה אחת או טווח של יציאות. עיינו גם במאמר סקירה על הרצת Docker.
    -d הפעלה במצב מנותק. עיינו גם במאמר סקירה על הרצת Docker.
    -v, --volume ההגדרה קובעת איזה מכשיר תושבת לעוצמת הקול. שימו לב שאם מגדירים את Edge Microgateway להשתמש ב-TLS בקונטיינר Docker, צריך לחשוף את יציאה 8443 אם טוענים את ספריית קובצי היומן. למידע נוסף, ראו VOLUME [מערכות קבצים משותפות]. למידע נוסף, ראו שימוש ב-TLS בקונטיינר Docker.
    EDGEMICRO_ORG שם הארגון של Apigee שבו השתמשת כדי להגדיר את Edge Microgateway.
    EDGEMICRO_ENV השם של סביבת Apigee שבה השתמשת כדי להגדיר את Edge Microgateway.
    EDGEMICRO_PROCESSES מספר התהליכים שצריך להתחיל.
    EDGEMICRO_KEY המפתח הוחזר כשהגדרת את Edge Microgateway.
    EDGEMICRO_SECRET הסוד הוחזר כשהגדרת את Edge Microgateway.
    EDGEMICRO_CONFIG משתנה שמכיל את קובץ התצורה של Edge Microgateway בקידוד base64.
    SERVICE_NAME אם משתמשים ב-Kubernetes, הפרמטר הזה מאוכלס אוטומטית. אחרת, אפשר להגדיר כל שינוי שרוצים. אם לא תציינו שום דבר, שם השירות יוגדר כ-default.
    DEBUG כדי לאפשר ניפוי באגים, יש להגדיר את הערך *.
    HTTP_PROXY HTTPS_PROXY לשימוש כש-Edge Microgateway פועל מאחורי חומת אש והשער לא יכול לתקשר עם Apigee Edge. אפשר לקרוא מידע נוסף במאמר הגדרת Edge Microgateway מאחורי חומת אש של חברה.

    לדוגמה: HTTP_PROXY=http://10.203.0.1:5187/
    NO_PROXY רשימה מופרדת בפסיקים של דומיינים שאליהם Microgateway של Edge לא אמור לשמש כשרת proxy. אפשר לקרוא מידע נוסף במאמר הגדרת Edge Microgateway מאחורי חומת אש של חברה.

    לדוגמה: localhost,127.0.0.1,localaddress,.localdomain.com
    NODE_EXTRA_CA_CERTS (אופציונלי) כדאי להשתמש בפרמטר הזה אם משתמשים ברשות אישורים שאינה מהימנה כברירת מחדל לפי Node.js. צריך להגדיר את הערך של הפרמטר הזה לנתיב לקובץ שמכיל אישור מהימן אחד או יותר בפורמט PEM. לפרטים נוספים אפשר לעיין במאמר בנושא אישורי TLS (אבטחת שכבת התעבורה).
    --security-opt (אופציונלי) מגדיר את אפשרויות האבטחה הרצויות של Docker. ראו תצורת אבטחה במסמכי התיעוד של Docker.
    --cap-drop (אופציונלי) מגדיר מגבלות על היכולות של Linux שמותרות בקונטיינר. מידע נוסף על הרשאות זמן ריצה ויכולות Linux במסמכי התיעוד של Docker.

    לדוגמה:

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-e EDGEMICRO_PROCESS=1 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL \
gcr.io/apigee-microgateway/edgemicro

  5. כדי לבדוק שהמאגר פועל:

    docker ps

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

    CONTAINER ID    IMAGE         COMMAND                CREATED          STATUS          PORTS                                             NAMES
8b92e082ea9c    edgemicro    "/tmp/entrypoint.sh"   12 minutes ago   Up 12 minutes    0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp    edgemicro

בדיקה של קריאה ל-API

אחרי שמפעילים את Edge Microgateway בקונטיינר, אפשר לבצע אליו קריאות ל-API. לדוגמה, אם נתיב הבסיס של ה-API הוא /hello:

http://localhost:8000/hello

פלט לדוגמה:

{"error":"missing_authorization","error_description":"Missing Authorization header"}

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

בדיקת API עם מפתח API תקין

בממשק המשתמש של Edge, עוברים לאפליקציה למפתחים שיצרתם קודם לכן. מציגים את מפתח הצרכן בדף האפליקציה למפתחים ומעתיקים אותו. הערך הזה הוא מפתח ה-API. תשתמשו במפתח הזה כדי לבצע קריאות ל-API מאומתות.

צריך להפעיל את ה-API עם הכותרת x-api-key באופן הבא. ערך מפתח הצרכן שהעתקתם מהאפליקציה למפתחים הוא מפתח ה-API. כברירת מחדל, Edge Microgateway מצפה מכם להעביר את המפתח בכותרת בשם x-api-key, כך:

curl -i http://localhost:8000/hello -H "x-api-key:apikey"

לדוגמה:

curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

למידע נוסף על ביצוע קריאות ל-API מאומתות דרך Edge Microgateway באמצעות מפתחות API ואסימוני OAuth, ראו חלק 4: Secure Edge Microgateway.

הפסקת המיקרו-שער של Edge

כדי להפסיק את Edge Microgateway, משתמשים בפקודת Docker הבאה:

docker stop edgemicro

הפעלה מחדש של Edge Microgateway

אחרי הפסקת השימוש ב-Edge Microgateway, אפשר להפעיל אותו מחדש באמצעות פקודת Docker הזו:

docker start edgemicro

שימוש ב-TLS בקונטיינר של Docker

בקטע הזה נסביר איך מגדירים TLS ל-Edge Microgateway שפועל בקונטיינר של Docker. אפשר להגדיר את שרת Edge Microgateway להשתמש ב-TLS עבור בקשות נכנסות (כיוון צפון), ולהגדיר את Edge Microgateway כלקוח TLS עבור בקשות יוצאות שיטרגטו נקודות קצה (כיוון דרום).

היכן להציב קובצי אישורים

למכל Docker שפועל בו Edge Microgateway יש נקודת טעינה ב-/opt/apigee/.edgemicro. כשמגדירים את Edge Microgateway לשימוש באישורי TLS, אפשר להגדיר את קובצי האישורים בנקודת הטעינה הזו ולהפנות אליהם בקובץ התצורה של Edge Microgateway. קובץ התצורה הזה בדרך כלל נמצא בספרייה $HOME/.edgemicro, והוא נקרא your_org-your_env-config.yaml. לדוגמה:

...
edgemicro:
  ssl:
   key: /opt/apigee/.edgemicro/southbound/tls.key
   cert: /opt/apigee/.edgemicro/southbound/tls.crt
...

שימוש ברשות אישורים שאינה מהימנה על ידי Node.js

אם אתם משתמשים ברשות אישורים (CA) שלא מהימנה כברירת מחדל על ידי Node.js (כמו במקרה של אישור בחתימה עצמית), כדאי להשתמש בפרמטר NODE_EXTRA_CA_CERTS להרצת הקונטיינר.

מגדירים את הפרמטר הזה לנתיב של קובץ שמכיל אישור מהימן אחד או יותר בפורמט PEM. כדי לראות את אופן השימוש בפרמטר הזה, עיינו בדוגמאות כיצד להגדיר TLS לכיוון צפון וכיצד להגדיר TLS לכיוון דרום.

לדוגמה:

docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

למידע נוסף, ראו הפעלת Edge Micro בתור קונטיינר של Docker.

השבתה של אימות TLS (אבטחת שכבת התעבורה)

לא מומלץ לעשות זאת, אבל במקרים מסוימים כדאי להשבית את אימות ה-TLS (אבטחת שכבת התעבורה) ל-Edge Microgateway שפועל בקונטיינר. היכולת להשבית TLS לא מובנית בקונטיינר Edge Microgateway Docker כברירת מחדל. כדי להשלים את המשימה, צריך ליצור תמונת Docker מותאמת אישית עבור Edge Microgateway. בהמשך תוכלו למצוא הוראות כלליות לבניית תמונה מותאמת אישית ולהשבתת אימות TLS (אבטחת שכבת התעבורה).

  1. שכפול או הורדה של מאגר המקור של Edge Microgateway מ-https://github.com/apigee-internal/microgateway.

  2. cd לספרייה microgateway/kubernetes/docker/edgemicro בספריית קוד המקור.

    לדוגמה:

    cd $HOME/git/microgateway/kubernetes/docker/edgemicro

  3. פותחים את הקובץ entrypoint.sh ומשנים את הקוד כך שיאשר את משתנה הסביבה NODE_TLS_REJECT_UNAUTHORIZED. בהמשך, כשמריצים את המאגר, מציינים ערך עבור המשתנה.

  4. יוצרים את הקונטיינר של Docker:

    docker build -t edgemicro .

  5. כשאתם מריצים את המאגר, צריך לציין את האפשרות -e NODE_TLS_REJECT_UNAUTHORIZED = 1. לדוגמה:

docker run -P -p 8443:8443 -d --name edgemicro \
-v $HOME/.edgemicro:/opt/apigee/.edgemicro \
-v $HOME/.edgemicro:/opt/apigee/logs \
-e NODE_TLS_REJECT_UNAUTHORIZED = 1 \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \
-e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

דוגמה: איך להגדיר TLS לכיוון צפון

בקטע הזה מוסבר איך להגדיר חיבור TLS (נכנס) צפונה בשרת Edge Microgateway. TLS (אבטחת שכבת התעבורה) מאפשר ללקוחות להשתמש ב-HTTPS בעת ביצוע קריאות ל-API ל-Edge Microgateway. בדוגמה הבאה אנחנו משתמשים באישורים בחתימה עצמית.

1. שלבי ההגדרה הראשונית

  1. יש לאתר את הקובץ openssl.cnf במערכת. לדוגמה: /etc/ssl/openssl.cnf.
  2. יש לפתוח את הקובץ opensssl.cnf כדי לערוך אותו.

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

    [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

  4. כדי ליצור את מאפייני ה-SNI הנכונים, צריך להוסיף את הבית הבא ל-openssl.cnf:

    [ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

    קובץ opensssl.cnf לדוגמה:

    [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = www.example.com
DNS.2 = example.com
DNS.3 = localhost
DNS.4 = localhost.localdomain
DNS.5 = 127.0.0.1
DNS.6 = ::1
DNS.7 = fe80::1

  5. אם עדיין לא עשיתם זאת, פועלים לפי השלבים המפורטים בסעיף דרישות מוקדמות כדי לאתחל ולהגדיר את Edge Microgateway, אבל בשלב הזה צריך ליצור שרת proxy מבוסס-Edge Microgateway, מוצר API, מפתח ואפליקציה למפתחים. בנוסף, הייתם צריכים להריץ את הפקודה edgemicro configure ולקבל מפתח וסוד.

2. יצירת אישורים בחתימה עצמית

בשלב הבא, מפיקים את האישורים והמפתחות הדרושים כדי ליצור TLS (אבטחת שכבת התעבורה):

  1. cd לספרייה $HOME/.edgemicro.

  2. יוצרים את סקריפט ה-Bash הבא. אתם יכולים לתת לו כל שם שתרצו. לדוגמה: keygen.sh.

    #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

  3. בקובץ ה-Bash, יש לוודא שהנתיב לקובץ openssl.cnf נכון.

  4. מפעילים את קובץ ה-Bash. תוצג בקשה לפרטי האישור. חשוב לוודא שהשם המשותף הוא localhost.

  5. בודקים שהקבצים הבאים נוצרו:

    • rootca.key
    • rootca.pem
    • tls.key
    • tls.csr
    • rootca.srl
    • tls.crt

3. עריכת קובץ התצורה של Edge Microgateway

  1. פותחים את קובץ התצורה של Edge Micro בעורך. לדוגמה:

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. עורכים את בית edgemicro באופן הבא. שימו לב שאתם מבצעים שינויים במאפיינים port ו-ssl:

    edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

  3. מריצים את הפקודה הבאה כדי לקודד ב-base64 את קובץ התצורה של Edge Microgateway שנמצא ב-$HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    כאשר your_org ו-your_env הם הארגון והסביבה שבהם השתמשתם כשהרצתם את הפקודה edgemicro config.

    חשוב לזכור להציב סימני סימונים עורפיים (`) מסביב לפקודה. לדוגמה:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

למידע נוסף, ראו Run Edge Micro as a Docker container (הרצת הקונטיינר של Docker).

4. הפעלת המאגר

  1. מריצים את הפקודה הבאה כדי להריץ את הקונטיינר של Docker עם Edge Microgateway:

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
gcr.io/apigee-microgateway/edgemicro:latest

  2. שימו לב לפרמטרים הבאים המשמשים בפקודה. הם שונים מהפקודה הבסיסית המתוארת ב-Run Edge Micro as a Docker container (הרצה של קונטיינר של Docker).

    • הערך של port מוגדר ל-8443.
    • תושבת לעוצמת הקול כדי לטעון את קובצי המפתח והאישורים.
    • המשתנה NODE_EXTRA_CA_CERTS משמש להוספת רשות אישורים בהתאמה אישית (לפי הצורך במקרה של אישורים בחתימה עצמית).

5. בדיקת ההגדרה של TLS (אבטחת שכבת התעבורה)

  1. מריצים את פקודת ה-cURL הבאה כדי לבדוק את ההגדרה. מחליפים בפקודה את ה-basepath ואת מפתח ה-API. בדוגמה הבאה ההנחה היא שאתם נמצאים בספרייה שבה ממוקם rootca.pem ובשרת ה-proxy שיצרתם יש את נתיב הבסיס /hello:

    curl -v https://localhost:8443/hello --cacert rootca.pem \
-H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"

  2. הפלט המילולי של cURL מציג כל שלב בלחיצת היד של TLS. אם מופיעה תגובת HTTP 200, ההגדרה הסתיימה בהצלחה:

    *   Trying ::1...ey:Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
* TCP_NODELAY set
* Connected to localhost (::1) port 8443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
*   CAfile: rootca.pem
  CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  start date: Dec 14 22:35:28 2018 GMT
*  expire date: Oct  3 22:35:28 2021 GMT
*  common name: localhost (matched)
*  issuer: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com
*  SSL certificate verify ok.
> GET /hello HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key:Az82fdnfaONVCOE4NKhajxAboDA3FAo
>
< HTTP/1.1 200 OK
< x-powered-by: Apigee
< access-control-allow-origin: *
< x-frame-options: ALLOW-FROM RESOURCE-URL
< x-xss-protection: 1
< x-content-type-options: nosniff
< content-type: text/plain; charset=utf-8
< etag: W/"d-GHB1ZrJKk/wdVTdB/jgBsw"
< date: Fri, 14 Dec 2018 22:43:13 GMT
< via: 1.1 google
< alt-svc: clear
< x-response-time: 1325
< Connection: keep-alive
< Transfer-Encoding: chunked
<
* Connection #0 to host localhost left intact
Hello, Guest!

דוגמה: איך להגדיר TLS לכיוון דרום

בקטע הזה מוסבר איך להגדיר חיבור TLS (יוצא) דרומה בין שרת Edge Microgateway לבין אפליקציית יעד לקצה העורפי. בדוגמה הבאה משתמשים באישורים בחתימה עצמית.

1. שלבי ההגדרה הראשונית

  1. יש לאתר את הקובץ openssl.cnf במערכת. לדוגמה: /etc/ssl/openssl.cnf.
  2. יש לפתוח את הקובץ opensssl.cnf כדי לערוך אותו.

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

    [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

  4. כדי ליצור את מאפייני ה-SNI הנכונים, צריך להוסיף את הבית הבא ל-openssl.cnf:

    [ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

    קובץ opensssl.cnf לדוגמה:

    [ req ]
distinguished_name      = req_distinguished_name
attributes              = req_attributes
req_extensions          = v3_req

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name)
localityName                    = Locality Name (eg, city)
0.organizationName              = Organization Name (eg, company)
organizationalUnitName          = Organizational Unit Name (eg, section)
commonName                      = Common Name (eg, fully qualified host name)
commonName_max                  = 64
emailAddress                    = Email Address
emailAddress_max                = 64

[ req_attributes ]
challengePassword               = A challenge password
challengePassword_min           = 4
challengePassword_max           = 20

[ alt_names ]
DNS.1 = helloworld
DNS.2 = localhost
DNS.3 = localhost.localdomain
DNS.4 = 127.0.0.1
DNS.5 = ::1
DNS.6 = fe80::1

  5. מריצים את הפקודה edgemicro configure:

    edgemicro configure -o your_org -e your_env -u your_username

    לפרטים נוספים על התצורה, אפשר לעיין בחלק 1: הגדרת Edge Microgateway.

  6. מעתיקים את המפתח ואת פרטי הכניסה הסודיים שהוחזרו מ-edgemicro configure. תזדקק לערכים האלו כדי להפעיל את המאגר. לדוגמה:

    The following credentials are required to start edge micro
  key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0
  secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430

2. יצירת אפליקציית יעד של Node.js

  1. cd לספרייה .edgemicro.

  2. יוצרים את סקריפט ה-Bash הבא. אתם יכולים לתת לו כל שם שתרצו. לדוגמה: keygen.sh.

    #!/bin/bash
# generate ca
openssl genrsa -out rootca.key 2048
openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem
# generate key
openssl genrsa -out tls.key 2048
openssl req -new -key tls.key -out tls.csr
# sign cert
openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf

  3. בקובץ ה-Bash, יש לוודא שהנתיב לקובץ openssl.cnf נכון.

  4. מפעילים את קובץ ה-Bash. תוצג בקשה לפרטי האישור. חשוב לוודא שהשם המשותף הוא hellworld.

  5. בודקים שהקבצים הבאים נוצרו:

    • rootca.key
    • rootca.pem
    • tls.key
    • tls.csr
    • rootca.srl
    • tls.crt

  6. יצירת קובץ חדש בשם server.js.

    'use strict';

const express = require('express');
const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync("tls.key"),
  cert: fs.readFileSync("tls.crt")
};

// Constants
const PORT = 9443;
const HOST = '0.0.0.0';

// App
const app = express();
app.get('/', (req, res) => {
  res.send('Hello world\n');
});

https.createServer(options, app).listen(PORT);

  7. יצירת קובץ package.json באותה ספרייה עם server.js. לדוגמה:

    {
  "name": "helloworld",
  "version": "1.0.0",
  "description": "",
  "main": "server.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "node server.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^4.16.4",
    "fs": "0.0.1-security",
    "https": "^1.0.0"
  }
}

  8. מריצים את הפקודה npm install כדי לקבל את יחסי התלות.

  9. יוצרים Dockerfile חדש באותה ספרייה כמו server.js, שבה WORKDIR הוא הנתיב לשורש של אפליקציית Node.js:

    FROM node:8-alpine
WORKDIR path-to-your-node-app
COPY package*.json ./

RUN npm install
COPY . .
EXPOSE 9443
CMD [ "npm", "start" ]

  10. יוצרים את תמונת ה-Docker:

    docker build -t helloworld .

  11. מפעילים את האפליקציה לדוגמה:

    docker run -P -p 9443:9443 --name helloworld helloworld

3. יצירת ישויות ב-Apigee Edge

  1. יוצרים שרת proxy מבוסס-Edge Microgateway עם ההגדרות האלה. למידע נוסף, ראו יצירת שרת proxy ל-Edge Microgateway-aware API ב-Edge.

    • שם שרת Proxy: edgemicro_local
    • גרסה: 1
    • נתיב הבסיס: /local
    • יעד: https://helloworld:9443

  2. יוצרים מוצר API. פרטים נוספים זמינים במאמר בנושא יצירת מוצר.

  3. יוצרים מפתח. פרטים נוספים זמינים במאמר יצירת מפתח.

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

4. הפעלת המאגר

  1. פותחים את קובץ התצורה של Edge Micro בעורך. לדוגמה:

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. עורכים את בית edgemicro באופן הבא. שימו לב שאתם מבצעים שינויים במאפיינים port ו-ssl:

    edge_config:
...
edgemicro:
  port: 8443
  max_connections: 1000
  config_change_poll_interval: 600
  ssl:
    key: /opt/apigee/.edgemicro/tls.key
    cert: /opt/apigee/.edgemicro/tls.crt
    passphrase: admin123
    rejectUnauthorized: true
    requestCert: false
  logging:
...

  3. מריצים את הפקודה הבאה כדי לקודד ב-base64 את קובץ התצורה של Edge Microgateway שנמצא ב-$HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    כאשר your_org ו-your_env הם הארגון והסביבה שבהם השתמשתם כשהרצתם את הפקודה edgemicro config.

    חשוב לזכור להציב סימני סימונים עורפיים (`) מסביב לפקודה. לדוגמה:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. מריצים את הפקודה הבאה כדי להפעיל את Edge Microgateway בקונטיינר של Docker.

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

5. בדיקת ההגדרה של TLS (אבטחת שכבת התעבורה)

  1. מריצים את פקודת ה-cURL הבאה כדי לבדוק את ההגדרה. מחליפים את נתיב הבסיס שבו השתמשתם בשרת proxy שתומך ב-microgateway ואת מפתח ה-API שהתקבל מהאפליקציה למפתחים שיצרתם ב-Apigee Edge. לדוגמה:

    curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

    השגיאה הבאה אמורה להופיע:

    ...
*  subject: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  start date: Dec 10 02:12:22 2018 GMT
*  expire date: Sep 29 02:12:22 2021 GMT
*  issuer: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 502 Bad Gateway
< Date: Wed, 12 Dec 2018 05:25:01 GMT
< Connection: keep-alive
< Content-Length: 93
<
* Connection #0 to host localhost left intact
{"message":"unable to verify the first certificate","code":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}

  2. מפעילים מחדש את Edge Microgateway, אבל הפעם מוסיפים את המשתנה NODE_EXTRA_CA_CERTS.

    docker run -P -p 8443:8443 -d --name edgemicro \
-v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \
-v path_to_your_logs_dir:/opt/apigee/logs \
-e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \
-e EDGEMICRO_PORT=8443 \
-e EDGEMICRO_ORG=$EDGEMICRO_ORG \
-e EDGEMICRO_ENV=$EDGEMICRO_ENV \
-e EDGEMICRO_KEY=$EDGEMICRO_KEY \
-e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
--link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro

  3. מריצים את הפקודה הבאה של cURL. מחליפים את נתיב הבסיס ואת מפתח ה-API כמו קודם. לדוגמה:

    curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

  4. בודקים את הפלט. כשהפעולה תושלם, תתקבל תגובה בסטטוס HTTP 200:

    ...
> GET /local HTTP/1.1
> Host: localhost:8443
> User-Agent: curl/7.54.0
> Accept: */*
> x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd
>
< HTTP/1.1 200 OK
< x-powered-by: Express
< content-type: text/html; charset=utf-8
< etag: W/"c-M6tWOb/Y57lesdjQuHeB1P/qTV0"
< date: Wed, 12 Dec 2018 05:49:28 GMT
< x-response-time: 421
< Connection: keep-alive
< Transfer-Encoding: chunked
<
Hello world

הוספת פלאגין מותאם אישית

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

יש שתי אפשרויות לפריסת יישומי פלאגין במכונה של Edge Microgateway שפועלת בקונטיינר מסוגDocker:

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

אפשרות א': טענו את ספריית יישומי הפלאגין על אמצעי אחסון

(נוסף בגרסה 2.5.27) השלבים להוספת יישומי פלאגין באמצעות תושבת לעוצמת הקול דומים לשלבים הנדרשים להוספת כל פלאגין מותאם אישית ל-Edge Microgateway. כשאתם מריצים את הקונטיינר של Docker, אתם יכולים לטעון את ספריית יישומי הפלאגין במערכת המקומית (עוצמת הקול) בנקודת הטעינה של הקונטיינר, שהיא /opt/apigee/plugins. לאחר מכן מציינים את ספריית עוצמת הקול המקומית בקובץ התצורה של Edge Microgateway.

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

  1. הפסקת המיקרו-שער של Edge:

    edgemicro stop

  2. יצירת ספרייה עבור יישומי הפלאגין המותאמים אישית. לדוגמה, יוצרים

    $HOME/edgemicro/custom/plugins

  3. הוספת ספריית הפלאגין בהתאמה אישית לקובץ התצורה של Edge Microgateway. לדוגמה:

      plugins:
    dir: $HOME/edgemicro/custom/plugins
    sequence:
      - oauth
      - response-uppercase
  ````

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

    custom
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

  5. מריצים את הקונטיינר של Docker עם פקודה שדומה לזו, ותוך שימוש באפשרות -v כדי לטעון את ספריית יישומי הפלאגין בנפח האחסון של Docker. בפקודה הבאה לדוגמה, ספריית יישומי הפלאגין $HOME/edgemicro/custom/plugins (שבה נמצא הפלאגין המותאם אישית) ממופה לנקודת הטעינה של הקונטיינר /opt/apigee/plugins:

    docker run -P -p 8000:8000 -d --name edgemicro \
-v /var/tmp:/opt/apigee/logs \
-v $HOME/edgemicro/custom/plugins:/opt/apigee/plugins \
-e EDGEMICRO_PROCESSES=1 \
-e EDGEMICRO_ORG=jdoe \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=39c4b561100cd7f258768d1072f3e1d7c17b5f36a18fe89972bb5c9ce7e58fb \
-e EDGEMICRO_SECRET=f5f9e239a38b4e6cc99c2aa067716a84aebdcff9580a7925fc500e402b1a5fa \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicro \
--security-opt=no-new-privileges \
--cap-drop=ALL gcr.io/apigee-microgateway/edgemicro:latest

  6. צריך להפעיל את ה-API כדי לבדוק את הפלאגין.

מידע נוסף זמין במאמר VOLUME [מערכות קבצים משותפות].

אפשרות ב': בניית יישומי הפלאגין בקונטיינר

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

1. חבילה של יישומי הפלאגין

  1. כותבים ובודקים את הפלאגין בהתאם להוראות במאמר כתיבת פלאגין פשוט.

  2. צריך להציב את קוד הפלאגין במבנה המתאים של הספרייה. ספריות פלאגין חייבות להיות במבנה מוגדר. הדוגמה הבאה מציגה את המבנה שצריך לעקוב אחריו, כאשר response-uppercase ו-request-headers הם שמות התיקיות שמכילות קוד פלאגין מותאם אישית (השמות האלה הם דוגמאות בלבד, שמות התיקיות שלכם עשויים להיות שונים):

    plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

  3. cd לתיקייה plugin.

  4. בתיקייה plugin, דוחסים את כל התיקייה plugins:

    zip -r plugins.zip plugins/

2. יצירת תמונת Docker

בשלב הבא, יוצרים Dockerfile כדי להוסיף את קוד הפלאגין לתמונה של Edge Microgateway.

  1. יוצרים קובץ חדש בשם Dockerfile באותה ספרייה שבה נמצא קובץ ה-ZIP.

  2. מוסיפים את הקוד הבא אל Dockerfile ושומרים את הקובץ:

    USER root
RUN apk update && \
    apk upgrade && \
    apk add zipapk add zip && \
    mkdir /opt/apigee/customplugins && \
    chown apigee:apigee /opt/apigee/customplugins
COPY plugins.zip /opt/apigee/customplugins
RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins"
EXPOSE 8000
EXPOSE 8443
USER apigee
ENTRYPOINT ["entrypoint"]

  3. יוצרים תמונת Docker חדשה של Edge Microgateway באמצעות יישומי הפלאגין:

    docker build -t image-name .

    לדוגמה:

    docker build -t edgemicroplugins .

3. עדכון התצורה של Edge Microgateway

עכשיו, אחרי שיישומי הפלאגין נארזים, עליכם להוסיף אותם לקובץ התצורה של Edge Microgateway.

  1. פותחים את קובץ התצורה של Edge Microgateway בעורך:

    $HOME/.edgemicro/org-env-config.yaml

    לדוגמה:

    vi $HOME/.edgemicro/myorg-test-config.yaml

  2. מוסיפים את ספריית הפלאגין לקובץ התצורה. בדוגמה הבאה, המאפיין dir מציין את המיקום של קוד הפלאגין (שציינתם ב-Dockerfile). צריך לציין גם את השם של ספריית הפלאגין, בדוגמה שלמטה היא response-uppercase. 

    edgemicro:
  ...
  plugins:
    dir: /opt/apigee/plugins
    sequence:
      - oauth
      - response-uppercase

4. הפעלת המיקרו-גייט

לבסוף, עליכם להפעיל את המיקרו-שער במכל.

  1. מריצים את הפקודה הבאה כדי לבצע קידוד base64 בקובץ התצורה של Edge Microgateway, שנמצא ב-$HOME/.edgemicro:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`

    כאשר your_org ו-your_env הם הארגון והסביבה שבהם השתמשתם כשהרצתם את הפקודה edgemicro config.

    חשוב לזכור להציב סימני סימונים עורפיים (`) מסביב לפקודה. לדוגמה:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  2. מריצים את Edge Microgateway כקונטיינר. הפקודה מגדירה כמה משתני סביבה שמשמשים את זמן הריצה של הקונטיינר כדי להפעיל את Edge Microgateway:

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=your_org \
-e EDGEMICRO_ENV=your_env \
-e EDGEMICRO_KEY=your_key \
-e EDGEMICRO_SECRET=your_secret \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins image_name

    לדוגמה:

    docker run -P -p 8000:8000 -d --name edgemicroplugins \
-e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \
-e EDGEMICRO_ORG=docs \
-e EDGEMICRO_ENV=test \
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \
-e SERVICE_NAME=edgemicroplugins edgemicroplugins

  3. קרא ל-API שלך כדי לבדוק את הפלאגין:

    כדי לבדוק שקוד הפלאגין מבוצע על ידי קריאה ל-API ומוודאים שהפלט תקין:

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    לדוגמה, הפלאגין response-uppercase עשוי להחזיר תשובה כזו:

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
  HELLO, WORLD!