파일 저장소로 Azure Blob Storage 구성

Mattermost는 사용자가 업로드한 항목(첨부 파일, 프로필 이미지, 플러그인 자산, 이모지, 컴플라이언스 내보내기)을 Azure Storage 계정에 저장할 수 있습니다. 이 가이드는 관리자가 Azure 쪽을 프로비저닝하고 시스템 콘솔에서 Mattermost 서버가 이를 바라보도록 설정하는 절차를 안내합니다.

사전 요구 사항

• 스토리지 계정과 컨테이너가 이미 생성된 Azure 구독.
• Azure 포털, 또는 Azure CLI(az)가 설치되어 있고 az login으로 로그인된 상태. 아래에서 두 방식 모두 설명합니다.
• 시스템 관리자 계정으로 시스템 콘솔에 접근할 수 있는 Mattermost 배포(v11.9 이상).

다른 백엔드에서 기존 파일을 마이그레이션할 계획이라면, 구성을 변경하기 전에 현재 저장 위치(S3 버킷, 로컬 디스크 등)를 백업하세요. 파일 드라이버를 전환해도 기존 파일이 자동으로 마이그레이션되지는 않습니다.

1단계: 인증 모드 선택

Mattermost는 서버가 Azure에 인증하는 두 가지 방식을 지원합니다. 서버 실행 환경에 맞는 방식을 선택하세요.

• Shared key: 서버가 스토리지 계정 액세스 키로 각 요청에 서명합니다. 호스트가 Azure ID를 갖고 있을 필요가 없으므로 Mattermost가 실행되는 어디에서나(온프레미스, Azure가 아닌 클라우드, 로컬 개발 환경) 동작합니다. 다만 키가 config.json에 저장되는 장기 유효 시크릿이라는 단점이 있습니다.
• Default credential (Microsoft Entra ID): 서버가 Microsoft Entra ID에서 토큰을 받아 요청에 서명합니다. Mattermost 구성에 장기 유효 시크릿이 남지 않습니다. 호스트 환경이 이미 ID를 제공하는 Azure 상의 배포(Azure VM / App Service / AKS의 관리 ID, 페더레이션 워크로드용 워크로드 ID, 또는 서비스 주체)에 권장되는 방식입니다.

두 모드는 Azure 쪽 설정이 조금 다릅니다. 선택한 방식에 해당하는 하위 섹션을 따르세요. 나중에 시스템 콘솔에서 Azure authentication 설정을 바꿔 모드를 전환할 수 있습니다.

옵션 A: Shared key

스토리지 계정 액세스 키를 가져옵니다.

Azure 포털

1. 스토리지 계정을 연 뒤 Security + networking > Access keys로 이동합니다.
2. key1(또는 key2) 옆의 Show를 선택해 값을 복사합니다.

Azure CLI

az storage account keys list \
    --account-name acmemattermost \
    --resource-group mm-prod-files \
    --query "[0].value" -o tsv

옵션 B: Default credential (Microsoft Entra ID)

서버는 Azure SDK의 DefaultAzureCredential을 사용하며, 런타임에 다음 순서로 사용할 수 있는 ID를 탐색합니다. 토큰을 반환하는 첫 번째 소스가 사용됩니다.

1. EnvironmentCredential — 서비스 주체 환경 변수.
2. WorkloadIdentityCredential — 페더레이션 워크로드 ID.
3. ManagedIdentityCredential — 플랫폼이 제공하는 관리 ID.
4. AzureCLICredential — 로그인된 az 세션. 로컬 개발에 유용합니다.

SDK가 어떤 ID를 선택하든, 그 ID에 스토리지 계정 또는 컨테이너에 대한 Storage Blob Data Contributor(또는 동등한 read/write/list/delete 데이터 플레인 작업을 갖는 사용자 지정 역할)가 부여되어 있어야 합니다. 그렇지 않으면 TestConnection이 AuthorizationPermissionMismatch를 반환합니다.

호스트에 맞는 ID 소스를 선택하세요.

사용할 계정을 준비하려면 Azure 포털이나 아래와 같이 Azure CLI로 역할을 할당해야 합니다(Mattermost가 인증에 사용할 ID의 주체로 바꿔 넣으세요).

STORAGE_ACCOUNT_ID=$(az storage account show \
    --name acmemattermost \
    --resource-group mm-prod-files \
    --query id -o tsv)

