Opsi startup Extensible Service Proxy

OpenAPI | gRPC

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 `managed` atau `fixed`. Opsi `--rollout_strategy=managed` mengonfigurasi ESP agar menggunakan konfigurasi layanan terbaru yang di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP mendeteksi perubahan dan otomatis mulai menggunakannya. Sebaiknya tentukan opsi ini, bukan ID konfigurasi tertentu yang akan digunakan ESP. Anda tidak perlu menentukan opsi `--version` saat menetapkan `--rollout_strategy` ke `managed`.
`-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.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Menetapkan port yang ditampilkan ESP untuk koneksi HTTP/2.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Menetapkan port yang ditampilkan ESP untuk koneksi HTTPS.¹
`-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`.

¹ 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=http://example.com`
`--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 --cors_allow_origin_regex=^https?://.+\.example\.com$` Ekspresi reguler dalam contoh sebelumnya mengizinkan origin dengan `http` atau `https` dan subdomain `example.com` apa pun.

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_methods=GET,POST,PUT,OPTIONS`
`--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_headers=Origin,Content-Type,Accept`
`--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_allow_credentials`
`--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 --cors_expose_headers=Content-Length`

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