AKS(Azure Kubernetes Service) 노드 NAP(자동 프로비저닝)에 대한 AKSNodeClass 리소스 구성

이 문서에서는 Karpenter를 사용하여 AKSNodeClass 리소스를 구성하여 AKS(Azure Kubernetes Service) NAP(노드 자동 프로비저닝)에 대한 Azure 관련 설정을 정의하는 방법을 설명합니다. AKSNodeClass 를 사용하면 VM(가상 머신) 이미지, 운영 체제(OS) 디스크 크기, 노드당 최대 Pod 및 kubelet 구성과 같이 Karpenter가 프로비전하는 노드의 다양한 측면을 사용자 지정할 수 있습니다.

중요합니다

November 30, 2025부터 AKS(Azure Kubernetes Service) 더 이상 Azure Linux 2.0에 대한 보안 업데이트를 지원하거나 제공하지 않습니다. Azure Linux 2.0 노드 이미지는 202512.06.0 릴리스에 고정되어 있습니다. 2026년 10월 31일부터 노드 이미지가 제거되며 노드 풀의 크기를 조정할 수 없습니다. 노드 풀을 지원되는 Kubernetes 버전으로 업그레이드하거나 osSku AzureLinux3 마이그레이션하여 지원되는 Azure Linux 버전으로 마이그레이션합니다. 자세한 내용은 GitHub 서비스 종료 이슈 및 Azure 업데이트 서비스 종료 공지를 참조하세요. 공지 사항 및 업데이트 소식을 접하려면 AKS 릴리스 정보를 참고하세요.

AKSNodeClass 리소스 개요

AKSNodeClass 리소스를 사용하면 NAP에 대한 Azure 관련 설정을 구성할 수 있습니다. 각 NodePool 리소스는 AKSNodeClass를 spec.template.spec.nodeClassRef 사용하여 참조해야 합니다. 동일한 NodePools 가리키는 여러 AKSNodeClass 사용하여 여러 노드 풀에서 공통 Azure 구성을 공유할 수 있습니다.

중요합니다

기존 AKSNodeClass에서 설정을 변경해도 실행 중인 노드가 다시 구성되지 않습니다. NAP는 이전 구성에서 프로비전된 노드를 드리프트됨으로 표시하고 참조하는 NodePool 리소스의 중단 제어에 따라 해당 노드를 대체합니다. 노드를 대체하지 않고 기존 Azure 리소스에 태그 변경 내용이 적용되므로 이 tags 필드는 유일한 예외입니다. 자세한 내용은 Drift 및 중단 예산을 참조하세요. 프로덕션 워크로드에서 사용하는 AKSNodeClass를 수정하기 전에 이 지침을 검토하세요.

이미지 패밀리 구성

imageFamily 필드는 AKSNodeClass를 통해 프로비저닝된 노드의 기본 VM 이미지와 부트스트래핑 로직을 설정합니다. 이미지 패밀리를 지정하지 않으면 Kubernetes 버전에 따른 기본 OS 버전이 사용됩니다. GPU는 호환되는 VM 크기의 두 이미지 패밀리에서 모두 지원됩니다. Kubernetes 버전당 기본 OS 버전에 대한 자세한 내용은 AKS OS 버전 설명서를 참조하세요.

지원되는 이미지 패밀리

  • Ubuntu: Ubuntu는 AKS 노드에 대한 기본 Linux 배포입니다.
    • OS 버전 기본값은 Kubernetes 버전에 따라 변경됩니다. Ubuntu 22.04는 Kubernetes 버전 1.25~1.33의 기본값입니다. Ubuntu 24.04는 Kubernetes 버전 1.34 이상에 대한 기본값입니다.
  • AzureLinux: Azure Linux는 AKS 워크로드에 대한 Microsoft 대체 Linux 배포판입니다. 자세한 내용은 Azure Linux 설명서를 참조하세요.

이미지 패밀리 구성 예제

다음 예제에서는 AKSNodeClass을(를) AzureLinux 이미지 패밀리를 사용하도록 구성합니다.

spec:
  imageFamily: AzureLinux

FIPS 규격 노드 이미지 구성

FIPS(Federal Information Processing Standards) 규격 노드 이미지를 사용하도록 설정할 수도 있습니다. AKS의 FIPS에 대한 자세한 내용은 FIPS 설명서를 참조하세요.

fipsMode 필드는 기본적으로 사용 안 함으로 설정되며 다음 옵션으로 설정할 수 있습니다.

  • FIPS - FIPS 규격 노드 이미지 선택
  • 사용 안 함 - FIPS 규격 노드 이미지 사용 안 함

다음 예제에서는 'AKSNodeClass'를 설정하여 fipsModeFIPS로 FIPS 규격 노드 이미지를 선택하도록 구성합니다.

spec:
  fipsMode: FIPS

아티팩트 스트리밍

아티팩트 스트리밍을 사용하면 컨테이너 이미지를 ACR(Azure Container Registry)에서 AKS(Azure Kubernetes Service) 스트리밍할 수 있습니다. AKS는 초기 Pod 시작에 필요한 계층만 끌어오기 때문에 워크로드를 배포하는 데 걸리는 시간이 줄어듭니다.

사전 요구 사항

  • 아티팩트 스트리밍을 사용하려면 AKS 클러스터와 통합된 프리미엄 계층 ACR이 있어야 합니다.
  • ACR에서 아티팩트 스트리밍을 사용하도록 설정해야 합니다.

ACR에서 아티팩트 스트리밍을 사용하도록 설정하는 방법에 대한 지침은 아티팩트 스트리밍 설명서를 참조하세요.

NAP 클러스터에서 아티팩트 스트리밍 사용

NAP(노드 자동 프로비저닝)가 사용하도록 설정된 클러스터는 AKSNodeClass CRD 필드를 사용하여 spec.artifactStreaming.enabled 아티팩트 스트리밍을 사용하도록 설정할 수 있습니다. 이 AKSNodeClass CRD와 연결된 새 노드 또는 기존 NAP 관리 노드에 아티팩트 스트리밍을 사용하도록 설정하려면 이 필드를 true 설정합니다.

apiVersion: karpenter.azure.com/v1beta1
kind: AKSNodeClass
metadata:
  name: my-node-class
spec:
  # Enables artifact streaming; To use this feature container images must also enable artifact streaming on ACR
  # Valid values: true, false; defaults to false if not specified
  artifactStreaming:
    enabled: 
      true

참고

AKS NAP 관리 노드에서 아티팩트 스트리밍을 사용하려면 ACR(Azure Container Registry)에서도 아티팩트 스트리밍을 사용하도록 설정해야 합니다. ACR에서 이 옵션을 설정하지 않으면 필드가 기본적으로 false로 설정됩니다.

VNet(가상 네트워크) 서브넷 구성

vnetSubnetID 필드는 노드 네트워크 인터페이스를 프로비전하는 데 사용해야 하는 Azure VNet 서브넷을 지정합니다. 이 필드는 선택적입니다. 서브넷을 지정하지 않으면 NAP는 Karpenter 설치 중에 구성된 기본 서브넷을 사용합니다. 자세한 내용은 NAP에 대한 서브넷 구성을 참조하세요.

서브넷 구성 예제

서브넷 ID는 다음 예제와 같이 ARM(전체 Azure Resource Manager) 형식이어야 합니다.

spec:
  vnetSubnetID: "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Network/virtualNetworks/{vnet-name}/subnets/{subnet-name}"

OS 디스크 크기 구성

osDiskSizeGB 필드는 OS 디스크의 크기를 기가바이트 단위로 지정합니다. 기본값은 128GB이고 최소값은 30GB입니다.

다음과 같은 워크로드에는 더 큰 OS 디스크 크기를 고려합니다.

  • 중요한 데이터를 로컬에 저장합니다.
  • 컨테이너 이미지에 대한 추가 공간이 필요합니다.
  • 디스크 I/O 요구 사항이 높습니다.

OS 디스크 크기 구성 예제

spec:
  osDiskSizeGB: 256  # 256 GB OS disk

임시 OS 디스크 구성

NAP는 사용 가능한 경우 임시 OS 디스크를 자동으로 사용하며 요청된 디스크 크기에 적합합니다. 임시 OS 디스크는 관리 디스크에 비해 성능이 더욱 향상되고 비용이 저렴합니다.

임시 디스크 선택 조건

시스템은 다음 시나리오에서 임시 디스크를 자동으로 선택합니다.

  • VM 인스턴스 유형은 임시 OS 디스크를 지원합니다.
  • 임시 디스크 용량이 요청 osDiskSizeGB된 디스크 용량보다 크거나 같습니다.
  • VM에는 충분한 임시 스토리지 용량이 있습니다.

