This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
Status Authors Coach DRIs Owning Stage Created
proposed @msaleiko @stanhu 2023-06-05

mail_room 이메일 수신을 예약된 Sidekiq 작업으로 대체

요약

GitLab 사용자는 이메일을 통해 새 이슈 및 댓글을 제출할 수 있습니다. 관리자는 GitLab이 정기적으로 검색하고 새로운 안 읽은 이메일을 가져오는 특별한 메일함을 구성합니다. 이메일 주소의 서브 주소 부분에 슬러그와 해시에 따라, 해당 이메일이 이슈를 기록할지, 서비스 데스크 이슈를 추가할지 또는 기존 이슈에 댓글을 추가할지를 결정합니다.

현재로서, 이메일은 별도의 mail_room 프로세스에 의해 수신됩니다. 우리는 mail_room을 통해 이메일 수신을 중단하고 대신에 예약된 Sidekiq 작업을 사용하여 GitLab 내에서 직접 수행하고자 합니다.

이는 서비스 데스크를 위한 사용자 정의 이메일 주소 기입, 상세한 헬스 로깅, 다른 서비스 제공 업체 어댑터(예: API를 통한 Gmail)를 통합하기 쉬워진다는 기초를 제공하며, 고객의 Self-Managed형 비용 및 인프라 설정을 줄이고 팀 구성원들이 GDK에서 이메일 수신과 작업하기가 용이해집니다.

용어

  • 이메일 수신: IMAP 또는 API를 통해 메일함에서 이메일을 읽고 처리를 위해 전달하는 것입니다(예: 이슈 생성 또는 댓글 추가)
  • 서브 주소: 이메일 주소는 로컬 부분(@ 이전의 모든 것)과 도메인 부분으로 되어 있습니다. 이메일 서브 주소를 사용하면 로컬 부분 뒤에 + 기호를 추가하여 해당 이메일 주소의 고유한 변형을 만들 수 있습니다. 이러한 서브 주소를 사용하여 이메일 주소를 필터링, 범주화 또는 구분하기 위해 사용할 수 있으며 모든 이메일은 동일한 메일함으로 전달됩니다. 예: user+subaddress@example.com 및 user+1@example.com 및 user@example.com에 대한 서브 주소
  • mail_room: 설정된 메일함마다 새 프로세스를 생성하여 정기적으로 새 이메일을 읽고 해당 이메일을 처리 단위로 전달하는 실행 가능한 스크립트
  • incoming_email: 이메일 주소는 이메일을 통해 댓글을 추가하고 이슈를 생성하는 데 사용됩니다. 이슈 댓글의 GitLab 알림에 회신할 때, 이 응답 이메일은 구성된 incoming_email 메일함으로 전송되어 mail_room에 읽히고 GitLab에서 처리됩니다. 또한 이 주소를 서비스 데스크 이메일 주소로 사용할 수 있습니다. 구성은 인스턴스별이며 이 메일함에 액세스하려면 완전한 IMAP 또는 Microsoft Graph API 자격 증명이 필요합니다.
  • service_desk_email: 서비스 데스크 전용 별칭 이메일 주소입니다. incoming_email에서 생성된 주소를 사용하여 서비스 데스크 이슈를 생성할 수 있습니다.
  • delivery_method: 관리자는 mail_room이 검색한 이메일을 GitLab로 전달하는 방식을 정의할 수 있습니다. 레거시 및 이제 사용되지 않는 방법은 sidekiq로, 이 방법은 Redis 대기열에 새 작업을 직접 추가합니다. 현재 및 권장되는 방법은 webhook으로, 이 방법은 내부 GitLab API 엔드포인트로 POST 요청을 보냅니다. 그런 다음, 작업 데이터 압축을 위한 완전한 프레임워크를 사용하여 새 작업을 추가합니다. 단점은 대규모 설정에서 분배가 어려운 공유 키 파일을 mail_room 및 GitLab 사이에서 필요로 한다는 것입니다.

동기

