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 ESP Docker container. Saat container ESP dimulai, container tersebut menjalankan skrip yang disebut start_esp, 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 Endpoints.
-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 untuk menggunakan konfigurasi layanan terbaru yang di-deploy. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan 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 Anda perlukan untuk menyetel opsi ini. Saat menentukan --rollout_strategy=fixed atau saat Anda tidak menyertakan opsi --rollout_strategy, Anda harus menyertakan opsi --version dan menentukan ID konfigurasi. Dalam hal ini, setiap kali Anda men-deploy konfigurasi Endpoints baru, Anda harus memulai ulang ESP dengan ID konfigurasi baru.
-p HTTP1_PORT --http_port HTTP1_PORT Menetapkan port yang diekspos ESP untuk koneksi HTTP/1.x.1
-P HTTP2_PORT --http2_port HTTP2_PORT Menetapkan port yang diekspos ESP untuk koneksi HTTP/2.1
-S SSL_PORT --ssl_port SSL_PORT Menetapkan port yang diekspos 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
-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 permintaan atau 1 permintaan dari setiap 10 detik diaktifkan dengan Cloud Trace. Tetapkan flag ini untuk menonaktifkan pengambilan sampel otomatis tersebut. Cloud Trace masih dapat diaktifkan dari header HTTP permintaan dengan konteks rekaman aktivitas, terlepas dari nilai tanda ini. Lihat Melacak API untuk mengetahui 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 dan kemudian segera meluncurkan NGINX dengan file konfigurasi kustom yang diberikan. 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 menggunakan akun layanan untuk membuat token akses guna memanggil Service Infrastructure API. Satu-satunya saat Anda perlu menentukan opsi ini adalah saat ESP berjalan di platform selain Google Cloud, seperti desktop lokal, Kubernetes, atau penyedia cloud lain. Lihat Membuat akun layanan untuk mengetahui informasi selengkapnya.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH Tentukan endpoint pemeriksaan kondisi pada port yang sama dengan backend aplikasi. Misalnya, -z healthz membuat ESP menampilkan kode 200 untuk lokasi /healthz, alih-alih meneruskan permintaan ke backend. Default: tidak digunakan.
tidak ada --dns DNS_RESOLVER Tentukan resolver DNS. Misalnya, --dns 169.254.169.254 menggunakan server Metadata GCP sebagai DNS resolver. 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 di 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 serta mengirim permintaan ke backend API Anda 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 mem-mount file JSON yang berisi kunci pribadi untuk akun layanan dan file konfigurasi NGINX kustom sebagai volume di dalam penampung Docker ESP. Contoh sebelumnya memetakan direktori $HOME/Downloads di komputer lokal ke direktori esp di container. Saat Anda menyimpan file kunci pribadi untuk akun layanan, file tersebut biasanya didownload ke direktori Downloads. Anda dapat menyalin file kunci pribadi ke direktori lain jika Anda mau. Lihat Mengelola data di Docker untuk mengetahui informasi selengkapnya.

Menambahkan dukungan CORS ke ESP

Lihat Mendukung CORS untuk mengetahui 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. Saat Anda menyertakan --cors_preset=basic atau --cors_preset=cors_with_regex, ESP:

  • Mengasumsikan semua jalur lokasi memiliki kebijakan CORS yang sama.
  • Merespons permintaan sederhana dan permintaan preflight HTTP OPTIONS.
  • Menyimpan hasil permintaan preflight OPTIONS ke dalam 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 asal 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 menyetel Access-Control-Allow-Origin.
Contoh:
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

Ekspresi reguler dalam contoh sebelumnya mengizinkan asal dengan http atau https dan subdomain apa pun dari example.com.

Setelah menyetel --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 oleh 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 mana yang dapat diekspos sebagai bagian dari respons sebagai string dengan setiap header yang dipisahkan oleh koma.
Contoh:
--cors_preset=basic
--cors_expose_headers=Content-Length

Jika opsi startup CORS ESP tidak sesuai dengan kebutuhan aplikasi Anda, 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 berikutnya

Pelajari: