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

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

  1. Pilih Publikasikan > Produk API di menu navigasi samping.
  2. Klik +CREATE.
  3. Isi bagian Detail produk sebagai berikut. Hanya kolom wajib diisi 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 agar Anda dapat mengetik nama secara manual dan layanan jarak jauh di kolom Layanan Jarak Jauh.
  7. Di kolom Remote Service, masukkan nama layanan jarak jauh. Ini adalah layanan target tempat adaptor membuat {i>proxy<i} untuk permintaan HTTP yang masuk. Untuk tujuan pengujian, gunakan httpbin.org atau httpbin.default.svc.cluster.local dengan Kubernetes.

    Tombol pilihan Remote Service dipilih, tombol yang mengaktifkan entri teks manual diaktifkan, dan layanan jarak jauh httpbin.org dimasukkan di kolom Remote Service.

  8. Di bagian Operation, masukkan / untuk jalur. Untuk mengetahui 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 {i>adaptor<i}.

  1. Pilih Publikasikan Aplikasi di menu navigasi samping.
  2. Klik + App.
  3. Isi bagian Detail Aplikasi sebagai berikut. Hanya kolom wajib diisi yang disebutkan dalam tabel berikut:
    4. 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, lalu pilih produk yang Anda baru saja dikonfigurasi: httpbin-product.
  5. Klik Create.
  6. Di bagian Credentials, klik Show di samping Key.
  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 daripada menggunakan kunci API. Ini menjelaskan cara menggunakan perintah apigee-remote-service-cli token untuk membuat, memeriksa, dan merotasi token JWT. Untuk lingkungan hybrid Apigee, Anda dapat menggunakan perintah ini untuk membuat secret Kubernetes untuk menyimpan 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:

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 has 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

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 klien dan mengirimkan token JWT berdasarkan jenis pemberian kredensial klien OAuth 2.0. Di beberapa kasus tersebut, Anda mungkin tidak dapat menggunakan proxy remote-token. Jika Anda harus menggunakan penyedia identitas yang bukan 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, lihat artikel ini di Apigee Komunitas: Menggunakan Penyedia Identitas Anda sendiri dengan Adaptor Apigee Envoy.

Logging

Anda dapat menyesuaikan level logging pada layanan $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Semua pencatatan log dikirim ke {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:

Mengubah nama rahasia kebijakan

Rahasia Kubernetes yang di-deploy ke cluster berisi kredensial yang diperlukan adaptor untuk mengotentikasi komunikasi dengan {i>remote service proxy<i}. Rahasia ini memerlukan sebuah direktori pemasangan volume, yang dapat dikonfigurasi. Secara default, titik pemasangannya adalah /policy-secret. Untuk mengubah direktori 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 direktori 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 {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://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 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.

Mengambil data untuk laporan kustom

Adaptor mendukung penerusan metadata Envoy ke fitur pengambilan data Apigee, yang mengirimkan 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. Menentukan variabel pengambilan data menggunakan APIgee datacollectors API.
  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 (nama file ini envoy-config.yaml).
  5. Gunakan filter Envoy untuk menetapkan nilai bagi 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 to 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 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