레거시 Jira Cloud용 Openflow 커넥터에서 마이그레이션하기

이 주제는 레거시 Openflow Connector for Jira Cloud에서 새 Openflow Connector for Jira Cloud로 마이그레이션하는 방법을 설명해요.

출처: Snowflake 문서

본문

참고: 이 커넥터는 Snowflake Connector Terms가 적용돼요.

이 주제는 레거시 Openflow Connector for Jira Cloud에서 새 Openflow Connector for Jira Cloud로 마이그레이션하는 방법을 설명해요.

개요(Overview)

새 커넥터는 데이터가 Snowflake에 저장되는 방식을 바꾸는 완전한 재작성(rewrite)이에요. 새 커넥터는 두 개의 별도 플로우로 구성돼요: core flow(이슈, 프로젝트, 코멘트, 변경 기록, 작업 기록, 사용자, 투표, 워처, 원격 링크, 이슈 보안 스킴, 삭제된 이슈, 그리고 이슈 유형·우선순위·해결 상태·상태에 대한 조회 테이블)와 agile flow(보드, 스프린트, 보드 매핑).

core flow와 agile flow는 서로 다른 이름의 테이블을 만들므로 같은 Snowflake 대상 스키마에 쓸 수 있어요. 레거시 커넥터와 새 커넥터는 별도의 대상 스키마에 쓰는 한 마이그레이션 중 병렬로 실행할 수 있어요(같은 Openflow 런타임에서도). 따라서 레거시 커넥터를 폐기하기 전에 새 출력을 검증할 수 있어요.

기능 비교(Feature comparison)

측면	레거시 커넥터	새 커넥터
엔티티	이슈만(선택적 작업 기록 강화 포함).	Core flow: 이슈, 프로젝트, 사용자, 코멘트, 변경 기록, 작업 기록, 투표, 워처, 원격 링크, 보안 스킴, 권한, 프로젝트 컴포넌트, 프로젝트 버전, 사용자 그룹, 삭제된 이슈, 그리고 이슈 유형·우선순위·해결 상태·상태에 대한 조회 테이블. Agile flow: 보드, 스프린트, 보드-스프린트, 보드-프로젝트, 보드-이슈 매핑.
동시성	단일 스레드.	프로젝트별 병렬 이슈 가져오기, 선택적 멀티 노드 분산.
스키마 전략	`OBJECT` 컬럼의 원시 JSON과 동적으로 생성된 평탄화 뷰.	엔티티별 명시적 컬럼 스키마, API 응답에서 추가적(단위)으로 진화.
삭제 추적	지원되지 않음.	Jira 감사 로그 폴링으로 삭제된 이슈 추적(선택).
Agile 데이터	지원되지 않음.	별도의 agile 플로우로 사용 가능.

주요 차이점(Key differences)

스키마 변경

가장 중요한 차이는 데이터가 Snowflake에 저장되는 방식이에요:

측면	레거시 커넥터	새 커넥터
이슈 테이블	전체 원시 JSON을 `OBJECT` 타입으로 담은 `ISSUE` 컬럼이 있는 단일 테이블. 평탄화된 `_VIEW`가 자동 생성됨.	필드별 명시적 컬럼. 컬럼 이름은 Jira 필드 표시 이름에서 파생됨. 원시 JSON 폴백 없음.
기타 엔티티	사용 불가. 코멘트와 작업 기록은 이슈 JSON에 내장됨.	별도 테이블: `BOARD`, `BOARD_ISSUE`, `BOARD_PROJECT`, `BOARD_SPRINT`, `CHANGELOG`, `COMMENT`, `DELETED_ISSUE`, `FIELD`, `ISSUE_REMOTE_LINK`, `ISSUE_SECURITY_SCHEME`, `ISSUE_TYPE`, `ISSUE_VOTE`, `ISSUE_WATCHER`, `PERMISSION`, `PRIORITY`, `PROJECT`, `PROJECT_COMPONENT`, `PROJECT_VERSION`, `RESOLUTION`, `SPRINT`, `STATUS`, `USER`, `USER_GROUP`, `WORKLOG`. 전체 인벤토리는 Destination tables를 참고해요.
뷰	모든 이슈 필드가 평탄화된 자동 생성 `<table>_VIEW`.	뷰 생성 없음. 데이터는 대상 테이블에서 직접 쿼리 가능.

