Panduan operasi

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Cara mendapatkan kunci API

Contoh berikut menjelaskan cara mendapatkan kunci API yang dapat Anda gunakan untuk memvalidasi panggilan API ke layanan target yang di-proxy melalui Adaptor Apigee untuk Envoy.

CATATAN: Jika Anda adalah pengguna Apigee yang berpengalaman, langkah-langkah berikut akan sudah dikenal, karena merupakan konfigurasi Edge standar; namun, ikuti petunjuk ini dengan cermat, karena Anda harus menyisipkan konfigurasi Produk dan Aplikasi Developer tertentu.

1. Login ke Apigee

1. Login ke UI Apigee.
2. Pilih organisasi yang sama dengan yang Anda gunakan untuk menyediakan Adaptor Apigee untuk Envoy.

2. Membuat Developer

Anda dapat menggunakan developer yang ada untuk pengujian, atau membuat developer baru sebagai berikut:

1. Pilih Publikasi > Developer di menu navigasi samping.
2. Klik + Developer.
3. Isi dialog untuk membuat developer baru. Anda dapat menggunakan nama/email developer apa pun yang Anda inginkan.

3. Membuat Produk API

Ikuti contoh Pembuatan produk yang diberikan di bawah.

1. Pilih Publikasi > Produk API di menu navigasi samping.
2. Klik +CREATE.
3. Isi bagian Detail produk sebagai berikut. Hanya kolom yang diperlukan yang disebutkan dalam tabel berikut:

   Kolom	Nilai	Deskripsi
   Nama	httpbin-product	Nama unik produk API.
   Display Name	httpbin product	Nama deskriptif yang ingin Anda lihat di UI atau konteks tampilan lainnya.
   Akses	Public	Untuk tujuan contoh ini, Publik adalah pilihan yang baik.

4. Di bagian Operasi, klik +TAMBAHKAN OPERASI.
5. Di bagian Source, pilih Remote Service.
6. Alihkan tombol Sumber untuk memungkinkan Anda mengetik nama layanan jarak jauh secara manual di kolom Layanan Jarak Jauh.
7. Di kolom Remote Service, masukkan nama layanan jarak jauh. Ini adalah layanan target yang akan dijadikan proxy oleh adaptor untuk permintaan HTTP masuk. Untuk tujuan pengujian, gunakan httpbin.org atau httpbin.default.svc.cluster.local dengan Kubernetes.

   

8. Di bagian Operation, masukkan / untuk jalur. Untuk informasi tentang opsi jalur, lihat Mengonfigurasi jalur resource.
9. Klik SIMPAN untuk menyimpan operasi.
10. Klik SIMPAN untuk menyimpan produk API.

Untuk informasi selengkapnya, lihat Mengelola produk API.

4. Membuat Aplikasi Developer

Aplikasi developer berisi kunci API yang diperlukan untuk melakukan panggilan proxy API melalui adaptor.

1. Pilih Publikasikan Aplikasi di menu navigasi samping.
2. Klik + Aplikasi.
3. Isi bagian App Details sebagai berikut. Hanya kolom yang diperlukan yang disebutkan dalam tabel berikut:

Nama	httpbin-app
Developer	Pilih developer yang Anda buat sebelumnya, atau pilih developer yang Anda inginkan dari daftar.

4. Di bagian Kredensial, klik + Tambahkan produk dan pilih produk yang baru saja Anda konfigurasi: httpbin-product.
5. Klik Create.
6. Di bagian Kredensial, klik Tampilkan di samping Kunci.
7. Salin nilai Kunci Konsumen. Nilai ini adalah kunci API yang akan Anda gunakan untuk melakukan panggilan API ke layanan httpbin melalui Adaptor Apigee untuk Envoy.

Menggunakan autentikasi berbasis JWT

Anda dapat menggunakan token JWT untuk melakukan panggilan proxy API yang diautentikasi, bukan menggunakan kunci API. Bagian ini menjelaskan cara menggunakan perintah apigee-remote-service-cli token untuk membuat, memeriksa, dan memutar token JWT. Untuk lingkungan campuran Apigee, Anda dapat menggunakan perintah ini untuk membuat secret Kubernetes guna menyimpan JWT.

Ringkasan

Verifikasi dan autentikasi JWT ditangani oleh Envoy menggunakan Filter Autentikasi JWT.

Setelah diautentikasi, filter ext-authz Envoy akan mengirimkan header permintaan dan JWT ke apigee-remote-service-envoy. Token ini cocok dengan klaim api_product_list dan scope JWT terhadap Produk API Apigee untuk memberikan otorisasi terhadap target permintaan.

Membuat token JWT Apigee

Token JWT Apigee dapat dibuat menggunakan CLI:

apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

Atau dengan menggunakan endpoint token OAuth standar. Contoh curl:

curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

CATATAN: Header Content-type diperlukan.

Menggunakan token JWT

Setelah memiliki token, Anda cukup meneruskannya ke Envoy di header Otorisasi. Contoh:

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Kegagalan token JWT

Penolakan Envoy

Jika Envoy menolak token, Anda mungkin melihat pesan seperti:

Jwks remote fetch has failed

Jika demikian, pastikan konfigurasi Envoy Anda berisi URI yang valid di bagian remote_jwks, dapat dijangkau oleh Envoy, dan Anda telah menetapkan sertifikat dengan benar saat menginstal proxy Apigee. Anda akan dapat memanggil URI secara langsung dengan panggilan GET dan menerima respons JSON yang valid.

Contoh:

curl https://myorg-eval-test.apigee.net/remote-service/certs

Pesan lain dari Envoy mungkin terlihat seperti:

• "Audiens dalam Jwt tidak diizinkan"
• "Penerbit Jwt tidak dikonfigurasi"

Hal ini berasal dari persyaratan dalam konfigurasi Envoy yang mungkin perlu Anda ubah.

Memeriksa token

Anda dapat menggunakan CLI untuk memeriksa token. Contoh

apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

atau

apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Proses Debug

Lihat Kunci API yang valid gagal.

Menggunakan Penyedia Identitas Anda sendiri

Secara default, Adaptor Apigee untuk Envoy menggunakan proxy API remote-token sebagai layanan penyedia identitas untuk mengautentikasi aplikasi klien dan mengirimkan token JWT berdasarkan jenis pemberian kredensial klien OAuth 2.0. Namun, dalam beberapa kasus, Anda mungkin tidak dapat menggunakan proxy remote-token. Jika Anda harus menggunakan penyedia identitas yang bukan yang disediakan oleh Apigee, Anda dapat mengonfigurasi adaptor untuk menggunakan penyedia identitas lain. Untuk mengetahui detail tentang kasus penggunaan penyedia identitas non-Apigee ini dan konfigurasi yang diperlukan, lihat artikel ini di Komunitas Apigee: Menggunakan Penyedia Identitas Anda sendiri dengan Adaptor Envoy Apigee.

Logging

Anda dapat menyesuaikan tingkat logging di layanan $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Semua logging dikirim ke stderr.

Elemen	Wajib	Deskripsi
-l, --log-level	Level yang valid: debug, info, peringatan, error.	Menyesuaikan level logging. Default: info
-j, --json-log		Mengeluarkan output log sebagai kumpulan data JSON.

Envoy menyediakan logging. Untuk informasi selengkapnya, lihat link dokumentasi Envoy berikut:

• Logging Aplikasi
• Log Akses
• Logging Stackdriver dengan GKE

Mengubah nama secret kebijakan

Secret Kubernetes yang di-deploy ke cluster berisi kredensial yang diperlukan adaptor untuk mengautentikasi komunikasi dengan proxy layanan jarak jauh. Secret ini memerlukan titik pemasangan volume, yang dapat dikonfigurasi. Secara default, titik pemasangan adalah /policy-secret. Untuk mengubah titik pemasangan, ikuti langkah-langkah berikut:

