Atlassian Jira Cloud

Atlassian Jira Cloud (Agile) 플로우 설정

이 주제는 Openflow Connector for Jira Cloud의 agile 플로우인 Atlassian Jira Cloud (Agile) 플로우를 설치하고 구성하는 단계를 설명해요. core 플로우는 Set up the Atlassian Jira Cloud (Core) flow에 별도로 문서화되어 있어요.

출처: Snowflake 문서

본문

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

이 주제는 Openflow Connector for Jira Cloud의 agile 플로우인 Atlassian Jira Cloud (Agile) 플로우를 설치하고 구성하는 단계를 설명해요. core 플로우는 Set up the Atlassian Jira Cloud (Core) flow에 별도로 문서화되어 있어요.

agile 플로우는 core 플로우와 독립적이에요. 자체 API 토큰, 파라미터 컨텍스트, 상태 서비스, Snowflake 대상 구성이 있어요. 두 플로우는 서로 다른 이름의 테이블을 만들므로 같은 Snowflake 데이터베이스와 스키마에 쓸 수 있어요.

전제 조건(Prerequisites)

1. About Openflow Connector for Jira Cloud을 검토했는지 확인해요.
2. Set up Openflow - BYOC 또는 Set up Openflow - Snowflake Deployments를 설정했는지 확인해요.
3. Openflow - Snowflake Deployments를 사용한다면 configuring required domains을 검토하고, Jira Cloud 커넥터에 필요한 도메인에 대한 액세스를 부여했는지 확인해요.

자격 증명 가져오기

Jira Cloud 관리자로서 Atlassian 계정에서 다음 작업을 수행해요. core 플로우의 API 토큰을 재사용하거나 별도의 토큰을 만들 수 있어요. core 플로우와 agile 플로우는 같은 토큰을 사용할 수 있지만, 어쨌든 항상 기본 Jira API 속도 예산을 공유해요.

1. API tokens 페이지로 이동해요.
2. Create API token with scopes를 선택해요.
3. Create an API token 대화상자에서 API 토큰의 설명적인 이름을 제공하고 API 토큰의 만료 날짜를 선택해요. 만료 날짜는 1~365일로 할 수 있어요.
4. API 토큰 앱 Jira를 선택해요.
5. Required API scopes에 나열된 agile 스코프를 선택해요.
6. Create token을 선택해요.
7. Copy your API token 대화상자에서 Copy를 선택해 생성된 API 토큰을 복사한 다음 커넥터 파라미터에 붙여넣거나 안전하게 저장해요.
8. Close를 선택해 대화상자를 닫아요.

Required API scopes

스코프가 있는 Atlassian API 토큰은 클래식(classic)(더 넓음, 권장)과 세부(granular)(더 좁음) 스코프를 모두 나열해요. agile 플로우는 Jira Software 스코프를 사용해요. Atlassian이 클래식 스코프를 문서화했을 때 클래식 스코프가 권장 시작 집합이에요. 조직이 더 좁은 토큰을 요구할 때 세부 스코프를 사용해요. 세부 토큰은 Atlassian이 엔드포인트에 나열한 모든 스코프가 필요하지 하나만은 필요하지 않아요.

BOARD 테이블은 항상 만들어지므로, 모든 토큰은 다음 표의 BOARD 행에 있는 스코프가 필요해요.

커넥터는 연결 검증을 위해 GET /rest/api/3/myself도 호출해요. BOARD_ISSUE 수집 경로도 시작 시 Jira 시간대를 조회하기 위해 이 엔드포인트를 호출해요. 이 엔드포인트에는 클래식 스코프 read:jira-user 또는 세부 스코프 read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira를 사용해요.

보드를 수집하려면 API 토큰 소유자가 보드와 그 저장된 필터(saved filter)를 볼 수 있어야 해요. 저장된 필터는 소유자가 보유하거나, 그룹, 토큰 소유자가 탐색할 수 있는 프로젝트, 또는 공개 액세스를 통해 토큰 소유자와 공유될 때 표시돼요.

선택적 테이블을 켜는 Enabled Tables 파라미터는 Jira Cloud (Agile) Ingestion Parameters을 참고해요.

다음 표는 각 대상 테이블, Atlassian이 문서화한 경우의 권장 클래식 스코프, Atlassian이 엔드포인트에 문서화한 전체 세부 스코프 집합, 그리고 커넥터가 호출하는 엔드포인트에 대한 링크를 나열해요:

테이블	클래식 스코프(가능할 때 권장)	세부 스코프	Jira API 참조	참고
BOARD (항상)	read:jira-work (Get filter만)	Get all boards: read:board-scope:jira-software, read:project:jira / Get configuration: read:board-scope.admin:jira-software, read:project:jira / Get filter: read:filter:jira, read:group:jira, read:project:jira, read:project-role:jira, read:user:jira, read:jql:jira, read:application-role:jira, read:avatar:jira, read:issue-type-hierarchy:jira	Get all boards, Get configuration, Get filter	Get all boards와 Get configuration은 Jira Software 엔드포인트이며 클래식 스코프가 없음. Get filter는 Jira Platform 엔드포인트
SPRINT (SPRINT와 BOARD_SPRINT 채움)	없음	read:sprint:jira-software	Get all sprints	Atlassian은 이 엔드포인트에 대해 세부 Jira Software 스코프만 문서화함. 이 엔드포인트는 API 토큰 소유자가 볼 권한이 있는 스프린트만 반환
BOARD_PROJECT	없음	read:board-scope.admin:jira-software, read:project:jira	Get projects associated with the board	BOARD 기준선으로 커버됨. Atlassian은 이 엔드포인트에 대해 세부 Jira Software 스코프만 문서화함
BOARD_ISSUE	read:jira-work	read:issue-details:jira, read:field.default-value:jira, read:field.option:jira, read:field:jira, read:group:jira	Search for issues using JQL	관련 프로젝트에 대한 Browse projects. 이슈별 권한 검사(예: 이슈 수준 보안)에 실패한 이슈는 조용히 건너뜀

두 플로우에서 단일 API 토큰을 재사용한다면 이 스코프를 Required API scopes에 문서화된 core flow 스코프와 결합해요.

스코프가 없는 토큰도 지원되며, 오로지 API 토큰 소유자의 권한에 기반해 액세스를 부여돼요. 다만 세밀한 액세스 제어를 위해 스코프가 있는 토큰을 권장해요.

Snowflake 계정 설정하기

core 플로우에 대한 Snowflake 계정 설정을 이미 완료했다면, agile 플로우에 같은 역할, 서비스 사용자, 키 쌍, 데이터베이스, 스키마, 웨어하우스를 재사용할 수 있어요. agile 플로우 파라미터는 이 같은 Snowflake 구성을 가리켜요.

그렇지 않으면 다음 작업을 수행해요:

Openflow 관리자로서 Snowflake 계정을 설정하려면 다음 작업을 수행해요. 기본 SNOWFLAKE_MANAGED 인증 전략을 사용하면 런타임의 execute-as 역할이 커넥터가 Snowflake에 접근할 때 사용하는 신원이 되므로, 그 역할에 다음 권한을 부여해요.

참고: Openflow - BYOC Deployments에 커넥터를 배포하고 권장하는 SNOWFLAKE_MANAGED 대신 KEY_PAIR 인증 전략을 사용한다면, 런타임의 관리 토큰에 의존하는 대신 이 같은 execute-as 역할을 서비스 사용자에게 부여해요. 서비스 사용자를 만들려면 Set up key-pair authentication for Openflow - BYOC Deployments을 참고해요.

데이터베이스, 스키마, 웨어하우스 만들기

1. 대상 데이터베이스를 만들어요:

   USE ROLE OPENFLOW_ADMIN;
   CREATE DATABASE IF NOT EXISTS <destination_database>;
   

2. 대상 스키마를 만들어요:

   CREATE SCHEMA IF NOT EXISTS <destination_database>.<destination_schema>;
   

3. 런타임의 execute-as 역할에 필요한 권한을 부여해요:

   GRANT USAGE ON DATABASE <destination_database> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
   GRANT USAGE ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
   GRANT CREATE TABLE ON SCHEMA <destination_database>.<destination_schema> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
   

4. 웨어하우스를 만들거나(기존 것을 사용하거나) 사용 권한을 부여해요:

   CREATE WAREHOUSE IF NOT EXISTS <openflow_warehouse>
     WITH
     WAREHOUSE_SIZE = 'XSMALL'
     AUTO_SUSPEND = 300
     AUTO_RESUME = TRUE;
   
   GRANT USAGE, OPERATE ON WAREHOUSE <openflow_warehouse> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;
   

