Opsi startup Extensible Service Proxy

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.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=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: