Skip to document
pieroot log
Welcome
Markdown으로 보기
Markdown Preview

OpenStack Manila를 이용한 CephFS 기반 공유 파일 시스템 배포 가이드

Frontmatter 2026-02-23 · 3 tags
---
title: OpenStack Manila를 이용한 CephFS 기반 공유 파일 시스템 배포 가이드
author: 봉정근
date:
modified:
category: 📗 Docs
tags: [openstack, ceph, kolla ansible]
---

OpenStack에서 공유 파일 스토리지를 제공하는 Manila를 CephFS Native 백엔드로 Kolla Ansible 환경에 배포하는 전체 과정과 핵심 설정을 안내한다. Ceph에 메타데이터와 데이터 풀을 만들고 CephFS 파일시스템을 생성한 뒤, 적절한 키링을 생성해 두 경로에 복사한다. Manila 이미지와 Flavor를 준비하고, globals.yml에 Manila 및 CephFS Native 옵션을 활성화하며, 필요 시 manila-share.conf에 추가 설정을 넣는다. 배포 전 MDS 상태와 ceph.conf 탭 문자 등을 확인하고, 배포 후 컨테이너와 서비스 상태를 검증한다. 마지막으로 share type을 생성하고 CephFS share를 만들며, 접근 권한을 부여해 인스턴스에서 마운트하는 절차를 설명한다.

OpenStack Manila를 이용한 CephFS 기반 공유 파일 시스템 배포 가이드
OpenStack에서 VM이나 컨테이너에 공유 파일 스토리지를 제공하려면 Manila라는 서비스가 필요하다. Manila은 SFaaS(Shared File Systems as a Service)를 제공하는 OpenStack 프로젝트로, NFS나 CIFS 같은 프로토콜을 통해 여러 인스턴스가 동시에 접근할 수 있는 파일 시스템을 관리한다.
이번 글에서는 Kolla Ansible 환경에서 Manila을 CephFS Native 백엔드로 배포하는 전 과정을 다룬다. Ceph 풀 생성부터 키링 설정, globals.yml 구성, 배포, 그리고 실제 공유 볼륨 마운트까지 단계별로 정리했다.
📌
이 글에서 다루는 내용
  • Manila이란 무엇인가, 왜 필요한가
  • Ceph 스토리지에서 CephFS 풀 및 파일시스템 생성
  • Manila용 Ceph 키링 생성 및 설정 파일 복사
  • Manila 서비스 이미지 업로드 및 Flavor 생성
  • Kolla Ansible globals.yml 및 manila-share.conf 설정
  • 배포 및 Share Type 생성
  • 실제 CephFS 공유 볼륨 마운트

🤔 Manila이란?

Manila은 OpenStack의 공유 파일 시스템 서비스다. Cinder가 블록 스토리지(디스크)를 제공한다면, Manila은 파일 스토리지(공유 폴더)를 제공한다. 여러 VM이 동시에 같은 스토리지에 접근해야 하는 경우에 필수적이다.
💡
Manila의 핵심 구성 요소
  • manila-api: 사용자 요청을 받는 API 서비스
  • manila-scheduler: 어떤 백엔드에 share를 생성할지 결정하는 스케줄러
  • manila-share: 실제로 스토리지 백엔드와 통신하여 share를 관리하는 서비스
  • manila-data: share 마이그레이션 등 데이터 관련 작업을 수행하는 서비스
Manila의 백엔드로는 여러 가지를 사용할 수 있지만, 이번 글에서는 CephFS Native 드라이버를 사용한다. CephFS Native 방식은 별도의 NFS 게이트웨이 없이 Ceph 클라이언트가 직접 CephFS에 마운트하는 방식이다. 오버헤드가 적고 성능이 좋다는 장점이 있다.
⚠️
CephFS Native vs CephFS NFS
  • CephFS Native: Ceph 클라이언트가 직접 마운트. 성능이 좋지만, 인스턴스에 Ceph 클라이언트가 설치되어 있어야 한다
  • CephFS NFS: NFS-Ganesha를 통해 NFS 프로토콜로 제공. 호환성이 좋지만 NFS 게이트웨이가 병목이 될 수 있다
CephFS Native 백엔드 아키텍처
CephFS Native 백엔드 아키텍처

🔧 Ceph 스토리지 준비