레거시 ISSUE 컬럼(예: SELECT issue:fields:summary) 또는 자동 생성된 _VIEW를 참조하는 모든 쿼리는 새 컬럼 이름을 직접 사용하도록 다시 작성되어야 해요(예: SELECT SUMMARY).

파라미터 변경

레거시 커넥터의 다음 파라미터는 새 커넥터에서 사용할 수 없어요:

레거시 파라미터	현재 해당 항목
Search Type	제거됨. 새 커넥터는 발견된 프로젝트의 모든 이슈를 항상 가져옴. `Project Keys Filter`로 수집을 특정 프로젝트로 제한
JQL Query	제거됨. 새 커넥터는 이슈 필터링에 임의의 JQL을 지원하지 않음. 대신 `Project Keys Filter` 사용
Project Names	프로젝트 키(이름이나 ID가 아니라)를 받는 `Project Keys Filter`로 대체됨
Status Category	제거됨. 새 커넥터는 상태와 관계없이 모든 이슈를 가져옴
Updated After	제거됨. 새 커넥터는 증분 상태를 자동으로 관리함
Created After	제거됨. 새 커넥터는 증분 상태를 자동으로 관리함
Destination Table	제거됨. 새 커넥터는 구성된 대상 스키마에 엔티티당 고정 테이블 이름(`ISSUE`, `PROJECT`, `COMMENT` 등)을 만듬
Fetch All Worklogs	제거됨. 새 커넥터는 `WORKLOG`가 `Enabled Tables`에 나열되면 모든 작업 기록을 기본적으로 별도의 `WORKLOG` 테이블로 가져옴
Connection Method	파라미터로 노출되지 않음. 새 커넥터는 `DIRECT` 연결 방식을 사용함

새 커넥터에서 도입된 파라미터는 다음과 같아요:

파라미터	설명
Deletes Fetch Strategy	Jira 감사 로그를 통한 삭제된 이슈 추적을 활성화함. 레거시 커넥터에는 없음
Merge Interval	저널-대상(journal-to-destination) 병합 작업 사이의 시간 간격. core flow와 agile flow 모두에서 사용 가능

또한 agile 데이터(보드, 스프린트, 보드 매핑)는 이제 파라미터 토글이 아니라 별도의 agile 플로우를 통해 사용할 수 있어요. agile 플로우 설치 및 구성에 대한 자세한 내용은 Set up the Atlassian Jira Cloud (Agile) flow을 참고해요.

API 토큰 스코프

스코프가 있는 API 토큰을 사용한다면, 새 커넥터는 활성화하는 기능에 따라 추가 스코프가 필요할 수 있어요. core flow 스코프는 Required API scopes를, agile flow 스코프는 Required API scopes를 참고해요.

Snowflake 권한

새 커넥터는 대상 스키마에 대한 CREATE TABLE만 필요해요. 레거시 커넥터는 평탄화된 이슈 뷰를 만들려면 추가로 CREATE VIEW가 필요했어요. 새 커넥터는 뷰를 만들지 않으므로 CREATE VIEW 권한이 더 이상 필요하지 않아요. 기존 역할을 재사용한다면 레거시 커넥터가 폐기된 후 CREATE VIEW를 취소할 수 있어요.

마이그레이션 단계