현재 구현은 확장성이 부족하며 상당한 인프라 유지보수가 필요합니다. 또한, 구성 오류에 대한 적절한 가시성 및 전반적인 시스템 상태가 부족합니다. 또한 다중 노드 리눅스 패키지(Omnibus) 설치 설정 및 지원 처리가 어려우며, 주기적인 이메일 수신 문제로 반응적 지원이 필요합니다.

우리는 mail_room 젠파 (gitlab-mail_room)의 포크를 사용하고 있으며, 이것은 상위 스트림으로 이전되지 않을 GitLab 특정 기능을 포함하고 있어 상당한 유지 보수 부담이 있습니다.

서비스 데스크 단일 엔지니어 그룹(SEG)은 서비스 데스크를 위한 사용자 정의 이메일 주소에 대해 작업을 시작하고, 16.4에서 베타로 첫 번째 반복을 출시했습니다. MVC로 전달 및 SMTP 모드 introduced를 나타내고 있어 관리자는 사용자 정의 이메일 주소에서 프로젝트의 incoming_mail 이메일 주소로부터 이메일 전달을 설정합니다. 또한 GitLab이 사용자 정의 이메일 주소로부터 이메일을 보낼 수 있도록 SMTP 자격 증명을 제공합니다. 이 접근 방법에는 작업에 필요한 추가적인 이메일 수신이 필요하지 않습니다.

두 번째 반복으로는 Microsoft Graph 지원을 추가하여 서비스 데스크를 위한 사용자 정의 이메일 주소를 추가로 제공하기를 원합니다. 따라서 시스템에서 정의된 두 개의 주소 이상을 수신하기 위한 해결 경로를 탐구할 것입니다. 우리는 특혜를 받은 사용자가 사용자 정의 이메일 계정을 연결하고 Microsoft 고문 업데이트를 받을 수 있는 방법이 필요합니다. GitLab은 이메일 업데이트를 받기 위한 공개 엔드포인트가 필요할 것입니다. Self-Managed 인스턴스의 경우 이 방법이 작동하지 않을 수 있으므로, Microsoft 고객을 위한 직접적인 이메일 수신이 필요할 것입니다. 그러나 이 방법을 사용하면 우리가 수백 개의 메일함을 폴링할 수 있는 GitLab SaaS의 성능과 효율성을 향상시킬 수 있습니다.

목표

우리의 이러한 노력의 목표는 이메일 수신의 확장성을 향상시키고 인프라를 크게 줄이는 것입니다.

  1. 이 통합을 통해 별도의 프로세스를 위한 설치가 필요하지 않게되며, IMAP 및 Microsoft Graph를 통한 직접 사용자 정의 이메일 주소 수신(개선된 헬스 모니터링, 데이터 보존(원본 보존), 이메일 크기 제한 내에서의 첨부 파일 처리)를 포함한 향후 계획의 길을 열어줄 것입니다.
  2. 팀 구성원들이 이메일 수신 기능을 개발하기가 쉬워질 것입니다. 지금은 여러 매뉴얼 단계가 필요합니다.

비목표

이 설계도는 나열된 모든 향후 계획에 대한 모든 구현 세부사항을 설명한다는 목적은 아닙니다. 그러나 이 것은 이후 기능(사용자 정의 서비스 데스크 이메일 주소 IMAP/Microsoft Graph, 상태 체크 등)을 위한 기초가 될 것입니다.

다른 수신 방법은 포함하지 않습니다. 우리는 현재 세트(기존의 IMAP 및 Microsoft Graph API를 사용한 incoming_email 및 service_desk_email)에 중점을 두고 있습니다.

현재 설정

관리자는 gitlab.rb 구성 파일에서 이메일 메일함(incoming_email 및 service_desk_email)의 설정(자격 증명 및 전달 방법)을 구성합니다. 변경 후 GitLab은 새 설정을 적용하려면 재구성 및 재시작해야 합니다.

우리는 별도의 프로세스인 mail_room을 사용하여 해당 메일함에서 이메일을 수신합니다. mail_room은 각 구성된 메일함마다 스레드를 생성하고 매분 해당 메일함을 폴링합니다. 그사이에 스레드는 유휴 상태입니다. mail_room은 gitlab.rb의 설정에서 생성된 설정 파일을 읽습니다.