Manila이 CephFS를 사용하려면, 먼저 Ceph 클러스터에 CephFS용 풀과 파일시스템을 생성해야 한다.
OpenStack Manila를 위한 CephFS 준비 과정
OpenStack Manila를 위한 CephFS 준비 과정

기존 CephFS 확인

먼저 현재 Ceph 클러스터에 이미 생성된 CephFS volume이 있는지 확인한다.
bash
# 기존 FS 확인
ceph fs volume ls

Manila용 CephFS 생성

manila라는 이름의 CephFS가 없다면 새로 생성한다.
bash
# 없으면 생성 (MDS도 함께 배포됨)
ceph fs volume create manila
💡
왜 ceph fs volume create를 사용하는가?
예전 방식처럼 ceph osd pool create로 metadata/data pool을 직접 만들고 ceph fs new를 실행할 수도 있다. 하지만 cephadm 기반 환경에서는 ceph fs volume create manila 명령을 쓰면 CephFS 생성과 MDS 배포 흐름이 함께 처리되어 더 단순하다. 명령어 세 줄 줄어드는 건 언제나 환영이다

NFS manager module 활성화

CephFS Native만 사용할 경우 필수는 아니지만, CephFS NFS 백엔드를 함께 검토하거나 NFS-Ganesha 기반 구성을 사용할 예정이라면 Ceph manager의 NFS module을 활성화해둔다.
bash
# Ceph NFS manager module 활성화
ceph mgr module enable nfs
📝
CephFS Native와 NFS module의 관계
CephFS Native 드라이버는 인스턴스가 Ceph 클라이언트로 직접 마운트하는 방식이다. 반면 CephFS NFS 방식은 NFS-Ganesha를 통해 NFS 프로토콜로 제공한다. 이 글은 Native 구성을 중심으로 설명하지만, NFS 백엔드까지 확장할 가능성이 있다면 nfs manager module을 미리 활성화해두는 편이 좋다.
이름을 cephfs 로 잘못 지정했지만 manila 로 변경해서 진행할 예정이니 코드블럭 따라서 하면 된다.
이름을 cephfs 로 잘못 지정했지만 manila 로 변경해서 진행할 예정이니 코드블럭 따라서 하면 된다.
생성이 완료되면 상태를 확인한다.
bash
# 파일시스템 목록 확인
ceph fs ls

# manila 파일시스템 상태 확인
ceph fs status manila
notion image

MDS(Metadata Server) 확인

notion image
⚠️
MDS가 없으면?
CephFS 파일시스템이 존재해도 MDS 데몬이 없으면 실제로 마운트가 불가능하다. ceph fs status에서 MDS가 active 상태인지 반드시 확인하자. cephadm을 사용하는 경우 ceph orch apply mds manila로 MDS를 배포할 수 있다.
notion image
만약 위와같이 뜬다면 MDS를 제거했거나 아직 안만들었기 때문이다. CephFS는 메타데이터를 관리하기 위해 MDS 데몬이 반드시 필요하다. Ceph 스토리지에서 MDS 서비스를 생성해주면 된다. 이거 빼먹으면 나중에 manila-share가 올라오질 않는다

🔑 Ceph 키링 생성 및 설정 파일 배치

Manila이 CephFS에 접근하려면 적절한 권한을 가진 Ceph 사용자 키링이 필요하다.

Manila용 키링 생성

bash
# /etc/ceph/ceph.client.manila.keyring 파일 생성
ceph auth get-or-create client.manila \
    mon 'allow r' \
    mgr 'allow r' \
    osd 'allow rw tag cephfs *=manila' \
    mds 'allow rw path=/' \
    -o /etc/ceph/ceph.client.manila.keyring
notion image
📝
키링 권한 해설
  • mon 'allow r': 모니터 정보 읽기. 클러스터 상태 확인에 필요
  • mgr 'allow r': 매니저 정보 읽기
  • osd 'allow rw tag cephfs *=manila': manila이라는 이름의 CephFS에 대해 읽기/쓰기 허용. 다른 풀에는 접근 불가
  • mds 'allow rw path=/': MDS를 통해 파일시스템 전체 경로에 대해 읽기/쓰기 허용

Kolla Ansible 설정 디렉토리에 파일 복사

