명령줄에서 API 허브 프로비저닝

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

이 문서에서는 명령줄에서 API 허브를 프로비저닝하는 방법을 설명합니다. 마법사 스타일 UI를 사용하여 API 허브를 프로비저닝하려면 Cloud 콘솔에서 API 허브 프로비저닝을 참조하세요.

시작하기 전에

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Make sure that you have the following role or roles on the project:

   • roles/serviceusage.serviceUsageAdmin
   • roles/cloudkms.admin
   • roles/apihub.provisioningAdmin
   • roles/resourcemanager.projectIamAdmin

   Check for the roles

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM
   2. Select the project.

   3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

   4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

   Grant the roles

   1. In the Google Cloud console, go to the IAM page.

      IAM으로 이동
   2. 프로젝트를 선택합니다.
   3. 액세스 권한 부여를 클릭합니다.

   4. 새 주 구성원 필드에 사용자 식별자를 입력합니다. 일반적으로 Google 계정의 이메일 주소입니다.

   5. 역할 선택 목록에서 역할을 선택합니다.
   6. 역할을 추가로 부여하려면 다른 역할 추가를 클릭하고 각 역할을 추가합니다.
   7. 저장을 클릭합니다.

   단계 요약

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

   1. 1단계: API 사용 설정. Apigee API 허브가 작동하려면 Google Cloud API 세트를 사용 설정해야 합니다.
   2. 2단계: Apigee API 허브 서비스 ID 만들기 서비스 ID를 사용하면 API 허브 인스턴스가 작업을 실행하는 데 필요한 Google Cloud API를 호출할 수 있습니다.
   3. 3단계: 암호화 구성. Google-owned and Google-managed encryption key (GMEK) 또는 고객 관리 암호화 키(CMEK) 접근 방식을 사용하여 API 저장 데이터를 암호화하고 복호화할지 여부를 선택할 수 있습니다. CMEK와 Google 소유 키 및 Google-owned and Google-managed encryption keys비교를 참조하세요.
   4. 4단계: API 허브 인스턴스 만들기 마지막으로 호스트 프로젝트를 등록하고 API 허브 인스턴스를 만들어야 합니다.

   프로비저닝 단계

   시작하기 전에 섹션에 설명된 기본 요건을 충족하는지 확인합니다.

   1단계: API 사용 설정

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

   이 태스크에 필요한 권한

   이 작업을 완료하는 데 필요한 권한이 포함된 사전 정의된 역할을 Apigee API 허브 프로비저닝 도구에 제공하거나 필요한 최소 권한을 제공하는 보다 세분화된 권한을 부여할 수 있습니다. 사전 정의된 역할과 API 사용 설정 권한을 참조하세요.

   1. 다음 services enable 명령어를 실행하여 필수 Google Cloud API를 사용 설정합니다.

      gcloud services enable apihub.googleapis.com \
          cloudkms.googleapis.com --project=YOUR_PROJECT_ID

      여기서 YOUR_PROJECT_ID는 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.

   2단계: Apigee API 허브 서비스 ID 만들기

   서비스 ID를 사용하면 API 허브 인스턴스가 작업을 실행하는 데 필요한 Google Cloud API를 호출할 수 있습니다.

   1. 서비스 ID를 만듭니다.

      gcloud beta services identity create --service=apihub.googleapis.com \
        --project=YOUR_PROJECT_ID

      여기서 YOUR_PROJECT_ID는 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.

   2. 에이전트가 성공적으로 생성되었는지 확인합니다. 응답에는 에이전트 이름이 [e-mail] 형식으로 포함됩니다. 예를 들면 다음과 같습니다.

      Service identity created: [e-mail]

      이 서비스 ID를 이후 단계에서 사용해야 합니다.

   3단계: 암호화 구성

   이 단계에서는 API 허브 인스턴스의 데이터 암호화가 관리되는 방식을 구성합니다. Google-owned and Google-managed encryption key (GMEK)를 사용하거나 자체적인 고객 관리 암호화 키(CMEK)를 만들 수 있습니다. CMEK와 Google 소유 키 및 Google-owned and Google-managed encryption keys비교를 참조하세요.

   CMEK 단계

   데이터 암호화에 CMEK를 사용하려면 다음 단계를 따르세요.

   1. 런타임 데이터베이스 암호화 키링과 키를 만듭니다. 원하는 경우 기존 CMEK 키와 키링을 사용할 수 있습니다. API 허브 인스턴스를 만들려는 위치와 동일한 위치에 키를 만들어야 합니다.

      1. 새 키링을 만듭니다.

         키링의 이름은 조직에서 고유해야 합니다. 두 번째 또는 후속 리전을 만드는 경우 이름이 다른 키링의 이름과 동일하면 안 됩니다.

         gcloud kms keyrings create KEY_RING_NAME \
           --location KEY_RING_LOCATION --project YOUR_PROJECT_ID

         각 항목의 의미는 다음과 같습니다.

         • KEY_RING_NAME: 생성할 키링의 이름입니다.
         • KEY_RING_LOCATION: 키링의 물리적 위치입니다. 이 위치는 이후 단계에서 만들 API 허브 인스턴스에 사용할 위치와 동일해야 합니다. 지원되는 다음 위치 중 하나를 사용해야 합니다.

           리전 설명	리전 이름
           아이오와	us-central1
           북버지니아	us-east4
           오리건	us-west1
           벨기에	europe-west1
           런던	europe-west2
           싱가포르	asia-southeast1
           뭄바이	asia-south1
           상파울로	southamerica-east1
           시드니	australia-southeast1

         • YOUR_PROJECT_ID: 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.

      2. 암호화 키를 만들고 키링에 추가합니다.

         gcloud kms keys create KEY_NAME \
           --keyring KEY_RING_NAME \
           --location KEY_LOCATION \
           --purpose "encryption" \
           --project YOUR_PROJECT_ID

         각 항목의 의미는 다음과 같습니다.

         • KEY_NAME: 만들려는 데이터베이스 키의 이름입니다.
         • KEY_RING_NAME: 방금 만든 키링의 이름입니다.
         • KEY_LOCATION: 키의 물리적 위치입니다. 키링을 만들 때 사용한 위치를 사용합니다.

      3. 키 ID를 가져옵니다.

         gcloud kms keys list \
           --location=KEY_LOCATION \
           --keyring=KEY_RING_NAME \
           --project=YOUR_PROJECT_ID

         키 ID에는 다음 구문(파일 경로와 유사)이 포함됩니다. 이 키 ID는 나중에 사용해야 하므로 보관합니다.

         projects/YOUR_PROJECT_ID/locations/KEY_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

      4. Apigee 서비스 에이전트가 새 키를 사용할 수 있는 액세스 권한을 부여합니다.

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

         여기서 SERVICE_ACCOUNT는 2단계에서 만든 서비스 계정의 ID입니다. 이 ID는 다음과 같은 형식으로 표시됩니다. [e-mail]

         이 명령어는 키를 Apigee API 허브 서비스 에이전트에 결합합니다.

         이 요청이 완료되면 gcloud는 다음과 비슷한 응답을 보냅니다.

         Updated IAM policy for key [runtime].
         bindings:
         - members:
           - serviceAccount:[e-mail]
           role: roles/cloudkms.cryptoKeyEncrypterDecrypter
         etag: BwWqgEuCuwk=
         version: 1

         다음과 같은 오류가 표시되는 경우:

         INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.

         서비스 계정 이메일 주소에 있는 프로젝트 이름이 아닌 프로젝트 번호를 사용했는지 확인합니다.

   GMEK 단계

   데이터 암호화에 GMEK를 사용하려면 다음 단계인 4단계: API 허브 인스턴스 만들기로 지금 이동하세요. 추가 키 구성이 필요하지 않습니다.

   4단계: API 허브 인스턴스 만들기

   호스트 프로젝트는 Apigee API 허브를 프로비저닝할 Google Cloud 프로젝트입니다. 호스트 프로젝트당 API 허브 인스턴스를 하나만 프로비저닝할 수 있습니다.

   1. 호스트 프로젝트를 등록합니다.

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -d '{
        "gcpProject": "projects/YOUR_PROJECT_ID"
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/hostProjectRegistrations?host_project_registration_id=HOST_ID

      각 항목의 의미는 다음과 같습니다.

      • YOUR_PROJECT_ID: 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.
      • PROJECT_LOCATION: Apigee API 허브 인스턴스를 호스팅할 물리적 위치(리전)입니다. CMEK 키와 키링을 만들 때 사용한 위치를 사용해야 합니다. 지원되는 리전은 다음과 같습니다.

        리전 설명	리전 이름
        아이오와	us-central1
        북버지니아	us-east4
        오리건	us-west1
        벨기에	europe-west1
        런던	europe-west2
        싱가포르	asia-southeast1
        뭄바이	asia-south1
        상파울로	southamerica-east1
        시드니	australia-southeast1

      • HOST_ID: 호스트 프로젝트의 이름입니다.
   2. API 허브 인스턴스를 만듭니다.

      CMEK를 사용하는 경우

      데이터 암호화에 CMEK를 사용한 경우 다음 명령어를 실행합니다.

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "cmekKeyName":"KEY_NAME",
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"CMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      각 항목의 의미는 다음과 같습니다.

      • KEY_NAME(필수): CMEK 키의 정규화된 이름입니다. 이 이름은 키가 생성될 때 반환되었습니다. 예를 들면 projects/YOUR_PROJECT_ID/locations/HOST_LOCATION/hostProjectRegistrations/HOST_ID입니다.
      • VERTEX_LOCATION(선택사항): API 허브의 시맨틱 검색 기능과 연결된 데이터인 Vertex AI 기반 검색 데이터를 저장할 멀티 리전 위치를 지정합니다. 이 값으로 us 또는 eu를 사용할 수 있습니다. 이러한 멀티 리전 중 하나를 사용하지 않으려면 이 파라미터를 생략하여 시맨틱 검색을 사용 중지할 수 있습니다.
      • encryptionType(필수): CMEK를 사용해야 합니다.
      • YOUR_PROJECT_ID: 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.
      • PROJECT_LOCATION: 호스트 프로젝트를 등록할 때 사용한 위치와 동일한 위치를 사용해야 합니다.
      • INSTANCE_ID: API 허브 인스턴스의 이름입니다. 이 값은 4~40자(영문 기준)여야 하며 유효한 문자는 /[a-z][A-Z][0-9]-_/입니다.

      GMEK를 사용하는 경우

      데이터 암호화에 GMEK를 사용하는 경우 다음 명령어를 실행합니다.

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"GMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      각 항목의 의미는 다음과 같습니다.

      • VERTEX_LOCATION(선택사항): API 허브의 시맨틱 검색 기능과 연결된 데이터인 Vertex AI 기반 검색 데이터를 저장할 멀티 리전 위치를 지정합니다. 이 값으로 us 또는 eu를 사용할 수 있습니다. 이러한 멀티 리전 중 하나를 사용하지 않으려면 이 파라미터를 생략하여 시맨틱 검색을 사용 중지할 수 있습니다.
      • encryptionType는 GMEK여야 합니다. 암호화 유형을 제공하지 않으면 기본값은 GMEK입니다.
      • YOUR_PROJECT_ID: 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.
      • PROJECT_LOCATION: 호스트 프로젝트를 등록할 때 사용한 위치와 동일한 위치를 사용해야 합니다.
      • INSTANCE_ID: API 허브 인스턴스의 이름입니다. 이 값은 4~40자(영문 기준)여야 하며 유효한 문자는 /[a-z][A-Z][0-9]-_/입니다.

   5단계: (선택사항) 런타임 프로젝트 연결 만들기

   Apigee 프록시가 있는 프로젝트에 API 허브를 프로비저닝한 경우 이 선택적 단계를 수행하여 API 허브에 프록시를 자동으로 등록합니다.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" \
     https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/runtimeProjectAttachments?runtimeProjectAttachmentId=YOUR_PROJECT_ID

   각 항목의 의미는 다음과 같습니다.

   • YOUR_PROJECT_ID: 시작하기 전에에서 만든 Cloud 프로젝트 ID입니다.
   • PROJECT_LOCATION: 호스트 프로젝트를 등록할 때 사용한 위치와 동일한 위치를 사용해야 합니다.

   다음 단계

   이제 API 허브를 사용할 준비가 되었습니다.

   • API 허브를 사용하는 데 필요한 역할 및 권한 검토
   • API 허브 속성 구성
     • 속성 관리
     • 빠른 시작: 속성 만들기 및 수정
   • API 리소스 등록
     • API 리소스 관리
     • 빠른 시작: API 등록
   • API 버전 추가
     • 버전 개요
     • 빠른 시작: API 버전 만들기