애플리케이션 라우팅 추가 항목을 사용하는 고급 NGINX 수신 컨트롤러 및 수신 구성
애플리케이션 라우팅 추가 항목은 수신 컨트롤러 및 수신 개체를 구성하는 두 가지 방법을 지원합니다.
- 여러 컨트롤러 만들기, 프라이빗 부하 분산 장치 구성, 고정 IP 주소 설정과 같은 NGINX 수신 컨트롤러 구성
- 주석을 통한 수신 리소스별 구성
필수 조건
애플리케이션 라우팅 추가 항목이 있는 AKS 클러스터
AKS 클러스터에 연결
로컬 컴퓨터에서 Kubernetes 클러스터에 연결하려면 Kubernetes 명령줄 클라이언트인 kubectl을 사용합니다. az aks install-cli 명령을 사용하여 로컬로 설치할 수 있습니다. Azure Cloud Shell을 사용하는 경우 kubectl이 이미 설치되어 있습니다.
az aks get-credentials 명령을 사용하여 Kubernetes 클러스터에 연결하도록 kubectl을 구성합니다.
az aks get-credentials --resource-group <ResourceGroupName> --name <ClusterName>
NGINX 수신 컨트롤러 구성
애플리케이션 라우팅 추가 항목은 NginxIngressController라는 Kubernetes CRD(사용자 지정 리소스 정의)를 사용하여 NGINX 수신 컨트롤러를 구성합니다. 더 많은 수신 컨트롤러를 만들거나 기존 구성을 수정할 수 있습니다.
다음은 구성하도록 설정할 수 있는 속성에 대한 참조입니다 NginxIngressController.
| 속성 | 설명 |
|---|---|
| ingressClassName | NGINX 수신 컨트롤러에 사용할 이름 IngressClass 입니다. 기본값은 지정되지 않은 경우의 NginxIngressController 이름으로 설정됩니다. |
| controllerNamePrefix | 관리되는 NGINX 수신 컨트롤러 리소스의 접두사를 지정하는 데 사용되는 이름입니다. 기본값은 nginx입니다. |
| loadBalancerAnnotations | 부하 분산 장치 주석을 설정 하여 NGINX 수신 컨트롤러 서비스의 동작을 제어하는 주석 집합 |
| 스케일링 | NGINX 수신 컨트롤러의 크기를 조정하는 방법에 대한 구성 옵션입니다. |
| scaling.minReplicas | 수신 컨트롤러 복제본 수에 대한 하한입니다. 기본값은 2개의 Pod입니다. |
| scaling.maxReplicas | 수신 컨트롤러 복제본 수의 상한입니다. 기본값은 100개의 Pod입니다. |
| scaling.threshold | 워크로드에 따라 NGINX 수신 컨트롤러 Pod의 크기를 얼마나 빨리 조정해야 하는지 정의합니다. Rapid 는 수신 컨트롤러가 갑작스럽고 중요한 트래픽 급증을 처리하기 위해 신속하고 적극적으로 확장될 것임을 의미합니다. Steady 는 더 많은 작업을 처리하는 복제본을 줄이면 비용 효율성을 우선합니다. Balanced 는 대부분의 사용 사례에 적합한 두 가지 조합입니다. 지정되지 않은 경우 이 필드는 기본적으로 .로 설정 Balanced됩니다. |
| defaultBackendService | NGINX 수신 컨트롤러가 기본적으로 처리해야 하는 Kubernetes 서비스는 모든 URL 경로를 처리하고 수신-NGINX 컨트롤러가 이해하지 못하는 호스트(예: 수신과 매핑되지 않은 모든 요청)입니다. 컨트롤러는 트래픽을 서비스의 첫 번째 포트로 전달합니다. 지정하지 않으면 기본 제공 백 엔드를 사용합니다. |
| defaultBackendService.namespace | 서비스의 네임스페이스입니다. |
| defaultBackendService.name | 서비스의 이름입니다. |
| defaultSSLCertificate | 이 속성에서 참조하는 비밀에는 기본 백 엔드 서비스에 액세스할 때 사용할 기본 인증서가 포함됩니다. 이 속성이 제공되지 않으면 NGINX는 자체 서명된 인증서를 사용합니다. 섹션이 tls: 수신에 설정되지 않은 경우 NGINX는 기본 인증서를 제공하지만 HTTPS 리디렉션을 강제하지는 않습니다. |
| defaultSSLCertificate.forceSSLRedirect | 섹션을 지정하지 않는 수신에 대한 리디렉션을 tls: 강제로 수행합니다. |
| defaultSSLCertificate.keyVaultURI | 기본 SSL 인증서를 찾을 수 있는 Azure Key Vault URI입니다. 키 자격 증명 모음을 사용하도록 추가 기능을 구성해야 합니다. |
| defaultSSLCertificate.secret | 기본 SSL 비밀이 클러스터에 있는 이름과 네임스페이스를 구성합니다. |
| defaultSSLCertificate.secret.name | 비밀 이름입니다. |
| defaultSSLCertificate.secret.namespace | 비밀의 네임스페이스입니다. |
일반 구성
기본 NGINX 수신 컨트롤러 구성 제어(미리 보기)
참고 항목
추가 기능을 사용하도록 설정할 때 NGINX 수신 컨트롤러 구성 제어는 Kubernetes 버전 1.30 이상 및 aks-preview Azure CLI 확장 버전 7.0.0b5 이상에서 API 2024-06-02-preview사용할 수 있습니다. AKS 클러스터 버전을 확인하려면 사용 가능한 AKS 클러스터 업그레이드 확인을 참조하세요.
NGINX를 사용하여 애플리케이션 라우팅 추가 항목을 사용하도록 설정하면 공용 Azure 부하 분산 장치로 구성된 app-routing-namespace에 default라는 수신 컨트롤러가 생성됩니다. 해당 수신 컨트롤러는 webapprouting.kubernetes.azure.com이라는 수신 클래스 이름을 사용합니다.
기본값이 공용 또는 내부 IP를 가져오는지 또는 추가 기능을 사용하도록 설정할 때 생성되는지 여부를 제어할 수도 있습니다.
가능한 구성 옵션은 다음과 같습니다.
None: 기본 Nginx 수신 컨트롤러가 만들어지지 않으며 이미 있는 경우 삭제되지 않습니다. 원하는 경우 사용자는 기본NginxIngressController사용자 지정 리소스를 수동으로 삭제해야 합니다.Internal: 기본 Nginx 수신 컨트롤러는 내부 부하 분산 장치를 사용하여 생성됩니다. 외부로 만들기 위해 사용자 지정 리소스에NginxIngressController대한 주석 변경 내용은 덮어씁니다.External: 외부 부하 분산 장치로 만든 기본 Nginx 수신 컨트롤러입니다. 내부로 만들기 위해 사용자 지정 리소스에NginxIngressController대한 주석 변경 내용은 덮어씁니다.AnnotationControlled(기본값): 기본 Nginx 수신 컨트롤러는 외부 부하 분산 장치를 사용하여 만들어집니다. 사용자는 기본NginxIngressController사용자 지정 리소스를 편집하여 부하 분산 장치 주석을 구성할 수 있습니다.
클러스터를 만들 때 기본 수신 컨트롤러 구성 제어
새 클러스터에서 애플리케이션 라우팅을 사용하도록 설정하려면 명령을 사용하여 az aks create 플래그와 --app-routing-default-nginx-controller 플래그를 --enable-app-routing 지정합니다. 앞에서 설명한 <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>
또 다른 공용 NGINX 수신 컨트롤러 만들기
공용 Azure Load Balancer를 사용하여 또 다른 NGINX 수신 컨트롤러를 만들려면 다음을 수행합니다.
다음 YAML 매니페스트를 nginx-public-controller.yaml이라는 새 파일에 복사하고 파일을 로컬 컴퓨터에 저장합니다.
apiVersion: approuting.kubernetes.azure.com/v1alpha1 kind: NginxIngressController metadata: name: nginx-public spec: ingressClassName: nginx-public controllerNamePrefix: nginx-publickubectl apply명령을 사용하여 NGINX 수신 컨트롤러 리소스를 생성합니다.kubectl apply -f nginx-public-controller.yaml다음 예제 출력은 생성된 리소스를 보여줍니다.
nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
개인 IP 주소를 사용하여 내부 NGINX 수신 컨트롤러 만들기
개인 IP 주소가 있는 내부 연결 Azure Load Balancer를 사용하여 NGINX 수신 컨트롤러를 만들려면 다음을 수행합니다.
다음 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"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 수신 컨트롤러를 만들려면 다음을 수행합니다.
az group create명령을 사용하여 Azure 리소스 그룹을 만듭니다.az group create --name myNetworkResourceGroup --location eastusaz network public ip create명령을 사용하여 고정 공용 IP 주소를 만듭니다.az network public-ip create \ --resource-group myNetworkResourceGroup \ --name myIngressPublicIP \ --sku Standard \ --allocation-method static참고 항목
AKS 클러스터에서 기본 SKU 부하 분산 장치를 사용하는 경우, 공용 IP를 정의할 때
--sku매개 변수에 Basic을 사용합니다. 기본 SKU IP만 기본 SKU 부하 분산 장치에서 작동하며, 표준 SKU IP만 표준 SKU 부하 분산 장치에서 작동합니다.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}다음 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"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
수신에서 수신 컨트롤러 사용
다음 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: Prefixkubectl 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 수신 컨트롤러를 제거할 수 있습니다.
참고 항목
NginxIngressController를 만들 때 사용한 이름으로 <IngressControllerName>을 업데이트합니다.
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 컨트롤러 메트릭을 모니터링하는 방법을 알아보세요.
Azure Kubernetes Service