Konfigurasi ApigConfig - API Gateway

ApigConfig adalah Custom Resource Definition (CRD) yang disediakan oleh APIG Controller. Anda dapat menggunakannya untuk mengelola siklus hidup instans Gerbang APIG, mengonfigurasi opsi listener Ingress, menetapkan konfigurasi global, serta menerapkan kontrol akses IP global tingkat instans melalui daftar hitam dan daftar putih, pengumpulan log, dan Analisis Tracing.

Deskripsi ApigConfig

Deskripsi konfigurasi

ApigConfig adalah CRD yang digunakan oleh APIG Controller untuk mengelola siklus hidup dan konfigurasi global instans Gerbang APIG.

Satu ApigConfig berkorespondensi dengan satu instans Gerbang APIG. Untuk menggunakan beberapa instans Gerbang APIG, Anda harus membuat beberapa ApigConfig.

Kecuali dalam skenario reuse, penghapusan ApigConfig akan menghapus secara cascade instans Gerbang APIG yang terkait.

Kode contoh berikut menunjukkan konfigurasi ApigConfig lengkap.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    pay:
      payType: POSTPAY
    instance:
      spec: apigw.small.x1
    network:
      vSwitches:
      - "vsw-1"
      - "vsw-2"
      networkType: Internet
    securityGroupType: enterprise
  global:
    tls:
      enableHardwareAcceleration: true
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.2.XX.XX
  monitor:
    logging:
      sls:
        reuseProject: "xxx" # Nilai kosong menunjukkan bahwa proyek default digunakan.
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  apig
      watchNamespace: "" # "" menunjukkan resource Ingress di semua namespace.

Parameter	Deskripsi	Nilai default
`name`	Nama gerbang.	apig-ingress
`common.pay.payType`	Metode penagihan. Saat ini, hanya bayar sesuai penggunaan yang didukung. Jika Anda tidak mengonfigurasi parameter ini, metode bayar sesuai penggunaan digunakan secara default.	POSTPAY
`common.instance.spec`	Tipe instans gerbang. Nilai yang valid: apigw.small.x1 apigw.small.x2 apigw.small.x4 apigw.medium.x1 apigw.medium.x2 apigw.medium.x3 apigw.large.x1 apigw.large.x2 apigw.large.x3	apigw.small.x1
`common.network.vSwitches`	vSwitch primer dan sekunder. vSwitch primer dicantumkan terlebih dahulu, diikuti oleh vSwitch sekunder. Tentukan minimal satu dan maksimal dua vSwitch. Jika Anda membiarkannya kosong, vSwitch akan diambil dari node tempat pod Controller berjalan.	None
`common.network.networkType`	Tipe instans SLB publik yang dibeli untuk gerbang. Nilai yang valid: Internet Intranet	Internet
`common.securityGroupType`	Tipe grup keamanan. Nilai yang valid: enterprise: advanced security group normal: basic security group	normal
`global.tls.enableHardwareAcceleration`	Mengaktifkan atau menonaktifkan akselerasi perangkat keras TLS. Mengaktifkan fitur ini dapat meningkatkan performa trafik HTTPS secara signifikan.	Enabled
`global.ipAccessControl.whitelist`	Daftar putih IP global untuk kontrol akses.	Not configured
`global.ipAccessControl.blacklist`	Daftar hitam IP global untuk kontrol akses.	Not configured
`monitor.logging.sls`	Mengaktifkan atau menonaktifkan Simple Log Service (SLS). Untuk mengaktifkan fitur ini, berikan izin SLS yang diperlukan kepada Controller.	shutdown
`monitor.logging.sls.reuseProject`	Proyek tujuan di SLS tempat log akses dikirimkan. Nilai yang valid: Kosong: Proyek default dibuat dan digunakan. Nilai tertentu: Proyek yang sudah ada digunakan.	Kosong
`monitor.tracing.xTrace.sampleRate`	Laju sampel untuk Analisis Tracing OpenTelemetry	0
`monitor.tracing.openTelemetry`	Mengaktifkan atau menonaktifkan Analisis Tracing OpenTelemetry.	Opsi ini dinonaktifkan secara default dan saling eksklusif dengan OpenTelemetry.
`monitor.tracing.openTelemetry.sampleRate`	Laju sampel untuk Analisis Tracing OpenTelemetry.	100
`ingress.local.ingressClass`	Resource Ingress di bawah IngressClass tertentu dalam kluster yang didengarkan oleh gerbang APIG. Nilai yang valid: Tidak dikonfigurasi: Tidak mendengarkan resource Ingress apa pun. Diatur ke `apig`: Mendengarkan resource Ingress yang IngressClass-nya adalah apig. Diatur ke string kosong `""`: Mendengarkan semua resource Ingress. Diatur ke `nginx`: Mendengarkan resource Ingress yang IngressClass-nya adalah nginx atau yang tidak terkait dengan IngressClass apa pun. Diatur ke nilai lain: Mendengarkan resource Ingress yang IngressClass-nya adalah nilai yang ditentukan. Catatan Konfigurasi ini memiliki prioritas lebih rendah daripada mengasosiasikan ApigConfig melalui resource IngressClass.	Not configured
`ingress.local.watchNamespace`	Namespace dalam kluster yang resource Ingress-nya didengarkan oleh gerbang APIG. Nilai yang valid: Kosong: Mendengarkan semua namespace. Nilai tertentu: Mendengarkan namespace yang ditentukan. Hanya satu namespace yang didukung.	Kosong

