사설 CA 로 발급한 인증서를 쓰는 레지스트리·프록시·방화벽에 AKS 노드가 붙어야 할 때 노드의 신뢰 저장소에 그 CA 를 넣어야 한다. AKS 는 이를 Custom CA Trust 기능으로 제공한다. 클러스터가 API 서버와 kubelet 사이 통신에 쓰는 클러스터 CA 와는 별개이고, 클러스터 CA 를 바꾸는 기능이 아니다.
가장 흔한 오해 하나를 먼저 짚는다. 이 기능이 넣는 CA 는 노드의 신뢰 저장소에만 들어간다. 파드 안의 컨테이너에는 반영되지 않으므로, 애플리케이션이 그 CA 를 믿게 하려면 이미지에 넣거나 시크릿으로 마운트하는 별도 작업이 필요하다.
PEM 인증서를 최대 10개까지 빈 줄로 구분해 한 파일에 담는다. 새 클러스터 기준으로 파일 내용은 35 KB 를 넘을 수 없다.
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
앞뒤 공백, 여분의 빈 줄, 인증서가 아닌 내용이 섞이면 failed to decode one of SecurityProfile.CustomCATrustCertificates to PEM after base64 decoding 로 실패한다. 줄 끝이 CRLF 여도 x509: certificate signed by unknown authority 로 이어지므로 LF 로 정규화해서 넣는다.
Azure CLI 2.72.0 이상에서 --custom-ca-trust-certificates 로 파일 경로를 준다.
# 새 클러스터
az aks create \
--resource-group <rg> \
--name <cluster> \
--node-count 2 \
--custom-ca-trust-certificates ./ca-bundle.pem \
--generate-ssh-keys
# 기존 클러스터
az aks update \
--resource-group <rg> \
--name <cluster> \
--custom-ca-trust-certificates ./ca-bundle.pem
이 명령은 모델 업데이트를 일으킨다. 모든 노드가 같은 CA 를 갖도록 AKS 가 새 노드를 만들고 기존 노드를 drain 후 삭제하므로, 운영 중이라면 노드 교체가 일어난다는 전제로 일정을 잡는다.
az aks show --resource-group <rg> --name <cluster> \
--query 'securityProfile.customCaTrustCertificates'
노드에 들어갔는데도 이미지 pull 이 계속 실패하면 containerd 가 새 인증서를 아직 읽지 않은 것이다. 노드 셸에서 다시 읽힌다.
systemctl restart containerd
Windows 노드 풀은 지원하지 않는다. 한 클러스터 안에서 노드 풀마다 다른 CA 를 넣는 것도 지원하지 않는다 — 클러스터 전체가 같은 묶음을 쓴다.
노드 풀 수준의 미리보기 속성 enableCustomCATrust 는 2026-09-14 자로 폐지됐다. 이 속성에 의존하던 노드 풀은 스케일이나 인증서 갱신에서 실패할 수 있으므로 --custom-ca-trust-certificates 방식으로 옮겨야 한다. 남아 있는 속성은 2025-08-02-preview API 로 끈다.
POOL_ID=$(az aks nodepool show --resource-group <rg> --cluster-name <cluster> \
--name <nodepool> --query id --output tsv)
az resource update --ids "$POOL_ID" \
--api-version 2025-08-02-preview \
--set properties.enableCustomCATrust=false