NGINX tabanlı Wallarm Ingress Controller'ın İnce Ayarı¶

Wallarm çözümünden en iyi şekilde yararlanmak için self-hosted Wallarm Ingress controller için mevcut ince ayar seçeneklerini öğrenin.

Helm Chart için Ek Ayarlar¶

Ayarlar values.yaml dosyasında tanımlıdır. Varsayılan olarak, dosya aşağıdaki gibidir:

controller:
  wallarm:
    enabled: false
    apiHost: api.wallarm.com
    apiPort: 443
    apiSSL: true
    token: ""
    nodeGroup: defaultIngressGroup
    existingSecret:
      enabled: false
      secretKey: token
      secretName: wallarm-api-token
    postanalytics:
      kind: Deployment
      service:
        annotations: {}
      arena: "2.0"
      serviceAddress: "[::]:3313"
      livenessProbe:
        failureThreshold: 3
        initialDelaySeconds: 10
        periodSeconds: 10
        successThreshold: 1
        timeoutSeconds: 1
      tls:
        enabled: false
      #  certFile: "/root/test-tls-certs/server.crt"
      #  keyFile: "/root/test-tls-certs/server.key"
      #  caCertFile: "/root/test-tls-certs/ca.crt"
      #  mutualTLS:
      #    enabled: false
      #    clientCACertFile: "/root/test-tls-certs/ca.crt"
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wallarm-appstructure:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wallarm-antibot:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    metrics:
      port: 18080
      enabled: false

      service:
        annotations:
          prometheus.io/scrape: "true"
          prometheus.io/path: /wallarm-metrics
          prometheus.io/port: "18080"

        ## stats-exporter servisinin erişilebilir olduğu IP adresleri listesi
        ## Bkz: https://kubernetes.io/docs/user-guide/services/#external-ips
        ##
        externalIPs: []

        loadBalancerIP: ""
        loadBalancerSourceRanges: []
        servicePort: 18080
        type: ClusterIP
    init:
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wcliController:
      logLevel: warn
      commands:
        apispec:
          logLevel: INFO
        blkexp:
          logLevel: INFO
        botexp:
          logLevel: WARN
        cntexp:
          logLevel: ERROR
        cntsync:
          logLevel: INFO
        credstuff:
          logLevel: INFO
        envexp:
          logLevel: INFO
        ipfeed:
          logLevel: INFO
        iplist:
          logLevel: INFO
        jwtexp:
          logLevel: INFO
        metricsexp:
          logLevel: INFO
        mrksync:
          logLevel: INFO
        register:
          logLevel: INFO
        reqexp:
          logLevel: INFO
        syncnode:
          logLevel: INFO
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    wcliPostanalytics:
      logLevel: warn
      commands:
        apispec:
          logLevel: INFO
        blkexp:
          logLevel: INFO
        botexp:
          logLevel: WARN
        cntexp:
          logLevel: ERROR
        cntsync:
          logLevel: INFO
        credstuff:
          logLevel: INFO
        envexp:
          logLevel: INFO
        ipfeed:
          logLevel: INFO
        iplist:
          logLevel: INFO
        jwtexp:
          logLevel: INFO
        metricsexp:
          logLevel: INFO
        mrksync:
          logLevel: INFO
        register:
          logLevel: INFO
        reqexp:
          logLevel: INFO
        syncnode:
          logLevel: INFO
      resources: {}
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
    apiFirewall:
      enabled: true
      config:
        ...
      extraEnvs:
        - name: EXTRA_ENV_VAR_NAME
          value: EXTRA_ENV_VAR_VALUE
      metrics:
        enabled: false
        port: 9010
        endpointPath: /metrics
        host: ":9010"
        service:
          servicePort: 9010
        serviceMonitor:
          ## ServiceMonitor kaynağının oluşturulmasını etkinleştirir
          enabled: false
          ## Prometheus örneğiyle eşleşmek için kullanılan ekstra etiketler
          additionalLabels: {}
          # -- ServiceMonitor'a eklenecek açıklamalar (annotations)
          annotations: {}
          ## İş adını almak için kullanılacak etiket
          ## jobLabel: "app.kubernetes.io/name"
          namespace: ""
          namespaceSelector: {}
          ## Varsayılan: yalnızca .Release.Namespace veya namespaceOverride'ı scrape et
          ## Tüm ad alanlarını scrape etmek için aşağıdakini kullanın:
          ## namespaceSelector:
          ##   any: true
          scrapeInterval: 30s
          # honorLabels: true
          targetLabels: []
          relabelings: []
          metricRelabelings: []