이러한 조건이 충족되지 않으면 시스템은 다시 관리 디스크를 사용합니다.

임시 디스크 유형 및 우선 순위 지정

Azure VM에는 다양한 유형의 임시 스토리지가 있을 수 있습니다. 시스템은 다음 우선 순위 순서를 사용합니다.

  • NVMe 디스크(최고 성능)
  • 캐시 디스크(균형 잡힌 성능)
  • 리소스 디스크(기본 성능)

임시 디스크 구성 예제

다음 예제와 같이 노드 풀 요구 사항을 사용하여 노드에 충분한 임시 디스크 용량이 있는지 확인할 수 있습니다.

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: ephemeral-disk-pool
spec:
  template:
    spec:
      requirements:
        - key: karpenter.azure.com/sku-storage-ephemeralos-maxsize
          operator: Gt
          values: ["128"]  # Require ephemeral disk larger than 128 GB
      nodeClassRef:
        group: karpenter.azure.com
        kind: AKSNodeClass
        name: my-node-class
---
apiVersion: karpenter.azure.com/v1beta1
kind: AKSNodeClass
metadata:
  name: my-node-class
spec:
  osDiskSizeGB: 128  # This will use ephemeral disk if available and large enough

이 구성을 사용하면 임시 디스크가 128GB보다 큰 VM 인스턴스 유형만 선택되어 지정된 OS 디스크 크기에 대한 임시 디스크 사용이 보장됩니다.

최대 Pod 구성

maxPods 필드는 노드에서 예약할 수 있는 최대 Pod 수를 지정합니다. 이 설정은 클러스터 밀도와 네트워크 구성 모두에 영향을 줍니다.

최소값 maxPods 은 10이고 최대값은 250입니다.

에 대한 기본 동작 maxPods

기본 동작 maxPods 은 네트워크 플러그 인 구성에 따라 달라집니다. 다음 표에서는 기본값을 요약합니다.

네트워크 플러그 인 구성 노드당 기본값 maxPods
표준 네트워킹 (Azure CNI v1 또는 NodeSubnet) 30
Azure CNI 오버레이 네트워킹 사용 250
없음(네트워크 플러그 인 없음) 250
기타 구성 110(표준 Kubernetes 기본값)

최대 Pod 구성 예제

spec:
  maxPods: 50  # Allow up to 50 pods per node

LocalDNS 구성

LocalDNS는 워크로드에 가까운 DNS 쿼리를 확인하는 노드 수준 DNS 프록시를 배포하여 쿼리 대기 시간을 줄이고 일시적인 DNS 중단 중에 복원력을 향상합니다. 자세한 내용은 LocalDNS 설명서를 참조하세요. 기본적으로 LocalDNS는 사용 안 함으로 설정되며 다음 옵션으로 구성할 수 있습니다.

  • Disabled (기본값) - LocalDNS 기능을 사용하지 않도록 설정합니다. DNS 쿼리는 노드에서 로컬로 해결되지 않습니다.
  • Preferred - AKS는 노드 풀의 Kubernetes 버전에 따라 LocalDNS 사용을 관리합니다. 구성은 항상 유효성을 검사하고 포함하지만 올바른 Kubernetes 버전을 사용하지 않는 한 LocalDNS는 사용하도록 설정되지 않습니다.
  • Required - 모든 필수 구성 요소가 충족되면 LocalDNS가 노드 풀에 적용됩니다. 요구 사항이 충족되지 않으면 배포가 실패합니다.

LocalDNS 구성 예제

LocalDNS 구성(예: vnetDNSOverrides 및 kubeDNSOverrides.)을 사용자 지정할 수 있습니다. 지원되는 플러그 인에 대한 자세한 내용은 LocalDNS 사용자 지정을 참조하세요.

spec:
  localDNS:
    mode: Required
    vnetDNSOverrides:
      - zone: "."
        cacheDuration: "3600s"
        forwardDestination: VnetDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: PreferUDP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
      - zone: "cluster.local"
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: ForceTCP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
    kubeDNSOverrides:
      - zone: "."
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: PreferUDP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
      - zone: "cluster.local"
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: ForceTCP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"

기존 AKSNodeClass에서 LocalDNS 구성 업데이트

