שימוש ב-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 container, צריך ליצור (או לוודא שיש) את הישויות של 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. לפני שממשיכים לשלבים הבאים, חשוב לוודא שביצעתם את כל השלבים בקטע דרישות מוקדמות.

  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 run reference.
    -p ממפים באופן מפורש יציאה בודדת או טווח של יציאות. אפשר לעיין גם במאמר Docker run reference.
    -d הפעלה במצב מנותק. אפשר לעיין גם במאמר Docker run reference.
    -v, --volume מציין את נקודת העיגון של אמצעי אחסון. שימו לב: אם מגדירים את Edge Microgateway לשימוש ב-TLS במאגר Docker, צריך לחשוף את יציאה 8443 אם מעלים את ספריית קובצי היומן. אפשר גם לעיין בכרך [מערכות קבצים משותפות]. מידע נוסף זמין במאמר בנושא שימוש ב-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 רשימה של דומיינים ש-Edge Microgateway לא צריך להעביר אליהם בקשות כשרת proxy, כשהדומיינים מופרדים בפסיקים. מידע נוסף זמין במאמר בנושא הגדרת Edge Microgateway מאחורי חומת אש של חברה.

    לדוגמה: localhost,127.0.0.1,localaddress,.localdomain.com
    NODE_EXTRA_CA_CERTS (אופציונלי) משתמשים בפרמטר הזה אם משתמשים ב-CA שלא מהימן כברירת מחדל על ידי Node.js. מגדירים את הערך של הפרמטר הזה לנתיב לקובץ שמכיל אישור מהימן אחד או יותר בפורמט PEM. פרטים נוספים זמינים במאמר בנושא אישורי TLS.
    --security-opt (אופציונלי) הגדרת אפשרויות אבטחה רצויות של Docker. מידע נוסף זמין בקטע הגדרת אבטחה במאמרי העזרה של Docker.
    --cap-drop (אופציונלי) מגדיר מגבלות על היכולות של Linux שמותרות בקונטיינר. מידע נוסף זמין במאמר Runtime privilege and Linux capabilities (הרשאות בזמן ריצה ויכולות של 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, עוברים לאפליקציית המפתח שיצרתם קודם. בדף Developer App, מציגים את Consumer Key ומעתיקים אותו. הערך הזה הוא מפתח ה-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: אבטחת Edge Microgateway.

הפסקת Edge Microgateway

כדי להפסיק את 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, אפשר להפוך את קובצי האישורים לזמינים בנקודת ה-mount הזו ולהפנות אליהם בקובץ ההגדרות של 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
...

שימוש ב-CA שלא מהימן על ידי 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 לא מוטמעת בקונטיינר Docker של Edge Microgateway כברירת מחדל. כדי לבצע את המשימה, צריך ליצור קובץ אימג' של 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. מוסיפים את ה-stanza הבא ל-openssl.cnf כדי ליצור את מאפייני ה-SNI הנכונים:

    [ 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. בסיום, אמור להיות לכם פרוקסי עם 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`

אפשר לעיין גם במאמר הפעלת Edge Micro כקונטיינר 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. שימו לב לפרמטרים הבאים שבהם נעשה שימוש בפקודה. הם שונים מהפקודה הבסיסית שמתוארת במאמר הפעלת Edge Micro כקונטיינר Docker.

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

5. בדיקת הגדרות ה-TLS

  1. מריצים את פקודת ה-cURL הבאה כדי לבדוק את ההגדרה. מחליפים את נתיב הבסיס ואת מפתח ה-API בפקודה. בדוגמה הבאה אנחנו מניחים שאתם נמצאים בספרייה שבה נמצא rootca.pem, ולפרוקסי שיצרתם יש נתיב בסיס /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 יוצא (southbound) בין שרת 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. מוסיפים את ה-stanza הבא ל-openssl.cnf כדי ליצור את מאפייני ה-SNI הנכונים:

    [ 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 ל-API עם מודעות ל-Edge Microgateway ב-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 עם מודעות למיקרו-שער ואת מפתח ה-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 Microgateway:

    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

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

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

  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. יוצרים קובץ אימג' חדש של Edge Microgateway Docker עם הפלאגינים שלכם:

    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!