وحدة تحكم دخول NGINX المتقدمة وتكوينات الدخول مع الوظيفة الإضافية لتوجيه التطبيق

تدعم الوظيفة الإضافية لتوجيه التطبيق طريقتين لتكوين وحدات تحكم الدخول وعناصر الدخول:

• تكوين وحدة تحكم دخول NGINX مثل إنشاء وحدات تحكم متعددة وتكوين موازنات تحميل خاصة وإعداد عناوين IP ثابتة.
• التكوين لكل مورد دخول من خلال التعليقات التوضيحية.

المتطلبات الأساسية

نظام مجموعة AKS مع الوظيفة الإضافية لتوجيه التطبيق.

قم بالاتصال بمجموعة AKS

للاتصال بمجموعة Kubernetes من الكمبيوتر المحلي الخاص بك، يمكنك استخدام kubectl، عميل سطر أوامر Kubernetes. يمكنك تثبيته محليا باستخدام الأمر az aks install-cli . في حال كنت تستخدم Azure Cloud Shell، يكون kubectl مثبتاً بالفعل.

تكوين kubectl للاتصال بمجموعة Kubernetes باستخدام az aks get-credentials الأمر .

az aks get-credentials --resource-group <ResourceGroupName> --name <ClusterName>

تكوين وحدة تحكم دخول NGINX

تستخدم الوظيفة الإضافية لتوجيه التطبيق تعريف مورد مخصص Kubernetes (CRD) يسمى NginxIngressController لتكوين وحدات تحكم دخول NGINX. يمكنك إنشاء المزيد من وحدات التحكم في الدخول أو تعديل التكوين الموجود.

فيما يلي مرجع إلى الخصائص التي يمكنك تعيينها لتكوين NginxIngressController.

التكوينات الشائعة

التحكم في تكوين وحدة تحكم دخول NGINX الافتراضية (معاينة)

عند تمكين الوظيفة الإضافية لتوجيه التطبيق باستخدام NGINX، فإنه ينشئ وحدة تحكم دخول تسمى default في app-routing-namespace المكون مع موازن تحميل Azure مواجه عام. تستخدم وحدة تحكم الدخول هذه اسم فئة دخول ل webapprouting.kubernetes.azure.com.

يمكنك أيضا التحكم في ما إذا كان الافتراضي يحصل على عنوان IP عام أو داخلي، أو إذا تم إنشاؤه على الإطلاق عند تمكين الوظيفة الإضافية.

فيما يلي خيارات التكوين المحتملة:

• None: لم يتم إنشاء وحدة تحكم دخول Nginx الافتراضية ولن يتم حذفها إذا كانت موجودة بالفعل. يجب على المستخدمين حذف المورد المخصص الافتراضي NginxIngressController يدويا إذا رغبت في ذلك.
• Internal: يتم إنشاء وحدة تحكم دخول Nginx الافتراضية باستخدام موازن تحميل داخلي. سيتم الكتابة فوق أي تغييرات في التعليقات التوضيحية على NginxIngressController المورد المخصص لجعله خارجيا.
• External: وحدة تحكم دخول Nginx الافتراضية التي تم إنشاؤها باستخدام موازن تحميل خارجي. سيتم الكتابة فوق أي تغييرات في التعليقات التوضيحية على NginxIngressController المورد المخصص لجعله داخليا.
• AnnotationControlled (افتراضي): يتم إنشاء وحدة تحكم دخول Nginx الافتراضية باستخدام موازن تحميل خارجي. يمكن للمستخدمين تحرير المورد المخصص الافتراضي NginxIngressController لتكوين التعليقات التوضيحية لموازن التحميل.

az aks create \
--resource-group <ResourceGroupName> \
--name <ClusterName> \
--location <Location> \
--enable-app-routing \
--app-routing-default-nginx-controller <DefaultIngressControllerType>

az aks approuting update --resource-group <ResourceGroupName> --name <ClusterName> --nginx <DefaultIngressControllerType>

