שימוש ב-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. הישויות האלה כוללות מודל Edge עם בקרת גישה ל-Edge Microgateway שרת proxy, מוצר 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:

    chown -R 100:101 ~/.edgemicro/ \
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 מציינת טעינת עוצמת קול. חשוב לשים לב שאם מגדירים Microsoft 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 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 שמותרות בקונטיינר. מידע נוסף מופיע במאמר הרשאות זמן ריצה ויכולות Linux במסמכי התיעוד של Docker.

    לדוגמה:

    chown -R 100:101 ~/.edgemicro/ \
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. לדוגמה, אם ה-basepath של ה-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.

הפסקת Microsoft Edge Microgateway

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

docker stop edgemicro

הפעלה מחדש של Microsoft 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. כשמגדירים שימוש באישורי TLS (אבטחת שכבת התעבורה) ב-Edge Microgateway, אפשר להגדיר בקובצי אישורים שזמינים בנקודת הטעינה הזו, ומתייחסים אליהם קובץ התצורה של 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 עם גבול דרום.

לדוגמה:

chown -R 100:101 ~/.edgemicro/ \
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. לדוגמה:

chown -R 100:101 ~/.edgemicro/ \
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. מוסיפים את הבית הבא אל 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, אם עדיין לא עשיתם זאת. בסיום, ליצור שרת 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`

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

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

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

    chown -R 100:101 ~/.edgemicro/ \
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 משמש להוספת CA בהתאמה אישית (לפי הצורך במקרה כזה) של אישורים בחתימה עצמית).

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. מוסיפים את הבית הבא אל 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. יוצרים קובץ Docker חדש באותה ספרייה שבה נמצא server.js, כאשר WORKDIR הוא הנתיב לרמה הבסיסית (root) של אפליקציית 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 API ב-Edge.

    • שם שרת ה-proxy: edgemicro_local
    • גרסה: 1
    • Basepath: /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.

    chown -R 100:101 ~/.edgemicro/ \
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 הבאה. החלפה את ה-basepath שבו השתמשתם בשרת 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.

    chown -R 100:101 ~/.edgemicro/ \
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 הבאה. החלפה Basepath ומפתח ה-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

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

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

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

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

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

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

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

  1. Stop 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 של הקונטיינר:

    chown -R 100:101 ~/.edgemicro/ \
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. יוצרים תמונת 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 מציין את המיקום של קוד הפלאגין (שצוין על ידך בקובץ ה-Docker). צריך גם לציין את השם של ספריית יישומי הפלאגין, בדוגמה שלמטה הוא 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!