mail_room은 IMAP 및 Microsoft Graph를 통해 연결하고, 안 읽은 이메일을 가져와서 읽은 상태로 표시하거나 삭제합니다(설정에 따라). 그리고 이메일을 두 전달 방법 중 하나로 목적지로 분배합니다.

webhook 전달 방법 (권장)

webhook 전달 방법은 mail_room에서 GitLab으로 이메일을 이동시키는 권장 방법입니다. mail_room은 이메일 본문과 메타데이터를 내부 API 엔드포인트 /api/v4/internal/mail_room에 게시하고 올바른 핸들러 워커를 선택하여 실행을 예약합니다.

flowchart TB User --이메일 전송--> provider[(이메일 제공 업체 메일함)] mail_room --IMAP 또는 Microsoft Graph API를 통해 미확인 이메일 가져오기--> provider mail_room --HTTP POST--> api api --이메일을 위한 작업 추가--> create subgraph mail_room_process[mail_room] mail_room[mail_room 스레드] end subgraph GitLab api[내부 API 엔드포인트] create["이메일 주소를 기준으로 이슈/노트를 생성하는 Sidekiq 이메일 핸들러 작업"] end

sidekiq 전달 방법 (16.0부터 사용 중지됨)

sidekiq 전달 방법은 이메일 본문 및 메타데이터를 Sidekiq이 작업을 관리하기 위해 사용하는 Redis 대기열에 직접 추가합니다. 이는 전달 방법과 Redis 구성 사이에 강한 결합이 있어 사용되었으며 또한 작업 페이로드 압축과 같은 Sidekiq 프레임워크 최적화를 사용할 수 없었기 때문에 16.0에서 사용이 중지되었습니다.

flowchart TB User --이메일 전송--> provider[(이메일 제공 업체 메일함)] mail_room --IMAP 또는 Microsoft Graph API를 통해 미확인 이메일 가져오기--> provider mail_room --Redis 대기열에 직접 작성하여 핸들러 작업 실행 예약--> redis[Redis 대기열] redis --Sidekiq이 대기열에서 작업을 가져와 실행--> create subgraph mail_room_process[mail_room] mail_room[mail_room 스레드] end subgraph GitLab create["이메일 주소를 기반으로 이슈/노트를 생성하는 Sidekiq 이메일 핸들러 작업"] end

제안

Sidekiq 작업을 사용하여 정기적으로(매 분마다, 나중에 구성 가능하도록) 메일함을 폴링하도록 합니다. 모든 기존 레거시 이메일 흡수 인프라를 제거합니다.

flowchart TB User --이메일 전송--> provider[(이메일 제공 업체 메일함)] 흡수 --IMAP 또는 Microsoft Graph API를 통해 미확인 이메일 가져오기--> provider controller --"각 메일함에 대해 작업 트리거"--> 흡수 흡수 --가져온 각 이메일에 대해 작업 추가--> create subgraph GitLab controller[예약된 Sidekiq 흡수 컨트롤러 작업] 흡수[Sidekiq 메일함 흡수 작업] create["기존 Sidekiq 이메일 핸들러 작업 이메일 주소를 기반으로 이슈/노트를 생성하는"] end
  1. 매 분 또는 매 두 분마다 예약된 controller 작업을 사용합니다. 이 작업은 각 구성된 메일함(incoming_email 및 service_desk_email)에 대해 하나의 작업을 추가합니다.
  2. 구체적인 ingestion 작업은 메일함을 폴링하고 미확인 이메일을 다운로드하며, 이메일을 처리하는 작업을 추가합니다. 사용된 To 이메일 주소에 따라 어떤 이메일 핸들러를 사용할지 결정합니다.
  3. existing email handler 작업은 이슈를 생성하거나 Service Desk 이슈를 생성하거나 기존 이슈/Merge Request에 노트를 작성하려고 시도합니다. 이러한 핸들러는 mail_room을 통한 레거시 이메일 흡수에서도 사용됩니다.

Sidekiq 작업 및 작업 페이로드 크기 최적화

