diff --git a/docs/cb-mayfly-api.md b/docs/cb-mayfly-api.md index b5cb900..778d09d 100644 --- a/docs/cb-mayfly-api.md +++ b/docs/cb-mayfly-api.md @@ -1,68 +1,235 @@ -# 설치 -mayfly CLI 도구를 설치하려면 다음 단계를 따르십시오: +## API 서브 명령 사용 가이드 +이 가이드에서는 `cm-mayfly`의 `api` 서브 커맨드를 이용하여 `Name` 기반으로 Cloud-Migrator 시스템의 RESTful API를 실행하는 방법에 대해 소개합니다. -1. GitHub 저장소에서 소스 코드를 다운로드하거나 클론합니다. -2. Go 언어로 빌드하거나 실행 가능한 파일을 다운로드합니다. -3. 실행 가능한 파일을 시스템 경로에 추가하여 mayfly를 전역으로 사용할 수 있도록 합니다. +`api` 서브 커맨드는 `rest` 서브 커맨드처럼 복잡한 Bear 인증 설정 및 URI를 외울 필요 없이 호출하려는 서비스의 이름(프레임워크 이름)과 액션 이름(호출할 API 이름)의 조합으로 Cloud-Migrator 시스템에서 제공하는 간단한 REST API들을 호출할 수 있도록 가볍게 제공되는 유틸성 기능입니다. -## cm-mayfly 소스코드 다운로드 +## 순서 +1. 실행 환경 구축 +1. 환경 파일 수정 및 경로 +1. 환경 파일 구조 +1. 사용 방법 + + +## 실행 환경 구축 +`cm-mayfly`의 `api` 서브 커맨드를 사용하기 위해서는 실행 파일을 다운로드하거나 소스를 빌드하는 방법이 있습니다. + +`./bin` 폴더에 실행 파일이 있으며, `./conf` 폴더에 `api.yaml` 환경 설정 파일이 존재하므로 간단하게는 git에서 소스를 내려 받은 후 `./bin` 폴더에서 실행하면 됩니다. ```bash -git clone https://github.com/cm-mayfly/cm-mayfly.git +$ git clone https://github.com/cm-mayfly/cm-mayfly.git +$ cd cm-mayfly/bin +$ ./mayfly api ``` -# Golang 다운로드 -```bash -wget https://go.dev/dl/go1.21.4.linux-amd64.tar.gz + +만약, 소스를 수정하였거나 최신 소스를 직접 빌드하고 싶은 경우에는 README 설명을 참고하여 빌드하세요. +[How to build mayfly binary file from souce code](https://github.com/MZC-CSC/cm-mayfly/tree/develop?tab=readme-ov-file#how-to-build-mayfly-binary-file-from-souce-code) + + + +## 환경 파일 수정 및 경로 +`api` 서브 커맨드는 호출할 서버의 정보를 비롯하여 서비스 명칭과 API 명칭 파악을 위해 내부적으로 `./conf/api.yaml` 환경 파일을 이용하기에 `api.yaml` 파일의 환경 정보가 사용하려는 시스템의 인프라 정보와 일치하도록 ``각 프레임워크의 실제 서버 IP및 Port 등의 정보에 맞게 수정``하시기 바랍니다. + +기본 `환경 파일의 경로의 경우`, 현재는 `bin` 폴더 또는 `src` 폴더에서 접근하도록 되어 있기에 현재 폴더 기준으로 상위 폴더가 아닌 **하위 폴더의 conf 폴더**로 접근하므로 **반드시 `../conf/api.yaml` 경로에 존재**해야 합니다. + + +만약, 다른 경로나 다른 환경 파일을 이용하고 싶은 경우 매번 --config 플래그 옵션을 사용하여 다른 경로의 설정 파일을 지정할 수 있습니다. + + +## 환경 파일 구조 +api.yaml의 경우 아래와 같은 구조로 되어있습니다. +`api.yaml`파일에 RESTful API를 제공하는 각 프레임워크의 서비스 명(services:)과 해당 서비스 하위에 존재할 서비스 액션(serviceActions:)을 지정하는 형태로 되어있습니다. + +### 서비스 정의 +`services:` 하위에 `api` 서브 커맨드에서 지원할 프레임워크들의 정보를 서술합니다. +예를 들어, 대표 프레임워크인 cb-spider의 경우 `cb-spider:`로 서술합니다. + +`baseurl`에는 해당 프레임워크에서 제공하는 REST API URI의 기본이되는 `스키마 + 호스트 + 베이스 경로`의 조합으로 기입합니다. +예를 들어, cb-spider의 경우 localhost에서 1024포트를 사용하고 /spider 하위에 api가 존재한다면 `http://localhost:1024/spider`로 설정하면 됩니다. + +만약, 해당 프레임워크에서 REST 호출을 위한 인증 절차가 필요한 경우에는 `auth` 영역에 `username`과 `password` 항목으로 인증 정보를 지정하며 현재는 basic 타입인 Bear 방식만 제공하기에 `type`에는 basic을 입력합니다. +아직은 basic 인증 외의 다른 방식은 지원하고 있지 않기 때문에 사실상 `type` 부분은 중요하지 않으며, `인증 절차가 필요 없는 경우에는 auth 항목 하위의 값을 삭제`하면됩니다. + +**[설정 예시]** +``` +services: + cb-spider: #service name + baseurl: http://localhost:1024/spider # baseurl is Scheme + Host + Base Path + auth: #If you need an authentication method, describe the type and username and password in the sub + type: basic + username: default + password: default + ``` -## cm-mayfly 소스코드 빌드 -```bash -cd cm-mayfly/src -go build -o mayfly main.go +### 서비스의 액션 정의 +`serviceActions:` 영역은 `services:` 에서 정의된 특정 서비스에서 제공하는 REST API들에 대해서 액션으로 정의하는 영역입니다. + +예를 들어, 위에서 설명했던 `cb-spider:` 서비스(프레임워크)에서 제공하는 +API들을 정의하고 싶다면 아래처럼 정의합니다. +``` +serviceActions: + cb-spider: +``` + +이 영역 하위에 해당 서비스에서 제공하는 모든 API들을 아래와 같은 형태로 하나씩 서술하면됩니다. +해당 서비스 하위에 1:1 맵핑할 API의 액션 이름을 서술하고 하위에 `method` 영역에는 호출될 REST Method 방식을 지정하고 `resourcePath` 영역에는 최종 URL을 만들기 위해 서비스 영역에서 정의한 **baseurl** 이후의 남은 endpoint까지의 전체 URI를 서술합니다. +끝으로, 필요한 경우에는 description에 간단한 설명을 기술합니다.(현재는 미사용) + +**[액션 정의 형태]** + +``` +영문 액션명: + method: REST메소드 방식(get/put/post 등) + resourcePath: baseurl 이후의 URI 경로 + description: 액션에 대한 설명 +``` + +예를 들어, cb-spider에서 제공하는 `http://localhost:1024/spider/cloudod`라는 REST API를 `ListCloudOS`라는 액션 이름으로 지정하고 싶다면, cb-spider의 경우 `services:` 영역에 `cb-spider:`로 정의되어 있으며 `http://localhost:1024/spider` 까지는 `baseurl`에 지정되어 있기 때문에 남은 URI의 경우 `/cloudos`이며 GET 방식으로 호출하기 때문에 최종적으로는 아래처럼 정의합니다. + +``` +serviceActions: + cb-spider: + ListCloudOS: + method: get + resourcePath: /cloudos ``` -## API 호출 관리 CLI사용 방법 +동일한 형식으로, 이번에는 `http://localhost:1024/spider/driver/aws` 또는 `http://localhost:1024/spider/driver/gcp`처럼 cb-spider에서 제공하는 REST API중 URI가 가변되는 Get 방식의 REST API를 `GetCloudDriver`라는 액션 이름으로 지정하고 싶다면 아래처럼 가변 부분을 {}로 정의합니다. -이 CLI는 서비스 및 액션을 정의하고 해당 API를 호출하는데 사용됩니다.아래에서는 사용방법과 각 옵션에 대해 설명합니다. +``` +serviceActions: + cb-spider: + GetCloudDriver: + method: get + resourcePath: /driver/{driver_name} +``` + +`{driver_name}`처럼 {}로 지정된 액션의 경우에는, {}안에 있는 변수명이 매개변수 이름이되며, 사용자로부터 `-p` 또는 `--pathParam` 플래그를 이용해서 `--pathParam driver_name:AWS` 형태로 값을 전달 받을 수 있습니다. + +``` +$ ./mayfly api --service spider --action GetCloudDriver --pathParam driver_name:AWS + +$ ./mayfly api -s spider -a GetCloudDriver -p driver_name:AWS + +$ ./mayfly api -s spider -a GetCloudDriver -p driver_name:GCP +``` + +예로 설명드렸던, ListCloudOS와 GetCloudDriver 액션들의 최종 정의 형태는 아래와 같습니다. +``` +serviceActions: + cb-spider: + ListCloudOS: + method: get + resourcePath: /cloudos + GetCloudDriver: + method: get + resourcePath: /driver/{driver_name} +``` + +Cloud-Migrator 시스템의 경우 대부분의 프레임워크는 `Swagger` 기반으로 진행되고 있어서 Swagger 형태의 JSON 파일을 제공하고 있으므로 `api.yaml`파일의 설정 작업을 조금은 수월하게 진행할 수 있도록 `tool` 플래그를 제공하고 있으니 유사한 환경의 다른 프레임워크의 정보를 api.yaml에 정의하고 싶다면 tool 플래그를 활용하시기 바랍니다. +``` +$ ./mayfly api tool -f 스웨거파일.json + +$ ./mayfly api tool -f ./cb-tumblebug.json +``` -## 설정 +`tool` 플래그의 경우, 내부적으로 각 API의 액션 이름에 `operationId` 필드를 이용하기 때문에 `사용하려는 Swagger JSON 파일에는 반드시 operationId 필드가 정의`되어 있어야 합니다. +**[예시]** +``` +"basePath": "/tumblebug", +"paths": { + "/availableK8sClusterNodeImage": { + "get": { + "description": "Get available kubernetes cluster node image", + "summary": "Get available kubernetes cluster node image", + "operationId": "GetAvailableK8sClusterNodeImage", +``` -먼저 CLI를 실행가 전에 설정 파일을 준비해야 합니다.기본 설정 파일 경로는 "../conf/api.yaml"이지만, 필요에 따라 --config 옵션을 사용하여 다른 경로의 설정 파일을 지정할 수 있습니다. +## 사용 방법 +-s 또는 --service 플래그를 이용해서 호출을 희망하는 프레임워크를 설정하며, -a 또는 --action 플래그를 이용해서 해당 프레임워크에서 실제 호출하려는 API를 지정합니다. -## 기본 명령어 설명 +만약, 호출하려는 액션의 URI 경로가 가변 경로인 경우 --pathParam으로 경로 설정이 가능하며, 전달할 JSON Data 가 있는 경우 --data 또는 --file 플래그를 이용할 수 있습니다. ---service (-s): 호출할 서비스의 이름을 지정합니다. ---action (-a): 호출할 액션의 이름을 지정합니다. ---list (-l): 서비스 목록 또는 액션 목록을 조회합니다. ---pathParam (-p): 경로 파라미터를 지정합니다. ---queryString (-q): 쿼리 문자열을 지정합니다. ---data (-d): 서버에 전송할 데이터를 지정합니다. ---file (-f): 서버에 전송할 데이터가 포함된 파일을 지정합니다. ---output (-o): 서버 응답을 파일에 저장합니다. +그 외 일부 편의를 위한 플래그가 제공됩니다. +``` +Call the action of the service defined in api.yaml. For example: +$ ./mayfly api --help +$ ./mayfly api --list +$ ./mayfly api --service spider --list +$ ./mayfly api --service spider --action ListCloudOS +$ ./mayfly api --service spider --action GetCloudDriver --pathParam driver_name:AWS +$ ./mayfly api --service spider --action GetRegionZone --pathParam region_name:ap-northeast-3 --queryString ConnectionName:aws-config01 + +Usage: + mayfly api [flags] + mayfly api [command] + +Available Commands: + tool Swagger JSON parsing tool to assist in writing api.yaml files + +Flags: + -a, --action string Action to perform + -c, --config string config file (default "../conf/api.yaml") + -d, --data string Data to send to the server + -f, --file string Data to send to the server from file + -h, --help help for api + -l, --list Show Service or Action list + -m, --method string HTTP Method + -o, --output string Write to file instead of stdout + -p, --pathParam string Variable path info set "key1:value1 key2:value2" for URIs + -q, --queryString string Use if you have a query string to add to URIs + -s, --service string Service to perform + -v, --verbose Show more detail information + +Use "mayfly api [command] --help" for more information about a command. +``` -## 기본 명령어 예시 -./mayfly api --help -./mayfly api --list -./mayfly api --service mc-infra-connector --list -./mayfly api --service mc-infra-connector --action ListCloudOS -./mayfly api --service mc-infra-connector --action GetCloudDriver --pathParam driver_name:AWS -./mayfly api --service mc-infra-connector --action GetRegionZone --pathParam region_name:ap-northeast-3 --queryString ConnectionName:aws-config01 +### 주요 flag 설명 +--service (-s) : 호출할 서비스의 이름을 지정합니다. +--action (-a) : 호출할 액션의 이름을 지정합니다. +--pathParam (-p) : 경로 파라미터를 지정합니다. +--queryString (-q) : 쿼리 문자열을 지정합니다. +--data (-d) : 서버에 전송할 데이터를 지정합니다. +--file (-f) : 서버에 전송할 데이터가 포함된 파일을 지정합니다. +--output (-o) : 서버 응답을 파일에 저장합니다. +--config (-c) : 사용할 환경 설정 파일을 지정합니다. (기본값 "../conf/api.yaml") +--list (-l) : 사용 가능한 서비스 목록 또는 액션 목록을 조회합니다. -## 서비스 및 액션 선택 -다음으로,호출할 서비스와 액션을 선택해야 합니다. 서비스와 액션을 선택하지 않고 CLI를 실행하면 서비스 및 액션의 목록이 표시 됩니다. +### 기본 사용 형식 +액션만 필요한 경우 서비스와 액션만 지정하면됩니다. +``` +$ ./mayfly api --service --action -특정 서비스의 특정 액션 호출: -./mayfly api --service --action +$ ./mayfly api -s -a +``` -./mayfly api --service --action --pathParam --queryString +만약, 가변 경로와 쿼리 스트링이 존재하는 경우 아래처럼 지정합니다. +전달할 경로 파라메터가 많은 경우 "key1:value1 key2:value2"처럼 각각은 공백으로 구분합니다. +``` +$ ./mayfly api --service --action --pathParam --queryString -## 서비스 및 액션 예시 +$ ./mayfly api -s -a -p -queryString ``` -./mayfly api --service mc-infra-connector --action ListCloudOS + + +### 기본 사용 예시 +``` +$ ./mayfly api --help +$ ./mayfly api --list +$ ./mayfly api --service cb-spider --list +$ ./mayfly api --service cb-spider --action ListCloudOS +$ ./mayfly api --service cb-spider --action GetCloudDriver --pathParam driver_name:AWS +$ ./mayfly api --service cb-spider --action GetRegionZone --pathParam region_name:ap-northeast-3 --queryString ConnectionName:aws-config01 +``` + + +### 실행 결과 예시 +``` +$ ./mayfly api --service cb-spider --action ListCloudOS service calling... 2024/05/02 09:39:33.922447 WARN RESTY Using Basic Auth in HTTP mode is not secure, use HTTPS {"cloudos":["AWS","AZURE","GCP","ALIBABA","TENCENT","IBM","OPENSTACK","CLOUDIT","NCP","NCPVPC","NHNCLOUD","KTCLOUD","KTCLOUDVPC","DOCKER","MOCK","CLOUDTWIN"]} -``` \ No newline at end of file +```