localDNS 설정은 다른 AKSNodeClass 설정과 마찬가지로 드리프트 검색에 참여합니다. 기존 노드가 이미 참조하는 spec.localDNS에서 AKSNodeClass을(를) 변경하면 NAP는 표준 Drift 메커니즘을 통해 변경 사항을 적용합니다. NAP는 기존 노드를 이미지로 다시 설치하지 않습니다.

다음 동작은 LocalDNS 모드 또는 재정의를 변경할 때(예: Disabled을(를) mode에서 Required로 변경할 때) 적용됩니다.

  • 새 노드: AKSNodeClass를 업데이트한 후 NAP에서 프로비저닝하는 모든 노드는 새 LocalDNS 구성을 사용합니다.
  • 기존 노드: NAP는 기록된 구성이 더 이상 AKSNodeClass와 일치하지 않으므로 기존 NodeClaim 개체를 드리프트됨으로 표시합니다. NAP는 새 LocalDNS 구성을 사용하는 대체 노드를 시작한 다음, 드리프트된 노드를 스케줄 불가 상태로 설정하고, 비우고, 제거합니다.
  • 이미지로 다시 설치 없음: AKS 관리 노드 풀에서 LocalDNS를 사용하도록 설정하면 풀의 모든 노드가 이미지로 다시 설치됩니다. NAP는 대신 노드를 대체합니다. 어느 쪽이든 영향을 받는 노드의 Pod는 축출되고 다시 스케줄되므로 동일한 워크로드 영향이 있음을 감안하세요.

중요합니다

또한 AKSNodeClass를 Preferred 또는 mode로 설정하면 해결된 Disabled 구성이 변경되고 기존 노드에 드리프트를 발생시킵니다. localDNS 섹션 내의 모든 변경 내용은 kubeDNSOverrides 및 vnetDNSOverrides 값 포함, 노드 교체를 유발합니다.

교체가 시작될 때

드리프트 평가 및 교체는 업데이트된 AKSNodeClass를 적용하는 즉시 시작됩니다. 대체는 표준 NAP 중단 수명 주기를 따르므로 속도 및 타이밍은 NodePool를 참조하는 AKSNodeClass 리소스에 대해 구성한 중단 컨트롤에 따라 달라집니다.

NAP에서 대체를 조정하는 방법

LocalDNS 변경으로 인한 드리프트는 다음 표에 설명된 표준 NAP 중단 컨트롤을 준수합니다.

제어 LocalDNS로 인한 대체에 미치는 영향
중단 예산 (spec.disruption.budgets) 비율은 NAP가 한 번에 교체하는 노드 수를 제한합니다. 예산을 정의하지 않으면 NAP는 기본적으로 nodes: 10%의 예산 하나를 사용하므로 노드 풀 노드의 최대 10%가 동시에 중단됩니다.
예산 schedule 및 duration 교체는 유지 관리 기간에만 수행되도록 제한합니다. nodes: "0"을 기간 외로 설정하여 교체를 차단합니다.
파드 중단 예산(PDB) 노드 드레인 중 적용. NAP는 PDB를 위반하는 Pod를 제거하는 대신 대기합니다.
karpenter.sh/do-not-disrupt 주석 주석이 추가된 Pod 및 노드를 드리프트를 포함하여 자발적인 중단에서 제외합니다.
terminationGracePeriod 캡 드레인 시간. 이 설정은 기간이 경과할 때 PDB 및 karpenter.sh/do-not-disrupt 주석을 무시합니다.

대체는 완전히 직렬도 아니고 완전히 병렬도 아닙니다. NAP는 드리프트된 노드를 제거하기 전에 교체 용량을 프로비전하지만 중단 예산이 설정한 제한까지 동일한 AKSNodeClass를 동시에 참조하는 여러 노드를 대체할 수 있습니다.

Warning

노드 풀에서 중단 예산을 정의하지 않고 워크로드에 대한 Pod 중단 예산을 정의하지 않으면 사용 중인 AKSNodeClass에서 localDNS을(를) 변경하면 애플리케이션 수준 보호 없이 한 번에 최대 10%의 노드가 중단되어 워크로드 가동 중지 시간이 발생할 수 있습니다. 프로덕션 클러스터에서 localDNS를 변경하기 전에 중요한 워크로드에 대한 PDB를 정의하고 보수적인 중단 예산을 설정합니다.

