CLI를 사용한 API 허브 프로비저닝

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

이 섹션에서는 명령줄을 사용하여 API 허브를 프로비저닝하는 방법을 설명합니다.

단계 요약

프로비저닝 단계는 다음과 같습니다.

API 허브 기본 요건을 충족했는지 확인합니다.
1단계: API를 사용 설정합니다. Apigee를 사용하려면 Google Cloud API를 여러 개 사용 설정해야 합니다.
2단계: 환경 변수를 정의합니다. 환경 변수는 명령어를 실행할 때 일관성을 보장하는 데 도움이 됩니다.
3단계: 서비스 계정 및 CMEK를 만듭니다. 이 서비스 계정은 Google Cloud 클라이언트 라이브러리가 Google Cloud API에 인증하는 데 사용됩니다. 내부 API에 대한 정보는 민감한 정보로 간주될 수 있으므로 Apigee가 저장 데이터를 암호화 및 복호화(보호)하려면 CMEK가 필요합니다. CMEK는 인스턴스 위치와 동일한 리전에 있어야 합니다.
4단계: 인스턴스를 만듭니다. 인스턴스에 프로젝트와 관련 서비스가 저장됩니다.
인스턴스 상태를 확인합니다(선택사항). 인스턴스를 만드는 데 다소 시간이 걸릴 수 있으므로 이 명령어를 사용하여 상태를 확인합니다.
인스턴스를 삭제합니다(선택사항). 인스턴스를 삭제해야 하는 경우 이 명령어를 사용합니다.
작업 상태를 확인합니다(선택사항). 이 명령어를 사용하여 장기 실행 작업 상태를 확인합니다.

1단계: API 사용 설정

API 허브를 사용하려면 프로젝트에 다음 API를 사용 설정해야 합니다.

Apigee Registry API: API 허브는 API 레지스트리와 상호작용하여 조직의 API를 보고 관리합니다.
Cloud Key Management Service(KMS) API: 고객이 암호화 키를 관리하고 이 키로 암호화 작업을 수행할 수 있습니다.
Service Usage API: 서비스 소비자가 Google Cloud Platform에서 사용하기를 원하는 서비스를 사용 설정하거나, 사용 가능한 서비스 또는 사용 설정된 서비스를 나열하거나, 서비스 소비자가 더 이상 사용하지 않는 서비스를 중지합니다.

Google Cloud 콘솔 UI 또는 CLI를 사용하여 API를 사용 설정할 수 있습니다.

콘솔

UI를 사용하여 API를 사용 설정하려면 Google Cloud 콘솔에서 다음 단계를 수행합니다.

Apigee Registry API를 사용 설정합니다.

Apigee Registry API 사용 설정으로 이동

사용 설정을 클릭합니다.

Google Cloud가 Google Cloud 프로젝트에 대해 API를 사용 설정합니다.
Cloud Key Management Service(KMS) API를 사용 설정합니다.

Cloud KMS API 사용 설정으로 이동

사용 설정을 클릭합니다.

Google Cloud가 Google Cloud 프로젝트에 대해 API를 사용 설정합니다.
Service Usage API를 사용 설정합니다.
Service Usage API 사용 설정으로 이동

사용 설정을 클릭합니다.

Google Cloud가 Google Cloud 프로젝트에 대해 API를 사용 설정합니다.
API가 사용 설정되었는지 확인하려면 다음 안내를 따르세요.
사용 설정된 API 및 서비스로 이동

방금 추가한 API가 사용 설정된 API 목록에 표시됩니다.
- Apigee Registry API
- Cloud Key Management Service(KMS) API
- Service Usage API

gcloud

다음 명령어를 실행합니다.

gcloud services enable \
    apigeeregistry.googleapis.com \
    cloudkms.googleapis.com \
    serviceusage.googleapis.com --project=PROJECT_ID

여기서 PROJECT_ID는 Google Cloud 콘솔 프로젝트의 이름입니다.

(선택사항) 작업을 확인하려면 services list 명령어를 사용하여 사용 설정된 모든 API를 표시합니다.
```
gcloud services list
```
방금 사용 설정한 API를 포함한 사용 설정된 모든 서비스가 응답으로 표시됩니다.

2단계: 환경 변수 정의

환경 변수를 사용하면 일관성을 보장하고 이후 단계에서 문서를 쉽게 진행할 수 있습니다.

