clouderacloudera-managerbackupdisaster-recoveryoperationsrest-apisecurity

Cloudera Manager 설정 백업과 복원 실전 가이드

GET/PUT /cm/deployment 두 API로 Cloudera Manager Deployment를 백업·복원하는 절차와, Redaction·deleteCurrentDeployment 같은 함정을 운영 관점에서 정리했습니다.

Data Dynamics2026年9月30日16 min read

This post is not yet translated. The original Korean version is shown below.

Cloudera Manager는 REST API로 현재 관리 중인 Deployment Configuration을 JSON으로 Export하고, 필요하면 같은 JSON을 Import해 구성을 복원할 수 있습니다. 사용하는 API는 단 두 개입니다.

GET /api/vXX/cm/deployment    # Backup
PUT /api/vXX/cm/deployment    # Restore

단순해 보이지만 운영에서 이 두 API를 안전하게 쓰려면 Redaction과 deleteCurrentDeployment=true 두 가지를 반드시 이해해야 합니다. 이 글은 그 함정까지 포함한 실전 절차를 정리합니다.

무엇이 백업되는가

Export되는 Deployment 정보에는 일반적으로 다음이 포함됩니다.

Cloudera Manager 설정
Cluster 정의
Host 정보
Service 구성 · Role 구성 · Role Configuration Group
서비스 Configuration
사용자 및 일부 보안 관련 설정
Cloudera Manager가 관리하는 Deployment 구조

즉 특정 서비스 설정 백업이라기보다 Cloudera Manager Deployment Configuration 전체의 논리적 백업으로 이해하는 편이 정확합니다.

주의 이 기능은 HDFS DataNode 데이터, Hive · Kudu · HBase 데이터 같은 실제 사용자 데이터를 백업하지 않습니다. Cloudera Manager의 PostgreSQL/MySQL/Oracle 데이터베이스 자체를 물리적으로 백업하는 기능도 아닙니다.

요구 권한

Configuration Export / Import에는 다음 권한이 필요합니다.

Cluster Administrator   또는   Full Administrator

Cloudera Manager가 Data Hub Cluster를 관리하는 환경에서는 이 기능을 사용할 수 없습니다.

전체 흐름

Loading diagram…

가장 중요한 함정 — Sensitive Configuration Redaction

Cloudera Manager는 기본적으로 Export되는 Configuration의 민감 정보를 redaction 처리합니다. Password나 Credential 설정이 이렇게 저장됩니다.

{
  "name": "database_password",
  "value": "REDACTED"
}

이 상태의 JSON을 그대로 Restore하면 실제 Password가 없으므로 정상 복구가 되지 않을 수 있습니다. 복원 가능한 백업을 만들려면 둘 중 하나를 선택해야 합니다.

Export 시 Redaction 비활성화 — 실제 값을 포함한 JSON 생성
Restore 전에 REDACTED 값 수정 — 기본 설정으로 Export하고, 복원 직전에 실제 값으로 치환

운영 환경에서는 JSON 안에 Password가 평문으로 들어갈 수 있으므로 보관 위치와 접근 권한에 특히 주의해야 합니다.

Redaction 비활성화

Cloudera Manager Server의 JVM Option에 다음을 추가합니다.

vi /etc/default/cloudera-scm-server

기존 설정이 다음과 같다면,

export CMF_JAVA_OPTS="-Xmx4G"

-Dcom.cloudera.api.redaction=false를 추가합니다.

export CMF_JAVA_OPTS="-Xmx4G -Dcom.cloudera.api.redaction=false"

변경 후 Cloudera Manager Server를 재시작하고 상태를 확인합니다.

sudo systemctl restart cloudera-scm-server
systemctl status cloudera-scm-server

보안 주의 Redaction을 비활성화하면 Export JSON에 Password·Credential이 포함됩니다. 이 파일은 일반 Configuration 파일이 아니라 Secret으로 취급해야 합니다.

권장 권한과 보관 위치는 다음과 같습니다.

chmod 600 cm-deployment.json

Encrypted Backup Storage
Vault
Restricted NFS
Encrypted Object Storage

Backup

API Version 확인

Cloudera Manager 버전에 따라 API Version이 달라지므로, 문서의 숫자를 고정해서 쓰지 말고 먼저 확인합니다.

curl -u admin:password \
http://cm.example.com:7180/api/version

v49

이 경우 이후 API 경로는 /api/v49/cm/deployment가 됩니다.

HTTP 환경

curl -u <ADMIN_USER>:<ADMIN_PASSWORD> \
"http://<CM_HOST>:7180/api/v49/cm/deployment" \
-o cm-deployment.json

shell redirection을 써도 됩니다.

curl -u admin:password \
"http://cm01.example.com:7180/api/v49/cm/deployment" \
> /backup/cloudera/cm-deployment.json

HTTPS 환경

TLS가 구성된 환경에서는 HTTPS URL(기본 7183 포트)을 사용합니다.

curl -u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment" \
-o /backup/cloudera/cm-deployment.json

내부 CA 또는 자체 서명 인증서를 curl이 신뢰하지 않는 경우, 테스트 목적으로는 -k를 쓸 수 있습니다.

curl -k -u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment" \
-o cm-deployment.json

다만 운영에서는 -k를 상시 사용하기보다 CA Certificate를 신뢰하도록 구성하는 편이 바람직합니다.

curl --cacert /etc/pki/ca-trust/source/anchors/company-ca.pem \
-u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment" \
-o cm-deployment.json

백업 파일 검증

파일 크기와 JSON 유효성을 확인합니다.

ls -lh cm-deployment.json
jq empty cm-deployment.json      # 오류가 없으면 정상 JSON
jq '.' cm-deployment.json | less

REDACTED 항목 확인

복원 목적의 백업이라면 REDACTED 존재 여부를 반드시 확인합니다.

grep -n 'REDACTED' cm-deployment.json
grep -o 'REDACTED' cm-deployment.json | wc -l

개수가 0이면 Redaction이 없는 백업일 가능성이 높고, 12처럼 값이 나오면 Restore 전에 해당 항목을 확인해야 합니다.

백업 파일 보안

Redaction을 비활성화한 Deployment JSON은 사실상 Credential 백업입니다. 권한을 제한하고, 가능하면 암호화해 보관합니다.

chown root:root cm-deployment.json
chmod 600 cm-deployment.json
 
gpg -c cm-deployment.json        # → cm-deployment.json.gpg
shred -u cm-deployment.json      # 원본 삭제

버전 관리

Configuration 변경 전마다 타임스탬프를 붙여 백업해 두면 유용합니다.

BACKUP_DIR=/backup/cloudera
DATE=$(date '+%Y%m%d-%H%M%S')
 
curl -u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment" \
-o "${BACKUP_DIR}/cm-deployment-${DATE}.json"

cm-deployment-20260930-090000.json
cm-deployment-20261001-090000.json
cm-deployment-20261002-090000.json

Backup Script 예제

#!/bin/bash
 
CM_HOST="cm01.example.com"
CM_PORT="7183"
CM_USER="admin"
CM_PASSWORD="password"
 
API_VERSION="v49"
 
BACKUP_DIR="/backup/cloudera-manager"
DATE=$(date '+%Y%m%d-%H%M%S')
 
BACKUP_FILE="${BACKUP_DIR}/cm-deployment-${DATE}.json"
 
mkdir -p "${BACKUP_DIR}"
 
curl --fail --silent --show-error \
    -u "${CM_USER}:${CM_PASSWORD}" \
    "https://${CM_HOST}:${CM_PORT}/api/${API_VERSION}/cm/deployment" \
    -o "${BACKUP_FILE}"
 
if [ $? -ne 0 ]; then
    echo "ERROR: Cloudera Manager configuration backup failed."
    exit 1
fi
 
if ! jq empty "${BACKUP_FILE}" >/dev/null 2>&1; then
    echo "ERROR: Invalid JSON file."
    exit 1
fi
 
chmod 600 "${BACKUP_FILE}"
 
echo "Backup completed:"
echo "${BACKUP_FILE}"

실제 운영에서는 스크립트 안에 Password를 직접 적지 말고 Vault, 환경변수, 보호된 Credential 파일, Secret 관리 시스템 등을 사용하세요.

Restore

Restore는 백업 JSON을 Deployment API로 PUT해 수행합니다.

PUT /api/v49/cm/deployment?deleteCurrentDeployment=true

Restore 전 확인 항목

1. Backup JSON의 API/CM Version
2. REDACTED 값 존재 여부
3. Hostname 변경 여부
4. Cluster 이름
5. 서비스 및 Role 배치
6. Repository 설정
7. TLS / AutoTLS 관련 설정
8. Kerberos Principal / Keytab
9. Database 접속정보
10. External Service URL

특히 Hostname이나 인프라가 바뀐 환경에 Deployment Backup을 그대로 Restore하는 것은 위험합니다.

REDACTED 값 수정

백업 파일에 다음과 같은 값이 남아 있다면,

{
    "name": "database_password",
    "value": "REDACTED"
}

Restore 전에 실제 값으로 바꿔야 합니다.

{
    "name": "database_password",
    "value": "ActualPassword"
}

Cluster Service 중지

Cloudera 공식 절차는 Restore 전에 Cluster의 실행 중인 서비스를 중지하도록 안내합니다.

Cloudera Manager → Home → Cluster → Actions → Stop

