Extensible Service Proxy (ESP) adalah proxy berbasis NGINX yang memungkinkan Cloud Endpoints menyediakan fitur pengelolaan API. Anda mengonfigurasi ESP dengan menentukan opsi saat memulai penampung ESP Docker. Saat penampung ESP dimulai, skrip yang disebut start_esp
akan dijalankan, yang menulis file konfigurasi NGINX menggunakan opsi yang Anda tentukan dan meluncurkan ESP.
Anda menentukan opsi startup ESP dalam perintah docker run
, misalnya:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
Jika Anda men-deploy ESP ke Kubernetes, tentukan opsi startup dalam file manifes deployment di kolom args
, misalnya:
containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
Tabel berikut menjelaskan opsi startup ESP.
Opsi singkat | Opsi panjang | Deskripsi |
---|---|---|
-s SERVICE_NAME |
--service SERVICE_NAME |
Menetapkan nama layanan Endpoint. |
-R ROLLOUT_STRATEGY |
--rollout_strategy ROLLOUT_STRATEGY |
Tersedia di ESP versi 1.7.0 dan yang lebih baru. Tentukan |
-v CONFIG_ID |
--version CONFIG_ID |
Menetapkan ID konfigurasi layanan yang akan digunakan oleh ESP. Lihat
Mendapatkan nama layanan dan ID konfigurasi untuk mengetahui informasi yang perlu Anda tetapkan untuk menetapkan opsi ini.
Saat menentukan --rollout_strategy=fixed atau jika tidak
menyertakan opsi --rollout_strategy , Anda harus menyertakan
opsi --version dan menentukan ID konfigurasi. Dalam hal ini,
setiap kali men-deploy konfigurasi Endpoint baru, Anda harus
memulai ulang ESP dengan ID konfigurasi baru.
|
-p HTTP1_PORT |
--http_port HTTP1_PORT |
Menetapkan port yang ditampilkan ESP untuk koneksi HTTP/1.x.1 |
-P HTTP2_PORT |
--http2_port HTTP2_PORT |
Menetapkan port yang ditampilkan ESP untuk koneksi HTTP/2.1 |
-S SSL_PORT |
--ssl_port SSL_PORT |
Menetapkan port yang ditampilkan ESP untuk koneksi HTTPS.1 |
-a BACKEND |
--backend BACKEND |
Menetapkan alamat untuk server backend aplikasi HTTP/1.x. Nilai default
untuk alamat backend adalah http://127.0.0.1:8081 .Anda dapat menentukan awalan protokol, misalnya: --backend=https://127.0.0.1:8000 Jika Anda tidak menentukan awalan protokol, defaultnya adalah http .Jika server backend Anda berjalan di Compute Engine dalam container, Anda dapat menentukan nama container dan port, misalnya: --backend=my-api-container:8000 Untuk menentukan bahwa backend menerima traffic gRPC, tambahkan awalan grpc:// . Misalnya;--backend=grpc://127.0.0.1:8000 Jika server backend Anda berjalan di Compute Engine dalam container, dan menerima traffic gRPC, Anda dapat menentukan nama container dan port, misalnya: --backend=grpc://my-api-container:8000
|
-N STATUS_PORT |
--status_port STATUS_PORT |
Menetapkan port status (default: 8090 ).
|
tidak ada | --disable_cloud_trace_auto_sampling |
Secara default, ESP mengambil sampel 1 permintaan dari setiap 1.000 atau 1 permintaan dari setiap 10 detik diaktifkan dengan Cloud Trace. Tetapkan tanda ini untuk menonaktifkan pengambilan sampel otomatis tersebut. Cloud Trace masih dapat diaktifkan dari permintaan header HTTP dengan konteks trace, apa pun nilai flag ini. Lihat Melacak API untuk informasi selengkapnya. |
-n NGINX_CONFIG |
--nginx_config NGINX_CONFIG |
Menetapkan lokasi untuk file konfigurasi NGINX kustom. Jika Anda menentukan opsi ini, ESP akan mengambil file konfigurasi yang ditentukan, lalu segera meluncurkan NGINX dengan file konfigurasi kustom yang disediakan. Lihat Menggunakan konfigurasi nginx kustom untuk GKE untuk mengetahui informasi selengkapnya. |
-k SERVICE_ACCOUNT_KEY |
--service_account_key SERVICE_ACCOUNT_KEY |
Menetapkan file JSON kredensial akun layanan. Jika disediakan, ESP akan menggunakan akun layanan untuk membuat token akses guna memanggil Service Infrastructure API. Satu-satunya waktu Anda perlu menentukan opsi ini adalah saat ESP berjalan di platform selain Google Cloud, seperti desktop lokal, Kubernetes, atau penyedia cloud lainnya. Lihat Membuat akun layanan untuk informasi selengkapnya. |
-z HEALTHZ_PATH |
--healthz HEALTHZ_PATH |
Tetapkan endpoint health check pada port yang sama dengan backend
aplikasi. Misalnya, -z healthz membuat ESP menampilkan kode 200 untuk lokasi /healthz , bukan meneruskan permintaan ke backend. Default: tidak digunakan.
|
tidak ada | --dns DNS_RESOLVER |
Menentukan resolver DNS. Misalnya, --dns 169.254.169.254 menggunakan server Metadata GCP sebagai resolver DNS. Jika tidak ditentukan, defaultnya adalah
8.8.8.8 .
|
1 Port ini bersifat opsional dan harus berbeda satu sama lain.
Jika Anda tidak menentukan opsi port apa pun, ESP akan menerima koneksi HTTP/1.x
pada port 8080
.
Untuk koneksi HTTPS, ESP mengharapkan rahasia TLS
berada di /etc/nginx/ssl/nginx.crt
dan /etc/nginx/ssl/nginx.key
.
Contoh pemanggilan command line
Contoh berikut menunjukkan cara menggunakan beberapa argumen command line:
Untuk memulai ESP guna menangani permintaan yang masuk di port HTTP/1.x 80
dan port HTTPS 443
lalu kirim permintaan ke backend API di
127.0.0.1:8000
:
sudo docker run \ --detach \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --http_port=80 \ --ssl_port=443 \ --backend=127.0.0.1:8000
Untuk memulai ESP dengan konfigurasi NGINX kustom menggunakan file kredensial akun layanan untuk mengambil konfigurasi layanan dan terhubung ke kontrol layanan:
sudo docker run \ --detach \ --volume=$HOME/Downloads:/esp \ DOCKER_ARGUMENTS \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=echo-api.endpoints.example-project-12345.cloud.goog \ --rollout_strategy=managed \ --service_account_key=/esp/serviceaccount.json \ --nginx_config=/esp/nginx.conf
Perhatikan bahwa Anda harus menggunakan flag Docker --volume
atau --mount
untuk memasang file JSON yang berisi kunci pribadi untuk akun layanan dan file konfigurasi NGINX kustom sebagai volume di dalam container Docker ESP. Contoh sebelumnya memetakan direktori $HOME/Downloads
di komputer lokal ke direktori esp
di penampung. Saat Anda menyimpan file kunci pribadi untuk
akun layanan, file ini biasanya akan didownload ke direktori Downloads
. Anda dapat menyalin file kunci pribadi ke direktori lain jika ingin. Baca bagian Mengelola data di Docker untuk mengetahui informasi selengkapnya.
Menambahkan dukungan CORS ke ESP
Lihat Dukungan CORS untuk deskripsi opsi dukungan CORS yang tersedia. Bagian ini menjelaskan penggunaan flag startup ESP untuk mendukung CORS.
Untuk mengaktifkan dukungan CORS di ESP, sertakan opsi --cors_preset
dan tetapkan ke basic
atau cors_with_regex
. Jika Anda menyertakan
--cors_preset=basic
atau --cors_preset=cors_with_regex
, ESP:
- Mengasumsikan semua jalur lokasi memiliki kebijakan CORS yang sama.
- Merespons permintaan permintaan sederhana dan
preflight
HTTP OPTIONS
. - Menyimpan hasil permintaan
OPTIONS
preflight ke cache hingga 20 hari (1728000 detik). Menetapkan header respons ke nilai berikut:
Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization Access-Control-Expose-Headers: Content-Length,Content-Range
Untuk mengganti nilai default
Access-Control-Allow-Origin
,
tentukan salah satu opsi berikut:
Opsi | Deskripsi |
---|---|
--cors_allow_origin |
Gunakan dengan --cors_preset=basic untuk menetapkan
Access-Control-Allow-Origin ke origin tertentu.Contoh:
--cors_preset=basic
|
--cors_allow_origin_regex |
Gunakan dengan --cors_preset=cors_with_regex . Memungkinkan Anda menggunakan
ekspresi reguler untuk menetapkan Access-Control-Allow-Origin .Contoh:
--cors_preset=cors_with_regex
Ekspresi reguler dalam contoh sebelumnya mengizinkan origin dengan
|
Setelah menetapkan --cors_preset=basic
atau --cors_preset=cors_with_regex
untuk mengaktifkan CORS, Anda dapat mengganti nilai default header respons lainnya dengan menentukan satu atau beberapa opsi berikut:
Opsi | Deskripsi |
---|---|
--cors_allow_methods |
Menetapkan
Access-Control-Allow-Methods
ke metode HTTP yang ditentukan. Tentukan metode HTTP sebagai string, dengan setiap metode HTTP dipisahkan dengan koma.Contoh:
--cors_preset=basic
|
--cors_allow_headers |
Menetapkan
Access-Control-Allow-Headers
ke header HTTP yang ditentukan. Tentukan header HTTP sebagai string dengan setiap header HTTP dipisahkan dengan koma.Contoh:
--cors_preset=basic
|
--cors_allow_credentials |
Menyertakan header
Access-Control-Allow-Credentials
dengan nilai true dalam respons. Secara default, header
Access-Control-Allow-Credentials tidak disertakan dalam respons.Contoh:
--cors_preset=basic
|
--cors_expose_headers |
Menetapkan
Access-Control-Expose-Headers
ke header yang ditentukan. Tentukan header yang dapat ditampilkan sebagai bagian dari
respons sebagai string dengan setiap header dipisahkan oleh koma.Contoh:
--cors_preset=basic
|
Jika opsi startup ESP CORS tidak sesuai dengan kebutuhan aplikasi, Anda dapat membuat file nginx.conf
kustom dengan dukungan CORS yang diperlukan aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat
Membuat nginx.conf
kustom untuk mendukung CORS.
Langkah selanjutnya
Pelajari:
- Men-deploy ESP dan backend API ke Google Cloud
- Menjalankan ESP secara lokal atau di platform lain
- Skrip
start_esp
di GitHub