Deskripsi status

Setelah membuat resource ApigConfig, Anda dapat menjalankan perintah kubectl get ApigConfig untuk memeriksa statusnya. Status ApigConfig berubah secara berurutan sebagai berikut: Pending > Running > Listening. Penjelasan masing-masing status adalah sebagai berikut:

Pending: Gerbang APIG sedang dalam proses pembuatan. Proses ini memerlukan waktu sekitar 3 menit.
Running: Gerbang APIG telah berhasil dibuat dan sedang berjalan.
Listening: Gerbang APIG berjalan dan mendengarkan resource Ingress dalam kluster.
Failed: Gerbang APIG berada dalam status tidak valid. Untuk informasi lebih lanjut, lihat pesan pada bidang Status.

Deskripsi tag

Instans Gerbang APIG yang dibuat atau digunakan kembali melalui ApigConfig diberi tag sumber daya. Anda dapat melihat tag tersebut di bagian informasi dasar pada Konsol APIG.

Penting

Jangan mengedit tag dalam tabel berikut dari konsol Gerbang APIG karena tindakan ini dapat memengaruhi instans gerbang Anda.

Nama tag	Deskripsi
ack.aliyun.com	Mengelola lalu lintas masuk kluster layanan kontainer untuk gerbang APIG.
ingress.k8s.alibaba/ApigConfig	Mengasosiasikan gerbang APIG dengan ApigConfig.
kubernetes.reused.by.user	Menunjukkan apakah gerbang APIG digunakan kembali. Jika dalam skenario reuse, instans gerbang APIG tidak dihapus saat ApigConfig terkait dihapus.

Buat instans gerbang APIG

Konfigurasikan ApigConfig.
Kode contoh berikut membuat instans Gerbang APIG bernama apig-ingress dengan tipe instans `apigw.small.x1`. Anda dapat menyesuaikan pengaturan ApigConfig lainnya sesuai kebutuhan.
```
apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1
```
Buat resource IngressClass di kluster layanan kontainer dan asosiasikan dengan ApigConfig melalui spec.parameters untuk mendeklarasikan prosesor Ingress dalam kluster.
Setelah konfigurasi selesai, resource Ingress dalam kluster yang terkait dengan IngressClass ini akan diproses oleh instans Gerbang APIG yang terkait dengan ApigConfig.
```
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: apig
spec:
  controller: apig.alibabacloud.com/ingress
  parameters:
    apiGroup: apig.alibabacloud.com
    kind: ApigConfig
    name: apig-ingress
```