Kolla Ansible이 배포 시 Manila 컨테이너에 Ceph 설정을 주입할 수 있도록, 적절한 경로에 파일을 배치해야 한다.
bash
# Manila 설정 디렉토리 생성
mkdir -p /etc/kolla/config/manila
mkdir -p /etc/kolla/config/manila/manila-share

# Ceph 설정 파일 복사
cp /etc/ceph/ceph.conf /etc/kolla/config/manila/ceph.conf

# 키링 파일 복사 (manila 디렉토리와 manila-share 디렉토리 둘 다 필요)
cp /etc/ceph/ceph.client.manila.keyring \
   /etc/kolla/config/manila/ceph.client.manila.keyring
cp /etc/ceph/ceph.client.manila.keyring \
   /etc/kolla/config/manila/manila-share/ceph.client.manila.keyring
⚠️
왜 키링을 두 곳에 복사하는가?
/etc/kolla/config/manila/는 manila-api, manila-scheduler 등 전체 Manila 서비스에 공통으로 적용되는 설정이고, /etc/kolla/config/manila/manila-share/는 manila-share 서비스에만 특별히 적용되는 설정이다. manila-share가 실제로 CephFS와 통신하는 컴포넌트이므로, 키링이 반드시 manila-share 경로에도 존재해야 한다.
💡
ceph.conf에서 탭 문자 주의!
ceph config generate-minimal-conf 같은 명령어로 생성한 ceph.conf에는 앞에 탭 문자가 포함되어 있을 수 있다. Kolla Ansible의 ini 파서는 이 탭을 처리하지 못하므로, 복사하기 전에 반드시 탭을 스페이스로 변환하자.

🖼️ Manila 서비스 이미지 및 Flavor 준비

Manila의 Generic 드라이버(DHSS=True) 방식에서는 share server를 위한 별도의 VM 이미지와 Flavor가 필요하다. CephFS Native 드라이버에서는 share server가 필요 없지만(DHSS=False), 기본 설정에서 service_instance_flavor_id를 참조하므로 이미지와 Flavor를 미리 준비해두는 것이 안전하다.

서비스 이미지 다운로드 및 업로드

bash
# Manila 서비스 이미지 다운로드
wget https://tarballs.opendev.org/openstack/manila-image-elements/images/manila-service-image-master.qcow2

# Ceph 최적화를 위해 raw 포맷으로 변환
qemu-img convert -f qcow2 manila-service-image-master.qcow2 \
  -O raw manila-service-image-master.raw

# Glance에 업로드
glance image-create --name "manila-service-image" \
  --file manila-service-image-master.raw \
  --disk-format raw --container-format bare \
  --visibility public --progress
notion image
notion image
💡
왜 raw 포맷으로 변환하는가?
Ceph RBD를 Glance 백엔드로 사용하는 경우, raw 포맷이 성능상 유리하다. qcow2는 Ceph에서 내부적으로 다시 변환해야 하므로 오버헤드가 발생한다. 이미 Ceph 쓰는데 qcow2 쓸 이유가 없다

Flavor 생성

bash
# Manila 서비스용 Flavor 생성 (ID: 100, RAM: 128MB, Disk: 0GB, vCPU: 1)
nova flavor-create manila-service-flavor 100 128 0 1
📝
Flavor ID 100의 의미
Manila은 기본적으로 service_instance_flavor_id = 100을 사용한다. 다른 ID를 쓰고 싶다면 manila-share.conf에서 변경할 수 있다. CephFS Native 드라이버를 사용하는 경우 share server VM이 생성되지 않으므로, 이 Flavor는 실제로 사용되지 않지만 설정 검증 단계에서 참조될 수 있다.

⚙️ Kolla Ansible globals.yml 설정

이제 본격적으로 Kolla Ansible의 globals.yml에서 Manila 관련 설정을 진행한다.

Manila 활성화

yaml
enable_manila: "yes"
Manila 서비스를 배포하겠다는 선언이다. 이거 안 켜면 아무리 키링을 복사해도 아무 일도 안 일어난다

CephFS Native 백엔드 활성화

