Panduan operasi

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

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-kan melalui Adaptor Apigee untuk Envoy.

1. Login ke Apigee

  1. Buka UI Apigee di browser.
  2. Setelah berada di UI, pilih organisasi yang sama dengan yang Anda gunakan untuk mengonfigurasi Adaptor Apigee untuk Envoy.

2. Membuat Developer

Anda dapat menggunakan developer yang sudah ada untuk pengujian, atau membuat yang baru dengan cara berikut:

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

3. Membuat Produk API

Ikuti contoh pembuatan Produk yang diberikan di bawah ini. Lihat juga Tentang Konfigurasi produk API.

  1. Pilih Publikasikan > Produk API di menu navigasi samping.
  2. Klik + Produk API.
  3. Isi halaman Detail produk sebagai berikut.
  4. Kolom Nilai
    Nama httpbin-product
    Display Name httpbin product
    Lingkungan your_environment

    Tetapkan ini ke lingkungan yang Anda gunakan saat menyediakan Adaptor Apigee untuk Envoy.

    Akses Private
    Kuota 5 permintaan setiap 1 menit

    Lihat juga Kuota.

  5. Di bagian Apigee remote service targets, klik Add an Apigee remote service target.
  6. Pada dialog target layanan jarak jauh Apigee, tambahkan nilai berikut:
    Atribut Nilai Deskripsi
    Nama target Masukkan nama target layanan. Contoh: httpbin.org Endpoint target yang didahulukan oleh proxy Envoy.
    Jalur Masukkan jalur resource pada layanan yang akan dicocokkan. Sebagai contoh: /headers. Jalur permintaan yang akan dicocokkan pada endpoint target. Panggilan proxy API ke jalur ini akan cocok dengan produk API ini.
  7. Klik Simpan.