Gunakan kembali instans gerbang APIG yang ada

Untuk menggunakan kembali instans Gerbang APIG yang sudah ada, tentukan ID unik instans Gerbang APIG (dalam format gw-xxx) di spec.id saat membuat ApigConfig. Gunakan parameter spec.override untuk mengontrol apakah konfigurasi instans Gerbang APIG yang digunakan kembali akan ditimpa dengan pengaturan dari ApigConfig.

Kode contoh berikut menggunakan kembali instans Gerbang APIG yang sudah ada melalui ApigConfig. Instans gerbang diasosiasikan dengan kluster kontainer dan dikonfigurasi untuk mendengarkan resource Ingress dalam kluster yang memiliki ingressClass apig.

Penting

Dalam konfigurasi berikut, spec.override diatur ke false. Pengaturan ini mencegah opsi listener Ingress dan konfigurasi global Gerbang APIG yang sudah ada ditimpa. Jika instans gerbang belum diasosiasikan dengan kluster kontainer, instans tersebut akan secara otomatis diasosiasikan. Listener Ingress kemudian dikonfigurasi untuk mendengarkan resource Ingress dalam kluster yang ingressClass-nya cocok dengan nilai spec.ingress.local.ingressClass, yaitu apig dalam contoh ini. Jika instans gerbang sudah diasosiasikan dengan kluster kontainer, opsi listener Ingress aslinya tetap dipertahankan.
Untuk menimpa opsi listener Ingress dan konfigurasi global Gerbang APIG yang sudah ada, pastikan terlebih dahulu bahwa semua parameter gerbang yang diperlukan—seperti opsi listener Ingress, akselerasi perangkat keras, daftar hitam dan daftar putih global, serta observabilitas—telah dikonfigurasi dengan benar dalam ApigConfig Anda. Kemudian, atur spec.override ke `true`. Jika Anda mengatur spec.override ke `true` tanpa menentukan konfigurasi tersebut dalam ApigConfig, parameter gerbang asli akan ditimpa, yang dapat berdampak negatif terhadap lalu lintas.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: reuse
spec:
  id: gw-xxxx
  override: false
  ingress:
    local:
      ingressClass: apig

Parameter

Deskripsi

spec.id

ID instans gerbang APIG target yang akan digunakan kembali. Formatnya adalah `gw-xxx`.

spec.override

Menentukan apakah konfigurasi instans gerbang APIG yang digunakan kembali akan ditimpa berdasarkan ApigConfig.

Diatur ke true: Menimpa konfigurasi parameter gerbang asli (opsi listener Ingress, akselerasi perangkat keras, daftar hitam dan daftar putih global, serta observabilitas).
Diatur ke false: Tidak menimpa konfigurasi parameter gerbang asli (opsi listener Ingress, akselerasi perangkat keras, daftar hitam dan daftar putih global, serta observabilitas). Namun, jika instans gerbang yang ada belum diasosiasikan dengan kluster kontainer, instans tersebut akan secara otomatis diasosiasikan. Opsi listener Ingress akan diatur untuk mendengarkan resource Ingress dalam kluster yang ingressClass-nya cocok dengan nilai spec.ingress.local.ingressClass.

Hapus instans gerbang APIG

Satu ApigConfig berkorespondensi dengan satu instans Gerbang APIG. Kecuali dalam skenario reuse, penghapusan ApigConfig akan menghapus secara cascade instans Gerbang APIG yang terkait.

Kebijakan penghapusan ditunjukkan dalam tabel berikut.

Metode penagihan gerbang	Pembuatan otomatis oleh APIG Controller	Reuse gerbang yang dibeli di konsol
Pay-as-you-go	Hapus ApigConfig untuk menghapus instans gerbang secara otomatis.	Hapus ApigConfig, tetapi instans gerbang tetap dipertahankan.