yaml
enable_manila_backend_cephfs_native: "yes"
📝
Manila 백엔드 옵션들
  • enable_manila_backend_generic: Generic 드라이버 (Cinder 볼륨 기반, DHSS=True)
  • enable_manila_backend_cephfs_native: CephFS Native 드라이버 (이번 글에서 사용)
  • enable_manila_backend_cephfs_nfs: CephFS + NFS-Ganesha 드라이버
  • enable_manila_backend_glusterfs_nfs: GlusterFS + NFS 드라이버
CephFS Native는 DHSS(Driver Handles Share Servers)가 False이므로, share server VM을 생성하지 않는다. 직접 CephFS에 접근하기 때문에 구조가 단순하고 성능이 좋다.

Ceph 인증 정보 설정 (선택)

yaml
# Manila의 Ceph 사용자 이름 (기본값: manila)
# ceph_manila_user: "manila"
기본값이 manila이므로, 앞서 client.manila로 키링을 생성했다면 별도로 설정하지 않아도 된다.

CephFS 파일시스템 이름 설정

Ceph Pacific 이상 버전에서 여러 개의 CephFS 파일시스템을 운영하고 있다면, Manila이 사용할 파일시스템 이름을 명시적으로 지정해야 한다.
yaml
manila_cephfs_filesystem_name: "manila"
⚠️
파일시스템 이름 설정 안 하면?
기본적으로 Manila은 ceph fs volume ls 명령이 반환하는 첫 번째 파일시스템을 사용한다. CephFS가 하나만 있으면 문제없지만, 여러 개가 있는 환경에서는 의도치 않은 파일시스템을 사용할 수 있다. 명시적으로 지정하는 습관을 들이자.

📝 manila-share.conf 추가 설정

globals.yml 외에도, manila-share 서비스에 대한 추가 설정이 필요할 수 있다. /etc/kolla/config/manila-share.conf 파일을 생성하고 다음 내용을 추가한다.
plain text
[DEFAULT]
# Generic 백엔드를 함께 사용하는 경우 필요
# service_instance_flavor_id = 100

[cephfsnative1]
# CephFS Native 드라이버 설정
driver_handles_share_servers = False
share_backend_name = CEPHFS
share_driver = manila.share.drivers.cephfs.driver.CephFSDriver
cephfs_conf_path = /etc/ceph/ceph.conf
cephfs_protocol_helper_type = CEPHFS
cephfs_auth_id = manila
cephfs_cluster_name = ceph
cephfs_filesystem_name = manila
💡
설정 항목 해설
  • driver_handles_share_servers = False: CephFS Native는 share server VM을 생성하지 않는다
  • share_driver: CephFS 드라이버 클래스 경로
  • cephfs_auth_id = manila: 앞서 생성한 Ceph 사용자 이름과 일치해야 한다
  • cephfs_filesystem_name = manila: 사용할 CephFS 파일시스템 이름
⚠️
주의: Kolla Ansible 버전에 따라 다를 수 있다!
최신 Kolla Ansible에서는 enable_manila_backend_cephfs_native: "yes" 설정만으로 대부분의 manila-share.conf 설정이 자동 생성된다. 위 설정은 수동으로 커스터마이징이 필요한 경우에 참고하자. 자동 생성된 설정과 충돌하지 않도록 주의해야 한다.

🚀 배포

설정이 완료되었으면 배포를 진행한다.
bash
# 전체 배포 (처음 설치하는 경우)
kolla-ansible deploy -i multinode

# 이미 배포된 환경에서 Manila만 추가하는 경우
kolla-ansible reconfigure -i multinode --tags manila
⚠️
배포 전 체크리스트
  • [ ] enable_manila: "yes" 가 globals.yml에 설정되어 있는지 확인
  • [ ] enable_manila_backend_cephfs_native: "yes" 가 설정되어 있는지 확인
  • [ ] Ceph에 manila 파일시스템이 정상 생성되었는지 확인 (ceph fs ls)
  • [ ] MDS 데몬이 active 상태인지 확인 (ceph fs status manila)
  • [ ] /etc/kolla/config/manila/ceph.conf 파일이 존재하는지 확인
  • [ ] /etc/kolla/config/manila/manila-share/ceph.client.manila.keyring 파일이 존재하는지 확인
  • [ ] ceph.conf에 탭 문자가 없는지 확인
배포가 완료되면 Manila 관련 컨테이너들이 정상적으로 동작하는지 확인한다.
bash
# Manila 컨테이너 상태 확인
docker ps | grep manila