validation:
  enableCel: false
  forbidDangerousAnnotations: false

Bu ayarı değiştirmek için, helm install (Ingress controller kurulumu) veya helm upgrade (kurulu Ingress controller parametrelerinin güncellenmesi) komutlarının --set seçeneğini kullanmanızı öneririz. Örneğin:

helm install --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

helm upgrade --reuse-values --set controller.wallarm.enabled=true <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>

Aşağıda yapılandırabileceğiniz başlıca parametrelerin açıklaması verilmiştir. Diğer parametreler varsayılan değerlerle gelir ve nadiren değiştirilmesi gerekir.

controller.wallarm.enabled¶

Wallarm işlevlerini etkinleştirmenize veya devre dışı bırakmanıza olanak tanır.

Varsayılan değer: false

controller.wallarm.apiHost¶

Wallarm API uç noktası. Şunlardan biri olabilir:

• US Cloud için us1.api.wallarm.com.

• EU Cloud için api.wallarm.com,

Varsayılan değer: api.wallarm.com

controller.wallarm.token¶

Bir filtreleme node token değeri. Wallarm API'ye erişim için gereklidir.

Token, şu türlerden biri olabilir:

• API token (önerilir) - UI organizasyonu için node gruplarını dinamik olarak ekleyip/çıkarmanız gerekiyorsa veya ek güvenlik için token yaşam döngüsünü kontrol etmek istiyorsanız idealdir. Bir API token oluşturmak için:

  Bir API token oluşturmak için:

  1. Wallarm Console → Settings → API tokens bölümüne US Cloud veya EU Cloud içinde gidin.
  2. Node deployment/Deployment kullanım türüyle bir API token oluşturun.
  3. Node dağıtımı sırasında, oluşturulan token'ı kullanın ve controller.wallarm.nodeGroup parametresiyle grup adını belirtin. Farklı API token'ları kullanarak bir gruba birden fazla node ekleyebilirsiniz.

• Node token - Kullanılacak node gruplarını zaten bildiğiniz durumlar için uygundur.

  Bir node token oluşturmak için:

  1. Wallarm Console → Nodes bölümüne US Cloud veya EU Cloud içinde gidin.
  2. Bir node oluşturun ve node grubu adını belirleyin.
  3. Node dağıtımı sırasında, o gruba dahil etmek istediğiniz her node için grubun token'ını kullanın.

controller.wallarm.existingSecret.enabled: true ise bu parametre yok sayılır.

Varsayılan değer: belirtilmemiş

controller.wallarm.nodeGroup¶

Helm chart 4.6.8 sürümünden itibaren, yeni dağıtılan node'ları eklemek istediğiniz filtreleme node grubu adını belirtir. Bu şekilde gruplama yalnızca, Node deployment/Deployment kullanım türüne sahip bir API token ile node'lar oluşturup Cloud'a bağladığınızda kullanılabilir (değeri controller.wallarm.token parametresiyle iletilir).

Varsayılan değer: defaultIngressGroup

controller.wallarm.existingSecret¶

Helm chart 4.4.1 sürümünden itibaren, bu yapılandırma bloğunu kullanarak Wallarm node token değerini Kubernetes secret'larından çekebilirsiniz. Ayrı giz yönetimi olan ortamlarda (ör. harici bir secrets operator kullanıyorsanız) faydalıdır.

Node token'ı K8s secret'larında saklamak ve Helm chart'a çekmek için:

1. Wallarm node token ile bir Kubernetes secret oluşturun:

   kubectl -n <KUBERNETES_NAMESPACE> create secret generic wallarm-api-token --from-literal=token=<WALLARM_NODE_TOKEN>
   

   • <KUBERNETES_NAMESPACE>, Wallarm Ingress controller'lı Helm yayını için oluşturduğunuz Kubernetes namespace'idir
   • wallarm-api-token, Kubernetes secret adıdır
   • <WALLARM_NODE_TOKEN>, Wallarm Console UI'dan kopyalanan Wallarm node token değeridir

   Harici bir secrets operator kullanıyorsanız, bir secret oluşturmak için uygun dokümantasyonu izleyin.

2. values.yaml dosyasında aşağıdaki yapılandırmayı ayarlayın:

   controller:
     wallarm:
       token: ""
       existingSecret:
         enabled: true
         secretKey: token
         secretName: wallarm-api-token
   