Jalankan perintah berikut untuk menghapus ApigConfig.

kubectl delete ApigConfig your-config-name

Konfigurasi kontrol akses IP global tingkat instans

Konfigurasi daftar putih IP

Anda dapat mengonfigurasi daftar putih IP global tingkat instans untuk hanya mengizinkan IP sumber tertentu mengakses APIG Ingress.

Kode contoh berikut mengonfigurasi instans Gerbang APIG Ingress agar hanya mengizinkan akses dari alamat IP sumber 1.1.XX.XX atau blok CIDR 2.0.XX.XX/8.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      whitelist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

Konfigurasi daftar hitam IP

Anda dapat mengonfigurasi daftar hitam IP global tingkat instans untuk menolak akses dari IP sumber tertentu ke APIG Ingress.

Kode contoh berikut mengonfigurasi instans Gerbang APIG Ingress agar menolak akses dari alamat IP sumber 1.1.XX.XX atau blok CIDR 2.0.XX.XX/8.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  global:
    ipAccessControl:
      blacklist:
      - 1.1.XX.XX
      - 2.0.XX.XX/8
   ...

Aktifkan log SLS

Sebelum mengaktifkan log SLS, pastikan Anda telah memberikan izin SLS yang diperlukan kepada APIG Controller.

Kode contoh berikut mengonfigurasi Gerbang APIG Ingress untuk mengirimkan log akses ke proyek bernama demo.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # Konfigurasikan reuseProject untuk mengaktifkan SLS. Untuk menggunakan proyek default, biarkan kosong.
        reuseProject: "demo"
    ...

Aktifkan Analisis Tracing OpenTelemetry

Setelah mengonfigurasi Analisis Tracing OpenTelemetry Alibaba Cloud untuk gerbang, Anda dapat membangun sistem tracing dan pemantauan end-to-end guna mendiagnosis serta mengidentifikasi masalah online secara cepat.

Kode contoh berikut mengonfigurasi Analisis Tracing OpenTelemetry untuk Gerbang APIG Ingress dengan laju sampel (sampleRate) 100%.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    tracing:
      openTelemetry:
        sampleRate: "100"
   ...

Konfigurasi tambahan

Instans gerbang yang digunakan oleh APIG Ingress mendukung konfigurasi tambahan.

Untuk menerapkan konfigurasi ini, login ke Konsol Cloud-native API Gateway. Di menu APIG Gateway > Gateway List, temukan instans gerbang yang digunakan atau dibuat otomatis oleh APIG Controller. Klik ID instans, lalu klik Parameter Settings di panel navigasi sebelah kiri.