LocalDNS를 사용하도록 설정하면 가용성 위험을 줄일 수 있습니다

  1. 사용자 지정 DNS 서버가 노드 서브넷으로부터의 쿼리에 대해 UDP 및 TCP 포트 53 모두에서 응답하는지 확인합니다. 자세한 내용은 LocalDNS를 사용하도록 설정하기 전에 사용자 지정 DNS를 검증을 참조하세요.

  2. 모든 중요한 워크로드에 대한 Pod 중단 예산을 정의합니다.

  3. 다음 예제와 같이 NodePool을(를) 변경하기 전에 영향을 받는 AKSNodeClass 리소스에 대해 보수적인 중단 예산을 설정합니다.

    apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  disruption:
    budgets:
    - nodes: "1"   # Replace one node at a time

  4. localDNS 먼저 비프로덕션 AKSNodeClass 에 변경 사항을 적용하세요. 또는 LocalDNS를 사용하도록 설정된 AKSNodeClass를 만들고 이를 참조하는 NodePool로 워크로드를 마이그레이션합니다.

  5. 노드 클레임을 나열하여 교체 진행률을 모니터링합니다. 노드 클레임이 Drifted 상태 조건을 보고하지 않으면 교체가 완료됩니다.

    # List node claims and watch replacements appear as drifted nodes are removed
kubectl get nodeclaims

# Inspect the status conditions on a specific node claim
kubectl describe nodeclaim <nodeclaim-name>

  6. LocalDNS가 대체 노드에서 활성화되어 있는지 확인합니다. 자세한 내용은 LocalDNS 작동 확인을 참조하세요.

Kubelet 구성

kubelet 섹션에서는 노드 동작에 영향을 주는 다양한 kubelet 매개 변수를 구성할 수 있습니다. 이러한 매개 변수는 일반적인 kubelet 인수이므로 Azure 공급자는 단순히 노드의 kubelet에 전달합니다.

중요합니다

kubelet 설정을 신중하게 구성하고 먼저 비프로덕션 환경의 변경 내용을 테스트합니다.

CPU 관리

다음 설정은 kubelet에 대한 CPU 관리 동작을 제어합니다.

spec:
  kubelet:
    cpuManagerPolicy: "static"  # or "none"
    cpuCFSQuota: true
    cpuCFSQuotaPeriod: "100ms"
  • cpuManagerPolicy: kubelet에서 CPU 리소스를 할당하는 방법을 제어합니다. CPU 고정을 대기 시간에 민감한 워크로드에서 사용하려면 "static"로 설정하십시오.
  • cpuCFSQuota: CPU 제한을 지정하는 컨테이너에 대해 CPU 완전 공정 스케줄러(CFS) 할당량 적용을 사용하도록 설정합니다.
  • cpuCFSQuotaPeriod: CPU CFS 할당량 기간을 설정합니다.

이미지 가비지 수집

다음 설정은 kubelet에 대한 이미지 가비지 수집 동작을 제어합니다.

spec:
  kubelet:
    imageGCHighThresholdPercent: 85
    imageGCLowThresholdPercent: 80

이러한 설정은 kubelet이 컨테이너 이미지의 가비지 수집을 수행하는 시기를 제어합니다.

  • imageGCHighThresholdPercent: 이미지 가비지 수집을 트리거하는 디스크 사용 비율입니다.
  • imageGCLowThresholdPercent: 가비지 수집 후의 대상 디스크 사용 비율입니다.

토폴로지 관리

다음 설정은 kubelet에 대한 토폴로지 관리자 정책을 제어합니다.

spec:
  kubelet:
    topologyManagerPolicy: "best-effort"  # none, restricted, best-effort, single-numa-node

토폴로지 관리자는 CPU 및 디바이스(예: GPU) 리소스에서 대기 시간에 민감한 워크로드에 대한 리소스 할당을 조정하는 데 도움이 됩니다.

시스템 구성

다음 설정을 사용하면 kubelet에 대한 추가 시스템 매개 변수를 구성할 수 있습니다.

