Harbor Garbage Collection(GC) 오류 해결 방법

Overview

이 글에서는 Harbor의 Garbage Collection(GC) 실행 시 발생하는 에러를 트러블슈팅한 과정을 공유한다.

Harbor는 사용되지 않는 이미지와 태그를 정리하기 위해 Garbage Collection 기능을 제공하지만, GC 실행 중 registryctl 컨테이너와의 통신 오류로 인해 실패하는 경우가 발생할 수 있다.

 

해당 사례에서는 registryctl 컨테이너가 누락되어 있었고, 이로 인해 GC가 실행되지 못하고 실패하였다.
이 문제를 해결하기 위해 로그 확인, 컨테이너 상태 점검, 누락된 컨테이너 재기동 등을 수행하였으며, 최종적으로 GC 작업을 정상적으로 완료할 수 있었다.

 

 

 

 

 

 

 

---

 

 

 

Harbor Garbage Collection(GC) Error

 

 

 

Garbage Collection 실행을 한다.

 

 

 

 

Garbage Collection을 실행했지만 Status Error 가 발생했다.

 

 

 

 

Logs 부분을 클릭하면 에러코드를 확인할 수 있다.

 

 

 

 

코드를 확인해보면, gc를 실행하는 registry controller에 도달하지 못했다고 나온다. 즉 통신이 제대로 되지 않는 것으로 보인다.

2024-04-22T07:52:19Z [ERROR] [/jobservice/job/impl/gc/garbage_collection.go:105]: failed to start gc as registry controller is unreachable: failed to connect to tcp:registryctl:8080 after 60 seconds

 

 

 

 

현재 harbor는 docker-compose를 사용하여 내부서버에 컨테이너로 올라가 있다. 컨테이너를 확인해본다.

sudo docker-compose ps
      Name                     Command                  State                                          Ports
------------------------------------------------------------------------------------------------------------------------------------------------
harbor-core         /harbor/entrypoint.sh            Up (healthy)
harbor-db           /docker-entrypoint.sh 96 13      Up (healthy)
harbor-jobservice   /harbor/entrypoint.sh            Up (healthy)
harbor-log          /bin/sh -c /usr/local/bin/ ...   Up (healthy)   127.0.0.1:1514->10514/tcp
harbor-portal       nginx -g daemon off;             Up (healthy)
nginx               nginx -g daemon off;             Up (healthy)   0.0.0.0:80->8080/tcp,:::80->8080/tcp, 0.0.0.0:443->8443/tcp,:::443->8443/tcp
redis               redis-server /etc/redis.conf     Up (healthy)
registry            /home/harbor/entrypoint.sh       Up (healthy)

 

 

 

 

registryctl 컨테이너가 보이지 않는다!?  따라서 컨테이너 실행을 시켜줘야 한다.

sudo docker-compose up -d registryctl
Pulling registryctl (goharbor/harbor-registryctl:v2.3.0)...
v2.3.0: Pulling from goharbor/harbor-registryctl
7ec05e6a2d8c: Pull complete
acc0b9cd8517: Pull complete
9bc85802f5be: Pull complete
f93a60679062: Pull complete
d84a1c710a6e: Pull complete
75303d372b52: Pull complete
21417a3de3aa: Pull complete
Digest: sha256:30b402c0603428daa1c0feb47a490381fd6fe033bcc6e8eb8cbabc5b809865fe
Status: Downloaded newer image for goharbor/harbor-registryctl:v2.3.0
harbor-log is up-to-date
Creating registryctl ... done

 

 

 

 

컨테이너 상태를 확인한다.

docker ps
CONTAINER ID   IMAGE                                COMMAND                  CREATED         STATUS                            PORTS
                    NAMES
99ad5b20eb95   goharbor/harbor-registryctl:v2.3.0   "/home/harbor/start.…"   4 seconds ago   Up 2 seconds (health: starting)
                    registryctl
958ec3494eef   goharbor/harbor-jobservice:v2.3.0    "/harbor/entrypoint.…"   15 months ago   Up 3 months (healthy)
                    harbor-jobservice
1dc3e5ff4291   goharbor/nginx-photon:v2.3.0         "nginx -g 'daemon of…"   15 months ago   Up 3 months (healthy)             0.0.0.0:80->8080/tcp, :::80->8080/tcp, 0.0.0.0:443->8443/tcp, :::443->8443/tcp   nginx
830360c63440   goharbor/harbor-core:v2.3.0          "/harbor/entrypoint.…"   15 months ago   Up 3 months (healthy)
                    harbor-core
0e5f27f5a617   goharbor/registry-photon:v2.3.0      "/home/harbor/entryp…"   15 months ago   Up 3 months (healthy)
                    registry
3067b8f69d80   goharbor/redis-photon:v2.3.0         "redis-server /etc/r…"   15 months ago   Up 3 months (healthy)
                    redis
fa1a9855fc07   goharbor/harbor-db:v2.3.0            "/docker-entrypoint.…"   15 months ago   Up 3 months (healthy)
                    harbor-db
66ae775b1923   goharbor/harbor-portal:v2.3.0        "nginx -g 'daemon of…"   15 months ago   Up 3 months (healthy)
                    harbor-portal
873895d196bd   goharbor/harbor-log:v2.3.0           "/bin/sh -c /usr/loc…"   15 months ago   Up 3 months (healthy)             127.0.0.1:1514->10514/tcp
                    harbor-log

 

 

 

 

그리고 다시 GC를 실행해본다.

 

 

 

성공적으로 실행되었고 Status가 SUCCESS로 변경되었다. 그리고 로그를 확인해봐도 잘 작동하고 있다.

 

 

 

 

 

---

 

 

 

마무리 

Harbor의 Garbage Collection은 저장소의 불필요한 리소스를 정리하고 스토리지를 최적화하기 위한 중요한 기능이다.

이번 경험을 통해 다음과 같은 점을 다시금 확인할 수 있었다.

• GC 실행 오류가 발생하면 Job Logs에서 원인을 구체적으로 확인할 수 있다.
• registryctl은 GC를 포함한 여러 기능에서 핵심 역할을 하므로, 해당 컨테이너의 상태를 반드시 점검해야 한다.
• docker-compose 환경에서는 필요한 모든 서비스가 정상적으로 실행 중인지 확인하는 것이 기본이지만 매우 중요하다.
• GC 실패 시 무작정 재시도하지 말고, 로그 기반의 원인 분석 → 서비스 확인 → 컨테이너 재기동의 순서로 점검하는 것이 좋다.

 

 

이번 트러블슈팅은 단순한 오류 해결을 넘어 Harbor 내부 구성에 대한 이해를 높일 수 있는 좋은 기회였다.

운영 환경에서 안정적인 이미지 관리와 클린업을 위해 Garbage Collection의 동작 방식과 의존 서비스(registryctl 등)를 미리 점검해두는 것이 중요하다.