# For a managed identity (system-assigned on a VM/App Service/AKS pod):
az role assignment create \
    --assignee-object-id "<principalId-of-the-managed-identity>" \
    --assignee-principal-type ServicePrincipal \
    --role "Storage Blob Data Contributor" \
    --scope "$STORAGE_ACCOUNT_ID"

# For a service principal:
az role assignment create \
    --assignee "<appId-of-the-service-principal>" \
    --role "Storage Blob Data Contributor" \
    --scope "$STORAGE_ACCOUNT_ID"

2단계: Mattermost 구성

시스템 관리자로 로그인해 System Console > Environment > File Storage(시스템 콘솔 > 환경 > 파일 저장소)를 엽니다.

1. File storage system: Azure Blob Storage를 선택합니다. Azure 전용 필드가 나타나고 S3/로컬 필드는 숨겨집니다.

2. Azure cloud: 스토리지 계정을 호스팅하는 Azure 클라우드를 선택합니다.

   • Azure Commercial(기본값): 글로벌 Azure 클라우드({account}.blob.core.windows.net). 스토리지 계정 이름만 필요합니다.
   • Azure Government: 미국 정부 클라우드({account}.blob.core.usgovcloudapi.net). 스토리지 계정 이름만 필요합니다.
   • Custom Endpoint: 그 밖의 Azure 클라우드(예: Azure China), Azurite 에뮬레이터, 또는 리버스 프록시. 아래 Azure endpoint에 전체 Blob 서비스 URL을 입력합니다.

3. Azure Storage account: 스토리지 계정 이름(예: acmemattermost).

4. Azure container: 컨테이너 이름(예: mattermost).

5. Azure path prefix: 선택 사항입니다. Mattermost가 컨테이너 내부의 하위 경로(예: prod/)에 쓰도록 하려면 설정하세요. 컨테이너 루트를 사용하려면 비워 둡니다.

6. Azure authentication: 1단계에서 설정한 모드를 선택합니다.

   • Shared key(기본값): Mattermost가 스토리지 계정 액세스 키로 각 요청에 서명합니다. 옵션 A: Shared key를 진행했다면 이 항목을 선택하세요.
   • Default credential (Microsoft Entra ID): Mattermost가 호스트 환경이 제공하는 ID로 인증합니다. 옵션 B: Default credential (Microsoft Entra ID)를 진행했다면 이 항목을 선택하세요. 이 모드에서는 액세스 키를 사용하지 않으므로 아래의 Azure Storage account key 필드가 숨겨집니다.

7. Azure Storage account key(Azure authentication이 Shared key일 때만 표시): 옵션 A: Shared key에서 가져온 shared key를 붙여 넣습니다.