spec:
  kubelet:
    allowedUnsafeSysctls:
      - "kernel.msg*"
      - "net.ipv4.route.min_pmtu"
    containerLogMaxSize: "50Mi"
    containerLogMaxFiles: 5
    podPidsLimit: 4096
  • allowedUnsafeSysctls: Pod에서 사용할 수 있는 허용된 안전하지 않은 sysctls 목록입니다.
  • containerLogMaxSize: 회전 전 컨테이너 로그 파일의 최대 크기입니다.
  • containerLogMaxFiles: 보존할 컨테이너 로그 파일의 최대 수입니다.
  • podPidsLimit: 모든 Pod에서 허용되는 최대 프로세스 수입니다.

Linux 사용자 지정 OS 구성 설정

LinuxOSConfig 섹션에서는 노드 동작에 영향을 주는 다양한 kubelet 매개 변수를 구성할 수 있습니다. 이러한 매개 변수는 일반적인 사용자 지정 OS 인수이므로 NAP는 노드의 kubelet에 전달하기만 하면 됩니다.

사용자 지정 Linux OS 구성 설정, 기본값 및 고려 사항에 대한 자세한 내용은 사용자 지정 노드 구성 매개 변수 참조를 참조하세요.

중요합니다

Linux OS 설정을 신중하게 구성하고 먼저 비프로덕션 환경에서 변경 내용을 테스트합니다.

Linux 파일 핸들 제한 설정

다음 설정을 사용하여 파일 시스템 설정을 지정합니다.

spec:
  linuxOSConfig: 
    # Sysctl Settings  
    sysctls:  
      # File System Settings  
      fsFileMax: 2000000               # Range: 8192-12000500  Default: Max of available range
      fsInotifyMaxUserWatches: 1000000 # Range: 781250-2097152 Default: 1048576
      fsAioMaxNr: 1000000              # Range: 65536-6553500  Default: 65536
      fsNrOpen: 1000000                # Range: 8192-20000500  Default: 1048576

Linux 소켓 및 네트워크 튜닝 설정

다음 설정을 사용하여 TCP 및 네트워크 설정을 지정합니다.

spec:
  linuxOSConfig:
      # Network Settings  
      netCoreSomaxconn: 65535          # Range: 4096-3240000  Default: 16384
      netCoreNetdevMaxBacklog: 5000    # Range: 1000-3240000  Default: 1000
      netCoreRmemMax: 134217728        # Range: 212992-134217728  Default: 1048576
      netCoreOptmemMax: 102400         # Range: 20480-4194304     Default: 131072 
      netCoreWmemMax: 134217728        # Range: 212992-134217728  Default: 212992
      netCoreRmemDefault: 212992       # Range: 212992-134217728  
      netCoreWmemDefault: 212992       # Range: 212992-134217728  
      netIPv4IPLocalPortRange: "1024 65535" # Format: "first last", first: 1024-60999, last: 32768-65535  

      # Neighbor Table GC Thresholds  
      netIPv4NeighDefaultGcThresh1: 1024   # Range: 128-80000  Default: 4096
      netIPv4NeighDefaultGcThresh2: 2048   # Range: 512-80000  Default: 8192
      netIPv4NeighDefaultGcThresh3: 4096   # Range: 1024-80000  Default: 16384
      # Note: thresh1 <= thresh2 <= thresh3  

      # Connection Tracking  
      netNetfilterNfConntrackBuckets: 131072  # Range: 65536-524288   Default: dynamically calculated 
      netNetfilterNfConntrackMax: 262144       # Range: 131072-2097152 Default: dynamically calculated

Linux 작업자 제한 설정

다음 설정을 사용하여 커널 설정을 지정합니다.

spec:
  linuxOSConfig:
      # Kernel Settings  
      kernelThreadsMax: 100000         # Range: 20-513785  Default: Dynamically calculated

Linux 가상 메모리 설정

다음 옵션을 사용하여 Linux 커널의 Linux 가상 메모리 하위 시스템의 작업과 디스크에 더티 데이터의 쓰기를 조정합니다.

spec:
  linuxOSConfig:
      # Memory Management  
      vmMaxMapCount: 262144          # Range: 65530-262144 Default: Max of available range
      vmVfsCachePressure: 100        # Range: 0-100  Default: 100
      vmSwappiness: 60               # Range: 0-100  Default: 60

      # Swap File Configuration  
      swapFileSize: "2Gi"             # Default: (not set) | Pattern: quantity with units Note: Requires kubelet.failSwapOn: false  

      # Transparent Huge Pages  
      transparentHugePageEnabled: "madvise"    # Values: [always, madvise, never]  Default: always
      transparentHugePageDefrag: "defer+madvise" # Values: [always, defer, defer+madvise, madvise, never]  Default: madvise