1. Jalankan perintah ini:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   Contoh:

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. Buka $CLI_HOME/samples/apigee-envoy-adapter.yaml di editor.
3. Ubah nama titik pemasangan menjadi nama baru:

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. Simpan file dan terapkan ke mesh layanan:

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/apigee-envoy-adapter.yaml

Menggunakan proxy jaringan

Proxy HTTP dapat disisipkan menggunakan variabel lingkungan HTTP_PROXY dan HTTPS_PROXY di lingkungan biner apigee-remote-service-envoy. Saat menggunakannya, variabel lingkungan NO_PROXY juga dapat digunakan untuk mengecualikan host tertentu agar tidak dikirim melalui proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

Ingat bahwa proxy harus dapat dijangkau dari apigee-remote-service-envoy.

Tentang metrik dan analisis

Endpoint metrik Prometheus tersedia di :5001/metrics. Anda dapat mengonfigurasi nomor port ini. Lihat File konfigurasi.

Analisis Envoy

Link berikut memberikan informasi tentang cara mendapatkan data analisis proxy Envoy:

• Antarmuka admin
• Statistik
• Statistik cluster

Analisis Istio

Link berikut memberikan informasi tentang cara mendapatkan data analisis proxy Envoy:

• Tugas observabilitas
• Konfigurasi telemetri

Analisis Apigee

Layanan Jarak Jauh Apigee untuk Envoy mengirimkan statistik permintaan ke Apigee untuk pemrosesan analisis. Apigee melaporkan permintaan ini dengan nama Produk API terkait.

Untuk informasi tentang analisis Apigee, lihat Ringkasan layanan analisis.

Dukungan lingkungan multi-tenant

Sekarang Anda dapat mengaktifkan adaptor untuk melayani beberapa lingkungan di organisasi Apigee. Fitur ini memungkinkan Anda menggunakan satu Adaptor Apigee untuk Envoy yang terkait dengan satu organisasi Apigee untuk melayani beberapa lingkungan. Sebelum perubahan ini, satu adaptor selalu terikat dengan satu lingkungan Apigee.

Untuk mengonfigurasi beberapa dukungan lingkungan, ubah nilai tenant:env_name menjadi "*" dalam file config.yaml. Contoh:

1. Buka file config.yaml di editor.
2. Ubah nilai tenant.env_name menjadi "*". Contoh:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: apigee-remote-service-envoy
     namespace: apigee
   data:
     config.yaml: |
       tenant:
         remote_service_api: https://apitest.mydomain.net/remote-service
         org_name: my-org
         env_name: "*""
         allow_unverified_ssl_cert: true
       analytics:
         collection_interval: 10s
       auth:
         jwt_provider_key: https://apitest.mydomain.net/remote-token/token

3. Simpan file.
4. Terapkan file:

   kubectl apply -f $CLI_HOME/config.yaml

Saat mengonfigurasi mode multi-lingkungan, Anda juga harus mengonfigurasi Envoy untuk mengirim nilai lingkungan yang sesuai ke adaptor dengan menambahkan metadata berikut di bagian virtual_hosts:routes file envoy-config.yaml. Contoh:

1. Buat file envoy-config.yaml menggunakan CLI. Contoh:

   $CLI_HOME/apigee-remote-service-cli samples create \
     -t envoy-1.16 -c ./config.yaml --out myconfigs

