mc-data-manager API Swagger & scenarios

[JH-Lee-cloudlab]

mc-data-manager 사용 시나리오

v0.3.0

목차

• mc-data-manager Credential 설정 가이드
• mc-data-manager 사전 준비사항 및 WEB UI 사용 시나리오
• mc-data-manager API Swagger & 사용 시나리오

mc-data-manager Credential 설정 가이드

• 각 CSP 별 필요 credential 값

  • aws:
    • access key, secret key
  • ncp:
    • access key, secret key
  • gcp:
    • credential.json

  이외 설정 값은 각 CSP사의 서비스별 요구사항에 따라 파라미터로 요구

• credential은 data-manager bin 파일 기준 상대경로로 파일시스템에서 관리 ex) unix socket

• credential 관리 profile.json 구성 예시

[
    {
        "profileName": "default",
        "credentials": {
                ...
        }
    },
    {
        "profileName": "admin",
        "credentials": {
            "aws": {
                "accessKey": "",
                "secretKey": ""
            },
            "ncp": {
                "accessKey": "",
                "secretKey": ""
            },
            "gcp": {
                "type": "",
                "project_id": "",
                "private_key_id": "",
                "private_key": "",
                "client_email": "",
                "client_id": "",
                "auth_uri": "",
                "token_uri": "",
                "auth_provider_x509_cert_url": "",
                "client_x509_cert_url": "",
                "universe_domain": ""
            }
        }
    }
]

• 프로필 관리 인터페이스 FS(FileSystem), CLI(TBD), API(TBD), WEB_UI(TBD) 총 4가지
  • FS, CLI 의 경우 서버 관리자 권한이므로 CRUD 전체 기능 제공 (TBD)
  • API, WEB 의 경우 등록을 제외한 나머지 기능은 보안상 제한적으로 제공 (TBD)
• 현재는 FS 방식만 지원

mc-data-manager 사전 준비사항 및 WEB UI 사용 시나리오:

mc-data-manager Web UI : mc-data-manager web-ui

---

mc-data-manager API Swagger & 사용 시나리오

mc-data-manager API Swagger: mc-data-manager api-swagger

---

1. 데이터 백업

1. 데이터를 백업할 source point 정보와 target point 정보를 담아 API 요청을 보냅니다.(data backup)
   • 공통: provider, region, profileName
   • object storage: bucket, endpoint
   • rdb(MySQL): host, port, username, password, databaseName
   • nrdb: (GCP) databaseId, projectId
2. 로컬로 타겟의 데이터를 백업합니다.
3. 백업 결과 반환
   • result: 로그
   • error: 에러 발생한 경우 에러, 미발생시 null 반환

---

2. 데이터 복구

1. 복구 API 요청을 보냅니다.(data restore)
   • 공통: provider, region, profileName
   • object storage: bucket, endpoint
   • rdb(MySQL): host, port, username, password, databaseName
   • nrdb: (GCP) databaseId, projectId
2. 로컬에 백업된 데이터로 타겟에 데이터를 복구합니다.
3. 복구 결과 반환
   • result: 로그
   • error: 에러 발생한 경우 에러, 미발생시 null 반환

---

3. 데이터 마이그레이션

1. 마이그레이션할 source point 정보와 target point 정보를 담아 API 요청을 보냅니다.(data migration)
   • 공통: provider, region, profileName
   • object storage: bucket, endpoint
   • rdb(MySQL): host, port, username, password, databaseName
   • nrdb: (GCP) databaseId, projectId
2. source point의 데이터를 target point로 마이그레이션 합니다.
3. 마이그레이션 결과 반환
   • result: 로그
   • error: 에러 발생한 경우 에러, 미발생시 null 반환

[MZC-CSC]

@JH-Lee-cloudlab