GPU 설정

다음 필드를 사용하여 NVIDIA GPU 운영자와 같은 사용자 지정 GPU 드라이버 설치를 사용하도록 설정합니다.

spec:
  gpu:
    mode: 
      # acceptable values: [driver, none] default(or if not specified): driver
      # none skips gpu driver installation, driver has NAP manage the GPU driver installation  
      none

보안 설정

호스트에서 암호화

다음 필드는 프로비전된 노드에 호스트 수준 암호화를 사용할 수 있는지 여부를 지정합니다. 이 필드를 true설정하면 NAP에는 호스트에서 암호화를 지원하는 인스턴스 옵션만 포함됩니다.

spec:
  security:
    encryptionatHost: 
      # acceptable values: [true, false] default(or if not specified): false  
      false

호스트 기반 암호화에 대한 자세한 내용은 호스트의 암호화 설명서를 참조하세요.

사용자 지정 관리형 키 및 디스크 암호화 집합

NAP는 고객 관리형 키 및 디스크 암호화 집합을 사용하는 클러스터를 지원합니다. 클러스터 수준에서 이러한 옵션을 사용하도록 설정합니다. 설정해야 하는 필드가 없습니다 AKSNodeClass . 클러스터 ID에 적절한 RBAC(역할 기반 액세스 제어)가 있는지 확인합니다.

  • 클러스터 ID는 Reader 디스크 암호화 집합에 액세스할 수 있습니다.
  • 디스크 암호화 집합 리소스는 Azure Key Vault에 Key Vault Crypto Service Encryption User 액세스할 수 있습니다.

클러스터를 만드는 동안 사용하도록 설정된 고객 관리형 키 및 디스크 암호화 집합에 대한 자세한 내용은 Customer-Managed 키 설명서를 참조하세요.

NAP 클러스터에서 신뢰할 수 있는 시작 사용

NAP(노드 자동 프로비저닝)이 활성화된 클러스터는 AKSNodeClass CRD의 spec.security.trustedLaunch 필드를 사용하여 신뢰할 수 있는 시작을 활성화할 수 있습니다. 이 AKSNodeClass CRD와 연결된 새 노드 또는 기존 NAP 관리 노드에 대해 신뢰할 수 있는 시작을 사용하도록 secureBoot 및 vTPM 필드를 true로 설정합니다.

spec:
  security:
  # Enables trusted lunch
  # Valid values: true, false; defaults to false if not specified
     trustedLaunch:
       secureBoot: true
       vTPM: true

Azure 리소스 태그 구성

특정 AKSNodeClass 리소스를 사용하여 만든 모든 VM 인스턴스에 적용되는 Azure 리소스 태그를 지정할 수 있습니다. 태그는 비용 추적, 리소스 구성 및 규정 준수 요구 사항에 유용합니다.

태그 제한

  • Azure 리소스 태그는 리소스당 50개의 태그로 제한됩니다.
  • 태그 이름은 대/소문자를 구분하지 않지만 태그 값은 대/소문자를 구분합니다.
  • Azure 사용할 수 없는 일부 태그 이름을 예약합니다. 자세한 내용은 태그 지침 및 제한을 참조하세요.

예제 태그 구성

spec:
  tags:
    Environment: "production"
    Team: "platform"
    Application: "web-service"
    CostCenter: "engineering"

포괄적인 AKSNodeClass 구성 예제

다음 예제에서는 이 문서에서 설명하는 모든 설정을 포함하는 포괄적인 AKSNodeClass 구성을 보여 줍니다.

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      nodeClassRef:
        group: karpenter.azure.com
        kind: AKSNodeClass
        name: comprehensive-example
---
apiVersion: karpenter.azure.com/v1beta1
kind: AKSNodeClass
metadata:
  name: comprehensive-example
