브랜치 라이프사이클

브랜치 라이프사이클 (Branch Lifecycle)

lakeFS에서 브랜치는 만들기가 아주 저렴하지만, 그만큼 금방 쌓여요. 기능 개발, CI 실행, 실험, 일회성 탐색 작업이 모두 브랜치를 남겨 두거든요. 오래된 브랜치는 저장소 화면을 어수선하게 만들고, 그 브랜치가 참조하는 객체들이 가비지 컬렉션의 손길이 닿지 않게 막아 두기도 해요.

Branch Lifecycle 정책은 브랜치가 특정 이름 패턴에 일치하고 동시에 시간 기준(생성 후 경과 시간, 마지막 쓰기 이후 경과 시간, 또는 둘 다)을 넘었을 때 브랜치를 자동으로 삭제해요. 정책은 저장소별로 정의되고, 서버의 스케줄 잡이 평가해요.

출처: 문서

본문

lakeFS Team과 lakeFS Enterprise에서 사용할 수 있어요. 무료 평가판을 시작하거나 문의하세요.

Branch Lifecycle은 저장소를 어수선하게 만드는 일시적 브랜치를 처리하고, Object Lifecycle은 오래 살아남는 브랜치에서 나이 든 데이터를 만료시켜요. 두 기능이 가비지 컬렉션과 어떻게 결합해 완전한 보존(retention) 정책을 이루는지는 Data Retention 문서를 참고하세요.

동작 방식

저장소에 하나 이상의 정책(policy) 을 정의해요. 각 정책에는 다음이 들어가요:

• 브랜치 이름과 비교할 이름 패턴(name patterns) 목록 — glob 문법(*, ?, [abc])을 써요.

• max age(최대 나이) 와 max inactivity time(최대 비활성 시간) 중 최소 하나는 필요해요. max_age는 브랜치 생성 이후의 시간을 재고, max_inactivity_time은 마지막 쓰기 이후의 시간을 재요. 둘 다 설정하면 두 기준을 모두 넘어야 정책이 적용돼요.

• 선택적인 설명(description).

스케줄 잡이 설정된 cron 주기로 모든 저장소를 순회해요. 각 저장소에서 모든 브랜치를 정책 순서대로 평가하는데, 첫 일치가 이겨요(first match wins). 브랜치는 어떤 정책의 패턴 중 하나라도 일치하고, 그 정책이 요구하는 시간 기준을 넘었으면 삭제돼요:

• max_age만 설정된 경우: 브랜치의 생성 시각이 max_age보다 오래됐을 때.

• max_inactivity_time만 설정된 경우: 마지막 쓰기 이후 경과 시간이 max_inactivity_time보다 클 때.

• 둘 다 설정된 경우: 두 조건이 모두 성립할 때(AND).

비활성 시계를 초기화하는 쓰기 작업에는 커밋, 머지, 리셋, 리버트, 체리픽, 임포트, 브랜치 리타겟, 스테이징 영역 쓰기(객체 생성/수정/삭제)가 있어요. 읽기(UI에서 둘러보기, lakectl fs ls, 게이트웨이를 통한 S3 GET)는 집계되지 않아요.

저장소의 기본 브랜치는 항상 예외이고 어떤 패턴으로도 매칭되지 않아요. 생성 시각이 기록되지 않은 브랜치(lakeFS가 이 필드 추적을 시작하기 전에 만든 것)와 읽기 전용 저장소의 브랜치는 건너뛰어요. 마지막 업데이트 시각 추적이 시작된 이후 쓰인 적이 없는 브랜치는 비활성 계산에서 생성 시각으로 대체돼요.

브랜치 삭제는 표준 lakeFS 삭제 경로를 그대로 거치기 때문에, 설정해 둔 pre-delete-branch 및 post-delete-branch 훅도 그대로 발동해요.

정책 필드

정책 구조

API가 저장하고 반환하는 표준 JSON은 다음과 같아요. 값은 초 단위예요(604800 = 7일, 259200 = 3일, 86400 = 1일):

{
  "policies": [
    {
      "id": "feature-cleanup",
      "name_patterns": ["feature-*", "wip-*"],
      "max_age": 604800,
      "max_inactivity_time": 259200,
      "description": "Auto-clean feature and WIP branches once they're old and quiet"
    },
    {
      "id": "pol-a3f9c821",
      "name_patterns": ["temp-*"],
      "max_inactivity_time": 86400
    }
  ]
}

정책 관리

