Konfigurasi ApigConfig - API Gateway - Alibaba Cloud Documentation Center

ApigConfig adalah CRD yang disediakan oleh APIG Controller untuk mengelola siklus hidup instans gateway APIG, mengonfigurasi opsi listener Ingress, serta menentukan pengaturan global seperti kontrol akses IP, pengumpulan log, dan tracing.

Ikhtisar ApigConfig

Konfigurasi

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

Setiap ApigConfig berkorespondensi dengan satu instans gateway APIG. Untuk menggunakan beberapa instans gateway APIG, Anda harus membuat beberapa resource ApigConfig.

Kecuali dalam skenario reuse, menghapus ApigConfig juga akan menghapus instans gateway APIG yang sesuai.

Penting

Untuk instans gateway APIG yang dibuat menggunakan CRD (ApigConfig), kelola konfigurasi bisnis seperti API, entri rute, dan sertifikat di dalam CRD tersebut. Anda dapat menggunakan Konsol APIG untuk operasi seperti scaling. Jangan mengubah konfigurasi bisnis instans yang dibuat melalui CRD di Konsol, karena sinkronisasi CRD dapat menimpa perubahan Anda dan menyebabkan konflik konfigurasi.

Berikut ini contoh 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" # Biarkan kosong untuk menggunakan proyek default.
    tracing:
      openTelemetry:
        sampleRate: "100"
  ingress:
    local:
      ingressClass:  apig
      watchNamespace: "" # String kosong ("") menunjukkan resource Ingress di semua namespace.

Parameter	Deskripsi	Default
`name`	Nama gateway.	apig-ingress
`common.pay.payType`	Metode penagihan. Hanya bayar sesuai penggunaan yang didukung dan menjadi nilai default jika tidak ditentukan.	POSTPAY
`common.instance.spec`	Tipe instans gateway. Nilai 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 primary dan standby, dalam urutan tersebut. Tentukan satu atau dua vSwitch. Jika tidak ditentukan, vSwitch diwariskan dari node tempat pod APIG Controller berjalan.	Tidak ada
`common.network.networkType`	Aksesibilitas jaringan gateway. Nilai valid: Internet Intranet	Internet
`common.securityGroupType`	Jenis grup keamanan. Nilai valid: enterprise: advanced security group normal: basic security group	normal
`global.tls.enableHardwareAcceleration`	Menentukan apakah akan mengaktifkan akselerasi perangkat keras TLS. Fitur ini dapat meningkatkan performa traffic HTTPS secara signifikan.	Diaktifkan
`global.ipAccessControl.whitelist`	Daftar putih IP global.	Tidak dikonfigurasi
`global.ipAccessControl.blacklist`	Daftar hitam IP global.	Tidak dikonfigurasi
`monitor.logging.sls`	Menentukan apakah akan mengaktifkan pengumpulan log Simple Log Service (SLS). Untuk mengaktifkan fitur ini, berikan izin SLS yang diperlukan kepada APIG Controller.	Nonaktif
`monitor.logging.sls.reuseProject`	Proyek SLS untuk menyimpan log akses. Nilai valid: Kosong: Proyek default dibuat dan digunakan. Nilai tertentu: Proyek yang sudah ada digunakan.	Kosong
`monitor.tracing.xTrace.sampleRate`	Laju sampel untuk Tracing Analysis (x-trace).	0
`monitor.tracing.openTelemetry`	Mengaktifkan atau menonaktifkan tracing OpenTelemetry.	Nonaktif secara default. Saling eksklusif dengan opsi tracing `xTrace`.
`monitor.tracing.openTelemetry.sampleRate`	Laju sampel untuk tracing OpenTelemetry.	100
`ingress.local.ingressClass`	Menentukan resource Ingress mana yang diproses oleh instans gateway APIG, berdasarkan IngressClass-nya. Nilai valid: Tidak dikonfigurasi: Gateway tidak memproses resource Ingress apa pun. Diatur ke `apig`: Gateway memproses resource Ingress dengan IngressClass `apig`. String kosong (`""`): Mendengarkan semua resource Ingress. Diatur ke `nginx`: Mendengarkan resource Ingress yang memiliki IngressClass nginx atau tidak terkait dengan IngressClass apa pun. Diatur ke nilai lain: Gateway memproses resource Ingress dengan IngressClass yang cocok dengan nilai yang ditentukan. Catatan Pengaturan ini memiliki prioritas lebih rendah daripada asosiasi ApigConfig melalui IngressClass.	Tidak dikonfigurasi
`ingress.local.watchNamespace`	Namespace tempat gateway memantau resource Ingress. Nilai valid: String kosong: Memantau semua namespace. Nilai tertentu: Memantau namespace yang ditentukan. Hanya satu namespace yang dapat ditentukan.	Kosong

