Helm 기반 Jenkins 설치 시 InitContainer 실패 원인 분석 및 해결

문제 현상

Helm chart를 사용해 Jenkins를 AKS에 배포하려고 했으나, jenkins-0 Pod의 InitContainer 단계에서 이미지 풀(Pull)에 실패하는 문제가 발생했다.

Warning  Failed     kubelet  Failed to pull image "acrcloudbizcombase.azurecr.io/jenkins/jenkins-master:2.462.1-x-az-lts": 
rpc error: code = NotFound desc = failed to pull and unpack image ...
401 Unauthorized

❌ 잘못된 Base Image 사용

초기에 사용한 Dockerfile은 아래와 같았다.

FROM jenkins/inbound-agent:3261.v9c670a_4748a_9-1

이 이미지(jenkins/inbound-agent)는 Jenkins 에이전트용 이미지로, Jenkins Core(war 파일, 기본 설정 등)가 포함되지 않은 슬림한 에이전트 전용 이미지이다.

하지만 Helm chart는 Jenkins Controller(마스터)로 실행될 수 있는 이미지 구조를 필요로 한다.
즉, install-plugins.sh, /usr/share/jenkins/jenkins.war, 기본 초기화 스크립트 등 다양한 Jenkins 컨트롤러 컴포넌트가 포함되어 있어야 한다.

그래서 위 이미지를 기반으로 생성한 ACR 이미지는 Helm chart와 맞지 않아 init 컨테이너가 실패하게 되었던 것이다.

 

해결 방법

✔️ 올바른 Base Image 사용

Dockerfile을 아래처럼 수정하여 Jenkins 공식 Controller 이미지(jenkins/jenkins)를 사용한다.

FROM jenkins/jenkins:2.462.1-jdk17

USER root

# install plugin installer
RUN curl -sL https://raw.githubusercontent.com/jenkinsci/docker/master/install-plugins.sh \
    -o /usr/local/bin/install-plugins.sh && chmod +x /usr/local/bin/install-plugins.sh

# 필요한 패키지 설치
RUN apt-get update && apt-get install -y docker.io unzip curl vim jq

USER jenkins

 

그리고 아래 명령어로 linux/amd64 아키텍처로 빌드하여 ACR에 push한다.

docker buildx build \
  --platform linux/amd64 \
  -t acrcloudbizcombase.azurecr.io/jenkins/jenkins-master:2.462.1-x-az-lts \
  -f jenkins-controller.Dockerfile \
  --push .

TIP: buildx imagetools inspect 명령어로 빌드된 이미지에 linux/amd64 플랫폼이 포함되어 있는지 확인하자.

 

🔐 ACR 권한 문제 해결

AKS가 ACR에서 이미지를 pull 하려면, 다음 중 하나가 설정되어 있어야 한다.

• AKS에 할당된 Managed Identity에 ACR의 AcrPull 역할 할당
• Secret (imagePullSecret) 을 생성하여 Helm values.yaml에 등록

az role assignment create \
  --assignee <AKS_MANAGED_IDENTITY_PRINCIPAL_ID> \
  --role acrpull \
  --scope $(az acr show --name acrcloudbizcombase --query id -o tsv)

or

kubectl create secret docker-registry acr-auth \
  --docker-server=acrcloudbizcombase.azurecr.io \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=you@example.com \
  -n jenkins

 

그리고 values.yaml에 추가

controller:
  imagePullSecretName: acr-auth

 

 

처음엔 잘 되던 이미지가 Helm 기반 설치에선 실패해서 원인 파악이 어려웠지만,
에이전트 이미지와 컨트롤러 이미지의 차이를 정확히 이해한 덕분에 문제를 해결할 수 있었다.