애플리케이션 라우팅 추가 항목을 사용하는 고급 NGINX 수신 컨트롤러 및 수신 구성

애플리케이션 라우팅 추가 항목은 수신 컨트롤러 및 수신 개체를 구성하는 두 가지 방법을 지원합니다.

• 여러 컨트롤러 만들기, 프라이빗 부하 분산 장치 구성, 고정 IP 주소 설정과 같은 NGINX 수신 컨트롤러 구성
• 주석을 통한 수신 리소스별 구성

필수 구성 요소

애플리케이션 라우팅 추가 항목이 있는 AKS 클러스터

AKS 클러스터에 연결

로컬 컴퓨터에서 Kubernetes 클러스터에 연결하려면 Kubernetes 명령줄 클라이언트인 kubectl을 사용합니다. az aks install-cli 명령을 사용하여 로컬로 설치할 수 있습니다. Azure Cloud Shell을 사용하는 경우 kubectl이 이미 설치되어 있습니다.

az aks get-credentials 명령을 사용하여 kubectl을 구성하여 Kubernetes 클러스터에 연결합니다.

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

NGINX 수신 컨트롤러 구성

애플리케이션 라우팅 추가 항목은 라는 Kubernetes NginxIngressController를 사용하여 NGINX 수신 컨트롤러를 구성합니다. 더 많은 수신 컨트롤러를 만들거나 기존 구성을 수정할 수 있습니다.

이 표는 NginxIngressController를 구성하기 위해 설정 가능한 속성에 대한 참조를 보여줍니다.

분야	유형	설명	필수	기본값
controllerNamePrefix	문자열	관리되는 NGINX 인그레스 컨트롤러 리소스의 이름입니다.	예	nginx
customHTTPErrors	배열	오류 발생 시 기본 백 엔드로 보낼 오류 코드의 배열입니다.	아니오
defaultBackendService	객체	일치하지 않는 HTTP 트래픽을 라우팅하는 서비스입니다. 중첩된 속성을 포함합니다.	아니오
name	문자열	서비스 이름입니다.	예
namespace	문자열	서비스 네임스페이스입니다.	예
defaultSSLCertificate	객체	기본 백 엔드 서비스에 액세스하기 위한 기본 인증서를 포함합니다. 중첩된 속성을 포함합니다.	아니오
forceSSLRedirect	불리언	인증서가 설정되면 HTTPS 리디렉션을 강제합니다.	아니오	false
keyVaultURI	문자열	인증서를 저장하는 Key Vault 비밀에 대한 URI입니다.	아니오
secret	객체	기본 SSL 인증서에 대한 비밀 정보를 보유합니다. 중첩된 속성을 포함합니다.	아니오
name	문자열	비밀 이름입니다.	예
namespace	문자열	비밀 네임스페이스입니다.	예
httpDisabled	불리언	컨트롤러에 대한 HTTP 트래픽을 사용하지 않도록 설정하는 플래그입니다.	아니오
ingressClassName	문자열	컨트롤러에서 사용하는 IngressClass 이름입니다.	예	nginx.approuting.kubernetes.azure.com
loadBalancerAnnotations	객체	부하 분산 장치 주석을 설정하여 NGINX 인그레스 컨트롤러 서비스의 동작을 제어하는 주석을 매핑한 것입니다.	아니오
scaling	객체	컨트롤러 크기를 조정하기 위한 구성입니다. 중첩된 속성을 포함합니다.	아니오
maxReplicas	정수	복제본의 상한입니다.	아니오	100
minReplicas	정수	복제본에 대한 하한입니다.	아니오	2
threshold	문자열	크기를 얼마나 적극적으로 조정할지 정의하는 크기 조정 임계값입니다. rapid 갑작스런 급증을 위해 빠르게 확장하고, steady 비용 효율성을 선호하며 balanced , 혼합입니다.	아니오	balanced

일반 구성

기본 NGINX 인그레스 컨트롤러 설정 제어

NGINX를 사용하여 애플리케이션 라우팅 추가 항목을 사용하도록 설정하면 공용 Azure 부하 분산 장치로 구성된 default에 app-routing-namespace라는 수신 컨트롤러가 생성됩니다. 해당 수신 컨트롤러는 webapprouting.kubernetes.azure.com이라는 수신 클래스 이름을 사용합니다.