5. 커넥터가 수집한 테이블에 액세스가 필요한 다른 Snowflake 사용자가 있다면(예: Snowflake에서 커스텀 처리), 그 사용자에게 execute-as 역할을 부여해요.

커넥터 설정하기

agile 플로우는 Atlassian Jira Cloud (Agile) 프로세스 그룹으로 제공돼요. 데이터 엔지니어로서 그것을 설치하고 구성하려면 다음 작업을 수행해요.

커넥터 설치하기

데이터 엔지니어로서 커넥터를 설치하려면:

1. Openflow의 Connector library 탭으로 이동해요.
2. Openflow 커넥터 페이지에서 커넥터를 찾고 Install을 선택해요.
3. Select runtime 대화상자에서 Available runtimes 드롭다운 목록에서 런타임을 선택하고 Install을 클릭해요.

참고: 커넥터를 설치하기 전에, 수집된 데이터를 저장할 Snowflake에 데이터베이스와 스키마를 만들었는지 확인해요.

1. Snowflake 계정 자격 증명으로 배포에 인증하고, 런타임 애플리케이션이 Snowflake 계정에 접근하는 것을 허용하라는 프롬프트가 나오면 Allow를 선택해요. 커넥터 설치 과정은 완료되는 데 몇 분이 걸려요.
2. Snowflake 계정 자격 증명으로 런타임에 인증해요. Openflow 캔버스에 커넥터 프로세스 그룹이 추가된 상태로 나타나요. 가져온 후 agile flow는 캔버스에서 Atlassian Jira Cloud (Agile) 프로세스 그룹으로 나타나요.

커넥터 구성하기

1. 가져온 Atlassian Jira Cloud (Agile) 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Parameters를 선택해요.
2. Flow parameters에 설명된 대로 필수 파라미터 값을 채워요.

Flow parameters

agile 플로우는 자체 별도의 파라미터 컨텍스트를 사용해요. Jira 자격 증명과 Snowflake 대상은 core 플로우와 독립적으로 구성해야 해요. 두 플로우는 같은 Snowflake 대상 데이터베이스와 스키마를 가리킬 수 있어요.

• Jira Cloud (Agile) Source Parameters: Jira API와의 연결을 설정하는 데 사용
• Jira Cloud (Agile) Destination Parameters: Snowflake와의 연결을 설정하는 데 사용
• Jira Cloud (Agile) Ingestion Parameters: Jira에서 수집한 데이터의 구성을 정의하는 데 사용

Jira Cloud (Agile) Source Parameters

파라미터	설명
Jira Email	인증에 사용되는 Atlassian 계정의 이메일 주소
Jira API Token	Atlassian Jira 계정의 API 액세스 토큰. 구성할 스코프는 Required API scopes를 참고
Environment URL	Atlassian Jira 환경의 URL. 예: https://your-domain.atlassian.net

Jira Cloud (Agile) Destination Parameters

파라미터	설명	필수
Destination Database	데이터가 저장될 데이터베이스. Snowflake에 이미 존재해야 함. 이름은 대소문자를 구분함. 인용되지 않은 식별자는 대문자로 제공	예
Destination Schema	데이터가 저장될 스키마. Snowflake에 이미 존재해야 함. 이름은 대소문자를 구분함. 인용되지 않은 식별자는 대문자로 제공. 예: CREATE SCHEMA SCHEMA_NAME 또는 CREATE SCHEMA schema_name: SCHEMA_NAME 사용. CREATE SCHEMA "schema_name" 또는 CREATE SCHEMA "SCHEMA_NAME": 각각 schema_name 또는 SCHEMA_NAME 사용	예
Snowflake Authentication Strategy	다음 중 하나: Snowflake Openflow Deployment 또는 BYOC: SNOWFLAKE_MANAGED 사용(이 토큰은 Snowflake가 자동 관리함). BYOC 배포는 SNOWFLAKE_MANAGED를 사용하려면 이전에 execute-as roles을 구성해야 함. BYOC: 대안으로 BYOC는 인증 전략 값으로 KEY_PAIR를 사용할 수 있음	예
Snowflake Account Identifier	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: [organization-name]-[account-name] 형식의 Snowflake 계정 이름	예
Snowflake Private Key	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 개인 키. Snowflake Private Key File 또는 Snowflake Private Key 중 하나는 정의해야 함	아니요
Snowflake Private Key File	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 개인 키 파일은 비어 있어야 함. KEY_PAIR: PKCS8 표준에 따라 형식화되고 표준 PEM 헤더·푸터를 포함하는 인증용 RSA 개인 키가 들어 있는 파일을 업로드. 헤더 줄은 -----BEGIN PRIVATE로 시작함. Reference asset 체크박스를 선택해 개인 키 파일을 업로드	아니요
Snowflake Private Key Password	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: Snowflake 개인 키 파일과 연결된 비밀번호 제공	아니요
Snowflake Role	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 런타임의 execute-as 역할(또는 그 역할에 부여된 하위 역할) 사용. execute-as 역할은 Openflow UI에서 런타임의 View Details로 이동해 찾을 수 있음. KEY_PAIR: 서비스 사용자에 대해 구성된 유효한 역할 사용	예
Snowflake Username	다음 중 하나: SNOWFLAKE_MANAGED 인증 전략: 비어 있어야 함. KEY_PAIR: Snowflake 인스턴스에 연결하는 데 사용되는 사용자 이름 제공	예
Snowflake Warehouse	쿼리를 실행하는 데 사용되는 Snowflake 웨어하우스	예

