3단계 가져오기

요약

기존 컨테이너 레지스트리 메타데이터를 가져옵니다. 사용자는 1단계 가져오기가 시간당 2~4 TB 속도로 완료되었다고 보고했습니다. 1단계가 완료되는 동안 레지스트리를 정상적으로 계속 사용할 수 있습니다. /etc/gitlab/gitlab.rb 파일의 database 섹션에서 데이터베이스가 비활성화되어 있는지 확인합니다:

기존 컨테이너 레지스트리 메타데이터를 가져옵니다. 다음 절차는 대규모 레지스트리(200 GiB 이상)이거나 가져오기를 완료하는 동안 다운타임을 최소화하려는 경우에 권장됩니다.

저장소 사전 가져오기 (1단계)#

사용자는 1단계 가져오기가 시간당 2~4 TB 속도로 완료되었다고 보고했습니다. 느린 속도에서는 100TB 이상의 데이터가 있는 레지스트리는 48시간 이상이 걸릴 수 있습니다.

1단계가 완료되는 동안 레지스트리를 정상적으로 계속 사용할 수 있습니다.

/etc/gitlab/gitlab.rb 파일의 database 섹션에서 데이터베이스가 비활성화되어 있는지 확인합니다:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```
파일을 저장하고 GitLab을 재구성합니다.
데이터베이스 마이그레이션을 적용합니다.

가져오기를 시작하는 첫 번째 단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-one --log-to-stdout

/etc/gitlab/gitlab.rb 파일의 database 섹션에서 데이터베이스가 비활성화되어 있는지 확인합니다:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```
파일을 저장하고 GitLab을 재구성합니다.
데이터베이스 마이그레이션을 적용합니다.

가져오기를 시작하는 첫 번째 단계를 실행합니다:

sudo -u registry gitlab-ctl registry-database import --step-one --log-to-stdout

사전 요건:

외부 데이터베이스를 생성합니다.

/etc/gitlab/gitlab.rb 파일에 database 섹션을 추가하되, 메타데이터 데이터베이스가 비활성화된 상태로 시작합니다:

registry['database'] = {
  'enabled' => false, # Must be false!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

파일을 저장하고 GitLab을 재구성합니다.
아직 완료하지 않은 경우 데이터베이스 마이그레이션을 적용합니다.
가져오기를 시작하는 첫 번째 단계를 실행합니다:
```
sudo gitlab-ctl registry-database import --step-one
```

Note

필요한 다운타임 양을 줄이기 위해 가능한 한 빨리 다음 단계를 예약해야 합니다. 1단계 완료 후 이상적으로 1주일 이내에 진행하십시오. 1단계와 2단계 사이에 레지스트리에 기록된 새 데이터가 많을수록 2단계에 더 많은 시간이 걸립니다.

모든 저장소 데이터 가져오기 (2단계)#

이 단계에서는 레지스트리를 종료하거나 read-only 모드로 설정해야 합니다. 하지만 이 단계는 1단계보다 약 90% 빠르게 완료될 것으로 예상됩니다. 2단계가 실행되는 동안 다운타임을 위한 충분한 시간을 허용하십시오.

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-two --log-to-stdout

명령이 성공적으로 완료되면 모든 이미지가 완전히 가져와집니다. 이제 데이터베이스를 활성화하고, 구성에서 읽기 전용 모드를 해제하고, 레지스트리 서비스를 시작할 수 있습니다:

registry['database'] = {
  'enabled' => true, # Must be set to true!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo -u registry gitlab-ctl registry-database import --step-two --log-to-stdout

registry['database'] = {
  'enabled' => true, # Must be set to true!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-two

registry['database'] = {
  'enabled' => true, # Must be set to true!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

이제 모든 작업에 메타데이터 데이터베이스를 사용할 수 있습니다!

나머지 데이터 가져오기 (3단계)#

레지스트리가 이제 메타데이터에 데이터베이스를 완전히 사용하고 있지만, 잠재적으로 사용되지 않는 레이어 Blob에 대한 액세스 권한이 아직 없어 온라인 가비지 컬렉터가 이러한 Blob을 제거하지 못합니다.

3단계가 완료되는 동안 레지스트리를 정상적으로 계속 사용할 수 있습니다.

프로세스를 완료하려면 마이그레이션의 마지막 단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-three --log-to-stdout

sudo -u registry gitlab-ctl registry-database import --step-three --log-to-stdout

sudo gitlab-ctl registry-database import --step-three

해당 명령이 성공적으로 종료되면 레지스트리 메타데이터가 데이터베이스로 완전히 가져와집니다.

가져오기 후#

대규모 레지스트리는 가져오기 후 가비지 컬렉션 검토를 위해 수십만에서 수백만 개의 blob이 대기열에 추가될 수 있습니다. 이는 정상이며 기본 워커 간격으로는 처리에 시간이 걸립니다.

예상 동작과 처리 속도를 높이는 방법에 대한 안내는 다음을 참조하세요:

가져오기 후 - 가져오기 완료 후 예상 동작 개요.
온라인 가비지 컬렉션 상태 확인 - 가비지 컬렉션 검토 대기열을 모니터링합니다.
가비지 컬렉터 워커 간격 조정 - 대규모 백로그 처리를 일시적으로 가속화합니다.

3단계 가져오기

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

저장소 사전 가져오기 (1단계)#

1단계가 완료되는 동안 레지스트리를 정상적으로 계속 사용할 수 있습니다.

/etc/gitlab/gitlab.rb 파일의 database 섹션에서 데이터베이스가 비활성화되어 있는지 확인합니다:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```
파일을 저장하고 GitLab을 재구성합니다.
데이터베이스 마이그레이션을 적용합니다.

가져오기를 시작하는 첫 번째 단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-one --log-to-stdout

/etc/gitlab/gitlab.rb 파일의 database 섹션에서 데이터베이스가 비활성화되어 있는지 확인합니다:
```
registry['database'] = {
  'enabled' => false, # Must be false!
}
```
파일을 저장하고 GitLab을 재구성합니다.
데이터베이스 마이그레이션을 적용합니다.

가져오기를 시작하는 첫 번째 단계를 실행합니다:

sudo -u registry gitlab-ctl registry-database import --step-one --log-to-stdout

사전 요건:

외부 데이터베이스를 생성합니다.

/etc/gitlab/gitlab.rb 파일에 database 섹션을 추가하되, 메타데이터 데이터베이스가 비활성화된 상태로 시작합니다:

registry['database'] = {
  'enabled' => false, # Must be false!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

파일을 저장하고 GitLab을 재구성합니다.
아직 완료하지 않은 경우 데이터베이스 마이그레이션을 적용합니다.
가져오기를 시작하는 첫 번째 단계를 실행합니다:
```
sudo gitlab-ctl registry-database import --step-one
```

Note

모든 저장소 데이터 가져오기 (2단계)#

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-two --log-to-stdout

registry['database'] = {
  'enabled' => true, # Must be set to true!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo -u registry gitlab-ctl registry-database import --step-two --log-to-stdout

registry['database'] = {
  'enabled' => true, # Must be set to true!
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

레지스트리가 read-only 모드로 설정되어 있는지 확인합니다.

/etc/gitlab/gitlab.rb를 편집하고 registry['storage'] 구성에 maintenance 섹션을 추가합니다. 예를 들어, gs://my-company-container-registry 버킷을 사용하는 gcs 백엔드 레지스트리의 경우 구성은 다음과 같을 수 있습니다:
```
## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => {
    'readonly' => {
      'enabled' => true # Must be set to true.
    }
  }
}
```
파일을 저장하고 GitLab을 재구성합니다.

가져오기의 2단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-two

registry['database'] = {
  'enabled' => true, # Must be set to true!
  'host' => '<registry_database_host_placeholder_change_me>',
  'port' => 5432, # Default, but set to the port of your database instance if it differs.
  'user' => '<registry_database_username_placeholder_change_me>',
  'password' => '<registry_database_placeholder_change_me>',
  'dbname' => '<registry_database_name_placeholder_change_me>',
  'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
  'sslcert' => '</path/to/cert.pem>',
  'sslkey' => '</path/to/private.key>',
  'sslrootcert' => '</path/to/ca.pem>'
}

## Object Storage - Container Registry
registry['storage'] = {
  'gcs' => {
    'bucket' => '<my-company-container-registry>',
    'chunksize' => 5242880
  },
  'maintenance' => { # This section can be removed.
    'readonly' => {
      'enabled' => false
    }
  }
}

파일을 저장하고 GitLab을 재구성합니다.

이제 모든 작업에 메타데이터 데이터베이스를 사용할 수 있습니다!

나머지 데이터 가져오기 (3단계)#

3단계가 완료되는 동안 레지스트리를 정상적으로 계속 사용할 수 있습니다.

프로세스를 완료하려면 마이그레이션의 마지막 단계를 실행합니다:

sudo gitlab-ctl registry-database import --step-three --log-to-stdout

sudo -u registry gitlab-ctl registry-database import --step-three --log-to-stdout

sudo gitlab-ctl registry-database import --step-three

해당 명령이 성공적으로 종료되면 레지스트리 메타데이터가 데이터베이스로 완전히 가져와집니다.

가져오기 후#

예상 동작과 처리 속도를 높이는 방법에 대한 안내는 다음을 참조하세요:

가져오기 후 - 가져오기 완료 후 예상 동작 개요.
온라인 가비지 컬렉션 상태 확인 - 가비지 컬렉션 검토 대기열을 모니터링합니다.
가비지 컬렉터 워커 간격 조정 - 대규모 백로그 처리를 일시적으로 가속화합니다.