All services successfully stopped 상태를 확인할 때까지 기다립니다.

이 과정은 매우 중요합니다. 중지하지 않은 상태로 Restore API를 호출하면 Cloudera Manager가 서비스를 중지할 수 있고, 그 과정에서 실행 중인 Job이 종료될 수 있습니다. Production이라면 반드시 Maintenance Window를 확보하고 수행하세요.

HTTP 환경 Restore

curl \
-H "Content-Type: application/json" \
--upload-file /backup/cloudera/cm-deployment.json \
-u admin:password \
"http://cm01.example.com:7180/api/v49/cm/deployment?deleteCurrentDeployment=true"

-X PUT을 명시하는 방식도 가능합니다.

curl -X PUT \
-H "Content-Type: application/json" \
-u admin:password \
--data-binary @/backup/cloudera/cm-deployment.json \
"http://cm01.example.com:7180/api/v49/cm/deployment?deleteCurrentDeployment=true"

--upload-file은 curl에서 PUT으로 파일을 전송하므로 Cloudera 문서 예제에서 사용됩니다.

HTTPS 환경 Restore

curl \
--cacert /etc/pki/ca-trust/source/anchors/company-ca.pem \
-H "Content-Type: application/json" \
--upload-file /backup/cloudera/cm-deployment.json \
-u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment?deleteCurrentDeployment=true"

CA 검증이 필요 없다면 --cacert 줄을 빼면 됩니다.

`deleteCurrentDeployment=true`의 의미

Restore에서 가장 중요한 옵션입니다. 이 파라미터는 현재 Deployment Configuration을 제거한 뒤 전달한 Deployment Description을 적용하도록 요청합니다.

Loading diagram…

기존 Deployment를 유지하면서 일부 Configuration을 Merge하는 개념이 아닙니다. 단순한 설정 일부 수정 용도로 쓰는 API가 아니므로 Production에서는 매우 신중하게 사용해야 합니다.

Restore 이후 검증

Restore API 수행 직후 바로 Cluster를 시작하기보다 Configuration과 상태를 먼저 확인하는 것이 좋습니다.

Cloudera Manager UI

Hosts · Clusters · Services · Role Instances
Configuration · Parcels · Security

API로 확인

curl -u admin:password "https://cm01.example.com:7183/api/v49/hosts"
curl -u admin:password "https://cm01.example.com:7183/api/v49/clusters"
curl -u admin:password "https://cm01.example.com:7183/api/v49/clusters/Cluster1/services"

서비스 기동

Host/Role 상태에 문제가 없다면 서비스를 시작합니다.

Cloudera Manager → Cluster → Actions → Start

이후 환경에 존재하는 서비스의 Health를 확인합니다 (ZooKeeper, HDFS, YARN, Hive, Impala, Kudu, HBase, Kafka, Ranger, Atlas, Solr, Knox 등).

상태 점검

Cloudera Manager에서는 Cluster / Host / Service / Role Health와 Configuration Staleness, Restart Required를 확인합니다. 서비스별로는 다음을 수행합니다.

hdfs dfsadmin -report
hdfs haadmin -getAllServiceState
 
yarn node -list
 
kudu cluster ksck <master-list>

Hive는 beeline 접속 후 쿼리, Impala는 impala-shell 쿼리, Kafka는 Topic 조회 또는 Producer/Consumer 테스트로 확인합니다.

권장 운영 절차

Loading diagram…

Restore 직전, 현재 상태를 한 번 더 백업

기존 환경에 Restore하기 직전에 현재 Deployment를 반드시 한 번 더 Export하세요. 롤백 지점이 됩니다.

curl -u admin:password \
"https://cm01.example.com:7183/api/v49/cm/deployment" \
-o before-restore-$(date '+%Y%m%d-%H%M%S').json

Configuration Backup ≠ Database Backup

운영에서 자주 혼동되는 지점입니다.

GET /cm/deployment 는 Cloudera Manager가 관리하는 논리적 Deployment Configuration을 보존합니다.
Cloudera Manager Database 에는 CM의 내부 상태와 Metadata가 저장되며, 별도의 DB 백업이 필요합니다.

pg_dump scm > scm.sql

실질적인 DR 관점에서는 둘 다 보관해야 합니다.

Loading diagram…

즉 /cm/deployment Export만으로 Cloudera Platform 전체 DR이 완성되지는 않습니다.

권장 백업 디렉터리 구조

/backup/cloudera/
│
├── configuration/
│   ├── 20260928/cm-deployment.json
│   ├── 20260929/cm-deployment.json
│   └── 20260930/cm-deployment.json
│
├── database/
│   ├── scm.sql
│   ├── hive.sql
│   ├── ranger.sql
│   └── hue.sql
│
├── kerberos/
│   ├── krb5.conf
│   └── keytabs/
│
└── tls/
    ├── certificates/
    └── ca/