"ingressProfile": {
  "webAppRouting": {
    "nginx": {
        "defaultIngressControllerType": "None|Internal|External|AnnotationControlled"
    }
}

إنشاء وحدة تحكم دخول NGINX عامة أخرى

لإنشاء وحدة تحكم دخول NGINX أخرى مع موازن تحميل Azure عام:

1. انسخ بيان YAML التالي في ملف جديد يسمى nginx-public-controller.yaml واحفظ الملف على الكمبيوتر المحلي.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-public
   spec:
     ingressClassName: nginx-public
     controllerNamePrefix: nginx-public
   

2. إنشاء موارد وحدة تحكم دخول NGINX باستخدام kubectl apply الأمر .

   kubectl apply -f nginx-public-controller.yaml
   

   يظهر إخراج المثال التالي المورد الذي تم إنشاؤه:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
   

إنشاء وحدة تحكم دخول NGINX داخلية بعنوان IP خاص

لإنشاء وحدة تحكم دخول NGINX مع موازن تحميل Azure مواجه داخلي بعنوان IP خاص:

1. انسخ بيان YAML التالي في ملف جديد يسمى nginx-internal-controller.yaml واحفظ الملف على الكمبيوتر المحلي.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-internal
   spec:
     ingressClassName: nginx-internal
     controllerNamePrefix: nginx-internal
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-load-balancer-internal: "true"
   

2. إنشاء موارد وحدة تحكم دخول NGINX باستخدام kubectl apply الأمر .

   kubectl apply -f nginx-internal-controller.yaml
   

   يظهر إخراج المثال التالي المورد الذي تم إنشاؤه:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
   

إنشاء وحدة تحكم دخول NGINX بعنوان IP ثابت

لإنشاء وحدة تحكم دخول NGINX بعنوان IP ثابت على موازن تحميل Azure:

1. إنشاء مجموعة موارد Azure باستخدام az group create الأمر .

   az group create --name myNetworkResourceGroup --location eastus
   

2. إنشاء عنوان IP عام ثابت باستخدام az network public ip create الأمر .

   az network public-ip create \
       --resource-group myNetworkResourceGroup \
       --name myIngressPublicIP \
       --sku Standard \
       --allocation-method static
   

   إشعار

   إذا كنت تستخدم موازن تحميل SKU أساسي في نظام مجموعة AKS، فاستخدم Basic للمعلمة --sku عند تعريف IP عام. تعمل عناوين SKU IP الأساسية فقط مع موازن تحميل SKU الأساسي وتعمل عناوين SKU IP القياسية فقط مع موازنات تحميل SKU القياسية .

3. تأكد من أن هوية نظام المجموعة المستخدمة من قبل مجموعة AKS قد فوضت أذونات إلى مجموعة موارد IP العامة باستخدام az role assignment create الأمر .

   إشعار

   قم بتحديث <ClusterName> و <ClusterResourceGroup> باسم مجموعة AKS واسم مجموعة الموارد.

   CLIENT_ID=$(az aks show --name <ClusterName> --resource-group <ClusterResourceGroup> --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name myNetworkResourceGroup --query id -o tsv)
   az role assignment create \
       --assignee ${CLIENT_ID} \
       --role "Network Contributor" \
       --scope ${RG_SCOPE}
   

4. انسخ بيان YAML التالي في ملف جديد يسمى nginx-staticip-controller.yaml واحفظ الملف على الكمبيوتر المحلي.

   إشعار

   يمكنك إما استخدام service.beta.kubernetes.io/azure-pip-name لاسم IP العام، أو استخدام service.beta.kubernetes.io/azure-load-balancer-ipv4 لعنوان IPv4 ولعنوان service.beta.kubernetes.io/azure-load-balancer-ipv6 IPv6، كما هو موضح في مثال YAML. تضمن إضافة التعليق التوضيحي service.beta.kubernetes.io/azure-pip-name إنشاء LoadBalancer الأكثر كفاءة ويوصى به بشدة لتجنب التقييد المحتمل.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-static
   spec:
     ingressClassName: nginx-static
     controllerNamePrefix: nginx-static
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-pip-name: "myIngressPublicIP"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "myNetworkResourceGroup"
   

5. إنشاء موارد وحدة تحكم دخول NGINX باستخدام kubectl apply الأمر .

   kubectl apply -f nginx-staticip-controller.yaml
   

   يظهر إخراج المثال التالي المورد الذي تم إنشاؤه:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
   

تحقق من إنشاء وحدة تحكم الدخول

يمكنك التحقق من حالة وحدة تحكم دخول NGINX باستخدام kubectl get nginxingresscontroller الأمر .

kubectl get nginxingresscontroller -n <IngressControllerName>

يظهر إخراج المثال التالي المورد الذي تم إنشاؤه. قد يستغرق الأمر بضع دقائق حتى تتوفر وحدة التحكم:

NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
nginx-public   nginx-public   nginx                  True

يمكنك أيضا عرض الشروط لاستكشاف أي مشكلات وإصلاحها:

kubectl get nginxingresscontroller -n <IngressControllerName> -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'

يوضح إخراج المثال التالي شروط وحدة تحكم الدخول السليمة:

2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed

استخدام وحدة تحكم الدخول في الدخول

1. انسخ بيان YAML التالي في ملف جديد يسمى ingress.yaml واحفظ الملف إلى الكمبيوتر المحلي.

   إشعار

   تحديث <Hostname> باسم مضيف DNS الخاص بك. <IngressClassName> هو الذي قمت بتعريفه عند إنشاء NginxIngressController.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: aks-helloworld
     namespace: hello-web-app-routing
   spec:
     ingressClassName: <IngressClassName>
     rules:
     - host: <Hostname>
       http:
         paths:
         - backend:
             service:
               name: aks-helloworld
               port:
                 number: 80
           path: /
           pathType: Prefix
   

2. إنشاء موارد نظام المجموعة باستخدام kubectl apply الأمر .

   kubectl apply -f ingress.yaml -n hello-web-app-routing
   

   يظهر إخراج المثال التالي المورد الذي تم إنشاؤه:

   ingress.networking.k8s.io/aks-helloworld created
   

تحقق من إنشاء الدخول المدار

يمكنك التحقق من إنشاء الدخول المدار باستخدام kubectl get ingress الأمر .

kubectl get ingress -n hello-web-app-routing

يظهر إخراج المثال التالي الدخول المدار الذي تم إنشاؤه. قد تختلف فئة الدخول والمضيف وعنوان IP:

NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m

تنظيف وحدات التحكم في الدخول

يمكنك إزالة وحدة تحكم دخول NGINX باستخدام kubectl delete nginxingresscontroller الأمر .

kubectl delete nginxingresscontroller -n <IngressControllerName>

التكوين لكل مورد دخول من خلال التعليقات التوضيحية

تدعم وحدة تحكم دخول NGINX إضافة تعليقات توضيحية إلى كائنات دخول معينة لتخصيص سلوكها.

يمكنك إضافة تعليق توضيحي إلى كائن الدخول عن طريق إضافة التعليق التوضيحي المعني في metadata.annotations الحقل.

فيما يلي بعض الأمثلة على التعليقات التوضيحية للتكوينات الشائعة. راجع وثائق التعليقات التوضيحية للدخول NGINX للحصول على قائمة كاملة.

الحد الأقصى لحجم الجسم المخصص

بالنسبة إلى NGINX، يتم إرجاع خطأ 413 إلى العميل عندما يتجاوز الحجم في الطلب الحد الأقصى المسموح به لنص طلب العميل. لتجاوز القيمة الافتراضية، استخدم التعليق التوضيحي:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

انتهاء مهلة الاتصال المخصص

يمكنك تغيير المهلة التي تنتظرها وحدة تحكم الدخول NGINX لإغلاق اتصال مع حمل العمل الخاص بك. كل قيم المهلة بلا وحدة وبالثوان. لتجاوز المهلة الافتراضية، استخدم التعليق التوضيحي التالي لتعيين مهلة قراءة وكيل صالحة لمدة 120 ثانية:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

راجع المهلات المخصصة لخيارات التكوين الأخرى.

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

بروتوكول الواجهة الخلفية

بشكل افتراضي، تستخدم HTTP وحدة تحكم دخول NGINX للوصول إلى الخدمات. لتكوين بروتوكولات خلفية بديلة مثل HTTPS أو GRPC، استخدم التعليق التوضيحي:

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

أو

nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

راجع بروتوكولات الواجهة الخلفية لخيارات التكوين الأخرى.

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

مشاركة الموارد عبر الأصل (CORS)

لتمكين مشاركة الموارد عبر المنشأ (CORS) في قاعدة دخول، استخدم التعليق التوضيحي:

nginx.ingress.kubernetes.io/enable-cors: "true"

راجع تمكين CORS لخيارات التكوين الأخرى.

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

تعطيل إعادة توجيه SSL

بشكل افتراضي، تعيد وحدة التحكم توجيه (308) إلى HTTPS إذا تم تمكين TLS للدخول. لتعطيل هذه الميزة لموارد دخول معينة، استخدم التعليق التوضيحي:

nginx.ingress.kubernetes.io/ssl-redirect: "false"

راجع فرض HTTPS من جانب الخادم من خلال إعادة التوجيه لخيارات التكوين الأخرى.

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

إعادة كتابة عنوان URL

في بعض السيناريوهات، يختلف عنوان URL المكشوف في خدمة الواجهة الخلفية عن المسار المحدد في قاعدة الدخول. دون إعادة كتابة أي طلب إرجاع 404. هذا التكوين مفيد مع التوجيه المستند إلى المسار حيث يمكنك خدمة تطبيقي ويب مختلفين ضمن نفس المجال. يمكنك تعيين المسار المتوقع بواسطة الخدمة باستخدام التعليق التوضيحي:

nginx.ingress.kubernetes.io/rewrite-target": /$2

فيما يلي مثال على تكوين الدخول باستخدام هذا التعليق التوضيحي:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

الخطوات التالية

تعرف على مراقبة مقاييس وحدة تحكم ingress-nginx المضمنة مع الوظيفة الإضافية لتوجيه التطبيق مع Prometheus في Grafana كجزء من تحليل أداء واستخدام التطبيق الخاص بك.