2. Buka file yang dihasilkan (disebut envoy-config.yaml).
3. Tambahkan metadata berikut di bagian virtual_host atau routes pada file:

   typed_per_filter_config:
     envoy.filters.http.ext_authz:
       "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
       check_settings:
         context_extensions:
           apigee_environment: test

   Contoh berikut mengilustrasikan konfigurasi untuk virtual_host dengan beberapa rute yang ditentukan, dengan setiap rute mengirim traffic ke lingkungan tertentu:

   filter_chains:
       - filters:
         - name: envoy.filters.network.http_connection_manager
           typed_config:
             "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
             stat_prefix: ingress_http
             route_config:
               virtual_hosts:
               - name: default
                 domains: "*"
                 routes:
                 - match: { prefix: /test }
                   route:
                     cluster: httpbin
                   typed_per_filter_config:
                     envoy.filters.http.ext_authz:
                       "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                       check_settings:
                         context_extensions:
                            apigee_environment: test
                 - match: { prefix: /prod }
                   route:
                     cluster: httpbin
                   typed_per_filter_config:
                     envoy.filters.http.ext_authz:
                       "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                       check_settings:
                         context_extensions:
                            apigee_environment: prod

4. Ulangi langkah terakhir untuk menambahkan lingkungan tambahan sesuai kebutuhan.
5. Simpan file dan terapkan.
   Catatan: Jika env_name di config.yaml ditetapkan ke nilai lain selain "*", adaptor akan menampilkan error ke Envoy dan permintaan akan ditolak jika konfigurasi env_name adaptor tidak ditetapkan ke "*", atau properti env_name tidak cocok dengan metadata apigee_environment yang diteruskan.

Mengambil data untuk laporan kustom

Adaptor mendukung penerusan metadata Envoy ke fitur pengambilan data Apigee, yang mengirim data yang diambil dalam variabel yang Anda tentukan ke analisis Apigee untuk digunakan dalam laporan kustom. Fitur ini memberikan kemampuan yang mirip dengan kebijakan Pengambilan Data Apigee.

Untuk menggunakan fitur ini:

1. Buat resource REST Kolektor Data.
2. Tentukan variabel pengambilan data menggunakan API datacollectors Apigee.
3. Jika Anda belum melakukannya, buat file envoy-config.yaml menggunakan CLI. Contoh:

   $CLI_HOME/apigee-remote-service-cli samples create \
     -t envoy-1.16 -c ./config.yaml --out myconfigs

4. Buka file yang dihasilkan (disebut envoy-config.yaml).
5. Gunakan filter Envoy untuk menetapkan nilai untuk variabel kustom Anda di namespace envoy.filters.http.apigee.datacapture. Misalnya, Anda dapat menggunakan filter Header to Metadata atau filter Lua. Untuk informasi selengkapnya tentang filter ini, lihat Header-To-Metadata dan Lua.

   Nama variabel kustom harus diformat sebagai dc.XXXXX.

   Contoh filter Header ke Metadata:

    - name: envoy.filters.http.header_to_metadata
     typed_config:
       "@type": type.googleapis.com/envoy.extensions.filters.http.header_to_metadata.v3.Config
       request_rules:
         - header: "Host"
           on_header_present:
             metadata_namespace: envoy.filters.http.apigee.datacapture
             key: dc.host  # host (without the prefix) also works
             type: STRING
           remove: false

   Contoh filter Lua:

   - name: envoy.filters.http.lua
     typed_config:
       "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
       inline_code: |
         function envoy_on_request(request_handle)
           metadata = request_handle:streamInfo():dynamicMetadata()
           metadata:set("envoy.filters.http.apigee.datacapture", "dc.test", "A test string.")
         end

6. Tambahkan filter yang diinginkan ke file. Lihat contohnya di bawah.
7. Simpan file dan terapkan.

Mengonfigurasi mTLS antara adaptor dan runtime Apigee

Anda dapat menyediakan sertifikat TLS sisi klien di bagian tenant dari file config.yaml adaptor untuk menggunakan mTLS antara adaptor dan runtime Apigee. Perubahan ini berlaku untuk semua platform Apigee yang didukung. Tindakan ini juga mengaktifkan mTLS untuk analisis untuk platform Apigee Edge for Private Cloud. Contoh:

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false