또한 기본 IP에 공용 IP나 내부 IP를 할당할지, 추가 기능을 사용하도록 설정할 때 IP를 만들지 여부를 제어할 수 있습니다.

가능한 구성 옵션은 다음과 같습니다.

• None: 기본 Nginx 수신 컨트롤러는 만들어지지 않으며 이미 존재하는 경우 삭제되지 않습니다. 원하는 경우 사용자는 기본 NginxIngressController 사용자 지정 리소스를 수동으로 삭제해야 합니다.
• Internal: 기본 Nginx 수신 컨트롤러는 내부 부하 분산 장치로 만들어집니다. NginxIngressController 사용자 지정 리소스에 대한 모든 주석 변경 내용을 외부로 만들기 위해 적용하면 해당 변경 내용을 덮어씁니다.
• External: 외부 부하 분산 장치로 만들어진 기본 Nginx 수신 컨트롤러입니다. NginxIngressController 사용자 지정 리소스에 대한 모든 주석 변경 내용을 내부로 만들기 위해 적용하면 해당 변경 내용을 덮어씁니다.
• AnnotationControlled(기본값): 기본 Nginx 수신 컨트롤러는 외부 부하 분산 장치로 만들어집니다. 사용자는 기본 NginxIngressController 사용자 지정 리소스를 편집하여 부하 분산 장치 주석을 구성할 수 있습니다.

Azure CLI

클러스터를 만들 때 기본 수신 컨트롤러 구성 제어

새 클러스터에서 애플리케이션 라우팅을 사용하도록 설정하려면 az aks create 명령을 사용하고 --enable-app-routing 및 --app-routing-default-nginx-controller 플래그를 지정합니다. <DefaultIngressControllerType>을 이전에 설명한 구성 옵션 중 하나로 설정해야 합니다.

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

기존 클러스터에서 기본 수신 컨트롤러 구성 업데이트

기존 클러스터에서 애플리케이션 라우팅 기본 수신 컨트롤러 구성을 업데이트하려면 az aks approuting update 명령을 사용하고 --nginx 플래그를 지정합니다. <DefaultIngressControllerType>을 이전에 설명한 구성 옵션 중 하나로 설정해야 합니다.

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

이두박근

webAppRouting 프로필에는 nginx 속성이 있는 선택적 defaultIngressControllerType 구성이 있습니다. defaultIngressControllerType 속성을 앞서 설명한 구성 옵션 중 하나로 설정해야 합니다.

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

또 다른 공용 NGINX 수신 컨트롤러 만들기

공용 Azure Load Balancer를 사용하여 또 다른 NGINX 수신 컨트롤러를 만들려면 다음을 수행합니다.

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. kubectl apply 명령을 사용하여 NGINX 수신 컨트롤러 리소스를 생성합니다.

   kubectl apply -f nginx-public-controller.yaml
   

   다음 예제 출력은 생성된 리소스를 보여줍니다.

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

개인 IP 주소를 사용하여 내부 NGINX 수신 컨트롤러 만들기

개인 IP 주소가 있는 내부 연결 Azure Load Balancer를 사용하여 NGINX 수신 컨트롤러를 만들려면 다음을 수행합니다.

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. kubectl apply 명령을 사용하여 NGINX 수신 컨트롤러 리소스를 생성합니다.

   kubectl apply -f nginx-internal-controller.yaml
   

   다음 예제 출력은 생성된 리소스를 보여줍니다.

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

고정 IP 주소를 사용하여 NGINX 수신 컨트롤러 만들기

Azure Load Balancer에서 고정 IP 주소를 사용하여 NGINX 수신 컨트롤러를 만들려면 다음을 수행합니다.

1. az group create 명령을 사용하여 Azure 리소스 그룹을 만듭니다.

   az group create --name myNetworkResourceGroup --location eastus
   

2. az network public ip create 명령을 사용하여 고정 공용 IP 주소를 만듭니다.

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

   참고

   AKS 클러스터에서 기본 SKU 부하 분산 장치를 사용하는 경우, 공용 IP를 정의할 때 매개 변수에 --sku을 사용합니다. 기본 SKU IP만 기본 SKU 부하 분산 장치에서 작동하며, 표준 SKU IP만 표준 SKU 부하 분산 장치에서 작동합니다.