Q1. 각 API 는 Unique한 OperationId가 필요합니다.
Q2. requestObj, responseObj가 같고 path가 다른 API들이 다수 존재하는데 합쳐질 가능성이 있나요?
migrateTask가 api별로 내용이 다르다면 나뉘는게 맞을 것 같지만 호출하는 api가 합쳐져도 괜찮지 않을까요?
ex) 1) /migration/aws/gcp , 2) /migration/aws/ncp 에서 path에 aws to gcp, aws to ncp 로 가는 것 같은데
-> /migration 으로 통일하고 request 객체인 migrateTask 에
1)은 sourceProvider=aws, targetProvider=gcp
2)는 sourceProvider=aws, targetProvider=ncp 로하면 호출하는 api가 줄어들 수 있을 것 같습니다.

[heedaeshin]

@MZC-CSC
Q2

해당 과정은 Swagger에 존재하는 /task API에서 모두 가능합니다.

이 API는 다음과 같은 파라미터를 지원합니다:

• operationId (string)
• serviceType (string)
• taskType (string)
• taskStatus (string)
• sourcePoint (object) - { profileName, provider, ...etc }
• targetPoint (object) - { profileName, provider, ...etc }
• cron (string) - 스케줄링 관련 파라미터
• tz (string) - 스케줄링 관련 파라미터

이 API는 각 작업에 대해 CRUD(등록, 조회, 수정, 삭제) 기능을 제공합니다.

기존 경로가 보존된 이유는, 추후 /sample 경로로 매핑되어 추상화 API에서
어떤 기능에 어떤 파라미터가 요구되는지를 전달하기 위함입니다.

해당 API는 제공되지만,
이번 웹 콘솔 시나리오나 API 시나리오에서는 추후 /sample route에 해당하는 내용으로 진행될 예정입니다.
따라서 이번 릴리즈 시나리오에는 이 내용이 포함되지 않았습니다.

Q1

Sample로 통합 예정인 route에도 operationId는 존재합니다.

[yunkon-kim]

OperationId와 관련하여 오해가 있었던 것 같습니다 ㅠ

• Annotation에 //@ID 부분을 작성해 두시면
• API docs (swagger.json 등) 생성 시, operationId에 반영됩니다.

아래 예시를 참고하셔서 수정/보완해 주시면 될 것 같습니다.

Beetle 예시)
Annotation

// RecommendInfra godoc
// @ID RecommendInfra     <--------- Here
// @Summary Recommend an appropriate multi-cloud infrastructure (MCI) for cloud migration
// @Description Recommend an appropriate multi-cloud infrastructure (MCI) for cloud migration
// @Tags [Recommendation] Infrastructure
// @Accept  json
// @Produce  json
// @Param UserInfra body RecommendInfraRequest true "Specify the your infrastructure to be migrated"
// @Param x-request-id header string false "Custom request ID (NOTE: It will be used as a trace ID.)"
// @Success 200 {object} RecommendInfraResponse "The result of recommended infrastructure"
// @Failure 404 {object} common.SimpleMsg
// @Failure 500 {object} common.SimpleMsg
// @Router /recommendation/mci [post]

swagger.json

"/recommendation/mci": {
            "post": {
                "description": "Recommend an appropriate multi-cloud infrastructure (MCI) for cloud migration",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "[Recommendation] Infrastructure"
                ],
                "summary": "Recommend an appropriate multi-cloud infrastructure (MCI) for cloud migration",
                "operationId": "RecommendInfra", <--------- Here
                "parameters": [
                    {
                        "description": "Specify the your infrastructure to be migrated",
                        "name": "UserInfra",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/controller.RecommendInfraRequest"
                        }
                    },
                    {
                        "type": "string",
                        "description": "Custom request ID (NOTE: It will be used as a trace ID.)",
                        "name": "x-request-id",
                        "in": "header"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The result of recommended infrastructure",
                        "schema": {
                            "$ref": "#/definitions/controller.RecommendInfraResponse"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/common.SimpleMsg"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/common.SimpleMsg"
                        }
                    }
                }
            }
        },

[heedaeshin]

@MZC-CSC @yunkon-kim
#59
해당 PR에서 완료되었습니다.