Status

Setelah membuat resource ApigConfig, jalankan perintah kubectl get ApigConfig untuk memeriksa statusnya. Resource tersebut melewati status berikut: Pending > Running > Listening.

Pending: Instans gateway APIG sedang dibuat. Proses ini memakan waktu sekitar 3 menit.
Running: Instans gateway APIG telah dibuat dan berjalan.
Listening: Instans gateway APIG berjalan dan mendengarkan resource Ingress di kluster.
Failed: Instans gateway APIG berada dalam status tidak valid. Periksa Message di bidang Status untuk mengetahui penyebabnya.

Tag

Instans gateway APIG yang dibuat atau digunakan kembali melalui ApigConfig diberi tag sumber daya. Anda dapat melihat informasi tag di bagian Informasi Dasar pada Konsol APIG.

Penting

Jangan mengedit tag ini di Konsol APIG, karena tindakan tersebut dapat mengganggu instans gateway Anda.

Tag	Deskripsi
ack.aliyun.com	Menunjukkan bahwa gateway APIG mengelola traffic ingress kluster Container Service for Kubernetes (ACK).
ingress.k8s.alibaba/ApigConfig	Mengasosiasikan instans gateway APIG dengan ApigConfig.
kubernetes.reused.by.user	Menunjukkan apakah instans gateway APIG digunakan kembali. Instans yang digunakan kembali tidak dihapus saat ApigConfig terkait dihapus.

Buat instans gateway APIG