다음 환경 변수를 정의하고 동적 변수를 실제 값으로 바꿉니다.
```
export TOKEN=$(gcloud auth print-access-token)

# ----- Set key_ring_name and key_name to values that will help you identify the API hub encryption key in future. -----
export KEY_RING_NAME=YOUR_KEY_RING_NAME
export KEY_NAME=YOUR_KEY_NAME

export PROJECT_ID=YOUR_PROJECT_ID
export RUNTIME_LOCATION=YOUR_RUNTIME_LOCATION

# -----If you already have a CMEK, define this environment variable-----
export CMEK_KEY_ID=YOUR_CMEK_KEY_ID
```
각 항목의 의미는 다음과 같습니다.
- TOKEN은 Apigee Registry API 호출을 인증 및 승인하는 토큰입니다. 인증 헤더에 Bearer 토큰으로 전달해야 합니다. 토큰은 일정 시간 후 만료됩니다. 만료 후에는 동일 명령어를 사용해서 간단히 다시 생성할 수 있습니다. 자세한 내용은 print-access-token 명령어의 참조 페이지를 확인하세요.
- KEY_RING_NAME은 암호화 키링을 식별하는 데 사용할 키링의 이름입니다.
- KEY_NAME은 API 허브 암호화 키를 식별하는 데 사용할 키의 이름입니다.
- PROJECT_ID는 기본 요건의 일부로 만든 Cloud 프로젝트 ID입니다.
- RUNTIME_LOCATION은 나중에 만들 Apigee 레지스트리 인스턴스가 있는 물리적 위치입니다. CMEK 키는 런타임 위치와 동일한 리전에 있어야 합니다.
  
  참고:
  RUNTIME_LOCATION의 경우 영역 이름이 아닌 리전 이름을 사용해야 합니다. 예를 들어 us-west1은 리전 이름이고 us-west1-a는 리전 내 영역입니다. 리전 또는 영역 식별도 참조하세요.
  
  사용 가능한 런타임 위치 목록은 Apigee 위치를 참조하세요.
- CMEK_KEY_ID는 고객 관리 암호화 키의 키 ID입니다. 키 순환은 현재 지원되지 않습니다.
  
  키 ID에는 다음 구문(파일 경로와 유사)이 포함됩니다.
```
projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```
(선택사항) 방금 설정한 값을 에코하여 작업을 확인합니다. 명령어에 변수를 사용하려면 변수 이름 앞에 달러 기호($)를 추가합니다.
```
echo $TOKEN
echo $KEY_RING_NAME
echo $KEY_NAME
echo $PROJECT_ID
echo $RUNTIME_LOCATION

# -----If you already have a CMEK-----
echo $CMEK_KEY_ID
```

3단계: 서비스 계정 및 CMEK 만들기

이 섹션에서는 서비스 계정과 암호화 키링 및 키를 만드는 방법을 설명합니다.

프로젝트의 Apigee 레지스트리 제품별, 프로젝트별 서비스 계정을 만듭니다.

참고: 서비스 계정이 이미 생성된 경우에도 이 명령어를 여러 번 실행할 수 있습니다.
```
gcloud beta services identity create --service=apigeeregistry.googleapis.com --project=$PROJECT_ID
```
반환되는 서비스 계정은 다음과 유사합니다.
```
service-755582297973@gcp-sa-apigeeregistry.iam.gserviceaccount.com
```
생성된 서비스 계정을 변수에 넣습니다.
```
export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT
```

아래 단계에 따라 KMS를 사용하여 CMEK를 만들거나 기존 KMS 키를 사용합니다. CMEK 키는 런타임 위치와 동일한 리전에 있어야 합니다.

키링을 만듭니다.

gcloud kms keyrings create $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID

키를 만듭니다.

gcloud kms keys create $KEY_NAME \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --purpose "encryption" \
  --project $PROJECT_ID