8. Azure endpoint(Azure cloud가 Custom Endpoint로 설정된 경우에만 표시): 스킴과 스토리지 계정을 포함한 전체 Blob 서비스 URL입니다. Mattermost는 이 URL을 그대로 Azure SDK에 전달하므로, 스토리지 계정이 호스트 이름에 포함(vhost 방식, 예: https://acmemattermost.blob.core.chinacloudapi.cn/)되어 있거나 경로에 포함(path 방식, Azurite의 경우 예: http://localhost:10000/devstoreaccount1/)되어 있어야 합니다. 선택한 인증 모드는 이 URL이 가리키는 호스트를 기준으로 서명하므로, 그 호스트가 위에서 지정한 스토리지 계정을 제공해야 합니다.

9. Enable secure Azure Blob Storage connections(Azure cloud가 Azure Commercial 또는 Azure Government일 때만 표시): 기본값인 활성화 상태로 두세요. Custom Endpoint 클라우드는 Azure endpoint URL에서 스킴을 결정하므로 해당 모드에서는 이 토글이 숨겨집니다.

10. Azure request timeout (milliseconds): 기본값은 30000(30초)입니다. 대용량 객체 처리에 네트워크 시간이 더 필요한 경우에만 늘리세요.

설정을 저장한 뒤 Test Connection을 클릭합니다. Mattermost가 폼에 입력된 자격 증명으로 구성된 컨테이너에 대해 무해한 쓰기/읽기/삭제를 시도합니다. 초록색 Connection was successful 메시지가 표시되면 자격 증명, 컨테이너 이름, 엔드포인트가 모두 정상이라는 뜻입니다. 빨간색 오류 메시지에는 근본 원인이 포함되며, 흔한 사례는 문제 해결에 정리되어 있습니다.

3단계: 검증

1. 재시작한 뒤 시스템 콘솔이나 아무 채널을 새로 고칩니다.
2. 아무 채널에서 첨부 파일을 업로드합니다. 작은 이미지가 좋은 테스트입니다. Mattermost가 이미지 하나당 세 개의 blob(원본, 미리보기, 썸네일)을 저장하므로 일반 파일보다 업로드 경로를 더 폭넓게 검증할 수 있습니다.
3. 게시물에 첨부 파일과 미리보기가 평소처럼 표시되어야 합니다.
4. Azure 포털에서 컨테이너를 열어 <YYYYMMDD>/teams/<team>/channels/<channel>/users/<user>/<file_id>/ 경로 아래에 새 blob이 생성되었는지 확인합니다(로컬 디스크 및 S3 백엔드와 동일한 구조입니다). 이미지의 경우 <name>.<ext>, <name>_preview.<ext>, <name>_thumb.<ext>가 보입니다.

Amazon S3에서 기존 파일 마이그레이션

기존 배포를 S3에서 Azure Blob Storage로 전환하는 경우, Mattermost가 기록했을 키와 동일한 키로 파일 내용이 Azure 컨테이너에 존재해야 합니다. Mattermost 자체는 백엔드 간에 파일을 옮기지 않으므로, 드라이버를 전환하기 전에 한 번 실행하는 아웃오브밴드 복사 작업입니다.

Mattermost는 모든 백엔드에서 동일한 상대 경로에 blob을 기록합니다.

{path-prefix}/{YYYYMMDD}/teams/{teamID}/channels/{channelID}/users/{userID}/{fileID}/{filename}

따라서 S3 버킷에서 Azure 컨테이너로 키를 그대로 복사하는 것만으로 충분합니다. S3 쪽에서 AmazonS3PathPrefix를 사용한다면 Azure 쪽 AzurePathPrefix에 같은 값을 설정하거나, 복사 과정에서 접두사를 다시 쓰세요.

이를 수행하는 방법은 여러 가지가 있습니다. 권장하는 방법은 Amazon S3에서 Azure Blob Storage로의 클라우드 간 마이그레이션을 제공하는 Azure Storage Mover 서비스를 사용하는 것입니다.

rclone, AzCopy 같은 대안 도구도 도움이 됩니다.

(선택) 내보내기 백엔드 구성

컴플라이언스 및 데이터 내보내기는 일반 파일 업로드와 분리해 저장할 수 있습니다. 시스템 콘솔에서 File Storage 바로 아래에 있는 File Storage (Exports) 섹션은 위와 동일한 필드를 갖고 있으며 같은 Azure 자격 증명을 받습니다. 고객사들은 내보내기 보존 정책을 일반 업로드와 다르게 가져갈 수 있도록 보통 다른 컨테이너(또는 다른 계정)를 내보내기 대상으로 지정합니다. 내보내기 대상은 자체 드라이버와 자격 증명을 갖는 독립 백엔드이므로 일반 업로드와 같은 공급자를 쓸 필요가 없습니다. 예를 들어 업로드는 Amazon S3에 두고 내보내기는 Azure Blob Storage로 보내거나, 그 반대로 구성할 수 있습니다.

ExportAzure* 키의 전체 목록은 Enable dedicated export filestore target을 참고하세요.

문제 해결

레퍼런스

각 Azure 설정은 환경 설정 문서에 자세히 설명되어 있습니다.

• File storage system (FileSettings.DriverName)
• Azure Storage account (FileSettings.AzureStorageAccount)
• Azure container (FileSettings.AzureContainer)
• Azure path prefix (FileSettings.AzurePathPrefix)
• Azure authentication (FileSettings.AzureAuthMode)
• Azure Storage account key (FileSettings.AzureAccessKey)
• Azure cloud (FileSettings.AzureCloud)
• Azure endpoint (FileSettings.AzureEndpoint)
• Enable secure Azure Blob Storage connections (FileSettings.AzureSSL)
• Azure request timeout (FileSettings.AzureRequestTimeoutMilliseconds)