새 커넥터를 설정해요. 같은 또는 다른 Openflow 런타임에 core flow를 설치해요. agile 데이터가 필요하면 agile flow도 설치해요. 두 플로우가 레거시 커넥터가 사용하는 것과 다른 대상 스키마에 쓰도록 구성해요. 이렇게 하면 레거시와 새 커넥터가 동시에 실행될 수 있어요.
레거시 구성을 새 파라미터에 매핑해요.
- 레거시 커넥터의 Jira Email, Jira API Token, Environment URL 값을 새 core flow로 복사해요. agile flow를 사용한다면 그 플로우에도 이 값들을 별도로 구성해요.
- 레거시 커넥터가 Project Names를 사용한다면 Project Keys Filter 파라미터용 프로젝트 키로 변환해요.
- 레거시 커넥터가 JQL Query를 사용한다면 Project Keys Filter가 사용 사례를 충당하는지 평가해요. JQL이 프로젝트 외의 기준(예: 상태 또는 커스텀 필드)으로 필터링한다면, 그 필터들은 새 커넥터에서 사용할 수 없어요. 구성된 프로젝트의 모든 일치 이슈가 수집돼요.
- Issue Fields를 이전 구성과 일치하도록 설정해요. 기본값이 *all(레거시)에서 *standard로 변경됐어요.
- 각 플로우에 대한 Snowflake 대상 파라미터(데이터베이스, 스키마, 웨어하우스, 자격 증명)를 구성해요.
새 커넥터를 시작해요. core flow를 실행하고 초기 로드가 완료되도록 해요. agile flow를 사용한다면 그것도 시작해요.
데이터를 검증해요. 새 대상 테이블의 데이터를 레거시 대상 테이블과 비교해 완전성을 확인해요. 약간의 차이는 예상돼요: 레거시 커넥터는 삭제를 추적하지 않았으므로, Jira에서 삭제된 이슈는 레거시 테이블에는 여전히 나타나지만 새 ISSUE 테이블에는 나타나지 않아요(삭제 추적이 활성화된 경우 _SNOWFLAKE_DELETED = TRUE로 나타나요). 이슈가 삭제된 적이 있으면 행 수가 정확히 일치하지 않아요.
```
-- Compare issue counts (expect differences if issues were deleted in Jira)
SELECT COUNT(*) AS legacy_count FROM legacy_schema.JIRA_ISSUES;
SELECT COUNT(*) AS new_count FROM new_schema.ISSUE;

-- Spot-check specific issues. ISSUE_TYPE, PRIORITY, RESOLUTION, and STATUS
-- are Jira IDs; join the lookup tables to resolve names.
SELECT i.KEY, i.SUMMARY, s.NAME AS status_name
FROM new_schema.ISSUE i
LEFT JOIN new_schema.STATUS s ON i.STATUS = s.ID
WHERE i.KEY = 'PROJ-123';
```
다운스트림 쿼리를 업데이트해요. 레거시 테이블 구조를 참조하는 쿼리, 뷰, 대시보드, 파이프라인을 다시 작성해요. 주요 변경:
- 레거시 ISSUE OBJECT 컬럼이나 _VIEW 참조를 직접 컬럼 참조로 교체해요.
- FLATTEN 기반 쿼리를 표준 SELECT 문으로 교체해요.
- 새 엔티티 테이블들을 결합하도록 JOIN 문을 추가해요(예: ISSUE_ID로 ISSUE를 COMMENT와 조인, 또는 ISSUE.STATUS = STATUS.ID로 ISSUE를 STATUS와 조인해 상태 이름을 해석).
- 쿼리가 삭제된 이슈를 무시하도록 하려면 새 _SNOWFLAKE_DELETED 컬럼으로 필터링해요(WHERE _SNOWFLAKE_DELETED = FALSE). 레거시 커넥터는 삭제를 전혀 추적하지 않았으므로, JIRA_ISSUES에 대한 레거시 쿼리는 Jira에서 이후 제거된 이슈를 반환했었어요.
레거시 커넥터를 중지해요. 새 데이터가 완전하고 다운스트림 소비자가 업데이트된 것을 확인한 후, 레거시 커넥터 프로세스 그룹을 중지해요. 두 새 플로우(core와 agile)는 독립적으로 계속 실행될 수 있어요.
정리(Clean up). 선택적으로 더 이상 필요하지 않다고 확인한 후 레거시 대상 테이블과 뷰를 드롭해요.

참고: 레거시 커넥터와 새 커넥터가 같은 Jira API 토큰을 사용하면 같은 Jira API 속도 제한을 공유해요. 둘을 동시에 실행하면 API 호출 볼륨이 대략 두 배로 늘어나, API 사용량이 많은 Jira 인스턴스에서 속도 제한이 발생할 수 있어요. 마이그레이션 기간 동안 레거시 수집 빈도를 줄이거나, 속도 예산을 독립적으로 관리할 수 있는 별도의 API 토큰으로 새 커넥터를 실행하는 것을 고려해요.

레거시 Jira Cloud용 Openflow 커넥터에서 마이그레이션하기