Item konfigurasi	Tipe	Deskripsi
`EnableGenerateRequestId`	Bool	Berlaku untuk cakupan permintaan. Menghasilkan ID permintaan di header permintaan untuk pelacakan permintaan.
`EnableGzip`	Bool	Berlaku untuk tahap permintaan dan respons. Mengaktifkan gzip akan mengompresi permintaan dan respons. Ini mengurangi trafik gerbang tetapi meningkatkan konsumsi CPU gerbang.
`EnableSlashMerge`	Bool	Menentukan apakah akan menggabungkan karakter `'/'` yang redundan dalam permintaan. Jika Anda mengaktifkan fitur ini, karakter `'/'` yang redundan dalam `www.a.com//b` akan digabung, sehingga URL menjadi sama dengan `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	Berlaku untuk koneksi gerbang. Ukuran buffer untuk satu koneksi. Pengaturan ini memengaruhi throughput dan penggunaan memori gerbang. Rentang nilai: [0, 2147483647].
`XffTrustedNum`	Int	Berlaku untuk tahap permintaan. Jumlah proxy tepercaya di depan gerbang. Ini memengaruhi apakah gerbang menggunakan header permintaan yang dihasilkan klien seperti `x-forwarded-for` dan `x-request-id`. Rentang nilai: [0, 10]. Satuan: proxy.
`DownstreamHttp2MaxConcurrentStream`	Int	Berlaku untuk tahap permintaan. Jumlah maksimum stream konkuren pada satu koneksi ketika klien menggunakan HTTP/2. Rentang nilai: [0, 2147483647]. Satuan: byte.
`InitialStreamWindowSize`	Int	Berlaku untuk tahap permintaan. Ukuran jendela `stream` awal yang dinegosiasikan antara gerbang dan klien saat menggunakan HTTP/2. Rentang nilai: [65535, 2147483647]. Satuan: byte.
`InitialConnectionWindowSize`	Int	Berlaku untuk tahap permintaan. Ukuran jendela awal tingkat koneksi saat gerbang dan klien menggunakan HTTP/2. Rentang nilai: [65535, 2147483647]. Satuan: byte.
`EnableHttp3`	Bool	Menentukan apakah akan mendukung protokol HTTP/3. HTTP/3 tidak kompatibel dengan fitur akselerasi perangkat keras. Nonaktifkan akselerasi perangkat keras sebelum mengaktifkan dukungan HTTP/3.
`PathWithEscapedSlashes`	String	Menentukan tindakan untuk permintaan yang path URI-nya mengandung karakter escape seperti %2F, %2f, %5C, atau %5c. Nilai default adalah `KEEP_UNCHANGED`, yang berarti karakter tersebut tetap dipertahankan. Nilai yang valid: `KEEP_UNCHANGED`, `REJECT_REQUEST`, `UNESCAPE_AND_REDIRECT`, `UNESCAPE_AND_FORWARD`.
`ZipAlgorithm`	List<String>	Algoritma kompresi yang digunakan setelah kompresi diaktifkan. Jika `EnableGzip` dinonaktifkan, opsi `EnableGzip` akan diaktifkan secara otomatis. Nilai yang valid: `brotli`, `gzip`.
`EnableProxyProtocol`	Bool	Menentukan apakah akan mengaktifkan protokol PROXY. Jika lalu lintas masuk gerbang diakses melalui NLB, Anda harus mengaktifkan ini untuk mendapatkan alamat IP asal klien. Mengaktifkan ini tidak memengaruhi permintaan non-PROXY protocol.
`EnableCustomAuthConfigPush`	Bool	Berlaku untuk skenario di mana layanan otorisasi self-built digunakan. Saat diaktifkan, perubahan aturan otorisasi tidak menyebabkan gangguan koneksi. Ini cocok untuk skenario WebSocket dan bisnis online.
`KeepaliveHeaderTimeout`	Int	Menghasilkan header respons Keep-Alive untuk memberi tahu klien tentang waktu keepalive koneksi. Misalnya, jika diatur ke 10, header respons `keep-alive: timeout=10` dikembalikan. Jika diatur ke 0, header respons ini tidak dikembalikan. Rentang nilai: [0, 600]. Satuan: s.
`WebsocketTermGracePeriod`	Int	Waktu keepalive yang dipertahankan untuk koneksi WebSocket saat instans gerbang perlu menutup koneksi, misalnya selama peningkatan atau restart. Rentang nilai: [20, 900]. Satuan: s.
EnableGzipHardwareAccelerate	Bool	Menjalankan kompresi Gzip berdasarkan perangkat keras khusus. Saat diaktifkan, kompresi permintaan dan respons dilakukan, secara signifikan mengurangi trafik gerbang. Fitur ini menawarkan performa lebih tinggi dan konsumsi CPU lebih rendah dibandingkan Gzip berbasis perangkat lunak. Fitur ini tidak dapat diaktifkan di wilayah yang tidak didukung atau jika akselerasi perangkat keras Gzip tidak ditentukan saat pembelian. Setelah diaktifkan, `EnableGzip` dan `ZipAlgorithm` tidak akan berlaku.
EnableK8sSourceWorkloadFilter	Bool	Memfilter resource Ingress, Service, dan pod berdasarkan tag tertentu saat menambahkan sumber layanan. Filter invers didukung.