3. AKS 클러스터에서 사용하는 클러스터 ID에 az role assignment create 명령을 사용하여 공용 IP 리소스 그룹에 대한 권한이 위임되었는지 확인합니다.

   참고

   AKS 클러스터의 이름과 리소스 그룹 이름으로 <ClusterName> 및 <ClusterResourceGroup>을 업데이트합니다.

   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이라는 새 파일에 복사하고 파일을 로컬 컴퓨터에 저장합니다.

   참고

   YAML 예시에 표시된 대로 공용 IP 이름에 service.beta.kubernetes.io/azure-pip-name을 사용하거나 IPv4 주소에 service.beta.kubernetes.io/azure-load-balancer-ipv4를 사용하고 IPv6 주소에 service.beta.kubernetes.io/azure-load-balancer-ipv6을 사용할 수 있습니다. 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. kubectl apply 명령을 사용하여 NGINX 수신 컨트롤러 리소스를 생성합니다.

   kubectl apply -f nginx-staticip-controller.yaml
   

   다음 예제 출력은 생성된 리소스를 보여줍니다.

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

수신 컨트롤러가 생성되었는지 확인

kubectl get nginxingresscontroller 명령을 사용하여 NGINX 수신 컨트롤러의 상태를 확인할 수 있습니다.

참고

`NginxIngressController`를 만들 때 사용한 이름으로 <IngressControllerName>을 업데이트합니다.

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이라는 새 파일에 복사하고 파일을 로컬 컴퓨터에 저장합니다.

   참고

   DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <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

수신 컨트롤러 정리

kubectl delete nginxingresscontroller 명령을 사용하여 NGINX 수신 컨트롤러를 제거할 수 있습니다.

참고

<IngressControllerName>를 만들 때 사용한 이름으로 NginxIngressController을 업데이트합니다.

kubectl delete nginxingresscontroller -n <IngressControllerName>

주석을 통한 수신 리소스별 구성

NGINX 수신 컨트롤러는 특정 수신 개체에 주석을 추가하여 동작을 사용자 지정할 수 있도록 지원합니다.

필드에 각 주석을 추가하여 수신 개체에 metadata.annotations할 수 있습니다.

참고

주석 키와 값은 문자열만 가능합니다. 부울 또는 숫자 값과 같은 다른 형식은 따옴표로 묶어야 합니다(예: "true", "false", "100").

다음은 일반적인 구성에 대한 몇 가지 주석 예시입니다. 전체 목록은 NGINX 수신 주석 설명서를 검토하세요.

사용자 지정 최대 본문 크기

NGINX의 경우 요청 크기가 클라이언트 요청 본문의 최대 허용 크기를 초과하면 413 오류가 클라이언트에 반환됩니다. 기본값을 재정의하려면 다음 주석을 사용합니다.

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

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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"

다른 구성 옵션에 대해서는 사용자 지정 시간 초과를 검토합니다.

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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

백 엔드 프로토콜

기본적으로 NGINX 수신 컨트롤러는 HTTP를 사용하여 서비스에 연결합니다. HTTPS 또는 GRPC와 같은 대체 백 엔드 프로토콜을 구성하려면 다음 주석을 사용합니다.

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

또는

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

다른 구성 옵션은 백엔드 프로토콜을 검토하세요.

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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를 사용하도록 설정을 검토하세요.

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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 리디렉션 사용 안 함

수신에 대해 TLS를 사용하도록 설정된 경우 기본적으로 컨트롤러는 HTTPS로 리디렉션(308)합니다. 특정 수신 리소스에 대해 이 기능을 사용하지 않도록 설정하려면 다음 주석을 사용합니다.

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

다른 구성 옵션은 리디렉션을 통해 서버 쪽 HTTPS 적용을 검토하세요.

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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

다음은 이 주석을 사용한 수신 구성의 예입니다.

참고

DNS 호스트 이름으로 <Hostname>을 업데이트합니다. <IngressClassName>은 NginxIngressController를 만들 때 정의한 것입니다.

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

다음 단계

애플리케이션의 성능과 사용량 분석의 일환으로 Grafana에서 Prometheus를 사용하여 애플리케이션 라우팅 추가 항목에 포함된 Ingress-nginx 컨트롤러 메트릭을 모니터링하는 방법을 알아보세요.