다음을 통해 공유

AKS(Azure Kubernetes Service)용 애플리케이션 라우팅 추가 기능을 사용하는 고급 NGINX 수신 컨트롤러 및 수신 구성

이 문서에서는 AKS(Azure Kubernetes Service)에 대한 애플리케이션 라우팅 추가 기능을 사용하여 수신 컨트롤러 및 수신 개체를 구성하는 두 가지 방법을 안내합니다.

필수 구성 요소

AKS 클러스터에 연결

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

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

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

NGINX 인그레스 컨트롤러에 대한 구성 속성

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

다음 표에서는 다음을 구성하도록 설정할 수 있는 속성을 나열합니다.NginxIngressController

분야 유형 설명 필수 기본값
controllerNamePrefix 문자열 관리되는 NGINX 인그레스 컨트롤러 리소스의 이름입니다. 예 nginx
customHTTPErrors array 오류가 있는 경우 기본 백 엔드로 보낼 오류 코드의 배열입니다. 아니오
defaultBackendService 객체 일치하지 않는 HTTP 트래픽을 라우팅하는 서비스입니다. 중첩된 속성을 포함합니다. 아니오
 name 문자열 서비스 이름입니다. 예
 namespace 문자열 서비스 네임스페이스입니다. 예
defaultSSLCertificate 객체 기본 백 엔드 서비스에 액세스하기 위한 기본 인증서를 포함합니다. 중첩된 속성을 포함합니다. 아니오
 forceSSLRedirect boolean 인증서가 설정되면 HTTPS 리디렉션을 강제합니다. 아니오 false
 keyVaultURI 문자열 인증서를 저장하는 Key Vault 비밀에 대한 URI입니다. 아니오
 secret 객체 기본 SSL 인증서에 대한 비밀 정보를 보유합니다. 중첩된 속성을 포함합니다. 아니오
  name 문자열 비밀 이름. 예
  namespace 문자열 비밀 네임스페이스입니다. 예
httpDisabled boolean 컨트롤러에 대한 HTTP 트래픽을 사용하지 않도록 설정하는 플래그입니다. 아니오
ingressClassName 문자열 컨트롤러에서 사용하는 IngressClass 이름입니다. 예 nginx.approuting.kubernetes.azure.com
loadBalancerAnnotations 객체 부하 분산 장치 주석을 설정하여 NGINX 수신 컨트롤러 서비스의 동작을 제어하는 ​​주석 맵 아니오
scaling 객체 컨트롤러 크기를 조정하기 위한 구성입니다. 중첩된 속성을 포함합니다. 아니오
 maxReplicas integer 복제본의 상한. 아니오 100
 minReplicas integer 복제본의 하한. 아니오 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 수신 컨트롤러는 내부 부하 분산 장치를 사용하여 생성됩니다. 사용자 지정 리소스를 외부로 만들기 위한 모든 주석 설정 변경 사항은 덮어쓰여집니다.
  • External: 외부 로드 밸런서를 사용하여 생성된 기본 NGINX 인그레스 컨트롤러입니다. NginxIngressController 사용자 지정 리소스에 대한 모든 주석 변경 내용을 내부로 만들기 위해 덮어씁니다.
  • AnnotationControlled (기본값): 기본 NGINX 수신 컨트롤러는 외부 부하 분산 장치를 사용하여 만들어집니다. 기본 NginxIngressController 사용자 지정 리소스를 편집하여 부하 분산 장치 주석을 구성할 수 있습니다.)

새 클러스터에서 기본 수신 컨트롤러 구성 제어

  • az aks create 명령과 --enable-app-routing 및 --app-routing-default-nginx-controller 플래그를 사용하여 새 클러스터에서 애플리케이션 라우팅을 활성화합니다. <DefaultIngressControllerType>를 기본 NGINX 수신 컨트롤러 구성 제어에 설명된 구성 옵션 중 하나로 설정해야 합니다.

    az aks create \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --location $LOCATION \
  --enable-app-routing \
  --app-routing-default-nginx-controller <DefaultIngressControllerType>

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

  • 플래그가 있는 az aks approuting update--nginx 명령을 사용하여 기존 클러스터에서 애플리케이션 라우팅 기본 인그레스 컨트롤러 구성을 업데이트합니다. <DefaultIngressControllerType>를 기본 NGINX 수신 컨트롤러 구성 제어에 설명된 구성 옵션 중 하나로 설정해야 합니다.

    az aks approuting update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --nginx <DefaultIngressControllerType>

또 다른 공용 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 수신 컨트롤러 만들기

  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 수신 컨트롤러 만들기

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

    az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION

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

    az network public-ip create \
  --resource-group $NETWORK_RESOURCE_GROUP \
  --name $PUBLIC_IP_NAME \
  --sku Standard \
  --allocation-method static

    참고

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

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

    CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --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 주석을 추가하면 가장 효율적인 Load Balancer 만들기가 보장되며 잠재적인 제한을 방지하기 위해 적극 권장됩니다.

    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: "$PUBLIC_IP_NAME"
    service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"

  5. kubectl apply 명령을 사용하여 NGINX 수신 컨트롤러 리소스를 생성합니다.

    kubectl apply -f nginx-staticip-controller.yaml

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

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

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

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

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME

    다음 예제 출력에서는 생성된 리소스를 보여줍니다. 컨트롤러를 사용할 수 있으려면 몇 분 정도 걸릴 수 있습니다.

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

인그레스 컨트롤러의 상태 보기

  • 수신 컨트롤러의 조건을 확인하여 kubectl get nginxingresscontroller 명령을 사용해 문제를 해결합니다.

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -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 --namespace hello-web-app-routing

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

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

관리형 인그레스가 생성되었는지 확인합니다.

  • kubectl get ingress 명령을 사용하여 관리형 인그레스가 생성되었는지 확인합니다.

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

    다음 예와 유사하게 출력됩니다.

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

인그레스 컨트롤러 제거

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

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을/를 사용합니다. 같은 HTTPSGRPC대체 백 엔드 프로토콜을 구성하려면 다음 주석 중 하나를 사용합니다.

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

# GRPC annotation
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(크로스-원본 자원 공유)

Ingress 규칙에서 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

NGINX 상태 프로브 경로 업데이트

NGINX 인그레스 컨트롤러와 연결된 Azure Load Balancer의 기본 상태 프로브 경로는 "/healthz"로 설정해야 합니다. 정상적인 상태 점검을 위해 인그레스 컨트롤러 서비스에 다음 주석이 있는지 확인합니다.

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Helm을 사용하여 NGINX Ingress 컨트롤러를 관리하는 경우, 값 파일에서 Azure Load Balancer의 상태 확인용 주석을 정의하고 업그레이드 시 이를 적용할 수 있습니다.

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

이 구성은 서비스 가용성을 유지하는 데 도움이 되며 업그레이드 중에 예기치 않은 트래픽 중단을 방지합니다.

다음 단계

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

  • Last updated on