Varsayılan değer: existingSecret.enabled: false; bu durumda Helm chart, Wallarm node token'ını controller.wallarm.token değerinden alır.

controller.wallarm.postanalytics.arena¶

Postanalytics servisi için ayrılan bellek miktarını belirtir. Son 5-15 dakikaya ait istek verilerini saklamak için yeterli bir değer ayarlanması önerilir.

Varsayılan değer: 2.0

NGINX Node 5.x ve öncesinde, parametrenin adı controller.wallarm.tarantool.arena idi. Yükseltme sırasında yeniden adlandırma gerekir.

controller.wallarm.postanalytics.serviceAddress¶

wstore'un gelen bağlantıları kabul ettiği adres ve portu belirtir.

6.3.0 sürümünden itibaren desteklenir.

Varsayılan değer: [::]:3313 - tüm IPv4 ve IPv6 arayüzlerinde 3313 portunu dinler. Bu, 6.3.0'dan önceki sürümlerde de varsayılan davranıştı.

controller.wallarm.postanalytics.tls¶

Postanalytics modülüne güvenli bağlantı sağlamak için TLS ve karşılıklı TLS (mTLS) ayarlarını yapılandırır (opsiyonel):

controller:
  wallarm:
    postanalytics:
      tls:
        enabled: false
      #  certFile: "/root/test-tls-certs/server.crt"
      #  keyFile: "/root/test-tls-certs/server.key"
      #  caCertFile: "/root/test-tls-certs/ca.crt"
      #  mutualTLS:
      #    enabled: false
      #    clientCACertFile: "/root/test-tls-certs/ca.crt"

6.2.0 sürümünden itibaren desteklenir.

controller.wallarm.metrics.enabled¶

Bu anahtar, bilgi ve metrik toplamayı açıp kapatır. Kubernetes kümesinde Prometheus yüklüyse, ek bir yapılandırma gerekmez.

Varsayılan değer: false

controller.wallarm.apiFirewall¶

API Specification Enforcement yapılandırmasını kontrol eder; 4.10 sürümünden itibaren kullanılabilir. Varsayılan olarak etkinleştirilmiştir ve aşağıda gösterildiği gibi yapılandırılmıştır. Bu özelliği kullanıyorsanız, bu değerleri değiştirmemeniz önerilir.

controller:
  wallarm:
    apiFirewall:
      ### API Firewall işlevselliğini etkinleştir/devre dışı bırak (true|false)
      ###
      enabled: true
      readBufferSize: 8192
      writeBufferSize: 8192
      maxRequestBodySize: 4194304
      disableKeepalive: false
      maxConnectionsPerIp: 0
      maxRequestsPerConnection: 0
      config:
        mainPort: 18081
        healthPort: 18082
        specificationUpdatePeriod: 1m
        unknownParametersDetection: true
        #### TRACE|DEBUG|INFO|WARNING|ERROR
        logLevel: DEBUG
        ### TEXT|JSON
        logFormat: TEXT
      ...

Node 5.1.0 itibarıyla, aşağıdakiler sunulur (varsayılan değerler yukarıdaki örnekte gösterilmiştir):

controller.wallarm.apiFirewall.metrics¶

6.5.1 sürümünden itibaren, API Specification Enforcement modülü Prometheus uyumlu metrikleri sunabilir.

Etkinleştirildiğinde, metrikler varsayılan olarak http://<host>:9010/metrics adresinde kullanılabilir.

controller:
  wallarm:
    apiFirewall:
      metrics:
        enabled: false
        port: 9010
        endpointPath: /metrics
        host: ":9010"
        service:
          servicePort: 9010

controller.wallarm.apiFirewall.metrics.serviceMonitor¶

