Docker x509 인증서 오류 해결: unknown authority·사내 CA·프록시 점검 순서

AI로 제작한 개념 일러스트입니다. TLS 오류는 인증서를 검증하는 실행 환경과 신뢰 체인을 나누어 확인합니다.

Docker에서 x509: certificate signed by unknown authority 오류가 나타나면 비밀번호부터 바꾸기보다 어느 실행 주체가 TLS 인증서를 검증하지 못하는지 확인하세요. docker pull 단계의 데몬, Docker Desktop의 호스트 환경, 컨테이너 안의 프로그램은 인증서를 신뢰하는 위치가 다를 수 있습니다. 같은 주소가 브라우저에서 열린다는 사실만으로 Docker에서도 신뢰된다고 판단하기는 어렵습니다.

1. 오류가 발생한 위치부터 구분하기

이미지 다운로드가 실패했는지, 이미 실행된 컨테이너에서 사내 API 호출이 실패했는지 기록합니다. 첫 번째는 레지스트리와 Docker 실행 환경의 신뢰 설정을, 두 번째는 컨테이너·프로그램의 신뢰 저장소를 먼저 봅니다. 회사 HTTPS 검사 프록시를 통과할 때 제시되는 인증서가 외부망에서 받는 것과 다른지도 확인하세요. Docker CA 인증서 안내는 호스트와 컨테이너에 필요한 신뢰 설정을 구분합니다.

관찰한 상황	먼저 확인할 위치	확인 목적
docker pull에서 실패	실제 Docker 데몬·프록시 경로	레지스트리 인증서 체인을 신뢰하는지
컨테이너 안의 HTTPS만 실패	이미지·프로그램 신뢰 저장소	필요한 CA가 포함돼 있는지
회사망에서만 실패	HTTPS 검사 프록시와 승인된 사내 CA	다른 발급자로 보이는 이유
갱신 직후부터 실패	서버가 제공하는 체인과 접속 이름	중간 인증서·호스트 이름·기간 확인

2. 검증을 끄기 전에 인증서 정보를 관찰하기

아래는 로컬 파일과 연결 정보를 확인하는 예시입니다. registry.example.com:5000은 가상의 주소이며 실제 레지스트리의 이름·포트로 바꿔야 합니다. 인증서를 신뢰 목록에 추가하거나 운영 설정을 변경하는 명령은 아닙니다.

docker context show
openssl x509 -in approved-ca.crt -noout -subject -issuer -dates -fingerprint -sha256
openssl s_client -connect registry.example.com:5000 -servername registry.example.com -showcerts

첫 줄은 현재 Docker 문맥을 확인하는 용도입니다. 두 번째 줄은 이미 정식 경로로 받은 CA 파일 정보를 읽습니다. 세 번째 줄은 접속 대상이 제시하는 체인을 관찰하며, 출력이 나온 것만으로 신뢰 검증이 성공했다고 판단하면 안 됩니다. 요청한 호스트 이름, 발급자·기간, 제공된 체인과 오류 내용을 함께 기록하세요.

3. Linux Engine과 Docker Desktop 경로 구분

Docker 레지스트리 인증서 공식 문서는 네이티브 Linux Engine, rootless Linux, Windows Engine과 Docker Desktop의 경로를 구분합니다. 네이티브 Linux Engine의 대표적인 예는 아래와 같습니다. CA 파일은 .crt, 클라이언트 인증서는 .cert로 구분하므로 확장자를 바꾸는 것만으로 같은 용도가 되지는 않습니다.

/etc/docker/certs.d/registry.example.com:5000/ca.crt

# 주소에 포트를 쓰지 않는 기본 HTTPS 접속의 예
/etc/docker/certs.d/registry.example.com/ca.crt

이 경로를 모든 환경에 그대로 적용하지 마세요. Rootless Engine과 Docker Desktop은 별도 안내를 따라야 합니다. 현재 CLI가 원격 데몬을 가리킨다면 로컬 컴퓨터에 CA를 추가해도 원격 데몬의 신뢰 설정까지 바뀌는 것은 아닙니다. 변경 적용과 재시작 필요 여부는 해당 환경의 문서에 따라 계획합니다.

4. 사내 API가 컨테이너 안에서만 실패하는 예시

가상의 업무 API가 호스트에서는 열리지만 새 컨테이너 안에서는 인증서 오류를 낸다고 해 봅시다. 먼저 그 컨테이너가 사용하는 기본 이미지, CA 패키지와 프로그램의 신뢰 저장소를 확인합니다. 승인된 사내 CA가 이미지 빌드에 포함돼야 하는 환경이라면 이를 재현 가능한 빌드 과정에 반영하고, 새 이미지로 같은 요청을 시험합니다.

실행 중인 컨테이너에만 임시로 추가한 인증서는 컨테이너를 재생성하면 사라질 수 있습니다. 또한 운영체제 CA 저장소를 쓰지 않는 런타임은 프로그램별 설정이 필요할 수 있습니다. 장애 당시 조치와 영구 적용 방법을 구분해 기록하면 다음 배포에서 동일한 문제가 반복되는 것을 줄일 수 있습니다.

5. 자주 묻는 질문

insecure registry 설정으로 해결해도 되나요? 원인 진단을 끝내기 전에 TLS 검증을 완화하는 것을 기본 해결책으로 삼지 마세요. 서버 체인과 승인된 CA를 올바른 실행 환경에 연결하는 방식부터 검토합니다.

접속 중 내려받은 인증서를 바로 신뢰해도 되나요? 화면에 보이는 인증서만으로 신뢰를 결정하지 않습니다. 조직의 정식 배포 경로나 인증서 관리자에게 받은 CA와 지문을 확인해야 합니다.

인증서 만료도 같은 오류인가요? 실제 오류 문자열을 구분하세요. unknown authority, 기간 오류와 호스트 이름 불일치는 점검할 원인이 다릅니다. 이름과 체인을 함께 확인하는 이유입니다.

6. 수정 뒤에는 같은 경로로 재검증하기

처음 실패한 작업을 같은 Docker 문맥·네트워크·이미지로 다시 시험하고, 재생성 후에도 동작하는지 확인합니다. 서버 인증서 갱신 과정까지 점검하려면 기존 Certbot 인증서 갱신 실패 해결 글을 참고하세요. 오류를 숨기는 것보다 어떤 실행 주체가 어떤 CA를 신뢰해야 하는지 설명할 수 있어야 합니다.

자료 확인: 2026년 9월 28일. 제품 기능·요금·지원 범위는 변경될 수 있으므로 도입 직전 공식 문서와 해당 계정의 설정을 확인하세요.