Konfigurasi ApigConfig.
Contoh berikut membuat instans gateway APIG bernama apig-ingress dengan tipe instans apigw.small.x1. Ubah pengaturan ApigConfig lain sesuai kebutuhan.
```
apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
  name: apig-ingress
spec:
  name: apig-ingress
  common:
    instance:
      spec: apigw.small.x1
```
Di kluster Container Service for Kubernetes (ACK) Anda, buat IngressClass dan asosiasikan dengan ApigConfig menggunakan spec.parameters. Ini mendeklarasikan prosesor Ingress di kluster.
Setelah dikonfigurasi, instans gateway APIG yang terhubung akan memproses setiap Ingress yang terkait dengan IngressClass ini.
```
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 gateway APIG yang ada

Untuk menggunakan kembali instans gateway APIG yang sudah ada, tentukan ID-nya (misalnya, gw-xxx) di bidang spec.id ApigConfig Anda. Gunakan spec.override untuk mengontrol apakah pengaturan ApigConfig akan menimpa konfigurasi instans yang sudah ada.

Contoh berikut menggunakan kembali instans gateway APIG yang sudah ada. ApigConfig mengasosiasikan instans tersebut dengan kluster dan mengonfigurasinya untuk memproses resource Ingress dengan IngressClass apig.

Penting

Dalam konfigurasi berikut, spec.override diatur ke false, artinya opsi listener Ingress dan konfigurasi global gateway APIG yang sudah ada tidak ditimpa. Jika instans gateway yang sudah ada belum diasosiasikan dengan kluster kontainer, instans tersebut secara otomatis diasosiasikan dengan kluster dan opsi listener Ingress-nya dikonfigurasi untuk mendengarkan resource Ingress di kluster kontainer tempat ingressClass bernilai spec.ingress.local.ingressClass (dalam hal ini, apig). Jika instans gateway sudah diasosiasikan dengan kluster kontainer, opsi listener Ingress yang sudah ada tidak ditimpa.
Untuk menimpa opsi listener Ingress dan konfigurasi global gateway APIG yang sudah ada, pastikan parameter gateway dalam ApigConfig (opsi listener Ingress, akselerasi perangkat keras, daftar hitam dan putih alamat IP global, serta observabilitas) dikonfigurasi dengan benar sebelum mengaktifkan spec.override. Jika konfigurasi ini tidak ditentukan dalam ApigConfig, mengaktifkan spec.override akan menimpa parameter gateway asli (opsi listener Ingress, akselerasi perangkat keras, daftar hitam dan putih alamat IP global, serta observabilitas), yang dapat memengaruhi traffic.

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 gateway APIG target yang akan digunakan kembali. ID harus diawali dengan gw-.

spec.override

Menentukan apakah akan menimpa konfigurasi instans gateway APIG yang digunakan kembali berdasarkan pengaturan ApigConfig.

Diatur ke true: Menimpa konfigurasi gateway yang ada (opsi listener Ingress, akselerasi perangkat keras, daftar izin dan blokir global, serta observabilitas).
Jika parameter ini diatur ke false, konfigurasi gateway yang ada (seperti opsi listener Ingress, akselerasi perangkat keras, daftar izin dan blokir global, serta observabilitas) tidak ditimpa. Namun, jika instans gateway yang sudah ada belum diasosiasikan dengan kluster kontainer, instans tersebut secara otomatis diasosiasikan dengan kluster kontainer dan opsi listener Ingress-nya dikonfigurasi untuk mendengarkan resource Ingress di kluster kontainer yang ingressClass-nya diatur ke nilai spec.ingress.local.ingressClass.

Hapus instans gateway APIG

Menghapus ApigConfig juga akan menghapus instans gateway APIG yang sesuai, kecuali untuk instans yang digunakan kembali.

Tabel berikut menjelaskan kebijakan penghapusan.

Metode penagihan	Dibuat oleh APIG Controller	Gateway konsol yang digunakan kembali
pay-as-you-go	Menghapus ApigConfig secara otomatis menghapus instans gateway.	Menghapus ApigConfig tetap menyimpan instans gateway.

Untuk menghapus ApigConfig, jalankan perintah berikut:

kubectl delete ApigConfig your-config-name

Konfigurasi kontrol akses IP global

Konfigurasi daftar putih IP

Konfigurasi daftar putih IP global untuk hanya mengizinkan akses ke APIG Ingress Anda dari IP sumber tertentu.

Contoh berikut hanya mengizinkan akses dari IP sumber 1.1.XX.XX dan 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

Konfigurasi daftar hitam IP tingkat instans global untuk menolak akses dari IP sumber tertentu.

Contoh berikut menolak permintaan dari IP sumber 1.1.XX.XX dan 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 logging SLS

Sebelum mengaktifkan pengumpulan log, pastikan APIG Controller memiliki izin SLS yang diperlukan.

Untuk kluster ACK yang dikelola, lihat Berikan izin kepada APIG Controller.

Contoh berikut mengonfigurasi gateway untuk mengirimkan log akses ke proyek SLS bernama demo.

apiVersion: apig.alibabacloud.com/v1alpha1
kind: ApigConfig
metadata:
   name: apig-ingress
spec:
   ...
  monitor:
    logging:
      sls:
        # Konfigurasi reuseProject untuk mengaktifkan Simple Log Service. Jika ingin menggunakan proyek default, biarkan bidang ini kosong.
        reuseProject: "demo"
    ...

Aktifkan tracing OpenTelemetry

Konfigurasi tracing OpenTelemetry untuk gateway guna membangun sistem tracing end-to-end untuk mendiagnosis masalah produksi.

Contoh berikut mengonfigurasi tracing OpenTelemetry 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 gateway APIG Ingress mendukung konfigurasi tambahan berikut:

Untuk menerapkan pengaturan ini, buka Konsol Cloud-native API Gateway. Di halaman APIG Gateway > Gateway List, pilih instans gateway, lalu klik Parameter Settings di panel navigasi sebelah kiri.

Parameter	Type	Deskripsi
`EnableGenerateRequestId`	Bool	Jika diaktifkan, ID permintaan dihasilkan di header permintaan untuk keperluan tracing.
`EnableGzip`	Bool	Mengaktifkan kompresi Gzip untuk permintaan dan respons, mengurangi traffic gateway tetapi meningkatkan konsumsi CPU.
`EnableSlashMerge`	Bool	Jika diaktifkan, menggabungkan karakter `'/'` yang redundan di path permintaan. Misalnya, `www.a.com//b` menjadi `www.a.com/b`.
`DownstreamConnectionBufferLimits`	Int	Ukuran buffer koneksi tunggal, yang memengaruhi throughput dan penggunaan memori gateway. Rentang valid: [0, 2147483647].
`XffTrustedNum`	Int	Jumlah proxy tepercaya di depan gateway. Ini memengaruhi apakah gateway menggunakan header permintaan yang ditambahkan oleh proxy, seperti `x-forwarded-for` dan `x-request-id`. Rentang nilai: [0, 10]. Satuan: item.
`DownstreamHttp2MaxConcurrentStream`	Int	Jumlah maksimum stream konkuren pada koneksi tunggal ketika klien menggunakan HTTP/2. Rentang nilai: [0, 2147483647]. Satuan: byte.
`InitialStreamWindowSize`	Int	Ukuran jendela awal `stream` HTTP/2 yang dinegosiasikan antara gateway dan klien. Rentang nilai: [65535, 2147483647]. Satuan: byte.
`InitialConnectionWindowSize`	Int	Ukuran jendela awal tingkat koneksi HTTP/2 yang dinegosiasikan antara gateway dan klien. Rentang nilai: [65535, 2147483647]. Satuan: byte.
`EnableHttp3`	Bool	Menentukan apakah akan mendukung protokol HTTP/3. HTTP/3 tidak kompatibel dengan akselerasi perangkat keras TLS. Anda harus menonaktifkan akselerasi perangkat keras sebelum mengaktifkan HTTP/3.
`PathWithEscapedSlashes`	String	Menentukan aksi untuk permintaan yang path URI-nya mengandung karakter ter-escape seperti %2F, %2f, %5C, atau %5c. Nilai default adalah `KEEP_UNCHANGED`, yang mempertahankan karakter tersebut. Nilai valid: `KEEP_UNCHANGED`, `REJECT_REQUEST`, `UNESCAPE_AND_REDIRECT`, dan `UNESCAPE_AND_FORWARD`.
`ZipAlgorithm`	List<String>	Algoritma kompresi yang digunakan setelah kompresi diaktifkan. Jika opsi `EnableGzip` tidak diaktifkan saat parameter ini diatur, opsi tersebut akan diaktifkan secara otomatis. Nilai valid: `brotli`, `gzip`.
`EnableProxyProtocol`	Bool	Menentukan apakah akan mengaktifkan protokol PROXY. Saat traffic ingress dirutekan melalui Network Load Balancer (NLB), aktifkan opsi ini untuk mengambil alamat IP klien asli. Mengaktifkannya tidak memengaruhi permintaan non-PROXY protocol.
`EnableCustomAuthConfigPush`	Bool	Untuk layanan otorisasi yang dikelola sendiri. Jika diaktifkan, perubahan aturan otorisasi tidak mengganggu koneksi aktif, yang cocok untuk skenario WebSocket dan real-time lainnya.
`KeepaliveHeaderTimeout`	Int	Mengatur nilai header respons `Keep-Alive` yang dikembalikan ke klien. Misalnya, jika diatur ke 10, respons mencakup `keep-alive: timeout=10`. Jika diatur ke 0, header ini tidak dikembalikan. Rentang nilai: [0, 600]. Satuan: detik.
`WebsocketTermGracePeriod`	Int	Periode tenggang untuk koneksi WebSocket aktif saat gateway menutup koneksi, misalnya selama peningkatan atau restart. Rentang nilai: [20, 900]. Satuan: detik.
EnableGzipHardwareAccelerate	Bool	Mengaktifkan kompresi Gzip berakselerasi perangkat keras. Dibandingkan dengan Gzip perangkat lunak, ini memberikan performa lebih tinggi dengan konsumsi CPU lebih rendah. Opsi ini tidak tersedia di wilayah yang tidak didukung atau jika akselerasi perangkat keras Gzip tidak ditentukan saat pembelian. Saat diaktifkan, pengaturan `EnableGzip` dan `ZipAlgorithm` tidak berlaku.
EnableK8sSourceWorkloadFilter	Bool	Memfilter resource Ingress, Service, dan Pod berdasarkan label tertentu saat Anda menambahkan sumber layanan. Pemfilteran invers juga didukung.

