Anda sedang melihat dokumentasi Apigee Edge.
Buka dokumentasi
Apigee X. info
Edge Microgateway v. 3.2.x
Topik ini membahas cara mengelola dan mengonfigurasi Edge Microgateway.
Mengupgrade Edge Microgateway jika Anda memiliki koneksi internet
Bagian ini menjelaskan cara mengupgrade penginstalan Edge Microgateway yang ada. Jika Anda beroperasi tanpa koneksi internet, lihat Dapatkah saya menginstal Edge Microgateway tanpa koneksi internet?.
Apigee merekomendasikan agar Anda menguji konfigurasi yang ada dengan versi baru sebelum mengupgrade lingkungan produksi.
- Jalankan perintah
npm
berikut untuk mengupgrade ke Edge Microgateway versi terbaru:npm upgrade edgemicro -g
Untuk menginstal Edge Microgateway versi tertentu, Anda harus menentukan nomor versi dalam perintah penginstalan. Misalnya, untuk menginstal ke versi 3.2.3, gunakan perintah berikut:
npm install edgemicro@3.2.3 -g
- Lihat nomor versi aplikasi. Misalnya, jika Anda menginstal versi 3.2.3:
edgemicro --version current nodejs version is v12.5.0 current edgemicro version is 3.2.3
- Terakhir, upgrade ke proxy edgemicro-auth versi terbaru:
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
Melakukan perubahan konfigurasi
File konfigurasi yang perlu Anda ketahui mencakup:
- File konfigurasi sistem default
- File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi
- File konfigurasi dinamis untuk menjalankan instance
Bagian ini membahas file tersebut dan hal-hal yang perlu Anda ketahui tentang cara mengubahnya.
File konfigurasi sistem default
Saat Anda menginstal Edge Microgateway, file konfigurasi sistem default akan ditempatkan di sini:
prefix/lib/node_modules/edgemicro/config/default.yaml
Dengan prefix adalah direktori awalan npm
. Lihat
Lokasi penginstalan Edge Microgateway jika Anda tidak dapat menemukan direktori ini.
Jika mengubah file konfigurasi sistem, Anda harus menginisialisasi ulang, mengonfigurasi ulang, dan memulai ulang Edge Microgateway:
edgemicro initedgemicro configure [params]
edgemicro start [params]
File konfigurasi default untuk instance Edge Microgateway yang baru diinisialisasi
Saat Anda menjalankan edgemicro init
, file konfigurasi sistem (dijelaskan
di atas), default.yaml
, ditempatkan di direktori ~/.edgemicro
.
Jika mengubah file konfigurasi di ~/.edgemicro
, Anda harus mengonfigurasi ulang dan memulai ulang
Edge Microgateway:
edgemicro stopedgemicro configure [params]
edgemicro start [params]
File konfigurasi dinamis untuk menjalankan instance
Saat Anda menjalankan edgemicro configure [params]
, file konfigurasi
dinamis akan dibuat di ~/.edgemicro
. File diberi nama sesuai dengan pola ini: org-env-config.yaml
, dengan org dan env adalah nama organisasi dan lingkungan Apigee Edge Anda. Anda dapat menggunakan file ini untuk membuat perubahan konfigurasi, lalu memuat ulang tanpa waktu tunggu. Misalnya, jika menambahkan dan mengonfigurasi plugin,
Anda dapat memuat ulang konfigurasi tanpa mengalami periode nonaktif, seperti yang dijelaskan di bawah.
Jika Edge Microgateway sedang berjalan (opsi zero-downtime):
- Muat ulang konfigurasi Edge Microgateway:
edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET
Dengan keterangan:
- $ORG adalah nama organisasi Edge Anda (Anda harus menjadi administrator organisasi).
- $ENV adalah lingkungan di organisasi Anda (seperti "test" atau "prod").
- $KEY adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
- $SECRET adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
Contoh:
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \ -s 05c14356e42ed1...4e34ab0cc824
Jika Edge Microgateway dihentikan:
- Mulai ulang Edge Microgateway:
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
Dengan keterangan:
- $ORG adalah nama organisasi Edge Anda (Anda harus menjadi administrator organisasi).
- $ENV adalah lingkungan di organisasi Anda (seperti "test" atau "prod").
- $KEY adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
- $SECRET adalah kunci yang ditampilkan sebelumnya oleh perintah konfigurasi.
Contoh:
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \ -s 05c1435...e34ab0cc824
Berikut adalah contoh file konfigurasi. Untuk mengetahui detail tentang setelan file konfigurasi, lihat referensi konfigurasi Edge Microgateway.
edge_config: bootstrap: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://docs-test.apigee.net/edgemicro-auth/products' edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true oauth: allowNoAuthorization: false allowInvalidAuthorization: false verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey' analytics: uri: >- https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test
Menyetel variabel lingkungan
Perintah antarmuka command line yang memerlukan nilai untuk organisasi dan lingkungan Edge Anda, serta kunci dan secret yang diperlukan untuk memulai Edge Microgateway dapat disimpan dalam variabel lingkungan berikut:
EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET
Menetapkan variabel ini bersifat opsional. Jika menetapkannya, Anda tidak perlu menentukan nilainya saat menggunakan Antarmuka Command Line (CLI) untuk mengonfigurasi dan memulai Edge Microgateway.
Mengonfigurasi SSL di server Edge Microgateway
Tonton video berikut untuk mempelajari cara mengonfigurasi TLS di Microgateway Apigee Edge:
Video | Deskripsi |
---|---|
Mengonfigurasi TLS 1 arah Utara | Pelajari cara mengonfigurasi TLS di Microgateway Apigee Edge. Video ini memberikan Ringkasan TLS dan pentingnya, memperkenalkan TLS di Edge Microgateway, dan menunjukkan cara mengonfigurasi TLS Satu Arah Utara. |
Mengonfigurasi TLS 2 arah Northbound | Ini adalah video kedua tentang cara mengonfigurasi TLS di Microgateway Apigee Edge. Video ini menjelaskan cara mengonfigurasi TLS 2 arah northbound. |
Mengonfigurasi TLS Selatan 1 arah dan 2 arah | Video ketiga tentang cara mengonfigurasi TLS di Microgateway Apigee Edge ini menjelaskan cara mengonfigurasi TLS 1 arah dan 2 arah southbound. |
Anda dapat mengonfigurasi server Microgateway untuk menggunakan SSL. Misalnya, dengan SSL yang dikonfigurasi, Anda dapat memanggil API melalui Edge Microgateway dengan protokol "https", seperti ini:
https://localhost:8000/myapi
Untuk mengonfigurasi SSL di server Microgateway, ikuti langkah-langkah berikut:
- Buat atau dapatkan sertifikat dan kunci SSL menggunakan utilitas openssl atau metode apa pun yang Anda inginkan.
- Tambahkan atribut
edgemicro:ssl
ke file konfigurasi Edge Microgateway. Untuk daftar lengkap opsi, lihat tabel di bawah. Misalnya:
edgemicro: ssl: key: <absolute path to the SSL key file> cert: <absolute path to the SSL cert file> passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2 requestCert: true
- Mulai ulang Edge Microgateway. Ikuti langkah-langkah yang diuraikan dalam Membuat perubahan konfigurasi, bergantung pada file konfigurasi yang Anda edit: file default atau file konfigurasi runtime.
Berikut adalah contoh bagian edgemicro
dari file konfigurasi, dengan SSL
dikonfigurasi:
edgemicro: port: 8000 max_connections: 1000 max_connections_hard: 5000 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - oauth ssl: key: /MyHome/SSL/em-ssl-keys/server.key cert: /MyHome/SSL/em-ssl-keys/server.crt passphrase: admin123 #option added in v2.2.2 rejectUnauthorized: true #option added in v2.2.2
Berikut adalah daftar semua opsi server yang didukung:
Opsi | Deskripsi |
---|---|
key |
Jalur ke file ca.key (dalam format PEM). |
cert |
Jalur ke file ca.cert (dalam format PEM). |
pfx |
Jalur ke file pfx yang berisi kunci pribadi, sertifikat, dan sertifikat CA
klien dalam format PFX. |
passphrase |
String yang berisi frasa sandi untuk kunci pribadi atau PFX. |
ca |
Jalur ke file yang berisi daftar sertifikat tepercaya dalam format PEM. |
ciphers |
String yang menjelaskan cipher yang akan digunakan, dipisahkan dengan ":". |
rejectUnauthorized |
Jika benar, sertifikat server akan diverifikasi berdasarkan daftar CA yang disediakan. Jika verifikasi gagal, error akan ditampilkan. |
secureProtocol |
Metode SSL yang akan digunakan. Misalnya, SSLv3_method untuk memaksa SSL ke versi 3. |
servername |
Nama server untuk ekstensi TLS SNI (Server Name Indication). |
requestCert |
true untuk SSL 2 arah; false untuk SSL 1 arah |
Menggunakan opsi SSL/TLS klien
Anda dapat mengonfigurasi Edge Microgateway sebagai klien TLS atau SSL saat terhubung ke endpoint target. Dalam file konfigurasi Microgateway, gunakan elemen target untuk menetapkan opsi SSL/TLS. Perhatikan bahwa Anda dapat menentukan beberapa target spesifik. Contoh multi-target disertakan di bawah ini.
Contoh ini memberikan setelan yang akan diterapkan ke semua host:
edgemicro: ... targets: ssl: client: key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
Dalam contoh ini, setelan hanya diterapkan ke host yang ditentukan:
edgemicro: ... targets: - host: 'myserver.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true
Berikut adalah contoh untuk TLS:
edgemicro: ... targets: - host: 'myserver.example.com' tls: client: pfx: /Users/myname/twowayssl/ssl/client.pfx passphrase: admin123 rejectUnauthorized: true
Jika ingin menerapkan setelan TLS/SSL ke beberapa target tertentu, Anda harus menentukan host pertama dalam konfigurasi sebagai "kosong", yang mengaktifkan permintaan universal, lalu menentukan host tertentu dalam urutan apa pun. Dalam contoh ini, setelan diterapkan ke beberapa host tertentu:
targets: - host: ## Note that this value must be "empty" ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt passphrase: admin123 rejectUnauthorized: true - host: 'myserver1.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt rejectUnauthorized: true - host: 'myserver2.example.com' ssl: client: key: /Users/myname/twowayssl/ssl/client.key cert: /Users/myname/twowayssl/ssl/ca.crt rejectUnauthorized: true
Berikut adalah daftar semua opsi klien yang didukung:
Opsi | Deskripsi |
---|---|
pfx |
Jalur ke file pfx yang berisi kunci pribadi, sertifikat, dan sertifikat CA
klien dalam format PFX. |
key |
Jalur ke file ca.key (dalam format PEM). |
passphrase |
String yang berisi frasa sandi untuk kunci pribadi atau PFX. |
cert |
Jalur ke file ca.cert (dalam format PEM). |
ca |
Jalur ke file yang berisi daftar sertifikat tepercaya dalam format PEM. |
ciphers |
String yang menjelaskan cipher yang akan digunakan, dipisahkan dengan ":". |
rejectUnauthorized |
Jika benar, sertifikat server akan diverifikasi berdasarkan daftar CA yang disediakan. Jika verifikasi gagal, error akan ditampilkan. |
secureProtocol |
Metode SSL yang akan digunakan. Misalnya, SSLv3_method untuk memaksa SSL ke versi 3. |
servername |
Nama server untuk ekstensi TLS SNI (Server Name Indication). |
Menyesuaikan proxy edgemicro-auth
Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2.
Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure
. Anda dapat mengubah konfigurasi default proxy ini untuk menambahkan dukungan klaim kustom ke Token Web JSON (JWT), mengonfigurasi masa berlaku token, dan membuat token refresh. Untuk mengetahui detailnya, lihat halaman edgemicro-auth di GitHub.
Menggunakan layanan autentikasi kustom
Secara default, Edge Microgateway menggunakan proxy yang di-deploy di Apigee Edge untuk autentikasi OAuth2.
Proxy ini di-deploy saat Anda pertama kali menjalankan edgemicro configure
. Secara default, URL proxy ini ditentukan dalam file konfigurasi Edge Microgateway sebagai berikut:
authUri: https://myorg-myenv.apigee.net/edgemicro-auth
Jika Anda ingin menggunakan layanan kustom Anda sendiri untuk menangani autentikasi, ubah nilai authUri
dalam file konfigurasi agar mengarah ke layanan Anda. Misalnya, Anda mungkin memiliki
layanan yang menggunakan LDAP untuk memverifikasi identitas.
Mengelola file log
Edge Microgateway mencatat informasi tentang setiap permintaan dan respons. File log memberikan informasi yang berguna untuk proses debug dan pemecahan masalah.
Tempat file log disimpan
Secara default, file log disimpan di /var/tmp
.
Cara mengubah direktori file log default
Direktori tempat file log disimpan ditentukan dalam file konfigurasi Edge Microgateway. Lihat juga Melakukan perubahan konfigurasi.
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Ubah nilai dir untuk menentukan direktori file log yang berbeda.
Mengirim log ke konsol
Anda dapat mengonfigurasi logging sehingga informasi log dikirim ke output standar, bukan ke
file log. Tetapkan flag to_console
ke benar (true) sebagai berikut:
edgemicro: logging: to_console: true
Dengan setelan ini, log akan dikirim ke output standar. Saat ini, Anda tidak dapat mengirim log ke stdout dan ke file log.
Cara menetapkan level logging
Anda menentukan level log yang akan digunakan dalam konfigurasi edgemicro
. Untuk mengetahui
daftar lengkap level log dan deskripsinya, lihat atribut edgemicro.
Misalnya, konfigurasi berikut menetapkan level logging ke debug
:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: debug dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Cara mengubah interval log
Anda dapat mengonfigurasi interval ini di file konfigurasi Edge Microgateway. Lihat juga Melakukan perubahan konfigurasi.
Atribut yang dapat dikonfigurasi adalah:
- stats_log_interval: (default: 60) Interval, dalam detik, saat data statistik ditulis ke file log API.
- rotate_interval: (default: 24) Interval, dalam jam, saat file log diputar. Contoh:
edgemicro: home: ../gateway port: 8000 max_connections: -1 max_connections_hard: -1 logging: level: info dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Cara melonggarkan izin file log yang ketat
Secara default, Edge Microgateway membuat file log aplikasi (api-log.log
) dengan tingkat izin file
ditetapkan ke 0600. Tingkat izin ini tidak mengizinkan aplikasi atau pengguna eksternal
membaca file log. Untuk melonggarkan tingkat izin yang ketat ini, tetapkan logging:disableStrictLogFile
ke true
. Jika atribut ini adalah true
, file log akan dibuat dengan izin file yang ditetapkan ke 0755. Jika false
atau jika atribut tidak diberikan, izin defaultnya adalah 0600.
Ditambahkan di v3.2.3.
Contoh:
edgemicro: logging: disableStrictLogFile: true
Praktik pemeliharaan file log yang baik
Seiring bertambahnya data file log dari waktu ke waktu, Apigee merekomendasikan agar Anda mengadopsi praktik berikut:
- Karena file log dapat menjadi cukup besar, pastikan direktori file log memiliki ruang yang cukup. Lihat bagian berikut Tempat file log disimpan dan Cara mengubah direktori file log default.
- Hapus atau pindahkan file log ke direktori arsip terpisah minimal seminggu sekali.
- Jika kebijakan Anda adalah menghapus log, Anda dapat menggunakan perintah CLI
edgemicro log -c
untuk menghapus (membersihkan) log lama.
Konvensi penamaan file log
Setiap instance Edge Microgateway menghasilkan file log dengan ekstensi .log
. Konvensi
penamaan untuk file log adalah sebagai berikut:
edgemicro-HOST_NAME-INSTANCE_ID-api.log
Contoh:
edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
Tentang konten file log
Ditambahkan di: v2.3.3
Secara default, layanan logging menghilangkan JSON proxy, produk, dan Token Web JSON (JWT) yang didownload. Jika Anda ingin menampilkan objek ini ke konsol, tetapkan flag command line
DEBUG=*
saat Anda memulai Edge Microgateway. Contoh:
DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456
Isi file log "api"
File log "api" berisi informasi mendetail tentang alur permintaan dan respons melalui Edge Microgateway. File log "api" diberi nama seperti ini:
edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log
Untuk setiap permintaan yang dilakukan ke Edge Microgateway, empat peristiwa akan dicatat dalam file log "api":
- Permintaan masuk dari klien
- Permintaan keluar yang dibuat ke target
- Respons masuk dari target
- Respons keluar ke klien
Setiap entri terpisah ini direpresentasikan dalam notasi singkat untuk membantu membuat file log lebih ringkas. Berikut adalah empat contoh entri yang mewakili keempat peristiwa tersebut. Dalam file log, kode tersebut akan terlihat seperti ini (nomor baris hanya untuk referensi dalam dokumen, tidak muncul dalam file log).
(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0 (2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0 (3) 1436403888672 info tres s=200, d=7, i=0 (4) 1436403888676 info res s=200, d=11, i=0
Mari kita lihat satu per satu:
1. Contoh permintaan masuk dari klien:
1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
- 1436403888651 - Stempel tanggal Unix
- info - Level logging. Nilai ini bergantung pada konteks transaksi dan tingkat logging yang ditetapkan
dalam konfigurasi
edgemicro
. Lihat Cara menetapkan tingkat logging. Untuk data statistik, level ditetapkan kestats
. Data statistik dilaporkan pada interval reguler yang ditetapkan dengan konfigurasistats_log_interval
. Lihat juga Cara mengubah interval log. - req - Mengidentifikasi peristiwa. Dalam hal ini, permintaan dari klien.
- m - Kata kerja HTTP yang digunakan dalam permintaan.
- u - Bagian URL setelah jalur dasar.
- h - Host dan nomor port tempat Edge Microgateway memproses.
- r - Host dan port jarak jauh tempat permintaan klien berasal.
- i - ID permintaan. Keempat entri peristiwa akan memiliki ID yang sama. Setiap permintaan diberi ID permintaan unik. Menghubungkan data log berdasarkan ID permintaan dapat memberikan insight yang berharga tentang latensi target.
- d - Durasi dalam milidetik sejak permintaan diterima oleh Edge Microgateway. Pada contoh di atas, respons target untuk permintaan 0 diterima setelah 7 milidetik (baris 3), dan respons dikirim ke klien setelah 4 milidetik tambahan (baris 4). Dengan kata lain, total latensi permintaan adalah 11 milidetik, dengan 7 milidetik diambil oleh target dan 4 milidetik oleh Edge Microgateway itu sendiri.
2. Contoh permintaan keluar yang dibuat ke target:
1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0
- 1436403888651 - Stempel tanggal Unix
- info - Level logging. Nilai ini bergantung pada konteks transaksi dan tingkat logging yang ditetapkan
dalam konfigurasi
edgemicro
. Lihat Cara menetapkan tingkat logging. Untuk data statistik, level ditetapkan kestats
. Data statistik dilaporkan pada interval reguler yang ditetapkan dengan konfigurasistats_log_interval
. Lihat juga Cara mengubah interval log. - treq - Mengidentifikasi peristiwa. Dalam hal ini, permintaan target.
- m - Kata kerja HTTP yang digunakan dalam permintaan target.
- u - Bagian URL setelah jalur dasar.
- h - Host dan nomor port target backend.
- i - ID entri log. Keempat entri peristiwa akan memiliki ID yang sama.
3. Contoh respons masuk dari target
1436403888672 info tres s=200, d=7, i=0
1436403888651 - Stempel tanggal Unix
- info - Level logging. Nilai ini bergantung pada konteks transaksi dan tingkat logging yang ditetapkan
dalam konfigurasi
edgemicro
. Lihat Cara menetapkan tingkat logging. Untuk data statistik, level ditetapkan kestats
. Data statistik dilaporkan pada interval reguler yang ditetapkan dengan konfigurasistats_log_interval
. Lihat juga Cara mengubah interval log. - tres - Mengidentifikasi peristiwa. Dalam hal ini, respons target.
- s - Status respons HTTP.
- d - Durasi dalam milidetik. Waktu yang diperlukan untuk panggilan API oleh target.
- i - ID entri log. Keempat entri peristiwa akan memiliki ID yang sama.
4. Contoh respons keluar ke klien
1436403888676 info res s=200, d=11, i=0
1436403888651 - Stempel tanggal Unix
- info - Level logging. Nilai ini bergantung pada konteks transaksi dan tingkat logging yang ditetapkan
dalam konfigurasi
edgemicro
. Lihat Cara menetapkan tingkat logging. Untuk data statistik, level ditetapkan kestats
. Data statistik dilaporkan pada interval reguler yang ditetapkan dengan konfigurasistats_log_interval
. Lihat juga Cara mengubah interval log. - res - Mengidentifikasi peristiwa. Dalam hal ini, respons terhadap klien.
- s - Status respons HTTP.
- d - Durasi dalam milidetik. Ini adalah total waktu yang dibutuhkan oleh panggilan API, termasuk waktu yang dibutuhkan oleh API target dan waktu yang dibutuhkan oleh Edge Microgateway itu sendiri.
- i - ID entri log. Keempat entri peristiwa akan memiliki ID yang sama.
Jadwal file log
File log dirotasi pada interval yang ditentukan oleh atribut konfigurasi rotate_interval. Entri akan terus ditambahkan ke file log yang sama hingga interval rotasi berakhir. Namun, setiap kali Edge Microgateway dimulai ulang, Edge Microgateway akan menerima UID baru dan membuat kumpulan file log baru dengan UID ini. Lihat juga Praktik pemeliharaan file log yang baik.
Pesan error
Beberapa entri log akan berisi pesan error. Untuk membantu mengidentifikasi tempat dan penyebab terjadinya error, lihat referensi error Edge Microgateway.
Referensi konfigurasi Edge Microgateway
Lokasi file konfigurasi
Atribut konfigurasi yang dijelaskan di bagian ini terletak di file konfigurasi Edge Microgateway. Lihat juga Melakukan perubahan konfigurasi.
Atribut edge_config
Setelan ini digunakan untuk mengonfigurasi interaksi antara instance Edge Microgateway dan Apigee Edge.
- bootstrap: (default: none) URL yang mengarah ke layanan khusus
Microgateway Edge yang berjalan di Apigee Edge. Edge Microgateway menggunakan layanan ini untuk
berkomunikasi dengan Apigee Edge. URL ini ditampilkan saat Anda menjalankan perintah untuk membuat
pasangan kunci publik/pribadi:
edgemicro genkeys
. Lihat Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya. - jwt_public_key: (default: none) URL yang mengarah ke proxy Edge Microgateway yang di-deploy di Apigee Edge. Proxy ini berfungsi sebagai endpoint autentikasi untuk menerbitkan token akses yang ditandatangani kepada klien. URL ini ditampilkan saat Anda menjalankan perintah untuk men-deploy proxy: edgemicro configure. Lihat Menyiapkan dan mengonfigurasi Edge Microgateway untuk mengetahui detailnya.
- quotaUri: Tetapkan properti konfigurasi ini jika Anda ingin mengelola kuota melalui proxy
edgemicro-auth
yang di-deploy ke organisasi Anda. Jika properti ini tidak ditetapkan, endpoint kuota akan ditetapkan secara default ke endpoint Edge Microgateway internal.edge_config: quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
atribut edgemicro
Setelan ini mengonfigurasi proses Edge Microgateway.
- port: (default: 8000) Nomor port tempat proses Edge Microgateway memproses.
- max_connections: (default: -1) Menentukan jumlah maksimum koneksi masuk serentak yang dapat diterima Edge Microgateway. Jika jumlah ini
terlampaui, status berikut akan ditampilkan:
res.statusCode = 429; // Too many requests
- max_connections_hard: (default: -1) Jumlah maksimum permintaan serentak yang dapat diterima Edge Microgateway sebelum menonaktifkan koneksi. Setelan ini dimaksudkan untuk menggagalkan serangan denial of service. Biasanya, tetapkan ke angka yang lebih besar dari max_connections.
-
logging:
-
level: (default: error)
- info - (Direkomendasikan) Mencatat semua permintaan dan respons yang mengalir melalui instance Edge Microgateway.
- warn - Hanya mencatat pesan peringatan ke dalam log.
- error - Hanya mencatat pesan error ke dalam log.
- debug - Mencatat pesan debug beserta pesan info, peringatan, dan error.
- trace - Mencatat informasi pelacakan untuk error beserta pesan info, peringatan, dan error.
- none - Jangan membuat file log.
- dir: (default: /var/tmp) Direktori tempat file log disimpan.
- stats_log_interval: (default: 60) Interval, dalam detik, saat data statistik ditulis ke file log API.
- rotate_interval: (default: 24) Interval, dalam jam, saat file log diputar.
-
level: (default: error)
- plugin: Plugin menambahkan fungsi ke Edge Microgateway. Untuk mengetahui detail tentang cara mengembangkan plugin, lihat Mengembangkan plugin kustom.
- dir: Jalur relatif dari direktori ./gateway ke direktori ./plugins, atau jalur absolut.
- sequence: Daftar modul plugin yang akan ditambahkan ke instance Edge Microgateway Anda. Modul akan dieksekusi sesuai urutan yang ditentukan di sini.
-
debug: Menambahkan proses debug jarak jauh ke proses Edge Microgateway.
- port: Nomor port yang akan diproses. Misalnya, tetapkan debugger IDE Anda untuk memproses port ini.
- args: Argumen untuk proses debug. Misalnya:
args --nolazy
- config_change_poll_interval: (default: 600 detik) Edge Microgateway
memuat konfigurasi baru secara berkala dan menjalankan pemuatan ulang jika ada yang berubah. Polling
mengambil setiap perubahan yang dilakukan di Edge (perubahan pada produk, proxy yang mendukung microgateway, dll.) serta
perubahan yang dilakukan pada file konfigurasi lokal.
- disable_config_poll_interval: (default: false) Tetapkan ke true untuk menonaktifkan polling perubahan otomatis.
- request_timeout: Menetapkan waktu tunggu habis untuk permintaan target. Waktu tunggu ditetapkan dalam detik. Jika waktu tunggu habis, Edge Microgateway akan merespons dengan kode status 504. (Ditambahkan v2.4.x)
- keep_alive_timeout: Properti ini memungkinkan Anda menetapkan waktu tunggu Edge Microgateway (dalam milidetik). (Default: 5 detik) (Ditambah v3.0.6)
- headers_timeout: Atribut ini membatasi jumlah waktu (dalam milidetik)
yang akan ditunggu oleh parser HTTP untuk menerima
header HTTP lengkap.
Contoh:
edgemicro: keep_alive_timeout: 6000 headers_timeout: 12000
Secara internal, parameter menetapkan atribut
Server.headersTimeout
Node.js pada permintaan. (Default: 5 detik lebih lama dari waktu yang ditetapkan denganedgemicro.keep_alive_timeout
. Setelan default ini mencegah load balancer atau proxy secara keliru memutuskan koneksi.) (Ditambahkan v3.1.1) - noRuleMatchAction: (String) Tindakan yang akan dilakukan (mengizinkan atau menolak akses) jika
aturan pencocokan yang ditentukan dalam plugin
accesscontrol
tidak di-resolve (tidak cocok). Nilai yang valid:ALLOW
atauDENY
Default:ALLOW
(Ditambahkan: v3.1.7) - enableAnalytics: (default: true) Tetapkan atribut ke false untuk
mencegah plugin analisis
dimuat. Dalam hal ini, tidak ada panggilan ke analisis Apigee Edge yang akan dilakukan. Jika ditetapkan ke true, atau jika atribut ini tidak diberikan, plugin analisis akan berfungsi seperti biasa. Lihat
atribut edgemicro untuk mengetahui
detailnya. (Ditambahkan v3.1.8).
Contoh:
edgemicro enableAnalytics=false|true
- on_target_response_abort: Atribut ini memungkinkan Anda mengontrol
perilaku Edge Microgateway jika koneksi antara klien (Edge Microgateway) dan
server target ditutup sebelum waktunya.
Nilai Deskripsi Default Jika on_target_response_abort
tidak ditentukan, perilaku defaultnya adalah memotong respons tanpa menampilkan error. Dalam file log, pesan peringatan ditampilkan dengantargetResponse aborted
dan kode respons 502.appendErrorToClientResponseBody
Error kustom TargetResponseAborted
ditampilkan ke klien. Dalam file log, pesan peringatan ditampilkan dengantargetResponse aborted
dan kode respons 502. Selain itu, errorTargetResponseAborted
dicatat ke dalam log dengan pesanTarget response ended prematurely.
abortClientRequest
Edge Microgateway membatalkan permintaan dan peringatan ditulis ke file log: TargetResponseAborted
dengan kode status permintaan 502.
Contoh:
edgemicro: on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest
atribut header
Setelan ini mengonfigurasi cara header HTTP tertentu diperlakukan.
- x-forwarded-for: (default: true) Tetapkan ke false untuk mencegah header x-forwarded-for diteruskan ke target. Perhatikan bahwa jika header x-forwarded-for ada dalam permintaan, nilainya akan ditetapkan ke nilai client-ip di Edge Analytics.
- x-forwarded-host: (default: true) Tetapkan ke false untuk mencegah header x-forwarded-host diteruskan ke target.
- x-request-id: (default: true) Tetapkan ke false untuk mencegah header x-request-id diteruskan ke target.
- x-response-time: (default: true) Tetapkan ke false untuk mencegah header x-response-time diteruskan ke target.
- via: (default: true) Tetapkan ke salah untuk mencegah header via diteruskan ke target.
atribut oauth
Setelan ini mengonfigurasi cara autentikasi klien diterapkan oleh Edge Microgateway.
- allowNoAuthorization: (default: false) Jika disetel ke true, panggilan API diizinkan untuk melewati Edge Microgateway tanpa header Otorisasi sama sekali. Tetapkan ke false untuk mewajibkan header Authorization (default).
- allowInvalidAuthorization: (default: false) Jika disetel ke true, panggilan API diizinkan untuk diteruskan jika token yang diteruskan di header Authorization tidak valid atau sudah tidak berlaku. Tetapkan ini ke salah (false) untuk mewajibkan token yang valid (default).
- authorization-header: (default: Authorization: Bearer) Header yang digunakan untuk mengirim token akses ke Edge Microgateway. Anda dapat mengubah setelan default jika target perlu menggunakan header Otorisasi untuk tujuan lain.
- api-key-header: (default: x-api-key) Nama header atau parameter kueri yang digunakan untuk meneruskan kunci API ke Edge Microgateway. Lihat juga Menggunakan kunci API.
- keep-authorization-header: (default: false) Jika ditetapkan ke true, header Otorisasi yang dikirim dalam permintaan akan diteruskan ke target (header tersebut akan dipertahankan).
- allowOAuthOnly -- Jika disetel ke benar, setiap API harus membawa header Otorisasi dengan Bearer Access Token. Memungkinkan Anda hanya mengizinkan model keamanan OAuth (sambil mempertahankan kompatibilitas mundur). (Ditambahkan 2.4.x)
- allowAPIKeyOnly -- Jika disetel ke benar (true), setiap API harus membawa header x-api-key (atau lokasi kustom) dengan Kunci API.Memungkinkan Anda hanya mengizinkan model keamanan kunci API (sambil mempertahankan kompatibilitas mundur). (Ditambahkan 2.4.x)
- gracePeriod -- Parameter ini membantu mencegah error yang disebabkan oleh sedikit perbedaan antara jam sistem Anda dan waktu Not Before (nbf) atau Issued At (iat) yang ditentukan dalam token otorisasi JWT. Tetapkan parameter ini ke jumlah detik untuk mengizinkan perbedaan tersebut. (Ditambahkan 2.5.7)
Atribut khusus plugin
Lihat Menggunakan plugin untuk mengetahui detail tentang atribut yang dapat dikonfigurasi untuk setiap plugin.
Memfilter proxy
Anda dapat memfilter proxy yang mendukung microgateway yang akan diproses oleh instance Edge Microgateway.
Saat dimulai, Edge Microgateway akan mendownload semua proxy yang mendukung microgateway di organisasi yang terkait. Gunakan konfigurasi berikut untuk membatasi proxy yang akan diproses oleh gateway mikro. Misalnya, konfigurasi ini membatasi proxy yang akan diproses oleh microgateway
menjadi tiga: edgemicro_proxy-1
, edgemicro_proxy-2
,
dan edgemicro_proxy-3
:
edgemicro: proxies: - edgemicro_proxy-1 - edgemicro_proxy-2 - edgemicro_proxy-3
Memfilter produk berdasarkan nama
Gunakan konfigurasi berikut untuk membatasi jumlah produk API yang didownload dan diproses oleh Edge Microgateway. Untuk memfilter produk yang didownload, tambahkan parameter kueri productnamefilter
ke /products
API yang tercantum dalam file *.config.yaml
Edge Microgateway. Contoh:
edge_config: bootstrap: >- https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey' managementUri: 'https://api.enterprise.apigee.com' vaultName: microgateway authUri: 'https://%s-%s.apigee.net/edgemicro-auth' baseUri: >- https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s bootstrapMessage: Please copy the following property to the edge micro agent config keySecretMessage: The following credentials are required to start edge micro products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'
Perhatikan bahwa nilai parameter kueri harus ditentukan dalam format ekspresi reguler dan dienkode ke URL. Misalnya, ekspresi reguler ^[Ee]dgemicro.*$
menangkap nama seperti:
"edgemicro-test-1", "edgemicro_demo", dan "Edgemicro_New_Demo". Nilai yang dienkode URL, yang cocok untuk
digunakan dalam parameter kueri, adalah: %5E%5BEe%5Ddgemicro.%2A%24
.
Output debug berikut menunjukkan bahwa hanya produk yang difilter yang didownload:
... 2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK ... .... .... { "apiProduct":[ { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590549037549, "createdBy":"k***@g********m", "displayName":"test upper case in name", "environments":[ "prod", "test" ], "lastModifiedAt":1590549037549, "lastModifiedBy":"k***@g********m", "name":"Edgemicro_New_Demo", "proxies":[ "catchall" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1590548328998, "createdBy":"k***@g********m", "displayName":"edgemicro test 1", "environments":[ "prod", "test" ], "lastModifiedAt":1590548328998, "lastModifiedBy":"k***@g********m", "name":"edgemicro-test-1", "proxies":[ "Lets-Encrypt-Validation-DoNotDelete" ], "quota":"null", "quotaInterval":"null", "quotaTimeUnit":"null", "scopes":[ ] }, { "apiResources":[ "/", "/**" ], "approvalType":"auto", "attributes":[ { "name":"access", "value":"public" } ], "createdAt":1558182193472, "createdBy":"m*********@g********m", "displayName":"Edge microgateway demo product", "environments":[ "prod", "test" ], "lastModifiedAt":1569077897465, "lastModifiedBy":"m*********@g********m", "name":"edgemicro_demo", "proxies":[ "edgemicro-auth", "edgemicro_hello" ], "quota":"600", "quotaInterval":"1", "quotaTimeUnit":"minute", "scopes":[ ] } ] }
Memfilter produk menurut atribut khusus
Untuk memfilter produk berdasarkan atribut kustom:
- Di UI Edge, pilih proxy edgemicro_auth di organisasi/lingkungan tempat Anda mengonfigurasi Edge Microgateway.
- Di tab Develop, buka kebijakan JavaCallout di editor.
- Tambahkan atribut kustom dengan kunci
products.filter.attributes
dengan daftar nama atribut yang dipisahkan koma. Hanya produk yang berisi nama atribut kustom yang akan ditampilkan ke Edge Microgateway. - Anda dapat menonaktifkan pemeriksaan secara opsional
untuk melihat apakah produk diaktifkan untuk lingkungan saat ini dengan menetapkan
atribut kustom
products.filter.env.enable
kefalse
. (Defaultnya adalah true.) - (Khusus Cloud Pribadi) Jika Anda menggunakan Edge untuk Cloud Pribadi, tetapkan properti
org.noncps
ketrue
untuk mengambil produk untuk lingkungan non-CPS.
Contoh:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout"> <DisplayName>JavaCallout</DisplayName> <FaultRules/> <Properties> <Property name="products.filter.attributes">attrib.one, attrib.two</Property> <Property name="products.filter.env.enable">false</Property> <Property name="org.noncps">true</Property> </Properties> <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName> <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL> </JavaCallout>
Memfilter produk menurut status pencabutan
Produk API memiliki tiga kode status - Tertunda, Disetujui, dan Dicabut. Properti baru yang disebut allowProductStatus
telah ditambahkan ke kebijakan Variabel JWT Tetapkan di proxy edgemicro-auth. Untuk menggunakan properti ini guna memfilter produk API yang tercantum dalam JWT:
- Buka proxy edgemicro-auth di editor proxy Apigee.
- Tambahkan properti
allowProductStatus
ke XML kebijakan SetJWTVariables dan tentukan daftar kode status yang dipisahkan koma untuk memfilter. Misalnya, untuk memfilter berdasarkan status Tertunda dan Dibatalkan:<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Javascript timeLimit="20000" async="false" continueOnError="false" enabled="true" name="Set-JWT-Variables"> <DisplayName>Set JWT Variables</DisplayName> <FaultRules/> <Properties> <Property name="allowProductStatus">Pending,Revoked</Property> </Properties> <ResourceURL>jsc://set-jwt-variables.js</ResourceURL> </Javascript>
Jika Anda hanya ingin produk yang Disetujui dicantumkan, tetapkan properti sebagai berikut:
<Property name="allowProductStatus">Approved</Property>
- Simpan proxy.
Jika tag Property tidak ada, produk dengan semua kode status akan dicantumkan dalam JWT.
Untuk menggunakan properti baru ini, Anda harus mengupgrade proxy edgemicro-auth.
Mengonfigurasi frekuensi push analisis
Gunakan parameter konfigurasi ini untuk mengontrol frekuensi Edge Microgateway mengirim data analisis ke Apigee:
- bufferSize (Opsional): Jumlah maksimum kumpulan data analisis yang dapat disimpan buffer sebelum mulai menghapus kumpulan data terlama. Default: 10000
- batchSize (Opsional): Ukuran maksimum batch kumpulan data analisis yang dikirim ke Apigee. Default: 500
- flushInterval (Opsional): Jumlah milidetik di antara setiap penghapusan batch kumpulan data analisis yang dikirim ke Apigee. Default: 5000
Contoh:
analytics: bufferSize: 15000 batchSize: 1000 flushInterval: 6000
Menyamarkan data analisis
Konfigurasi berikut mencegah informasi jalur permintaan muncul di analisis Edge. Tambahkan hal berikut ke konfigurasi microgateway untuk menyamarkan URI permintaan dan/atau jalur permintaan. Perhatikan bahwa URI terdiri dari nama host dan bagian jalur permintaan.
analytics: mask_request_uri: 'string_to_mask' mask_request_path: 'string_to_mask'
Memisahkan panggilan API di Edge Analytics
Anda dapat mengonfigurasi plugin analisis untuk memisahkan jalur API tertentu sehingga muncul sebagai proxy terpisah di dasbor Edge Analytics. Misalnya, Anda dapat memisahkan API pemeriksaan kondisi di dasbor agar tidak tertukar dengan panggilan proxy API yang sebenarnya. Di dasbor Analytics, proxy yang dipisahkan mengikuti pola penamaan ini:
edgemicro_proxyname-health
Gambar berikut menunjukkan dua proxy yang dipisahkan di dasbor Analytics: edgemicro_hello-health
dan
edgemicro_mock-health
:
Gunakan parameter ini untuk memisahkan jalur relatif dan absolut di dasbor Analytics sebagai proxy terpisah:
- relativePath (Opsional): Menentukan jalur relatif untuk dipisahkan di dasbor Analytics. Misalnya, jika Anda menentukan
/healthcheck
, semua panggilan API yang berisi jalur/healthcheck
akan muncul di dasbor sebagaiedgemicro_proxyname-health
. Perhatikan bahwa tanda ini mengabaikan jalur dasar proxy. Untuk memisahkan berdasarkan jalur lengkap, termasuk jalur dasar, gunakan flagproxyPath
. - proxyPath (Opsional): Menentukan jalur proxy API lengkap, termasuk jalur dasar proxy, untuk memisahkan di dasbor analisis. Misalnya, jika Anda menentukan
/mocktarget/healthcheck
, dengan/mocktarget
adalah jalur dasar proxy, semua panggilan API dengan jalur/mocktarget/healthcheck
akan muncul di dasbor sebagaiedgemicro_proxyname-health
.
Misalnya, dalam konfigurasi berikut, setiap jalur API yang berisi /healthcheck
akan
dipisahkan oleh plugin analisis. Artinya, /foo/healthcheck
dan /foo/bar/healthcheck
akan dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health
di dasbor analisis.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 relativePath: /healthcheck
Dalam konfigurasi berikut, setiap API dengan jalur proxy /mocktarget/healthcheck
akan
dipisahkan sebagai proxy terpisah yang disebut edgemicro_proxyname-health
di
dasbor analisis.
analytics: uri: >- https://xx/edgemicro/ax/org/docs/environment/test bufferSize: 100 batchSize: 50 flushInterval: 500 proxyPath: /mocktarget/healthcheck
Menyiapkan Edge Microgateway di balik firewall perusahaan
Menggunakan proxy HTTP untuk komunikasi dengan Apigee Edge
Ditambahkan di versi 3.1.2.
Untuk menggunakan proxy HTTP untuk komunikasi antara Edge Microgateway dan Apigee Edge, lakukan langkah berikut:
- Tetapkan variabel lingkungan
HTTP_PROXY
,HTTPS_PROXY
, danNO_PROXY
. Variabel ini mengontrol host untuk setiap proxy HTTP yang ingin Anda gunakan untuk komunikasi dengan Apigee Edge, atau host yang tidak boleh menangani komunikasi dengan Apigee Edge. Contoh:export HTTP_PROXY='http://localhost:3786' export HTTPS_PROXY='https://localhost:3786' export NO_PROXY='localhost,localhost:8080'
Perhatikan bahwa
NO_PROXY
dapat berupa daftar domain yang dipisahkan koma yang tidak boleh di-proxy oleh Edge Microgateway.Untuk mengetahui informasi selengkapnya tentang variabel ini, lihat https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
- Mulai ulang Edge Microgateway.
Menggunakan proxy HTTP untuk komunikasi target
Ditambahkan di versi 3.1.2.
Untuk menggunakan proxy HTTP untuk komunikasi antara Edge Microgateway dan target backend, lakukan hal berikut:
- Tambahkan konfigurasi berikut ke file konfigurasi microgateway:
edgemicro: proxy: tunnel: true | false url: proxy_url bypass: target_host # target hosts to bypass the proxy. enabled: true | false
Dengan keterangan:
- tunnel: (Opsional) Jika benar, Edge Microgateway menggunakan metode HTTP CONNECT untuk melakukan tunneling permintaan HTTP
melalui satu koneksi TCP. (Hal yang sama berlaku jika variabel lingkungan, seperti
yang disebutkan di bawah,
untuk mengonfigurasi proxy diaktifkan TLS). Default:
false
- url: URL proxy HTTP.
- bypass: (Opsional) Menentukan satu atau beberapa URL host target yang dipisahkan koma yang harus mengabaikan proxy HTTP. Jika properti ini tidak ditetapkan, gunakan variabel lingkungan NO_PROXY untuk menentukan URL target yang akan dilewati.
- enabled: Jika benar dan
proxy.url
ditetapkan, gunakan nilaiproxy.url
untuk proxy HTTP. Jika benar danproxy.url
tidak ditetapkan, gunakan proxy yang ditentukan dalam variabel lingkungan proxy HTTPHTTP_PROXY
danHTTPS_PROXY
, seperti yang dijelaskan dalam Menggunakan proxy HTTP untuk komunikasi dengan Apigee Edge.
Contoh:
edgemicro: proxy: tunnel: true url: 'http://localhost:3786' bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy. enabled: true
- tunnel: (Opsional) Jika benar, Edge Microgateway menggunakan metode HTTP CONNECT untuk melakukan tunneling permintaan HTTP
melalui satu koneksi TCP. (Hal yang sama berlaku jika variabel lingkungan, seperti
yang disebutkan di bawah,
untuk mengonfigurasi proxy diaktifkan TLS). Default:
- Mulai ulang Edge Microgateway.
Menggunakan karakter pengganti di proxy yang mendukung Microgateway
Anda dapat menggunakan satu atau beberapa karakter pengganti "*" di jalur dasar proxy
edgemicro_* (yang mendukung Microgateway). Misalnya, jalur dasar
/team/*/members memungkinkan klien memanggil
https://[host]/team/blue/members dan
https://[host]/team/green/members tanpa Anda perlu membuat proxy API baru
untuk mendukung tim baru. Perhatikan bahwa /**/
tidak didukung.
Penting: Apigee TIDAK mendukung penggunaan karakter pengganti "*" sebagai elemen pertama jalur dasar. Misalnya, hal berikut TIDAK didukung: penelusuran /*/
.
Merotasi kunci JWT
Setelah pertama kali membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM terenkripsi Edge. Proses pembuatan pasangan kunci baru ini disebut rotasi kunci.
Cara Edge Microgateway menggunakan JWT
Token Web JSON (JWT) adalah standar token yang dijelaskan dalam RFC7519. JWT menyediakan cara untuk menandatangani serangkaian klaim, yang dapat diverifikasi dengan andal oleh penerima JWT.
Anda dapat membuat JWT menggunakan CLI dan menggunakannya di header Otorisasi panggilan API, bukan kunci API. Contoh:
curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"
Untuk informasi tentang cara membuat JWT dengan CLI, lihat Membuat token.
Apa yang dimaksud dengan rotasi kunci?
Setelah pertama kali membuat JWT, Anda mungkin perlu mengubah pasangan kunci publik/pribadi yang disimpan di KVM terenkripsi Edge. Proses pembuatan pasangan kunci baru ini disebut rotasi kunci. Saat Anda merotasi kunci, pasangan kunci pribadi/publik baru akan dibuat dan disimpan di KVM "microgateway" di organisasi/lingkungan Apigee Edge Anda. Selain itu, kunci publik lama dipertahankan beserta nilai ID kunci aslinya.
Untuk membuat JWT, Edge menggunakan informasi yang disimpan di KVM terenkripsi. KVM
bernama microgateway
dibuat dan diisi dengan kunci saat Anda pertama kali menyiapkan (mengonfigurasi)
Edge Microgateway. Kunci di KVM digunakan untuk menandatangani dan mengenkripsi JWT.
Tombol KVM mencakup:
-
private_key - Kunci pribadi RSA terbaru (yang baru dibuat) yang digunakan untuk menandatangani JWT.
-
public_key - Sertifikat terbaru (yang baru dibuat) yang digunakan untuk memverifikasi JWT yang ditandatangani dengan private_key.
-
private_key_kid - ID kunci pribadi terbaru (yang baru dibuat). ID kunci ini dikaitkan dengan nilai private_key dan digunakan untuk mendukung rotasi kunci.
-
public_key1_kid - ID kunci publik terbaru (yang baru dibuat). Kunci ini dikaitkan dengan nilai public_key1 dan digunakan untuk mendukung rotasi kunci. Nilai ini sama dengan kid kunci pribadi.
-
public_key1 - Kunci publik terbaru (yang baru dibuat).
Saat Anda melakukan rotasi kunci, nilai kunci yang ada akan diganti di peta dan kunci baru akan ditambahkan untuk mempertahankan kunci publik lama. Contoh:
-
public_key2_kid - ID kunci publik lama. Kunci ini dikaitkan dengan nilai public_key2 dan digunakan untuk mendukung rotasi kunci.
-
public_key2 - Kunci publik lama.
JWT yang ditampilkan untuk verifikasi akan diverifikasi menggunakan kunci publik baru. Jika verifikasi gagal, kunci publik lama akan digunakan, hingga masa berlaku JWT berakhir (setelah interval token_expiry*, default 30 menit). Dengan cara ini, Anda dapat "memutar" kunci tanpa langsung mengganggu traffic API.
Cara melakukan rotasi kunci
Bagian ini menjelaskan cara melakukan rotasi kunci.
- Untuk mengupgrade KVM, gunakan perintah
edgemicro upgradekvm
. Untuk mengetahui detail tentang cara menjalankan perintah ini, lihat Mengupgrade KVM. Anda hanya perlu melakukan langkah ini satu kali. - Untuk mengupgrade proxy edgemicro-oauth, gunakan perintah
edgemicro upgradeauth
. Untuk mengetahui detail tentang cara menjalankan perintah ini, lihat Mengupgrade proxy edgemicro-auth. Anda hanya perlu melakukan langkah ini satu kali. - Tambahkan baris berikut ke file
~/.edgemicro/org-env-config.yaml
, tempat Anda harus menentukan organisasi dan lingkungan yang sama dengan yang Anda konfigurasikan untuk digunakan microgateway:jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
Jalankan perintah rotasi kunci untuk memutar kunci. Untuk mengetahui detail tentang perintah ini, lihat Memutar kunci.
edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET
Contoh:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
Setelah rotasi kunci, Edge akan menampilkan beberapa kunci ke Edge Microgateway. Perhatikan dalam contoh berikut, setiap kunci memiliki nilai "kid" (ID Kunci) yang unik. Microgateway kemudian menggunakan kunci ini untuk memvalidasi token otorisasi. Jika validasi token gagal, microgateway akan memeriksa apakah ada kunci yang lebih lama dalam kumpulan kunci dan mencoba kunci tersebut. Format kunci yang ditampilkan adalah JSON Web Key (JWK). Anda dapat membaca format ini di RFC 7517.
{ "keys": [ { "kty": "RSA", "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ", "e": "AQAB", "kid": "2" }, { "kty": "RSA", "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw", "e": "AQAB", "kid": "1" } ] }
Mengonfigurasi penundaan "not before"
Untuk versi 3.1.5 dan sebelumnya, kunci pribadi baru yang dihasilkan oleh perintah rotatekey
langsung berlaku, dan token baru yang dihasilkan ditandatangani dengan kunci pribadi baru. Namun,
kunci publik baru hanya tersedia untuk instance Edge Microgateway setiap 10 menit (secara default)
saat konfigurasi microgateway dimuat ulang. Karena adanya jeda antara penandatanganan token
dan refresh instance microgateway, token yang ditandatangani dengan kunci terbaru akan ditolak hingga
semua instance menerima kunci terbaru publik.
Jika ada beberapa instance microgateway, jeda kunci publik terkadang menyebabkan error runtime yang terputus-putus dengan status 403, karena validasi token akan diteruskan di satu instance, tetapi gagal di instance lain hingga semua instance dimuat ulang.
Mulai versi 3.1.6, flag baru pada perintah rotatekey
memungkinkan Anda menentukan penundaan agar kunci pribadi
baru menjadi efektif, sehingga memberi waktu bagi semua instance microgateway untuk dimuat ulang
dan menerima kunci publik baru. Flag barunya adalah --nbf
, yang berarti "not before" (tidak sebelum).
Flag ini menggunakan nilai bilangan bulat, yaitu jumlah menit yang akan ditunda.
Dalam contoh berikut, penundaan ditetapkan ke 15 menit:
edgemicro rotatekey -o docs -e test \ -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \ -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \ --nbf 15
Perhatikan bahwa praktik yang baik adalah menetapkan penundaan lebih dari setelan konfigurasi config_change_poll_internal
,
yang secara default adalah 10 menit. Lihat juga atribut edgemicro.
Memfilter proxy yang didownload
Secara default, Edge Microgateway mendownload semua proxy di organisasi Edge Anda yang dimulai dengan awalan penamaan "edgemicro_". Anda dapat mengubah setelan default ini untuk mendownload proxy yang namanya cocok dengan pola.
- Buka file konfigurasi Edge Micro:
~/.edgemicro/org-env-config.yaml
- Tambahkan elemen proxyPattern di bagian edge_config. Misalnya, pola berikut akan
mendownload proxy seperti edgemicro_foo, edgemicro_fast, dan edgemicro_first.
edge_config: … proxyPattern: edgemicro_f*
Menentukan produk tanpa proxy API
Di Apigee Edge, Anda dapat membuat produk API yang tidak berisi proxy API apa pun. Konfigurasi produk ini memungkinkan kunci API yang terkait dengan produk tersebut berfungsi dengan proxy apa pun yang di-deploy di organisasi Anda. Mulai versi 2.5.4, Edge Microgateway mendukung konfigurasi produk ini.
Proses debug dan pemecahan masalah
Menghubungkan ke debugger
Anda dapat menjalankan Edge Microgateway dengan debugger, seperti node-inspector. Hal ini berguna untuk memecahkan masalah dan men-debug plugin kustom.
- Mulai ulang Edge Microgateway dalam mode debug. Untuk melakukannya, tambahkan
DEBUG=*
ke awal perintahstart
:DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
Untuk mengarahkan output debug ke file, Anda dapat menggunakan perintah ini:
export DEBUG=* nohup edgemicro start \ -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
- Mulai debugger dan setel untuk memproses nomor port untuk proses proses debug.
- Sekarang Anda dapat menelusuri kode Edge Microgateway, menetapkan titik henti sementara, melihat ekspresi, dan sebagainya.
Anda dapat menentukan flag Node.js standar yang terkait dengan mode debug. Misalnya,
--nolazy
membantu proses debug kode asinkron.
Memeriksa file log
Jika Anda mengalami masalah, pastikan untuk memeriksa file log guna mengetahui detail eksekusi dan informasi error. Untuk mengetahui detailnya, lihat Mengelola file log.
Menggunakan keamanan kunci API
Kunci API menyediakan mekanisme sederhana untuk mengautentikasi klien yang membuat permintaan ke Edge Microgateway. Anda bisa mendapatkan kunci API dengan menyalin nilai Kunci Konsumen (juga disebut Client ID) dari produk Apigee Edge yang menyertakan proxy autentikasi Edge Microgateway.
Penyimpanan kunci dalam cache
Kunci API ditukar dengan token pembawa, yang di-cache. Anda dapat menonaktifkan penyimpanan dalam cache dengan menetapkan header Cache-Control: no-cache
pada permintaan masuk ke Edge Microgateway.
Menggunakan kunci API
Anda dapat meneruskan kunci API dalam permintaan API sebagai parameter kueri atau dalam header. Secara default,
nama header dan parameter kueri adalah x-api-key
.
Contoh parameter kueri:
curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz
Contoh header:
curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Mengonfigurasi nama kunci API
Secara default, x-api-key
adalah nama yang digunakan untuk header kunci API dan parameter kueri.
Anda dapat mengubah default ini di file konfigurasi, seperti yang dijelaskan dalam Melakukan perubahan konfigurasi. Misalnya, untuk mengubah
nama menjadi apiKey:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false api-key-header: apiKey
Dalam contoh ini, parameter kueri dan nama header diubah menjadi apiKey
. Nama
x-api-key
tidak akan berfungsi lagi dalam kedua kasus tersebut. Lihat juga
Melakukan perubahan konfigurasi.
Contoh:
curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"
Untuk informasi selengkapnya tentang cara menggunakan kunci API dengan permintaan proxy, lihat Secure Edge Microgateway.
Mengaktifkan kode respons upstream
Secara default, plugin oauth
hanya menampilkan kode status error 4xx jika
respons bukan status 200. Anda dapat mengubah perilaku ini sehingga selalu menampilkan kode 4xx atau 5xx yang tepat, bergantung pada error.
Untuk mengaktifkan fitur ini, tambahkan properti oauth.useUpstreamResponse: true
ke konfigurasi Edge Microgateway Anda. Contoh:
oauth: allowNoAuthorization: false allowInvalidAuthorization: false gracePeriod: 10 useUpstreamResponse: true
Menggunakan keamanan token OAuth2
Bagian ini menjelaskan cara mendapatkan token akses dan token refresh OAuth2. Token akses digunakan untuk melakukan panggilan API yang aman melalui microgateway. Token refresh digunakan untuk mendapatkan token akses baru.
Cara mendapatkan token akses
Bagian ini menjelaskan cara menggunakan proxy edgemicro-auth
untuk mendapatkan token akses.
Anda juga bisa mendapatkan token akses menggunakan perintah CLI edgemicro token
.
Untuk mengetahui detail tentang CLI, lihat Mengelola token.
API 1: Mengirim kredensial sebagai parameter isi
Ganti nama organisasi dan lingkungan Anda di URL, dan ganti nilai Consumer Id dan Consumer Secret yang diperoleh dari aplikasi developer di Apigee Edge untuk parameter isi client_id dan client_secret:
curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \ -d '{"grant_type": "client_credentials", "client_id": "your_client_id", \ "client_secret": "your_client_secret"}' -H "Content-Type: application/json"
API 2: Mengirim kredensial dalam header Basic Auth
Kirim kredensial klien sebagai header Basic Authentication dan
grant_type
sebagai parameter formulir. Bentuk perintah ini juga dibahas dalam
RFC 6749: Framework Otorisasi OAuth 2.0.
http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \ -d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"
Contoh output
API akan menampilkan respons JSON. Perhatikan bahwa tidak ada perbedaan antara propertitoken
dan
access_token
. Anda dapat menggunakan salah satunya. Perhatikan bahwa expires_in
adalah
nilai bilangan bulat yang ditentukan dalam detik.
{ "token": "eyJraWQiOiIxIiwidHlwIjoi", "access_token": "eyJraWQiOiIxIiwid", "token_type": "bearer", "expires_in": 1799 }
Cara mendapatkan token refresh
Untuk mendapatkan token refresh, lakukan panggilan API ke endpoint /token
proxy
edgemicro-auth
. Anda HARUS melakukan panggilan API ini dengan jenis pemberian password
. Langkah-langkah berikut akan memandu Anda menyelesaikan prosesnya.
- Dapatkan token akses dan token refresh dengan
/token
API. Perhatikan bahwa jenis hibah adalahpassword
:curl -X POST \ https://your_organization-your_environment.apigee.net/edgemicro-auth/token \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq", "client_secret":"bUdDcFgv3nXffnU", "grant_type":"password", "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq", "password":"bUdD2FvnMsXffnU" }'
API menampilkan token akses dan token refresh. Responsnya akan terlihat mirip dengan ini. Perhatikan bahwa
expires_in
bernilai bilangan bulat dan ditentukan dalam detik.{ "token": "your-access-token", "access_token": "your-access-token", "token_type": "bearer", "expires_in": 108, "refresh_token": "your-refresh-token", "refresh_token_expires_in": 431, "refresh_token_issued_at": "1562087304302", "refresh_token_status": "approved" }
- Sekarang Anda dapat menggunakan token refresh untuk mendapatkan token akses baru dengan memanggil
endpoint
/refresh
dari API yang sama. Contoh:curl -X POST \ https://willwitman-test.apigee.net/edgemicro-auth/refresh \ -H 'Content-Type: application/json' \ -d '{ "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq", "client_secret":"bUdDc2Fv3nMXffnU", "grant_type":"refresh_token", "refresh_token":"your-refresh-token" }'
API menampilkan token akses baru. Responsnya akan terlihat seperti ini:
{ "token": "your-new-access-token" }
Pemantauan selamanya
Forever adalah alat Node.js yang otomatis memulai ulang aplikasi Node.js jika prosesnya berhenti atau mengalami error. Edge Microgateway memiliki file forever.json yang dapat Anda konfigurasikan untuk mengontrol berapa kali dan dengan interval berapa Edge Microgateway harus dimulai ulang. File ini mengonfigurasi layanan Forever yang disebut forever-monitor, yang mengelola Forever secara terprogram.
Anda dapat menemukan file forever.json di direktori penginstalan root Edge Microgateway. Lihat Tempat Edge Microgateway diinstal. Untuk mengetahui detail tentang opsi konfigurasi, lihat dokumentasi forever-monitor.
Perintah edgemicro forever
menyertakan flag yang memungkinkan Anda menentukan lokasi file forever.json
(flag -f
), dan memulai/menghentikan proses pemantauan Forever (flag -a
). Contoh:
edgemicro forever -f ~/mydir/forever.json -a start
Untuk mengetahui informasi selengkapnya, lihat Pemantauan selamanya di referensi CLI.
Menentukan endpoint file konfigurasi
Jika menjalankan beberapa instance Edge Microgateway, Anda dapat mengelola konfigurasinya dari satu lokasi. Anda dapat melakukannya dengan menentukan endpoint HTTP tempat Edge Micro dapat mendownload file konfigurasinya. Anda dapat menentukan endpoint ini saat memulai Edge Micro menggunakan flag -u.
Contoh:
edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key
dengan endpoint mgconfig menampilkan konten file konfigurasi Anda. Ini adalah file yang secara default berada di ~/.edgemicro
dan memiliki konvensi penamaan: org-env-config.yaml
.
Menonaktifkan buffering data koneksi TCP
Anda dapat menggunakan atribut konfigurasi nodelay
untuk menonaktifkan buffering data untuk
koneksi TCP yang digunakan oleh Edge Microgateway.
Secara default, koneksi TCP menggunakan algoritme
Nagle untuk melakukan buffering data sebelum mengirimnya. Menetapkan nodelay
ke true
,
akan menonaktifkan perilaku ini (data akan langsung memicu data setiap kali
socket.write()
dipanggil). Lihat juga dokumentasi Node.js untuk mengetahui detail selengkapnya.
Untuk mengaktifkan nodelay
, edit file konfigurasi Edge Micro sebagai berikut:
edgemicro: nodelay: true port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24
Menjalankan Edge Microgateway dalam mode mandiri
Anda dapat menjalankan Edge Microgateway yang sepenuhnya terputus dari dependensi Apigee Edge. Skenario ini, yang disebut mode mandiri, memungkinkan Anda menjalankan dan menguji Edge Microgateway tanpa koneksi Internet.
Dalam mode mandiri, fitur berikut tidak berfungsi karena memerlukan koneksi ke Apigee Edge:
- OAuth dan kunci API
- Kuota
- Analytics
Di sisi lain, plugin kustom dan penangkapan lonjakan berfungsi secara normal, karena tidak
memerlukan koneksi ke Apigee Edge. Selain itu, plugin baru yang disebut extauth
memungkinkan Anda
memberi otorisasi panggilan API ke microgateway dengan JWT saat dalam mode mandiri.
Mengonfigurasi dan memulai gateway
Untuk menjalankan Edge Microgateway dalam mode mandiri:
- Buat file konfigurasi yang diberi nama sebagai berikut:
$HOME/.edgemicro/$ORG
-
$ENV-config.yamlContoh:
vi $HOME/.edgemicro/foo-bar-config.yaml
- Tempelkan kode berikut ke dalam file:
edgemicro: port: 8000 max_connections: 1000 config_change_poll_interval: 600 logging: level: error dir: /var/tmp stats_log_interval: 60 rotate_interval: 24 plugins: sequence: - extauth - spikearrest headers: x-forwarded-for: true x-forwarded-host: true x-request-id: true x-response-time: true via: true extauth: publickey_url: https://www.googleapis.com/oauth2/v1/certs spikearrest: timeUnit: second allow: 10 buffersize: 0
- Ekspor variabel lingkungan berikut dengan nilai "1":
export EDGEMICRO_LOCAL=1
- Jalankan perintah
start
berikut, tempat Anda memberikan nilai untuk membuat instance proxy lokal:edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \ -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
Dengan keterangan:
- $ORG adalah nama "org" yang Anda gunakan dalam nama file konfigurasi.
- $ENV adalah nama "env" yang Anda gunakan dalam nama file konfigurasi.
- $LOCAL_PROXY_NAME adalah nama proxy lokal yang akan dibuat. Anda dapat menggunakan nama apa pun yang Anda inginkan.
- $LOCAL_PROXY_VERSION adalah nomor versi untuk proxy.
- $TARGET_URL adalah URL untuk target proxy. (Target adalah layanan yang dipanggil proxy.)
- $BASE_PATH adalah jalur dasar proxy. Nilai ini harus diawali dengan garis miring depan. Untuk jalur dasar root, cukup tentukan garis miring; misalnya, "/".
Contoh:
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
- Uji konfigurasi.
curl http://localhost:8000/echo { "error" : "missing_authorization" }
Karena plugin
extauth
berada dalam filefoo-bar-config.yaml
, Anda akan mendapatkan error "missing_authorization". Plugin ini memvalidasi JWT yang harus ada di header Otorisasi panggilan API. Di bagian berikutnya, Anda akan mendapatkan JWT yang akan memungkinkan panggilan API dilakukan tanpa error.
Contoh: Mendapatkan token otorisasi
Contoh berikut menunjukkan cara mendapatkan JWT dari endpoint JWT Edge Microgateway di Apigee Edge (edgemicro-auth/jwkPublicKeys
).
Endpoint ini di-deploy saat Anda melakukan penyiapan dan konfigurasi standar Edge Microgateway.
Untuk mendapatkan JWT dari endpoint Apigee, Anda harus melakukan penyiapan Edge Microgateway standar terlebih dahulu, dan
terhubung ke Internet. Endpoint Apigee digunakan di sini hanya sebagai contoh
dan tidak diperlukan. Anda dapat menggunakan endpoint token JWT lain jika mau. Jika ya, Anda harus mendapatkan JWT menggunakan
API yang disediakan untuk endpoint tersebut.
Langkah-langkah berikut menjelaskan cara mendapatkan token menggunakan endpoint edgemicro-auth/jwkPublicKeys
:.
- Anda harus melakukan penyiapan dan konfigurasi
standar Edge Microgateway untuk men-deploy proxy
edgemicro-auth
ke organisasi/lingkungan Anda di Apigee Edge. Jika telah melakukan langkah ini sebelumnya, Anda tidak perlu mengulanginya. - Jika men-deploy Edge Microgateway ke Apigee Cloud, Anda harus terhubung ke Internet agar dapat memperoleh JWT dari endpoint ini.
-
Hentikan Edge Microgateway:
edgemicro stop
- Dalam file konfigurasi yang Anda buat sebelumnya (
$HOME/.edgemicro
/org-env-config.yaml
), arahkan atributextauth:publickey_url
ke endpointedgemicro-auth/jwkPublicKeys
di organisasi/lingkungan Apigee Edge Anda. Contoh:extauth: publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
-
Mulai ulang Edge Microgateway seperti yang Anda lakukan sebelumnya, menggunakan nama org/env yang Anda gunakan dalam nama file konfigurasi. Contoh:
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
-
Dapatkan token JWT dari endpoint otorisasi. Karena Anda menggunakan endpoint
edgemicro-auth/jwkPublicKeys
, Anda dapat menggunakan perintah CLI ini:
Anda dapat membuat JWT untuk Edge Microgateway menggunakan perintah edgemicro token
atau
API. Contoh:
edgemicro token get -o your_org -e your_env \ -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy
Dengan keterangan:
- your_org adalah nama organisasi Apigee yang sebelumnya Anda konfigurasikan dengan Edge Microgateway.
- your_env adalah lingkungan dalam organisasi.
- Opsi
i
menentukan Kunci Konsumen dari aplikasi developer yang memiliki produk yang menyertakan proxyedgemicro-auth
. - Opsi
s
menentukan Consumer Secret dari aplikasi developer yang memiliki produk yang menyertakan proxyedgemicro-auth
.
Perintah ini meminta Apigee Edge untuk membuat JWT yang kemudian dapat digunakan untuk memverifikasi panggilan API.
Lihat juga Membuat token.Menguji konfigurasi mandiri
Untuk menguji konfigurasi, panggil API dengan token yang ditambahkan di header Otorisasi sebagai berikut:
curl http://localhost:8000/echo -H "Authorization: Bearer your_token
Contoh:
curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"
Contoh output:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
Menggunakan mode proxy lokal
Dalam mode proxy lokal, Edge Microgateway tidak memerlukan proxy yang mendukung microgateway untuk di-deploy di Apigee Edge. Sebagai gantinya, Anda mengonfigurasi "proxy lokal" dengan memberikan nama proxy lokal, jalur dasar, dan URL target saat memulai microgateway. Panggilan API ke microgateway kemudian dikirim ke URL target proxy lokal. Selain itu, mode proxy lokal berfungsi sama persis dengan menjalankan Edge Microgateway dalam mode normalnya. Autentikasi berfungsi dengan cara yang sama, begitu juga dengan penerapan kuota dan penghentian traffic puncak, plugin kustom, dan sebagainya.
Kasus penggunaan dan contoh
Mode proxy lokal berguna jika Anda hanya perlu mengaitkan satu proxy dengan instance Edge Microgateway. Misalnya, Anda dapat memasukkan Edge Microgateway ke Kubernetes sebagai proxy sidecar, dengan microgateway dan layanan masing-masing berjalan dalam satu pod, dan tempat microgateway mengelola traffic ke dan dari layanan pendampingnya. Gambar berikut mengilustrasikan arsitektur ini dengan Edge Microgateway berfungsi sebagai proxy sidecar di cluster Kubernetes. Setiap instance microgateway hanya berkomunikasi dengan satu endpoint di layanan pendampingnya:
Manfaat dari gaya arsitektur ini adalah Edge Microgateway menyediakan pengelolaan API untuk setiap layanan yang di-deploy ke lingkungan penampung, seperti cluster Kubernetes.
Mengonfigurasi mode proxy lokal
Untuk mengonfigurasi Edge Microgateway agar berjalan dalam mode proxy lokal, ikuti langkah-langkah berikut:
- Jalankan
edgemicro init
untuk menyiapkan lingkungan konfigurasi lokal, persis seperti yang Anda lakukan dalam penyiapan Edge Microgateway standar. Lihat juga Mengonfigurasi Edge Microgateway. - Jalankan
edgemicro configure
, seperti yang Anda lakukan dalam prosedur penyiapan Microgateway Edge standar. Contoh:edgemicro configure -o your_org -e your_env -u your_apigee_username
Perintah ini men-deploy kebijakan edgemicro-auth ke Edge dan menampilkan kunci serta secret yang akan Anda perlukan untuk memulai microgateway. Jika Anda memerlukan bantuan, lihat Mengonfigurasi Edge Microgateway.
- Di Apigee Edge, buat produk API dan dengan persyaratan konfigurasi wajib
berikut (Anda dapat mengelola semua konfigurasi lainnya sesuai keinginan):
- Anda harus menambahkan proxy edgemicro-auth ke produk. Proxy ini di-deploy secara otomatis saat Anda menjalankan
edgemicro configure
. - Anda harus memberikan jalur resource. Apigee merekomendasikan penambahan jalur ini ke produk:
/**
. Untuk mempelajari lebih lanjut, lihat Mengonfigurasi perilaku jalur resource. Lihat juga Membuat produk API dalam dokumentasi Edge.
- Anda harus menambahkan proxy edgemicro-auth ke produk. Proxy ini di-deploy secara otomatis saat Anda menjalankan
Di Apigee Edge, buat developer, atau Anda dapat menggunakan developer yang sudah ada jika ingin. Untuk mendapatkan bantuan, lihat Menambahkan developer menggunakan UI pengelolaan Edge.
- Di Apigee Edge, buat aplikasi developer. Anda harus menambahkan produk API yang baru saja Anda buat ke aplikasi. Untuk mendapatkan bantuan, lihat Mendaftarkan aplikasi di UI pengelolaan Edge.
- Di komputer tempat Edge Microgateway diinstal, ekspor variabel lingkungan berikut dengan nilai "1".
export EDGEMICRO_LOCAL_PROXY=1
- Jalankan perintah
start
berikut:edgemicro start -o your_org -e your_environment -k your_key -s your_secret \ -a local_proxy_name -v local_proxy_version -t target_url -b base_path
Dengan keterangan:
- your_org adalah organisasi Apigee Anda.
- your_environment adalah lingkungan di organisasi Anda.
- your_key adalah kunci yang ditampilkan saat Anda menjalankan
edgemicro configure
. - your_secret adalah secret yang ditampilkan saat Anda menjalankan
edgemicro configure
. - local_proxy_name adalah nama proxy lokal yang akan dibuat.
- local_proxy_version adalah nomor versi untuk proxy.
- target_url adalah URL untuk target proxy (layanan yang akan dipanggil proxy).
- base_path adalah jalur dasar proxy. Nilai ini harus diawali dengan garis miring depan. Untuk jalur dasar root, cukup tentukan garis miring; misalnya, "/".
Contoh:
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \ -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \ -t http://mocktarget.apigee.net -b /echo
Menguji konfigurasi
Anda dapat menguji konfigurasi proxy lokal dengan memanggil endpoint proxy. Misalnya,
jika Anda menentukan jalur dasar /echo
, Anda dapat memanggil proxy sebagai berikut:
curl http://localhost:8000/echo { "error" : "missing_authorization", "error_description" : "Missing Authorization header" }
Panggilan API awal ini menghasilkan error karena Anda tidak memberikan kunci API yang valid. Anda dapat menemukan kunci di aplikasi Developer yang Anda buat sebelumnya. Buka aplikasi di UI Edge, salin Kunci Konsumen, dan gunakan kunci tersebut sebagai berikut:
curl http://localhost:8000/echo -H 'x-api-key:your_api_key'
Contoh:
curl http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"
Contoh output:
{ "headers":{ "user-agent":"curl/7.54.0", "accept":"*/*", "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP", "client_received_start_timestamp":"1535134472699", "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==", "target_sent_start_timestamp":"1535134472702", "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896", "x-forwarded-proto":"http", "x-forwarded-host":"localhost:8000", "host":"mocktarget.apigee.net", "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513", "via":"1.1 localhost, 1.1 google", "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212", "connection":"Keep-Alive" }, "method":"GET", "url":"/", "body":"" }
Menggunakan sinkronisasi
Bagian ini menjelaskan cara menggunakan sinkronisasi, fitur opsional yang meningkatkan ketahanan Edge Microgateway dengan memungkinkannya mengambil data konfigurasi dari Apigee Edge dan menulisnya ke database Redis lokal. Dengan instance sinkronisasi yang berjalan, instance Edge Microgateway lainnya yang berjalan di node lain dapat mengambil konfigurasinya langsung dari database ini.
Fitur sinkronisasi saat ini didukung untuk berfungsi dengan Redis 5.0.x.
Apa yang dimaksud dengan sinkronisasi?
Sinkroniser memberikan tingkat ketahanan untuk Edge Microgateway. Hal ini membantu memastikan bahwa setiap instance Edge Microgateway menggunakan konfigurasi yang sama, dan bahwa jika terjadi gangguan internet, instance Edge Microgateway dapat dimulai dan berjalan dengan benar.
Secara default, instance Edge Microgateway harus dapat berkomunikasi dengan Apigee Edge untuk mengambil dan memuat ulang data konfigurasinya, seperti proxy API dan konfigurasi produk API. Jika koneksi internet dengan Edge terganggu, instance microgateway dapat terus berfungsi karena data konfigurasi terbaru di-cache. Namun, instance microgateway baru tidak dapat dimulai tanpa koneksi yang jelas. Selain itu, gangguan internet dapat menyebabkan satu atau beberapa instance microgateway berjalan dengan informasi konfigurasi yang tidak sinkron dengan instance lainnya.
Sinkronisasi Edge Microgateway menyediakan mekanisme alternatif untuk instance Edge Microgateway
guna mengambil data konfigurasi yang diperlukan untuk memulai dan memproses traffic proxy API.
Data konfigurasi yang diambil dari panggilan ke Apigee Edge mencakup: panggilan jwk_public_keys
,
panggilan jwt_public_key
, panggilan bootstrap, dan panggilan produk API.
Sinkronisasi memungkinkan semua instance Edge Microgateway
yang berjalan di node yang berbeda untuk dimulai dengan benar dan tetap sinkron meskipun
koneksi internet antara Edge Microgateway dan Apigee Edge terganggu.
Sinkroniser adalah instance Edge Microgateway yang dikonfigurasi secara khusus. Satu-satunya tujuannya adalah melakukan polling Apigee Edge (waktunya dapat dikonfigurasi), mengambil data konfigurasi, dan menulisnya ke database Redis lokal. Instance sinkronisasi itu sendiri tidak dapat memproses traffic proxy API. Instance Edge Microgateway lainnya yang berjalan di node yang berbeda dapat dikonfigurasi untuk mengambil data konfigurasi dari database Redis, bukan dari Apigee Edge. Karena semua instance microgateway mengambil data konfigurasinya dari database lokal, instance tersebut dapat memulai dan memproses permintaan API bahkan jika terjadi gangguan internet.
Mengonfigurasi instance sinkronisasi
Tambahkan konfigurasi berikut ke file org-env/config.yaml
untuk
penginstalan Edge Microgateway yang ingin Anda gunakan sebagai sinkroniser:
edgemicro: redisHost: host_IP redisPort: host_port redisDb: database_index redisPassword: password edge_config: synchronizerMode: 1 redisBasedConfigCache: true
Contoh:
edgemicro: redisHost: 192.168.4.77 redisPort: 6379 redisDb: 0 redisPassword: codemaster edge_config: synchronizerMode: 1 redisBasedConfigCache: true
Opsi | Deskripsi |
---|---|
redisHost |
Host tempat instance Redis Anda berjalan. Default: 127.0.0.1 |
redisPort |
Port instance Redis. Default: 6379 |
redisDb |
DB Redis yang akan digunakan. Default: 0 |
redisPassword |
Sandi database Anda. |
Terakhir, simpan file konfigurasi dan mulai instance Edge Microgateway. Tindakan ini akan mulai melakukan polling Apigee Edge dan menyimpan data konfigurasi yang didownload di database Redis.
Mengonfigurasi instance Edge Microgateway reguler
Dengan sinkronisasi yang berjalan, Anda dapat mengonfigurasi node Edge Microgateway tambahan untuk menjalankan instance microgateway reguler yang memproses traffic proxy API. Namun, Anda mengonfigurasi instance ini untuk mendapatkan data konfigurasinya dari database Redis, bukan dari Apigee Edge.
Tambahkan konfigurasi berikut ke setiap file org-env/config.yaml
node Edge Microgateway tambahan. Perhatikan bahwa properti synchronizerMode
disetel ke 0
. Properti ini menetapkan instance untuk beroperasi sebagai instance Edge Microgateway normal yang memproses traffic proxy API, dan instance akan mendapatkan data konfigurasinya dari database Redis.
edgemicro: redisHost: host_IP redisPort: host_port redisDb: database_index redisPassword: password edge_config: synchronizerMode: 0 redisBasedConfigCache: true
Contoh:
edgemicro: redisHost: 192.168.4.77 redisPort: 6379 redisDb: 0 redisPassword: codemaster edge_config: synchronizerMode: 0 redisBasedConfigCache: true
Properti konfigurasi
Properti konfigurasi berikut telah ditambahkan untuk mendukung penggunaan sinkronisasi:
Atribut | Nilai | Deskripsi |
---|---|---|
edge_config.synchronizerMode |
0 atau 1 | Jika 0 (default), Edge Microgateway beroperasi dalam mode standarnya. Jika 1, mulai instance Edge Microgateway untuk beroperasi sebagai sinkronisasi. Dalam mode ini, instance akan mengambil data konfigurasi dari Apigee Edge dan menyimpannya di database Redis lokal. Instance ini tidak dapat memproses permintaan proxy API; tujuannya hanya untuk melakukan polling Apigee Edge untuk data konfigurasi dan menulisnya ke database lokal. Kemudian, Anda harus mengonfigurasi instance microgateway lain untuk membaca dari database. |
edge_config.redisBasedConfigCache |
benar atau salah | Jika benar, instance Edge Microgateway akan mengambil data konfigurasinya dari database Redis, bukan dari Apigee Edge. Database Redis harus sama dengan database yang dikonfigurasi untuk ditulis oleh sinkronisasi. Jika database Redis tidak tersedia atau
jika database kosong, microgateway akan mencari file cache-config.yaml
yang ada untuk konfigurasinya.
Jika salah (default), instance Edge Microgateway akan mengambil data konfigurasi dari Apigee Edge seperti biasa. |
edgemicro.config_change_poll_interval |
Interval waktu, dalam detik | Menentukan interval polling untuk sinkronisasi guna mengambil data dari Apigee Edge. |
Mengonfigurasi URL pengecualian untuk plugin
Anda dapat mengonfigurasi microgateway untuk melewati pemrosesan plugin untuk URL yang ditentukan. Anda dapat mengonfigurasi URL "kecualikan" ini secara global (untuk semua plugin) atau untuk plugin tertentu.
Contoh:
... edgemicro: ... plugins: excludeUrls: '/hello,/proxy_one' # global exclude urls sequence: - oauth - json2xml - quota json2xml: excludeUrls: '/hello/xml' # plugin level exclude urls ...
Dalam contoh ini, plugin tidak akan memproses panggilan proxy API yang masuk dengan
jalur /hello
atau /proxy_one
. Selain itu, plugin json2xml
akan dilewati untuk API dengan /hello/xml
di jalurnya.
Menetapkan atribut konfigurasi dengan nilai variabel lingkungan
Anda dapat menentukan variabel lingkungan menggunakan tag dalam file konfigurasi. Tag variabel lingkungan yang ditentukan akan diganti dengan nilai variabel lingkungan yang sebenarnya. Penggantian hanya disimpan dalam memori dan tidak disimpan dalam file cache atau konfigurasi asli.
Dalam contoh ini, atribut key
diganti dengan nilai variabel lingkungan TARGETS_SSL_CLIENT_KEY
, dan seterusnya.
targets: - ssl: client: key: <E>TARGETS_SSL_CLIENT_KEY</E> cert: <E>TARGETS_SSL_CLIENT_CERT</E> passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>
Dalam contoh ini, tag <n>
digunakan untuk menunjukkan nilai bilangan bulat. Hanya bilangan bulat positif yang didukung.
edgemicro: port: <E><n>EMG_PORT</n></E>
Dalam contoh ini, tag <b>
digunakan untuk menunjukkan nilai boolean (
yaitu, benar atau
salah).
quotas: useRedis: <E><b>EMG_USE_REDIS</b></E>