정책은 lakeFS UI, lakectl, API 어디에서든 관리할 수 있어요.

웹 UI

• 저장소로 이동해요.

• Settings → Data Retention으로 가요.

• Branch lifecycle 섹션에서 Create rule을 눌러 새 규칙을 만들거나, 기존 행의 액션 메뉴로 편집·삭제해요. Max age (days), Max inactivity time (days) 필드는 '일' 단위 정수로 입력해요.

CLI

정책을 YAML 또는 JSON 파일로 작성한 뒤 적용해요. 아래 예시는 YAML이지만, JSON도 유효한 YAML이라 그대로 받아들여져요. lakectl에서는 max_age와 max_inactivity_time이 일 단위 정수예요.

cat > policies.yaml <<'EOF'
policies:
  - name_patterns: ["feature-*", "wip-*"]
    max_age: 7
    max_inactivity_time: 3
    description: "auto-cleanup of feature and WIP branches"
  - id: "temp-cleanup"
    name_patterns: ["temp-*"]
    max_inactivity_time: 1
EOF

lakectl branch-lifecycle set lakefs://my-repo -f policies.yaml

set은 서버가 지정한 id가 포함된 표준 정책 목록을 반환해요. 기본적으로 현재 ETag를 사전조건으로 보내서 동시 편집이 서로를 덮어쓰지 않게 하고, --force를 주면 이 확인을 건너뛰어요.

그 외 명령어:

lakectl branch-lifecycle get   lakefs://my-repo
lakectl branch-lifecycle clear lakefs://my-repo

clear는 멱등(idempotent) 동작으로, 저장소의 모든 정책을 제거해요.

서버 설정

정책은 서버 설정과 무관하게 저장소 자체에 저장돼요. 스케줄 잡은 항상 연결되어 있고 lakefs.yaml의 cron 주기로 돌아가요:

branch_lifecycle:
  schedule: "0 * * * *"    # standard cron (default: every hour at :00)

• branch_lifecycle.schedule (string : "0 * * * *") — 잡의 cron 스케줄이에요.

저장소 단위로 이 기능을 끄려면 그 저장소의 정책을 지우면 돼요. lakeFS를 여러 레플리카로 배포했더라도 잡은 한 인스턴스만 실행해요.

권한

이 기능은 다음 RBAC 액션으로 제어돼요:

• branches:GetBranchLifecyclePolicies — 저장소의 정책을 읽어요.

• branches:SetBranchLifecyclePolicies — 정책을 생성, 수정, 또는 삭제해요.

두 액션 모두 저장소 리소스 arn:lakefs:fs:::repository/{repositoryId} 범위로 묶여 있어요.

참고 사항

• 삭제는 영구적이에요. 브랜치가 한번 삭제되면 커밋되지 않은 변경은 사라져요. 다른 브랜치에서 도달 가능한 커밋 이력은 보존돼요.

• 하나의 브랜치가 여러 정책에 매칭될 수 있어요. 평가는 정책을 위에서 아래로 훑으면서, 아직 시간 기준을 넘지 않은 정책은 건너뛰어요. 브랜치 이름에 일치하고 동시에 임계값을 넘은 첫 정책이 이겨요. 브랜치가 삭제되는지 여부 자체는 순서에 영향을 받지 않아요 — 적용 가능한 정책이 하나라도 있으면 삭제돼요. 순서는 cron 로그에 '삭제자'로 기록될 정책을 정할 때만 의미가 있는데, 여러 임계값이 동시에 넘은 경우에 문제가 되죠.

• 태그와 커밋은 영향받지 않아요. Branch Lifecycle은 브랜치 참조만 삭제해요.

• 가드레일로 훅을 쓰세요. pre-delete-branch 훅은 라이프사이클 삭제에서도 발동하므로, 지우면 안 되는 브랜치의 삭제를 막는 장치로 쓸 수 있어요.

• lakeFS Mount는 sync 전까지 비활성 시계를 눌러 주지 않아요. 쓰기 모드 lakeFS Mount를 통한 쓰기는 로컬 캐시에 스테이징되기 때문에, everest sync(또는 커밋)로 플러시되기 전까지는 lakeFS가 활동을 보지 못해요. 활성인데 아직 sync되지 않은 마운트에만 의존하는 브랜치는 라이프사이클 기준으로는 유휴(idle)로 판정돼요.

더 알아보기 (Learn more)

공식 문서: lakeFS Branch Lifecycle 가이드