우리는 Sidekiq 작업과 이메일 작업 페이로드에 대한 크기 제한을 구현했고, 특히 첨부 파일이 있는 이메일은 이 기준을 통과하는 경우가 많습니다. 우리는 Sidekiq 메일함 흡수 작업에서 이메일 처리를 직접 처리하는 아이디어에 실험해 볼 필요가 있습니다. 우리는 이 모드와 각 이메일에 대한 Sidekiq 작업 사이를 전환하기 위해 ‘ops’ 피처 플래그를 사용할 수 있을 것입니다.

또한, 메시지 ID만 검색한 후에 완전한 메시지를 다운로드하는 솔루션 경로를 탐색해 보고 싶습니다(예를 들어 UID 범위로 필터링). 예를 들어, 우리는 메일함을 폴링하여 메시지 ID 디렉터리을 가져옵니다. 그런 다음 메시지 ID나 범위를 인수로 사용하여 매 25개(또는 n개)의 이메일마다 새 작업을 작성합니다. 그런 다음 이러한 작업은 전체 메시지를 다운로드하고 동기적으로 이슈나 답장을 추가합니다. 이메일 수가 25개 미만이면, 리소스를 저장하기 위해 현재 작업에서 직접 이메일을 처리할 수도 있습니다. 이렇게 하면 이메일의 크기가 제한 요소가되는 것을 제거할 수 있습니다. 단점은 한 번에 두 번의 IMAP 서버 호출이 필요하다는 것입니다(n+1).

실행 계획

  1. mail_room 이메일 흡수에 대한 사용을 중단합니다.
  2. gitlab-mail_room gem에서 연결별 로직을 삭제하여 새로운 별도의 gem으로 이동합니다. mail_room 및 기타 클라이언트가 여기에서 우리의 작업을 사용할 수 있습니다. 현재 우리는 IMAP 및 Microsoft Graph API 연결을 지원합니다.
  3. 새 작업을 추가합니다(만약 Sidekiq이 실행되지 않는다면 대용량의 작업 대기열을 피하기 위해 이당성 및 중복 제거 플래그를 설정합니다).
  4. gitlab.rb에서 이메일 흡수를 활성화하는 설정을 추가합니다. gitlab.rb에서 mailroom['enabled'] = false를 설정하여 mail_room 이메일 흡수를 비활성화합니다. 추가로 피처 플래그를 추가할 수도 있습니다.
  5. 베타에서 Self-Managed형되는 고객이 시도할 수 있도록 gitlab.com에서 먼저 사용합니다만 GA(General Availability)에는 추가합니다.
  6. GA(General Availability)에 롤아웃되고 삭제가 예정된 후, gitlab-mail_room에 대한 의존성을 완전히 제거하고, api/internal/mail_room에 대한 내부 API 엔드포인트, mail_room.yml 동적으로 생성되는 정적 구성 파일, 기타 구성 및 이진 파일을 모두 제거합니다.

변경 관리

우리는 GitLab 16.0에서 mail_room의 sidekiq 전달 방법을 사용 중지하기로 결정했고 GitLab 17.0에서 제거하는 일정을 계획했습니다. 이 설계 문서가 구현되고 고객들이 새로운 이메일 흡수를 사용할 수 있게 되면 sidekiq 전달 방법을 제거할 수 있습니다.

그 후에 mail_room을 제거하도록 일정을 계획해야 합니다(GitLab 17.0 이상). 이는 중단 변동 사항이 될 것입니다. 우리는 새로운 이메일 흡수를 사전에 기본값으로 만들 수 있기 때문에 Self-Managed형 고객들은 조치를 취할 필요가 없습니다.

대안적 해결책

아무것도 하지 않기

현재 설정은 우리를 제한하며 두 개의 이메일 주소만 가져올 수 있도록 합니다. IMAP 또는 API 통합을 통해 서비스 데스크 사용자 정의 이메일 주소를 게시하기 위해 위에서 설명한 것과 동일한 아키텍처를 제공해야 합니다. 그런 이유로 지금 바로 대처해야 하며, incoming_email 및 service_desk_email을 위한 일반적인 이메일 흡수를 먼저 포함하고 인프라 부하를 제거해야 합니다.

추가 자원

타임라인

  • 2023-09-26: 초기 설계안 버전이 Merge되었습니다.