FAQ

Apa yang harus saya lakukan jika titik akhir tetap kosong setelah saya menghapus dan membuat ulang APIG Ingress?

Jika Anda menghapus Ingress dan membuatnya kembali menggunakan file YAML yang sama, tetapi titik akhir tetap kosong setelah menunggu beberapa saat, biasanya opsi listener Ingress tidak dikonfigurasi di ApigConfig. Akibatnya, instans gateway APIG tidak memantau resource Ingress tersebut. Pecahkan masalah ini sebagai berikut:

Periksa apakah spec.ingress.local.ingressClass dikonfigurasi di ApigConfig. Jika bidang ini tidak dikonfigurasi, instans gateway APIG tidak memantau resource Ingress apa pun, dan titik akhir tidak dipulihkan setelah Anda membuat ulang Ingress. Atur bidang ini ke apig.
Pastikan IngressClass dari Ingress sesuai dengan nilai ingress.local.ingressClass di ApigConfig. Anda dapat menentukan IngressClass Ingress menggunakan anotasi kubernetes.io/ingress.class: apig atau bidang spec.ingressClassName.
Jalankan perintah kubectl get apigconfig untuk memeriksa apakah status ApigConfig adalah Listening.
Buat ulang Ingress setelah konfigurasi di atas benar. Titik akhir kemudian akan dipulihkan secara otomatis. Anda tidak perlu membuat ulang instans gateway APIG.