Jira Cloud (Agile) Ingestion Parameters

파라미터	설명
Enabled Tables	채울 선택적 테이블의 쉼표로 구분된 목록. BOARD 수집은 항상 활성화되어 있고 비활성화할 수 없음. 각 테이블에 필요한 API 스코프는 Required API scopes를 참고. 사용 가능한 값: BOARD_ISSUE(보드와 연결된 이슈), BOARD_PROJECT(보드와 연결된 프로젝트), SPRINT(스프린트와 보드-스프린트 연관, SPRINT와 BOARD_SPRINT 모두 채움). 기본값: BOARD_ISSUE, BOARD_PROJECT, SPRINT
Merge Interval	저널-대상(journal-to-destination) 병합 작업 사이의 시간 간격. 병합이 실행되면 Snowflake 웨어하우스가 재개됨. 이전 병합 이후 새 데이터가 로드되지 않았으면 병합은 건너뜀. 기본값: 1 min

플로우 실행하기

1. 캔버스를 마우스 오른쪽 버튼으로 클릭하고 Enable all Controller Services를 선택해요.
2. Atlassian Jira Cloud (Agile) 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Start를 선택해요. 플로우가 데이터 수집을 시작해요. 첫 실행 시 플로우는 대상 스키마에 필요한 Snowflake 테이블을 만들어요. agile flow가 만드는 전체 테이블 목록과 어떤 선택적 테이블이 채워지는지 제어하는 파라미터는 Destination tables을 참고해요.

커넥터 상태 재설정하기

처음부터 수집을 다시 시작하려면 agile flow의 수집 상태를 지워요. agile flow는 프로세서별 상태가 아니라 자체 중앙 집중식 상태 서비스를 사용해요.

상태를 재설정하려면:

1. Atlassian Jira Cloud (Agile) 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Stop을 선택해요.
2. 프로세스 그룹의 Controller Settings로 이동해요.
3. StandardJiraIngestionStateService 컨트롤러 서비스를 찾아 View State를 선택해요.
4. Clear State를 선택해요. 이렇게 하면 agile flow의 수집 추적이 지워져요.
5. 선택적으로 필요한 경우 커넥터 파라미터를 업데이트해요.
6. Atlassian Jira Cloud (Agile) 프로세스 그룹을 마우스 오른쪽 버튼으로 클릭하고 Start를 선택해요.

참고: agile flow의 대상 테이블(BOARD, SPRINT, BOARD_SPRINT, BOARD_PROJECT, BOARD_ISSUE)은 상태를 지우는지 여부와 관계없이 예약 실행마다 완전히 새로고침돼요.

다음 단계

• Set up the Atlassian Jira Cloud (Core) flow — core 플로우를 아직 설치하지 않았다면
• Migrate from the legacy Openflow Connector for Jira Cloud — 이전 버전의 Jira Cloud 커넥터에서 이동하는 경우

더 알아보기 (Learn more)

• Jira Cloud용 Openflow 커넥터 정보
• Atlassian Jira Cloud (Core) 플로우 설정