spec:
  # Image family configuration
  # Default: Ubuntu
  # Valid values: Ubuntu, AzureLinux, AzureContainerLinux
  imageFamily: Ubuntu

  # FIPS compliant mode - allows support for FIPS-compliant node images
  # Default: Disabled
  # Valid values: FIPS, Disabled
  fipsMode: Disabled

  # Artifact Streaming- allows use of artifact streaming feature; To use this feature container images must also enable artifact streaming on ACR
  # Valid values: true, false; defaults to false if not specified
  artifactStreaming:
    enabled: true

  # LocalDNS mode - allows use of LocalDNS feature
  # Default: Disabled
  # Valid values: Preferred, Required, Disabled
  # vnetDNSOverrides and kubeDNSOverrides are both required, even when mode is Disabled
  # Each list must include the "." and "cluster.local" zones, and each zone must set all nine fields
  localDNS:
    mode: Disabled
    # vnetDNSOverrides apply to DNS traffic from pods with dnsPolicy:default and from kubelet
    vnetDNSOverrides:
      - zone: "."
        cacheDuration: "3600s"
        forwardDestination: VnetDNS   # the "." zone can't forward to ClusterCoreDNS in vnetDNSOverrides
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: PreferUDP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
      - zone: "cluster.local"
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS   # cluster.local can't forward to VnetDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: ForceTCP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
    # kubeDNSOverrides apply to DNS traffic from pods with dnsPolicy:ClusterFirst
    kubeDNSOverrides:
      - zone: "."
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: PreferUDP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"
      - zone: "cluster.local"
        cacheDuration: "3600s"
        forwardDestination: ClusterCoreDNS
        forwardPolicy: Sequential
        maxConcurrent: 1000
        protocol: ForceTCP
        queryLogging: Error
        serveStale: Immediate
        serveStaleDuration: "3600s"

  # Virtual network subnet configuration (optional)
  # If not specified, uses the default --vnet-subnet-id from Karpenter installation
  vnetSubnetID: "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/my-rg/providers/Microsoft.Network/virtualNetworks/my-vnet/subnets/my-subnet"

  # OS disk size configuration
  # Default: 128 GB
  # Minimum: 30 GB
  osDiskSizeGB: 128

  # Maximum pods per node configuration
  # Default behavior depends on network plugin:
  # - Azure CNI with standard networking: 30 pods
  # - Azure CNI with overlay networking: 250 pods
  # - Other configurations: 110 pods
  # Range: 10-250
  maxPods: 30

  # GPU driver installation (optional)
  # Default: driver - NAP manages gpu driver installation
  # none skips gpu driver installation
  # Valid values: driver, none
  gpu:
    mode: 
      driver

  # Azure resource tags (optional)
  # Applied to all VM instances created with this AKSNodeClass
  tags:
    Environment: "production"
    Team: "platform-team"
    Application: "web-service"
    CostCenter: "engineering"

  # Kubelet configuration (optional)
  # All fields are optional with sensible defaults
  kubelet:
    # CPU management policy
    # Default: "none"
    # Valid values: none, static
    cpuManagerPolicy: "static"

    # CPU CFS quota enforcement
    # Default: true
    cpuCFSQuota: true

    # CPU CFS quota period
    # Default: "100ms"
    cpuCFSQuotaPeriod: "100ms"

    # Image garbage collection thresholds
    # imageGCHighThresholdPercent must be greater than imageGCLowThresholdPercent
    # Range: 0-100
    imageGCHighThresholdPercent: 85
    imageGCLowThresholdPercent: 80

    # Topology manager policy
    # Default: "none"
    # Valid values: none, restricted, best-effort, single-numa-node
    topologyManagerPolicy: "best-effort"

    # Allowed unsafe sysctls (optional)
    # Comma-separated list of unsafe sysctls or patterns
    allowedUnsafeSysctls:
      - "kernel.msg*"
      - "net.ipv4.route.min_pmtu"

    # Container log configuration
    # containerLogMaxSize default: "50Mi"
    containerLogMaxSize: "50Mi"
    
    # containerLogMaxFiles default: 5, minimum: 2
    containerLogMaxFiles: 5

    # Pod process limits
    # Default: -1 (unlimited)
    podPidsLimit: 4096

  security:
  # Enables trusted lunch
  # Valid values: true, false; default(or if not specified): false  
     trustedLaunch:
      secureBoot: true
      vTPM: true
  # Encryption at host
     encryptionatHost: 
      # acceptable values: [true, false] default(or if not specified): false  
      false

다음 단계

AKS의 노드 자동 프로비저닝에 대한 자세한 내용은 다음 문서를 참조하세요.

  • 에 마지막으로 업데이트됨