# 예상 결과:
# manila_api
# manila_scheduler
# manila_share
# manila_data

✅ 동작 확인

Manila 서비스 상태 확인

bash
# Manila 서비스 목록 확인
manila service-list
모든 서비스의 State가 up이고 Status가 enabled이면 정상이다. 특히 manila-share 서비스의 Host가 share1@cephfsnative1과 같은 형태로 표시되면 CephFS 백엔드가 제대로 연결된 것이다.

Share Type 생성

Manila에서 share를 생성하려면 share type이 먼저 존재해야 한다.
Manila CephFS Native share 생성 및 마운트 흐름
Manila CephFS Native share 생성 및 마운트 흐름
bash
# CephFS Native용 share type 생성 (DHSS=False)
manila type-create cephfs_native_type False

# share type에 CephFS 관련 extra-specs 설정
manila type-key cephfs_native_type set \
  share_backend_name=CEPHFS \
  vendor_name=Ceph \
  storage_protocol=CEPHFS
📝
Share Type 설정 포인트
  • False: DHSS(Driver Handles Share Servers)를 비활성화. CephFS Native는 share server를 사용하지 않으므로 반드시 False로 설정
  • share_backend_name=CEPHFS: manila-share.conf에서 설정한 share_backend_name과 일치해야 한다
  • 이 share type이 기본값이 아니라면, share 생성 시 --share-type cephfs_native_type을 명시해야 한다

Share 생성

bash
# 1GB 크기의 CephFS share 생성
manila create --name test-cephfs-share \
  --share-type cephfs_native_type \
  CephFS 1

# 상태 확인 (available이 되면 성공)
manila show test-cephfs-share
💡
Share 상태 확인 포인트
  • status가 available이면 정상 생성 완료
  • creating에서 멈춰있다면 manila-share 로그 확인: docker logs manila_share
  • error가 뜬다면 키링 권한이나 CephFS 파일시스템 설정을 재확인하자

접근 권한 부여 및 마운트

bash
# 접근 권한 부여 (cephx 인증 방식)
manila access-allow test-cephfs-share cephx <access_user>

# export location 확인
manila share-export-location-list test-cephfs-share
인스턴스에서 CephFS를 마운트하려면 Ceph 클라이언트가 설치되어 있어야 한다.
bash
# 인스턴스에서 Ceph 클라이언트 설치 (Ubuntu 기준)
apt-get install ceph-common

# CephFS 마운트
mkdir ~/manila-share
mount -t ceph <mon_ip>:6789:/ ~/manila-share \
  -o name=<access_user>,secret=<access_key>

핵심 정리

✅ Manila: OpenStack의 공유 파일 시스템 서비스. 여러 VM이 동시에 접근 가능한 파일 스토리지 제공
✅ CephFS Native 드라이버: NFS 게이트웨이 없이 Ceph 클라이언트가 직접 마운트. DHSS=False
✅ CephFS volume 생성: ceph fs volume create manila로 Manila용 CephFS와 MDS 배포 흐름을 단순화할 수 있다
✅ MDS 필수: CephFS는 MDS 데몬 없이는 동작하지 않는다. 배포 전 반드시 확인
✅ 키링 복사 위치: /etc/kolla/config/manila/와 /etc/kolla/config/manila/manila-share/ 두 곳에 복사
✅ Share Type 생성 필수: manila type-create로 DHSS=False share type을 만들어야 share 생성 가능

주의사항

⚠️ ceph.conf 탭 문자: Kolla Ansible의 ini 파서가 탭을 처리하지 못한다. 반드시 스페이스로 변환
⚠️ MDS 미배포: CephFS 파일시스템만 만들고 MDS를 안 만드는 실수를 조심하자. manila-share가 올라오지 않는다
⚠️ 키링 권한 부족: osd 'allow rw tag cephfs *=manila'에서 파일시스템 이름이 일치해야 한다. 이름이 다르면 접근 거부
⚠️ 파일시스템 이름 불일치: globals.yml의 manila_cephfs_filesystem_name과 실제 Ceph 파일시스템 이름이 동일한지 확인
⚠️ Ceph 버전 호환성: Ceph Pacific 이상에서는 여러 파일시스템을 지원하므로, 파일시스템 이름을 명시적으로 지정하는 것을 권장

참고 자료