자동 백업 Cron 예제

매일 새벽 2시에 백업한다면 다음과 같이 구성합니다.

0 2 * * * /opt/scripts/cm-config-backup.sh >> /var/log/cm-config-backup.log 2>&1

#!/bin/bash
 
source /root/.cm-credentials     # CM_USER, CM_PASSWORD
 
CM_HOST="cm01.example.com"
CM_PORT="7183"
 
API_VERSION=$(curl -ks \
    -u "${CM_USER}:${CM_PASSWORD}" \
    "https://${CM_HOST}:${CM_PORT}/api/version")
 
BACKUP_ROOT="/backup/cloudera/configuration"
DATE=$(date '+%Y%m%d')
TIME=$(date '+%H%M%S')
 
BACKUP_DIR="${BACKUP_ROOT}/${DATE}"
BACKUP_FILE="${BACKUP_DIR}/cm-deployment-${TIME}.json"
 
mkdir -p "${BACKUP_DIR}"
 
curl --fail --silent --show-error \
    -k \
    -u "${CM_USER}:${CM_PASSWORD}" \
    "https://${CM_HOST}:${CM_PORT}/api/${API_VERSION}/cm/deployment" \
    -o "${BACKUP_FILE}"
 
if ! jq empty "${BACKUP_FILE}" >/dev/null 2>&1; then
    echo "[ERROR] Invalid JSON"
    rm -f "${BACKUP_FILE}"
    exit 1
fi
 
chmod 600 "${BACKUP_FILE}"
 
REDACTED_COUNT=$(grep -o 'REDACTED' "${BACKUP_FILE}" | wc -l)
 
echo "Backup: ${BACKUP_FILE}"
echo "REDACTED count: ${REDACTED_COUNT}"

Credential 파일은 별도로 두고 권한을 제한합니다.

# /root/.cm-credentials
CM_USER=backup_admin
CM_PASSWORD=<password>

chmod 600 /root/.cm-credentials

더 높은 보안 수준이 필요하면 Vault 같은 Secret Manager를 사용하세요.

백업 주기 권장

종류	권장 주기
정기 Configuration Backup	Daily
CM 설정 변경 전	반드시
Parcel Upgrade 전	반드시
Runtime Upgrade 전	반드시
Host 추가/삭제 전후	권장
Service 추가/삭제 전	반드시
TLS 변경 전	반드시
Kerberos 변경 전	반드시
Major Configuration 변경 전	반드시

가장 안전한 운영은 정기 Daily Backup + 변경 트리거 Backup 두 가지를 병행하는 것입니다.

정리

핵심은 두 API입니다.

Backup    GET /api/vXX/cm/deployment
Restore   PUT /api/vXX/cm/deployment?deleteCurrentDeployment=true

그리고 반드시 기억할 네 가지 함정이 있습니다.

API Version — 문서 숫자를 고정하지 말고 /api/version으로 확인
Redaction — REDACTED가 남아 있으면 복원되지 않음. Export 시 비활성화하거나 복원 전에 치환
Password 포함 백업 — Redaction을 끈 JSON은 Secret으로 취급 (chmod 600 + 암호화)
deleteCurrentDeployment=true — Merge가 아니라 기존 정의 제거 후 적용. Cluster Stop 후 Maintenance Window에서만

마지막으로, /cm/deployment Export만으로 전체 DR이 완성되지 않습니다. Deployment JSON, Cloudera Manager Database, 서비스 DB(Hive/Ranger/Hue 등), Kerberos 설정과 Keytab, TLS 인증서와 CA, 외부 DB·External Service 구성까지 함께 백업해야 실제 장애나 재구축 상황에서 복구 가능성이 높아집니다.

무엇이 백업되는가

요구 권한

전체 흐름

가장 중요한 함정 — Sensitive Configuration Redaction

Redaction 비활성화

Backup

API Version 확인

HTTP 환경

HTTPS 환경

백업 파일 검증

REDACTED 항목 확인

백업 파일 보안

버전 관리

Backup Script 예제

Restore

Restore 전 확인 항목

REDACTED 값 수정

Cluster Service 중지

HTTP 환경 Restore

HTTPS 환경 Restore

deleteCurrentDeployment=true의 의미

Restore 이후 검증

Cloudera Manager UI

API로 확인

서비스 기동

상태 점검

권장 운영 절차

Restore 직전, 현재 상태를 한 번 더 백업

Configuration Backup ≠ Database Backup

권장 백업 디렉터리 구조

자동 백업 Cron 예제

백업 주기 권장

정리

`deleteCurrentDeployment=true`의 의미