Huawei Cloud OBS 업로드 스킬
개요
로컬 파일 또는 디렉토리를 Huawei Cloud OBS 버킷에 업로드하고, OBS 버킷 목록을 용량 및 객체 수와 함께 조회하며, crontab을 통해 정기 업로드를 예약합니다. 업로드 작업은 obsutil을 사용하며, 버킷 목록 및 통계는 hcloud obs ls + CES 메트릭을 사용합니다.
도구 분리 원칙:
- obsutil — 파일/디렉토리 업로드, 예약 업로드 동기화 (업로드 핵심 도구; hcloud CLI는 PutObject를 지원하지 않음)
- hcloud CLI —
hcloud obs ls(obsutil 모드)를 통한 버킷 목록 조회,hcloud CES ShowMetricData를 통한 버킷 용량/객체 수 통계 - crontab / 작업 스케줄러 — 정기 업로드를 위한 OS 수준 예약 작업 (데몬 프로세스 불필요)
보안 아키텍처:
- AK/SK는 대화 중 절대 읽거나, 출력하거나 인쇄하지 않음
- obsutil 자격 증명은 사용자가 자신의 터미널에서 구성함 (대화 중 요청 금지)
- 삭제 작업은 엄격히 금지됨 (되돌릴 수 없음); 범위를 벗어난 작업은 대체 안내와 함께 거부됨
- 디렉토리 업로드 시 디렉토리 구조 보존 여부(
-flat)는 고객의 명시적 답변에 따라 결정되며, 절대 추측하지 않음 - 모든 업로드(작업 2) 및 모든 예약 업로드 설정(작업 3)은 명령 또는 crontab 쓰기를 실행하기 전에 사용자의 명시적 확인을 요구함
- 에이전트는 사용자가 지정한 정확한 버킷 및 경로에 대해 이 스킬에 설명된 단계만 실행하며, 사용자를 대신하여 다른 OBS/CLI 작업을 절대 수행하지 않음
⚠️ 데이터 전송 고지
- 업로드는 로컬 파일/디렉토리를 원격 클라우드 스토리지로 전송하여 영구 저장합니다. 업로드 전에 사용자에게 명확히 알려야 합니다: "
<path>업로드는 OBS 버킷<Bucket>으로 데이터를 전송하여 클라우드에 저장합니다." 사용자가 의도하지 않은 경우 실행을 중단합니다.- 정기 업로드는 데이터를 반복적으로 로컬 디렉토리에서 클라우드로 주기적으로 푸시합니다. 각 실행 시 데이터가 원격으로 전송되고 저장된다는 점을 사용자에게 명시적으로 경고합니다.
- 업로드할 경로를 실행 전에 검토합니다. 경로가 광범위하거나(예: 홈 디렉토리) 예상치 못한 콘텐츠를 포함하는 경우 업로드 전에 사용자와 범위를 확인합니다.
⛔ 금지된 작업 (보안 제약)
이 스킬은 사용자 요청과 관계없이 다음 작업을 엄격히 금지합니다. 금지된 작업은 의미적으로 설명되며, 파괴적인 명령 예제는 제공되지 않습니다.
| 금지된 작업 | 이유 |
|---|---|
| ❌ 버킷 삭제 | 되돌릴 수 없음; 전체 버킷과 모든 객체를 파괴함 |
| ❌ 객체 삭제 | 되돌릴 수 없음; 삭제된 객체는 (버전 관리가 활성화되지 않은 경우) 복구 불가 |
| ❌ 객체 일괄 삭제 | 되돌릴 수 없음; 일괄 삭제는 광범위한 영향을 미침 |
| ❌ 버킷 비우기 | 되돌릴 수 없음; 버킷의 모든 객체를 제거함 |
| ❌ 객체 다운로드 | 이 스킬은 업로드 전용; 다운로드는 별도 워크플로우 |
| ❌ 버킷 생성 | 버킷 생성에는 전체 전제 조건을 갖춘 전용 스킬이 있음 |
| ❌ 버킷 간 객체 복사 | 버킷 간 객체 복사는 이 스킬의 범위를 벗어남 |
| ❌ 버킷 수명 주기 구성 수정 | 스토리지 비용 관리는 별도의 버킷 수준 구성 작업 |
| ❌ 보관된 객체 복원 | 아카이브 복원은 검색 모드 및 TTL이 있는 별도 워크플로우 |
| ❌ 사전 서명된 URL 생성 | 임시 공유는 SDK 서명이 필요함; CLI 업로드에서 지원되지 않음 |
| ❌ 버킷 ACL 또는 버킷 정책 수정 | 권한 관리는 별도의 보안 작업 |
| ❌ 사용자에게 대화에서 직접 AK/SK 제공 요청 | 자격 증명은 대화에 절대 나타나서는 안됨 |
| ❌ hcloud 구성 파일에서 AK/SK 추출 | 자격 증명은 암호화되어 직접 사용할 수 없음 |
| ❌ OBS 작업 전 obsutil 자격 증명 확인 생략 | 자격 증명이 구성되지 않으면 작업 실패 |
❌ 고객에게 묻지 않고 디렉토리 업로드에 -flat 사용 | -flat은 디렉토리 구조를 무시함; 고객의 명시적 답변을 따라야 함 |
| ❌ 로컬 경로, 버킷 이름 또는 대상 접두사 추측 | 필수 매개변수는 사용자가 제공해야 함 |
사용자가 삭제 작업을 요청하면 반드시 거부하고 다음을 알려야 합니다: "보안 제약으로 인해 이 스킬은 삭제 작업(버킷 삭제/객체 삭제/일괄 삭제/버킷 비우기)을 허용하지 않습니다. Huawei Cloud OBS 콘솔 또는 obsutil을 수동으로 사용하십시오."
사용자가 범위를 벗어난 작업을 요청하면 수행을 시도하지 마십시오. 아래 표에서 권장되는 대안을 사용자에게 알려주십시오:
| 작업 | 권장 대안 |
|---|---|
| 객체 다운로드 | 수동으로 obsutil cp obs://<Bucket>/<Key> <LocalPath> 또는 OBS 콘솔 사용 |
| 버킷 생성 | 전용 스킬 huawei-cloud-obs-bucket-create 또는 OBS 콘솔 사용 |
| 객체 복사 | 수동으로 hcloud OBS CopyObject 또는 OBS 콘솔 사용 |
| 수명 주기 구성 | OBS 콘솔(버킷 > 수명 주기) 또는 hcloud OBS SetBucketLifecycle 사용 |
| 보관된 객체 복원 | 수동으로 obsutil restore obs://<Bucket>/<Key> 또는 OBS 콘솔 사용 |
| 사전 서명된 URL | Huawei Cloud SDK(Java/Python/Go)를 사용하여 사전 서명된 URL 생성 또는 OBS 콘솔 사용 |
| 버킷 ACL/정책 | OBS 콘솔(버킷 > 권한) 또는 hcloud OBS SetBucketAcl/SetBucketPolicy 사용 |
아키텍처
Huawei Cloud OBS 업로드 관리
├── 작업 1: ListBucketsWithStats (용량 및 객체 수와 함께 버킷 목록 조회)
│ ├── 1a. hcloud obs ls: 모든 버킷 나열
│ ├── 1b. CES 메트릭 / OBS API: 버킷 용량 및 객체 수 쿼리
│ └── 1c. 버킷 통계 테이블을 사용자에게 보고
├── 작업 2: UploadFile (로컬 파일 또는 디렉토리를 대상 버킷에 업로드)
│ ├── 2a. 로컬 경로 + 버킷 이름 + 대상 접두사를 사용자와 확인
│ ├── 2b. 디렉토리의 경우: 고객에게 디렉토리 구조 보존 여부 질문(-flat 결정)
│ ├── 2c. 데이터가 원격으로 유지됨을 경고 + 명시적 사용자 확인
│ ├── 2d. obsutil cp: 단일 파일(-flat) 또는 디렉토리(-r, 고객 답변에 따라 선택적 -flat)
│ └── 2e. 업로드 결과 확인
└── 작업 3: ScheduledUpload (로컬 디렉토리를 대상 버킷에 정기 업로드 예약)
├── 3a. 로컬 디렉토리 + 버킷 + 접두사 + 예약 주기를 사용자와 확인
├── 3b. 고객에게 디렉토리 구조 보존 여부 질문(-flat 결정)
├── 3c. 지속성에 대한 경고 + 명시적 사용자 확인
├── 3d. obsutil 업로드 스크립트 생성(고객 답변에 따라 -flat 포함/미포함)
├── 3e. crontab / 작업 스케줄러 예약 작업 설정
└── 3f. 예약 작업이 설정되었는지 확인
전제 조건
전제 조건 확인 1/3: Huawei Cloud CLI(hcloud / KooCLI) >= 3.2.0 필요
hcloud version을 실행하여 버전이 3.2.0 이상인지 확인하십시오. 설치되지 않았거나 버전이 너무 낮은 경우, 참조/cli-installation-guide.md에서 설치 안내를 확인하십시오.
hcloud version
전제 조건 확인 2/3: obsutil >= 5.5.0 필요 (업로드 기능용) 파일/디렉토리 업로드에는 Huawei Cloud obsutil CLI 도구가 필요합니다.
obsutil version을 실행하여 버전이 5.5.0 이상인지 확인하십시오. 설치되지 않은 경우, 참조/cli-installation-guide.md에서 설치 안내를 확인하십시오.
obsutil version
전제 조건 확인 3/3: obsutil 자격 증명 구성 필요
hcloud obs 모듈은 내부적으로 obsutil에 매핑되며, 별도의 AK/SK 및 엔드포인트 구성이 필요합니다. OBS 작업을 수행하기 전에 obsutil 자격 증명이 구성되었는지 확인해야 합니다:
hcloud obs ls -limit=1응답이
Please set ak, sk and endpoint in the configuration file!또는InvalidAccessKeyId인 경우 obsutil 자격 증명이 구성되지 않은 것입니다.해결 방법: 사용자에게 자신의 터미널에서 obsutil 자격 증명을 구성하도록 안내하고(대화에서 AK/SK를 직접 제공하도록 요청하지 마십시오), 아래 보안 경고를 함께 제공하십시오:
obsutil 자격 증명이 구성되지 않았습니다. 터미널에서 다음 명령을 실행하여 구성하십시오(AK/SK는 Huawei Cloud 콘솔 "내 자격 증명" 페이지에서 얻을 수 있음): hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.<Region>.myhuaweicloud.com 예시(광저우 리전): hcloud obs config -i=<YourAK> -k=<YourSK> -e=obs.cn-south-1.myhuaweicloud.com 일반적인 엔드포인트: cn-north-4 → obs.cn-north-4.myhuaweicloud.com cn-east-3 → obs.cn-east-3.myhuaweicloud.com cn-south-1 → obs.cn-south-1.myhuaweicloud.com cn-southwest-2 → obs.cn-southwest-2.myhuaweicloud.com ⚠️ 보안 경고: 명령줄에 AK/SK를 입력하면 셸 기록 및 OS 프로세스 목록에 노출됩니다. 대화형 구성(`hcloud configure`) 또는 환경 변수(HW_ACCESS_KEY / HW_SECRET_KEY)를 선호합니다. 구성 후에는 일반 텍스트 명령을 사용한 경우 셸 기록을 지우십시오. 구성이 완료되면 다시 시도하십시오.
⚠️ hcloud 매개변수 형식 요구 사항
hcloud(KooCLI) 클라우드 서비스 API 명령(대문자 모듈, 예:
hcloud CES ShowMetricData) 반드시--param=value형식(등호로 연결)을 사용해야 합니다. 공백으로 구분된 형식은 지원되지 않습니다.✅ 올바름:
hcloud CES ShowMetricData --region=cn-south-1 --namespace=SYS.OBS❌ 틀림:
hcloud CES ShowMetricData --region cn-south-1참고:
hcloud obs(소문자, obsutil 모드)는 obsutil 명령에 직접 매핑되며 obsutil 매개변수 스타일을 사용합니다(예:hcloud obs ls,hcloud obs config -i=...).--param=value규칙이 적용되지 않습니다.hcloud OBS ListBuckets명령은 없습니다. 버킷을 나열하려면hcloud obs ls를 사용하십시오.
인증
보안 규칙 (반드시 따라야 함):
- AK/SK 값을 읽거나, 에코하거나, 인쇄하는 것은 금지됨
- 사용자에게 대화에서 직접 AK/SK를 입력하도록 요청하는 것은 금지됨
hcloud configure set을 사용하여 일반 텍스트 자격 증명 값을 전달하는 것은 금지됨- 사용자가 대화에서 직접 제공하는 AK/SK를 수락하는 것은 금지됨
- 환경 변수 또는 구성된 CLI 구성 파일에서 자격 증명을 읽는 것만 허용됨
⚠️ 자격 증명 노출 경고 (자격 증명 구성이 논의될 때 사용자와 공유):
- 명령줄 인수로 AK/SK 전달(예:
obsutil config -ak=... -sk=...또는hcloud configure set --access-key-id=...)은 자격 증명을 셸 기록, OS 프로세스 목록, 감사 로그, 터미널 녹화 및 복사된 문서에 노출시킵니다.- 대화형 구성(
hcloud configure) 또는 환경 변수(HW_ACCESS_KEY/HW_SECRET_KEY)를 선호합니다.- 일반 텍스트 명령을 통해 구성한 후 셸 기록(
history -c또는~/.bash_history에서 문제가 되는 줄 제거)을 지우십시오.- obsutil의 자격 증명 구성 파일(예:
~/.obsutilconfig)은 제한된 권한(예:600)을 가져야 합니다.⚠️ 중요: 사용자 제공 자격 증명 처리
사용자가 AK/SK를 직접 제공하려는 경우(예: "내 AK는 xxx, SK는 yyy"):
- 즉시 중단 - 어떤 명령도 실행하지 마십시오
- 정중히 거부하고 다음 메시지를 반환하십시오:
계정 보안을 위해 Huawei Cloud Access Key ID 및 Access Key Secret을 대화에서 직접 제공하지 마십시오. 다음 안전한 방법 중 하나를 사용하여 자격 증명을 구성하십시오: 방법 1: 대화형 구성 (권장) hcloud configure # 프롬프트에 따라 AK/SK를 입력하면 자격 증명이 로컬 구성 파일에 안전하게 저장됩니다. 방법 2: 환경 변수 구성 export HW_ACCESS_KEY=<your-access-key-id> export HW_SECRET_KEY=<your-access-key-secret> 구성이 완료되면 요청을 다시 시도하십시오.- 자격 증명이 구성될 때까지 Huawei Cloud 작업 실행을 계속하지 마십시오
CLI 구성 확인:
hcloud configure list출력에 유효한 구성(AK/SK, IAM 등)이 포함되어 있는지 확인하십시오.
유효한 자격 증명이 없으면 여기서 중단하십시오.
IAM 권한 정책
IAM 사용자에게 필요한 권한이 있는지 확인하십시오. 전체 권한 테이블은 참조/iam-policies.md를 참조하십시오.
최소 필요 권한:
obs:bucket:list— 버킷 나열obs:bucket:get— 버킷 속성(용량, 객체 수) 가져오기obs:object:get— 객체 정보 읽기obs:object:put— 객체 업로드
권한 경계:
- 범위 제약: 이 스킬은 다음 도구 작업만 수행할 수 있으며, 확인 후 사용자가 지정한 버킷/경로에 대해서만 수행할 수 있습니다:
hcloud obs ls/obsutil ls— 사용자 지정 범위에 대한 버킷 및 객체 나열hcloud CES ShowMetricData/hcloud OBS GetBucketStorageInfo— 버킷 용량/객체 수 읽기obsutil cp— 확인된 로컬 파일/디렉토리를 확인된 버킷에 업로드crontab(Linux/macOS) 또는schtasks(Windows) — 확인된 예약 업로드 작업 쓰기/제거
- 다른 모든 CLI/도구 작업(삭제, 다운로드, 복사, 버킷 생성, 구성 수정 등)은 엄격히 범위를 벗어나며 거부되어야 합니다.
- 다음 경우 중단해야 함: 자격 증명이 없거나 유효하지 않은 경우, 사용자가 확인을 거부하는 경우, 대상 버킷이 존재하지 않는 경우, 로컬 경로가 존재하지 않는 경우.
- 금지된 작업: 모든 삭제 작업, 위에 나열된 범위를 벗어난 모든 작업, 여기 있는 도구 목록 수정, 확인된 범위를 넘어서는 명령 실행.
핵심 워크플로우
작업 1: 용량 및 객체 수와 함께 버킷 목록 조회
obsutil을 통해 버킷을 나열한 다음 CES 용량 메트릭 또는 OBS API를 사용하여 버킷 용량 및 객체 수를 쿼리합니다.
⚠️ 도구 분리:
hcloud obs ls는 목록 조회용,hcloud CES ShowMetricData는 통계용
hcloud obs ls: 모든 버킷 나열(obsutil 모드;--region매개변수 없음 — 리전은hcloud obs config -e=...로 설정)hcloud CES ShowMetricData/ OBS API: 각 버킷의 용량 및 객체 수 쿼리
단계:
1. hcloud obs ls -s 실행
2. 출력을 파싱하여 버킷 이름 목록 가져오기
3. 각 버킷에 대해 hcloud CES ShowMetricData를 사용하여
- bucket_size (bytes) 및
- object_count 쿼리
4. 사용자에게 표 형식으로 보고
CES 메트릭 쿼리 명령 예시:
hcloud CES ShowMetricData --region=cn-south-1 --namespace=SYS.OBS --metric_name=bucket_size --dimensions=0=..bucket_name:my-obs-bucket --filter=average --period=86400 --from=2025-01-01T00:00:00Z --to=2025-01-02T00:00:00Z
참고: 실제
from및to값은 현재 시간에 맞게 조정되어야 합니다.--period=86400(1일) 및 최근 24시간을 사용하면 최신 측정값을 얻을 수 있습니다.
작업 2: OBS 버킷에 파일/디렉토리 업로드
이 워크플로우는 확인된 로컬 파일 또는 디렉토리를 확인된 대상 OBS 버킷에 업로드합니다. 모든 업로드는 obsutil을 사용하여 수행됩니다.
⚠️ 업로드 단계 (반드시 따라야 함):
- 매개변수 수집: 로컬 경로, 버킷 이름, 대상 접두사(선택 사항)를 요청하십시오 — 추측하지 마십시오.
- 경로 유형 확인: 파일인지 디렉토리인지 확인하십시오.
- 디렉토리 구조 확인 (디렉토리의 경우에만): 디렉토리 업로드 시 반드시 고객에게 디렉토리 구조를 유지할지 물어보십시오(즉,
-flat사용 여부). 절대 추측하거나 기본값을 가정하지 마십시오.- 데이터 지속성 경고: "
<path>업로드는 데이터를 OBS 버킷<Bucket>으로 전송하여 클라우드에 저장합니다."라는 메시지를 표시하십시오.- 명시적 확인 받기: 실행 전에 사용자에게 "계속하시겠습니까?"라고 물으십시오.
- 업로드 실행: 적절한 obsutil cp 명령을 실행하십시오.
- 결과 확인: 업로드가 성공했는지 확인하십시오.
파일 업로드 명령 예시:
obsutil cp /home/user/document.pdf obs://my-obs-bucket/target-prefix/
디렉토리 업로드 명령 예시 (디렉토리 구조 유지):
obsutil cp /home/user/my-folder obs://my-obs-bucket/target-prefix/ -r
디렉토리 업로드 명령 예시 (평면화, 구조 무시):
obsutil cp /home/user/my-folder obs://my-obs-bucket/target-prefix/ -r -flat
참고:
/접두사는 대상 접두사를 나타냅니다.
작업 3: 정기 업로드 예약 (crontab)
이 워크플로우는 로컬 디렉토리에서 지정된 OBS 버킷으로 정기적으로 동기화하는 crontab 작업을 설정합니다.
⚠️ 예약 업로드 단계 (반드시 따라야 함):
- 매개변수 수집: 로컬 디렉토리 경로, 버킷 이름, 대상 접두사, 예약 주기(예: 매일 오전 2시, 매시간 등)를 요청하십시오 — 추측하지 마십시오.
- 디렉토리 구조 확인: 디렉토리 업로드 시 반드시 고객에게 디렉토리 구조를 유지할지 물어보십시오(즉,
-flat사용 여부). 절대 추측하지 마십시오.- 데이터 지속성 경고: 예약된 각 실행 시 데이터가 원격으로 전송되고 저장된다는 점을 사용자에게 명시적으로 경고하십시오.
- 명시적 확인 받기: 실행 전에 사용자에게 "계속하시겠습니까?"라고 물으십시오.
- 업로드 스크립트 생성: 동기화를 수행하는 셸 스크립트를 만드십시오.
- crontab 항목 추가: 적절한 crontab 항목을 추가하십시오.
- 확인: crontab 항목이 올바르게 추가되었는지 확인하십시오.
업로드 스크립트 예시 (예: /home/user/obs-sync.sh):
#!/bin/bash
/usr/local/bin/obsutil cp /home/user/my-folder obs://my-obs-bucket/target-prefix/ -r
crontab 항목 예시 (매일 오전 2시):
0 2 * * * /home/user/obs-sync.sh >> /home/user/obs-sync.log 2>&1
참고: Linux/macOS의 경우
crontab -e를 사용하여 crontab을 편집하고, Windows의 경우schtasks를 사용하십시오.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 업로드 실패 | obsutil 자격 증명이 구성되지 않음 | 전제 조건에 따라 obsutil 자격 증명 구성 |
| 업로드 실패 | 로컬 경로가 존재하지 않음 | 경로를 확인하고 다시 시도 |
| 업로드 실패 | 버킷이 존재하지 않음 | 버킷 이름 확인 |
| 권한 거부됨 | IAM 권한 부족 | IAM 정책 확인 (obs:bucket:list, obs:object:put) |
| CES 메트릭 쿼리 실패 | 잘못된 리전 또는 잘못된 --param=value 형식 | 명령 형식 확인 |
| crontab이 실행되지 않음 | 잘못된 경로 또는 권한 | 절대 경로를 사용하고 스크립트에 실행 권한이 있는지 확인 |