Prometheus Operator kullanıyorsanız (örneğin, kube-prometheus-stack'in bir parçası olarak), API Specification Enforcement metriklerini scrape etmek için chart'ın otomatik olarak bir ServiceMonitor kaynağı oluşturmasını yapılandırabilirsiniz.

serviceMonitor yapılandırma seçenekleri 6.5.1 sürümünden itibaren mevcuttur.

Varsayılan değerlerle yapılandırma seçenekleri:

controller:
  wallarm:
    apiFirewall:
      metrics:
        ...
        serviceMonitor:
          ## ServiceMonitor kaynağının oluşturulmasını etkinleştirir
          enabled: false
          ## Prometheus örneğiyle eşleşmek için kullanılan ekstra etiketler
          additionalLabels: {}
          # -- ServiceMonitor'a eklenecek açıklamalar (annotations)
          annotations: {}
          ## İş adını almak için kullanılacak etiket
          ## jobLabel: "app.kubernetes.io/name"
          namespace: ""
          namespaceSelector: {}
          ## Varsayılan: yalnızca .Release.Namespace veya namespaceOverride'ı scrape et
          ## Tüm ad alanlarını scrape etmek için aşağıdakini kullanın:
          ## namespaceSelector:
          ##   any: true
          scrapeInterval: 30s
          # honorLabels: true
          targetLabels: []
          relabelings: []
          metricRelabelings: []

controller.wallarm.container_name.extraEnvs¶

Çözüm tarafından kullanılan Docker konteynerlerine iletilecek ekstra ortam değişkenleri. 4.10.6 sürümünden itibaren desteklenir.

Aşağıdaki örnek, https_proxy ve no_proxy değişkenlerinin Docker konteynerlerine nasıl geçirileceğini gösterir. Bu kurulum, giden HTTPS trafiğini belirlenmiş bir proxy üzerinden yönlendirir; yerel trafik ise onu atlar. Bu tür bir yapılandırma, Wallarm API'si ile olanlar gibi dış haberleşmelerin güvenlik nedeniyle bir proxy üzerinden geçirilmesi gereken ortamlarda önemlidir.

controller:
  wallarm:
    apiHost: api.wallarm.com
    enabled: "true"
    token:  <API_TOKEN>
    init:
      extraEnvs:
        - name: https_proxy
          value: https://1.1.1.1:3128

validation.enableCel¶

Ingress kaynaklarının Doğrulayıcı Kabul Politikaları kullanılarak doğrulanmasını etkinleştirir.

Bu özellik için gereklidir:

• Kubernetes v1.30 veya üzeri

• Wallarm Helm chart sürümü 5.3.14+ (5.x serisi) veya 6.0.2+

true olarak ayarlandığında, Helm chart aşağıdakileri dağıtır:

• Tüm Ingress kaynakları (networking.k8s.io/v1) için CEL kurallarını tanımlayan ValidatingAdmissionPolicy ingress-safety-net

• Bu kuralları cluster-wide olarak Deny eylemiyle çalıştıran ValidatingAdmissionPolicyBinding ingress-safety-net-binding

Varsayılan kurallar, tipik olarak nginx -t ile tespit edilen yaygın yanlış yapılandırmaları yakalar:

• Joker ana bilgisayar adlarını yasaklama (ör. *.example.com)

• Bir Ingress içindeki tüm host değerlerinin benzersiz olmasını sağlama

• Her HTTP yolunun bir servis adı ve port içerdiğini doğrulama

• Tüm yolların / ile başlamasını gerektirme

• Yaygın boyut/zaman/boolean annotation formatlarını doğrulama (proxy-buffer-size, proxy-read-timeout, ssl-redirect)

Doğrulama, Ingress oluşturma veya güncelleme sırasında gerçekleşir ve yanlış yapılandırılmış kaynaklar reddedilir.

Bu mekanizma, CVE-2025-1974 nedeniyle şu anda upstream NGINX Ingress Controller'da devre dışı olan şablon testinin yerini alır.

Varsayılan değer: false

Doğrulama kurallarını özelleştirme

Varsayılan kural setini Common Expression Language (CEL) kullanarak genişletebilir veya değiştirebilirsiniz:

1. İstenen sürümün Wallarm Helm chart'ını indirin.

2. templates/ingress-safety-vap.yaml dosyasındaki kuralları değiştirin.

3. Chart'ı, standart dağıtım talimatlarına göre değiştirilmiş dizinden dağıtın.

validation.forbidDangerousAnnotations¶

Açıkça tehlikeli NGINX Ingress annotation'larını server-snippet ve configuration-snippet engelleyen ek bir CEL kuralını etkinleştirir.

Tüm snippet annotation'larına izin vermek saldırı yüzeyini genişletir: Ingress oluşturma veya güncelleme iznine sahip herhangi bir kullanıcı güvensiz veya kararsız davranışlar ekleyebilir.

Bu özellik için gereklidir:

• Kubernetes v1.30 veya üzeri

• Wallarm Helm chart sürümü 6.3.0+

• validation.enableCel true olarak ayarlanmış olmalı

Varsayılan değer: false (açıkça tehlikeli server-snippet ve configuration-snippet annotation'larının engellenmesi devre dışıdır)

Global Controller Settings¶

ConfigMap aracılığıyla uygulanır.

Standart olanların yanı sıra, aşağıdaki ek parametreler desteklenir:

• wallarm-acl-export-enable

• wallarm-upstream-connect-attempts

• wallarm-upstream-reconnect-interval

• wallarm-process-time-limit

• wallarm-process-time-limit-block

• wallarm-request-memory-limit

Ingress Annotation'ları¶

Bu annotation'lar, Ingress'in bireysel örneklerinin işlenmesine yönelik parametreleri ayarlamak için kullanılır.

Standart olanlara ek olarak, aşağıdaki ek annotation'lar desteklenir:

• nginx.ingress.kubernetes.io/wallarm-mode, varsayılan: "off"

• nginx.ingress.kubernetes.io/wallarm-mode-allow-override

• nginx.ingress.kubernetes.io/wallarm-fallback

• nginx.ingress.kubernetes.io/wallarm-application

• nginx.ingress.kubernetes.io/wallarm-block-page

• nginx.ingress.kubernetes.io/wallarm-parse-response

• nginx.ingress.kubernetes.io/wallarm-parse-websocket

• nginx.ingress.kubernetes.io/wallarm-unpack-response

• nginx.ingress.kubernetes.io/wallarm-parser-disable

• nginx.ingress.kubernetes.io/wallarm-partner-client-uuid

Annotation'ı Ingress kaynağına uygulama¶

Ayarları Ingress'inize uygulamak için lütfen aşağıdaki komutu kullanın:

kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> <ANNOTATION_NAME>=<VALUE>

• <YOUR_INGRESS_NAME>, Ingress'inizin adıdır

• <YOUR_INGRESS_NAMESPACE>, Ingress'inizin namespace'idir

• <ANNOTATION_NAME>, yukarıdaki listeden annotation adıdır

• <VALUE>, yukarıdaki listeden annotation değeridir

Annotation örnekleri¶

Engelleme sayfası ve hata kodunun yapılandırılması¶

nginx.ingress.kubernetes.io/wallarm-block-page annotation'ı, aşağıdaki nedenlerle engellenen isteğe verilecek yanıtta döndürülen engelleme sayfasını ve hata kodunu yapılandırmak için kullanılır:

• İstek, şu türde kötü amaçlı yükler içerir: girdi doğrulama saldırıları, vpatch saldırıları veya düzenli ifadelere dayalı olarak tespit edilen saldırılar.

• Yukarıdaki listeden kötü amaçlı yükler içeren istek, gri listeye alınmış IP adresinden gelmiştir ve node, istekleri güvenli engelleme modunda filtreler.

• İstek, yasaklı listede (denylist) olan IP adresinden gelmiştir.

Örneğin, herhangi bir engellenen isteğe verilecek yanıtta varsayılan Wallarm engelleme sayfasını ve 445 hata kodunu döndürmek için:

kubectl annotate ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> nginx.ingress.kubernetes.io/wallarm-block-page="&/usr/share/nginx/html/wallarm_blocked.html response_code=445 type=attack,acl_ip,acl_source"

Engelleme sayfası ve hata kodu yapılandırma yöntemleri hakkında daha fazla bilgi →

libdetection modunu yönetme¶

libdetection modunu aşağıdaki seçeneklerden biriyle kontrol edebilirsiniz:

• Aşağıdaki nginx.ingress.kubernetes.io/server-snippet annotation'ını Ingress kaynağına uygulayarak:

  kubectl annotate --overwrite ingress <YOUR_INGRESS_NAME> -n <YOUR_INGRESS_NAMESPACE> nginx.ingress.kubernetes.io/server-snippet="wallarm_enable_libdetection off;"
  

  wallarm_enable_libdetection için kullanılabilir değerler on/off'tur.

• controller.config.server-snippet parametresini Helm chart'a geçirerek:

  Ingress controller kurulumuIngress controller parametrelerini güncelleme

  helm install --set controller.config.server-snippet='wallarm_enable_libdetection off;' <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>
  

  Doğru Ingress controller kurulumu için diğer parametreler de gereklidir. Lütfen bunları da --set seçeneğiyle iletin.

  helm upgrade --reuse-values --set controller.config.server-snippet='wallarm_enable_libdetection off;' <INGRESS_CONTROLLER_RELEASE_NAME> wallarm/wallarm-ingress -n <KUBERNETES_NAMESPACE>
  

  wallarm_enable_libdetection için kullanılabilir değerler on/off'tur.

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send