4. Membuat Aplikasi Developer

  1. Pilih Publikasikan > Aplikasi di menu navigasi samping.
  2. Klik + App.
  3. Isi halaman Aplikasi Developer sebagai berikut. Jangan Simpan hingga diperintahkan untuk melakukannya.
  4. Nama httpbin-app
    Display Name httpbin app
    Developer Pilih developer yang Anda buat sebelumnya, atau pilih developer yang Anda inginkan dari daftar.
  5. Selanjutnya, tambahkan produk API ke aplikasi:
    1. Di bagian Kredensial, klik + Tambahkan produk, lalu pilih produk yang Anda baru saja dikonfigurasi: httpbin-product.
    2. Klik Buat.
    3. Di bagian Credentials, klik Show di samping Key.
    4. Salin nilai Kunci Konsumen. Nilai ini adalah kunci API yang akan Anda gunakan untuk melakukan panggilan API ke layanan httpbin.

    Tentang produk API

    Produk API adalah kontrol utama untuk Apigee Remote Service. Saat Anda membuat Produk API dan mengikatnya ke layanan target, Anda membuat kebijakan yang akan diterapkan ke setiap permintaan yang Anda konfigurasikan Adaptor Apigee untuk Envoy untuk ditangani.

    Definisi Produk API

    Saat menentukan Produk API di Apigee, Anda dapat menetapkan sejumlah parameter yang akan digunakan untuk mengevaluasi permintaan:

    • Target
    • Request path
    • Kuota
    • Cakupan OAuth

    Target Layanan Jarak Jauh

    Definisi Produk API akan diterapkan pada permintaan jika permintaan tersebut cocok dengan keduanya binding (misalnya, httpbin.org) dan jalur permintaan (misalnya, /httpbin). Daftar target potensial disimpan sebagai atribut di Produk API.

    Secara default, Apigee Remote Service memeriksa header :authority (host) khusus Envoy terhadap daftar targetnya; namun dapat dikonfigurasi untuk menggunakan {i>header<i} lainnya.

    Jalur Resource API

    Jalur yang dimasukkan cocok sesuai dengan aturan berikut:

    • Garis miring tunggal (/) itu sendiri cocok dengan jalur apa pun.
    • * valid di mana saja dan cocok dalam segmen (di antara garis miring).
    • ** valid di akhir dan cocok dengan apa saja hingga akhir baris.

    Kuota

    Kuota menentukan jumlah pesan permintaan yang boleh dikirim oleh aplikasi ke API selama satu jam, hari, minggu, atau bulan. Saat aplikasi mencapai batas kuota, panggilan API berikutnya ditolak.

    Kasus penggunaan kuota

    Kuota memungkinkan Anda memberlakukan jumlah permintaan yang dapat diajukan klien ke layanan dalam waktu tertentu. Kuota sering digunakan untuk menerapkan kontrak bisnis atau SLA dengan developer dan partner, bukan untuk pengelolaan traffic operasional. Sebagai contoh, kuota dapat digunakan guna membatasi lalu lintas untuk layanan gratis, sekaligus memungkinkan akses penuh pelanggan yang membayar.

    Kuota ditentukan di Produk API

    Parameter kuota dikonfigurasi di Produk API. Misalnya, saat Anda membuat API Produk, secara opsional Anda dapat menetapkan batas kuota, unit waktu, dan interval yang diizinkan.

    Karena kunci API dipetakan kembali ke Produk API, setiap kali kunci API diverifikasi penghitung kuota yang sesuai dapat dikurangi (jika Kuota ditentukan dalam Produk terkait).

    Tidak seperti dalam runtime Apigee, Kuota yang dimasukkan dalam definisi Produk otomatis diterapkan oleh Apigee Remote Service. Jika permintaan diotorisasi, permintaan akan dihitung terhadap kuota yang diizinkan.

    Tempat kuota dipertahankan

    Kuota dikelola dan diperiksa secara lokal oleh proses Remote Service dan secara asinkron dikelola dengan Apigee Runtime. Artinya, kuotanya tidak tepat dan cenderung beberapa layanan berlebih jika Anda memiliki lebih dari satu Layanan Jarak Jauh yang mempertahankan kuota. Jika koneksi ke Apigee Runtime terganggu, kuota lokal akan berlanjut secara mandiri kuota hingga waktu tersebut dapat terhubung kembali ke Runtime Apigee.

    Cakupan OAuth

    Jika menggunakan token JWT, Anda dapat membatasi token ke subset cakupan OAuth yang diizinkan. Cakupan yang ditetapkan ke token JWT Anda yang diterbitkan akan diperiksa dengan cakupan Produk API.

    Tentang Aplikasi developer

    Setelah mengonfigurasi Produk API, Anda akan membuat Aplikasi yang terkait dengan Developer. Aplikasi memberikan akses klien ke Produk API terkait dengan Kunci API atau Token JWT.

    Menggunakan autentikasi berbasis JWT

    Anda dapat menggunakan token JWT untuk melakukan panggilan proxy API yang diautentikasi daripada menggunakan kunci API. Ini menjelaskan cara menggunakan perintah apigee-remote-service-cli token untuk membuat, memeriksa, dan merotasi token JWT.

    Ringkasan

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

    Setelah diautentikasi, filter ext-authz Envoy mengirim header permintaan dan JWT ke apigee-remote-service-envoy. Data 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:

    $CLI_HOME/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"

    Menggunakan token JWT

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

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

    Kegagalan token JWT

    Penolakan usulan

    Jika Envoy menolak token, Anda mungkin melihat pesan seperti:

    Jwks remote fetch is failed

    Jika ya, pastikan konfigurasi Envoy Anda berisi URI yang valid di remote_jwks, yang dapat dijangkau oleh Envoy, dan Anda dapat setel sertifikat saat Anda menginstal proxy Apigee. Anda seharusnya sudah dapat untuk 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 di Jwt tidak diizinkan"
    • "Penerbit Jwt tidak dikonfigurasi"

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

    Memeriksa token

    Anda dapat menggunakan CLI untuk memeriksa token Anda. Contoh

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

    atau

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

    Proses Debug

    Lihat Kunci API yang valid gagal.

    Logging

    Anda dapat menyesuaikan level logging pada layanan $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Semua pencatatan log dikirim ke {i>stdout<i} dan {i>stderr<i}.

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

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

    Menggunakan proxy jaringan

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

    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 analisis proxy Envoy data:

    Analisis Istio

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

    Analisis Apigee

    Apigee Remote Service for Envoy mengirimkan statistik permintaan ke Apigee untuk pemrosesan analisis. Apigee melaporkan permintaan ini di bagian nama Produk API terkait.

    Untuk mengetahui informasi tentang analisis Apigee, lihat Ringkasan layanan Analytics.

    Dukungan lingkungan multi-tenant

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

    Untuk mengonfigurasi beberapa dukungan lingkungan, ubah nilai tenant:env_name menjadi * di 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://myorg-myenv.apigee.net/remote-service
            org_name: apigee-docs-hybrid-a
            env_name: *
            allow_unverified_ssl_cert: true
          analytics:
            collection_interval: 10s
          auth:
            jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token
    3. Simpan file.
    4. Terapkan file tersebut:
      kubectl apply -f $CLI_HOME/config.yaml

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

    1. Membuat 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 (nama file ini envoy-config.yaml).
    3. Tambahkan metadata berikut di virtual_host atau Bagian routes dari 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 ditentukan, di mana setiap rute mengirimkan 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.

    Mengonfigurasi mTLS antara adaptor dan runtime Apigee

    Anda dapat memberikan sertifikat TLS sisi klien di bagian tenant pada file config.yaml adaptor untuk menggunakan mTLS antara adaptor dan runtime Apigee. Ini perubahan berlaku untuk semua platform Apigee yang didukung. Layanan ini juga mengaktifkan mTLS untuk analisis untuk platform Apigee Edge untuk 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