키가 생성되었는지 확인합니다. 키 생성을 완료하는 데 몇 분 정도 걸릴 수 있습니다. 이 명령어가 빈 목록을 반환하면 기다렸다가 다시 시도하세요. 키가 표시되면 다음 단계로 진행할 수 있습니다.
```
gcloud kms keys list \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
반환된 키는 다음과 비슷합니다.
```
projects/my-project/locations/us-west1/keyRings/my-key-ring-name/cryptoKeys/my-key-name
```

생성된 키를 변수에 넣습니다.

export CMEK_KEY_ID=projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

CMEK의 서비스 계정에 권한을 부여합니다.

gcloud kms keys add-iam-policy-binding $KEY_NAME \
  --location $RUNTIME_LOCATION \
  --keyring $KEY_RING_NAME \
  --member serviceAccount:$SERVICE_ACCOUNT \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project $PROJECT_ID

서비스 계정에 CMEK에 대한 roles/cloudkms.cryptoKeyEncrypterDecrypter 권한이 있는지 확인합니다.
```
gcloud kms keys get-iam-policy $CMEK_KEY_ID
```

4단계: 인스턴스 만들기

이 섹션에서는 API 허브의 단일 인스턴스를 만듭니다. 프로젝트당 하나의 인스턴스만 있을 수 있습니다.

샘플 요청

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances?instance_id=default \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "config": {
      "cmek_key_name": "'"$CMEK_KEY_ID"'"
  }
}'

샘플 응답

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

일반적인 오류 - 잘못된 입력 데이터

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`Instance is a singleton, and instance_id must be set to "default".`
가능한 원인:	`instance_id`를 `default` 이외의 값으로 설정합니다.
솔루션:	`instance_id`로 `default`를 사용합니다.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`global is not a supported location to create Instance.`
가능한 원인:	`global`을 위치로 설정합니다.
솔루션:	위에 나열된 지원되는 런타임 위치 중 하나를 사용합니다.

HTTP 상태 코드:	`401 Unauthorized`
오류 메시지:	`Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.`
가능한 원인:	인증 토큰이 잘못되었습니다.
솔루션:	요청 토큰이 형식이 잘못되었거나 만료되었을 수 있습니다. `token="$(gcloud auth print-access-token)"`을 실행하여 인증 토큰을 재생성하고 `Authorization: Bearer ${token}`을 헤더로 전달합니다.

HTTP 상태 코드:	`403 PERMISSION_DENIED`
오류 메시지:	`Location RUNTIME_LOCATION is not found or access is unauthorized.`
가능한 원인:	위치가 지원되지 않는 위치로 설정되었습니다.
솔루션:	위에 나열된 지원되는 런타임 위치 중 하나를 사용합니다.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`Instance.config.cmek_key_name must be provided to create Instance.`
가능한 원인:	`cmek_key_name`이 데이터에 제공되지 않았습니다.
솔루션:	CMEK 이름을 제공합니다. 자세한 안내는 서비스 계정 및 CMEK 만들기를 참조하세요.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`Invalid key format: a valid key should be in the form of projects/PROJECT/locations/us-central1/keyRings/KEYRING/cryptoKeys/CRYPTOKEY.`
가능한 원인:	`cmek_key_name`의 형식이 잘못되었습니다.
솔루션:	키 형식을 수정합니다.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`CMEK key location needs to match the location of instance creation.`
가능한 원인:	CMEK가 다른 위치에 있습니다.
솔루션:	CMEK의 위치를 수정합니다.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`Apigee Registry service account must have roles/cloudkms.cryptoKeyEncrypterDecrypter permission on the CMEK key.`
가능한 원인:	Apigee 서비스 계정에 CMEK에 대한 권한이 없습니다. 서비스 계정에 필요한 권한이 부족한 것만 알 수 있습니다. 키가 전혀 존재하지 않을 수도 있지만, 이것은 확인되지 않습니다.
솔루션:	키가 존재하는지 확인하고 Apigee Registry 서비스 계정에 키에 대해 필요한 권한이 있는지 확인합니다.

일반적인 오류 - 잘못된 상태

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	인스턴스가 활성 상태인 경우: `Instance is ACTIVE at SOME_LOCATION. It cannot be created again.` 인스턴스가 활성 상태가 아닌 경우: `Instance has state STATE at SOME_LOCATION. It cannot be created.`
가능한 원인:	인스턴스가 이미 있거나 특정 위치에서 생성 중일 때 이 API를 호출했습니다.
솔루션:	이 API가 실수로 트리거된 경우 오류를 무시합니다. 정상적인 호출이며 실제로 이 위치에 인스턴스를 만들려는 경우에는 현재 인스턴스 위치에서 `DeleteInstance`를 먼저 호출합니다.

인스턴스 가져오기

이 섹션에서는 프로젝트와 연관된 API 허브 런타임에 대한 세부정보(리전, 상태 등)를 가져오는 방법을 설명합니다.

샘플 요청

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

샘플 응답 - 인스턴스 만들기 진행 중

{
  "name": "projects/my-project/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:32:14.944703257Z",
  "state": "CREATING",
  "stateMessage": "Creating instance...\nDetails: projects/PROJECT_ID/locations/RUNTIME_LOCATION/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
  }
}

샘플 응답 - 인스턴스 만들기 완료

{
  "name": "projects/myproject/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:56:31.087709218Z",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/my-project/locations/us-central1/keyRings/apihub-key-ring/cryptoKeys/apihub-key"
  },
  "state": "ACTIVE",
  "stateMessage": "Instance is active and ready to use."
}

일반적인 오류

HTTP 상태 코드:	`404 Not Found`
오류 메시지:	`Resource was not found.`
가능한 원인:	인스턴스가 없는 위치에서 이 API를 호출했습니다.
솔루션:	인스턴스를 만들려는 위치에서 `GetInstance` API를 호출하기 전에 `CreateInstance` API를 호출합니다. 인스턴스가 생성되었지만 위치를 모를 경우 어느 위치에서든 `CreateInstance` API를 호출하면 작업이 실패하고 인스턴스 위치에 대한 힌트를 제공하는 메시지가 표시됩니다.

인스턴스 삭제

이 섹션에서는 인스턴스를 삭제하는 방법을 설명합니다.

참고: DeleteInstance는 완료하는 데 10-15초 정도 걸리는 장기 실행 작업(LRO)입니다. DeleteInstance를 호출하면 작업 ID가 반환됩니다. LRO 상태를 확인하려면 작업 ID를 사용하여 GetOperation을 호출합니다.

샘플 요청

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

샘플 응답

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": false
}

일반적인 오류

HTTP 상태 코드:	`404 Not Found`
오류 메시지:	`Resource was not found.`
가능한 원인:	인스턴스가 없는 위치에서 이 API를 호출했습니다.
솔루션:	인스턴스가 `ACTIVE` 또는 `FAILED`인 위치에서만 `DeleteInstance`를 호출합니다.

HTTP 상태 코드:	`400 Bad Request`
오류 메시지:	`Instance must be ACTIVE or FAILED to be deleted. Current state: STATE.`
가능한 원인:	인스턴스 상태가 `ACTIVE` 또는 `FAILED`이 아닌 위치에서 이 API를 호출합니다.
솔루션:	인스턴스가 `ACTIVE` 또는 `FAILED`인 위치에서만 `DeleteInstance`를 호출합니다.

작업 가져오기

이 섹션에서는 작업 상태를 확인하는 방법을 설명합니다. 작업을 완료하는 데 시간이 오래 걸리면(LRO) API가 작업 ID를 반환합니다. 작업 ID를 사용하여 GetOperation을 호출하면 작업 상태가 반환됩니다.

샘플 요청

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/operations/OPERATION_ID \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

여기서 OPERATION_ID는 인스턴스 만들기에 설명된 대로 LRO에 대해 반환되는 값이고 operation-1650479361714-5dd1a2c1068bf-464fac6b-18eeb734 형식입니다.

샘플 응답 - 인스턴스 만들기 진행 중

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

샘플 응답 - 인스턴스 만들기 완료

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "endTime": "2022-03-11T08:56:31.069701960Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.Instance",
    "name": "projects/my-project/locations/us-central1/instances/default",
    "createTime": "2022-03-11T08:32:14.944703257Z",
    "updateTime": "2022-03-11T08:56:31.069701960Z",
    "config": {
      "location": "us-central1",
      "cmekKeyName": ""projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
    },
    "state": "ACTIVE",
    "stateMessage": "Instance is active and ready to use."
  }
}

샘플 응답 - 인스턴스 삭제 완료

{
  "name": "projects/my-project/locations/us-east1/operations/operation-1647669637561-5da8bfb743b86-4af586a4-83c04472",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-19T06:00:38.046462309Z",
    "endTime": "2022-03-19T06:01:01.382751041Z",
    "target": "projects/my-project/locations/us-east1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

다음 단계

API 허브 사용을 시작하는 방법에 대한 도움말은 다음 단계를 참조하세요.