Provision API hub from the command line

This page applies to Apigee and Apigee hybrid.

This document explains how to provision API hub from the command line. If you prefer to provision API hub using the wizard-style UI, see Provision API hub in the Cloud console.

Before you begin

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.

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

Go to project selector

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

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

Go to project selector

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

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.
  Go to IAM
2. Select the project.
3. Click Grant access.
4. In the New principals field, enter your user identifier. This is typically the email address for a Google Account.
5. In the Select a role list, select a role.
6. To grant additional roles, click Add another role and add each additional role.
7. Click Save.

Summary of steps

The provisioning steps are as follows:

Step 1: Enable APIs. You must enable a set of Google Cloud APIs for Apigee API hub to operate.
Step 2: Create the Apigee API hub service identity. The service identity allows the API hub instance to call the Google Cloud APIs it requires to perform its operations.
Step 3. Configure encryption. You can choose whether to use a Google-owned and Google-managed encryption key (GMEK) or Customer-managed encryption key (CMEK) approach to encrypt and decrypt your API data at rest. See Comparison of CMEK and Google-owned and Google-owned and Google-managed encryption keys.
Step 4: Create the API hub instance. To finish up, you must register the host project and create the API hub instance.

Provisioning steps

Ensure that you have met the prerequisites described in Before you begin.

Step 1: Enable APIs

To provision API hub, you must enable the following APIs in your Google Cloud project:

Permissions required for this task

You can give the Apigee API hub provisioner a predefined role that includes the permissions needed to complete this task, or give more fine-grained permissions to provide the least privilege necessary. See Predefined roles and API enablement permissions.

Enable the required Google Cloud APIs by executing the following services enable command:
```
gcloud services enable apihub.googleapis.com \
    cloudkms.googleapis.com --project=YOUR_PROJECT_ID
```
Where YOUR_PROJECT_ID is the Cloud project ID that you created in Before you begin.

Step 2: Create the Apigee API hub service identity

The service identity allows the API hub instance to call the Google Cloud APIs it requires to perform its operations.

Create the service identity:
```
gcloud beta services identity create --service=apihub.googleapis.com \
  --project=YOUR_PROJECT_ID
```
Where YOUR_PROJECT_ID is the Cloud project ID that you created in Before you begin.
Verify that the agent was successfully created. The response includes the name of the agent in the following format: service-PROJECT_NUMBER@gcp-sa-apihub.iam.gserviceaccount.com. For example:
```
Service identity created: service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com
```
Note that you will need to use this service identity in a later step.

Step 3: Configure encryption

In this step, you configure how the encryption of data in your API hub instance is managed. You can use a Google-owned and Google-managed encryption key (GMEK) or create your own customer-managed encryption key (CMEK). See Comparison of CMEK and Google-owned and Google-owned and Google-managed encryption keys.

CMEK steps

Follow these steps if you wish to use CMEK for data encryption:

Create a runtime database encryption key ring and key. You can use an existing CMEK key and key ring if you wish. Note that the key must be created in the same location where you plan to create the API hub instance.

Create a new key ring:

The key ring's name must be unique to your organization. If you create a second or subsequent region, the name cannot be the same as any other key ring.

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

Where:

KEY_RING_NAME: The name of the key ring to create.

KEY_RING_LOCATION: The physical location of the key ring. This location must be the same as you plan to use for the API hub instance you will create in a later step. You must use one of these supported locations:

Region description	Region name
Iowa	`us-central1`
Northern Virginia	`us-east4`
Oregon	`us-west1`
Belgium	`europe-west1`
London	`europe-west2`
Singapore	`asia-southeast1`
Mumbai	`asia-south1`
Sao Paulo	`southamerica-east1`
Sydney	`australia-southeast1`

YOUR_PROJECT_ID: The Cloud project ID that you created in Before you begin.

Create the encryption key and add it to the key ring:
```
gcloud kms keys create KEY_NAME \
  --keyring KEY_RING_NAME \
  --location KEY_LOCATION \
  --purpose "encryption" \
  --project YOUR_PROJECT_ID
```
Where:
- KEY_NAME: The name of the database key you are creating.
- KEY_RING_NAME: The name of the key ring you just created.
- KEY_LOCATION: The physical location of the key. Use the same location you used to create the key ring.

Get the key ID:

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

The key ID has the following syntax (similar to a file path). Retain this key ID, as you will need to use it in a later step:

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

Grant access for the Apigee Service Agent to use the new key:

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

Where: SERVICE_ACCOUNT is the ID of the service account you created in Step 2. The ID will look something like this: service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com.

This command binds the key to the Apigee API hub Service Agent.

On successful completion of this request, gcloud responds with something similar to the following:

Updated IAM policy for key [runtime].
bindings:
- members:
  - serviceAccount:service-1234567890@gcp-sa-apihub.iam.gserviceaccount.com
  role: roles/cloudkms.cryptoKeyEncrypterDecrypter
etag: BwWqgEuCuwk=
version: 1

If you get an error like the following:

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

Be sure that you used the project number and not the project name in the service account email address.

GMEK steps

If you wish to use GMEK for data encryption, go to the next step, Step 4: Create the API hub instance, now. No further key configuration is required.

Step 4: Create the API hub instance

A host project is the Google Cloud project in which you will provision Apigee API hub. You can provision only one API hub instance per host project.

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

Where:

YOUR_PROJECT_ID: The Cloud project ID that you created in Before you begin.

PROJECT_LOCATION: The physical location (region) where you'd like to host your Apigee API hub instance. You must use the same location you used to create the CMEK key and key ring. The supported regions are:

Region description	Region name
Iowa	`us-central1`
Northern Virginia	`us-east4`
Oregon	`us-west1`
Belgium	`europe-west1`
London	`europe-west2`
Singapore	`asia-southeast1`
Mumbai	`asia-south1`
Sao Paulo	`southamerica-east1`
Sydney	`australia-southeast1`

HOST_ID: The name of the host project.

Create the API hub instance:
With CMEK

If you used CMEK for data encryption, execute the following command:
```
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
```
Where:
- KEY_NAME (Required): The fully qualified name of the CMEK key. This name was returned when the key was created. For example: projects/YOUR_PROJECT_ID/locations/HOST_LOCATION/hostProjectRegistrations/HOST_ID.
- VERTEX_LOCATION (Optional): Specifies the multi-region location in which to store your Vertex AI-based search data, the data associated with the Semantic Search feature of API hub. You can use either us or eu for this value. If you do not want to use either of these multi-regions, you can disable Semantic Search by omitting this parameter.
- encryptionType (Required) You must use CMEK.
- YOUR_PROJECT_ID is the Cloud project ID that you created in Before you begin.
- PROJECT_LOCATION: You must use the same location you used to register the host project.
- INSTANCE_ID: The name of the API hub instance. This value should be 4-40 characters, and valid characters are /[a-z][A-Z][0-9]-_/.
With GMEK

If you are using GMEK for data encryption, execute the following command:
```
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
```
Where:
- VERTEX_LOCATION (Optional): Specifies the multi-region location in which to store your Vertex AI-based search data, the data associated with the Semantic Search feature of API hub. You can use either us or eu for this value. If you do not want to use either of these multi-regions, you can disable Semantic Search by omitting this parameter.
- encryptionType must be GMEK. If you do not provide an encryption type, GMEK is the default.
- YOUR_PROJECT_ID is the Cloud project ID that you created in Before you begin.
- PROJECT_LOCATION: You must use the same location you used to register the host project.
- INSTANCE_ID: The name of the API hub instance. This value should be 4-40 characters, and valid characters are /[a-z][A-Z][0-9]-_/.

Step 5: (Optional) Create a runtime project attachment

If you provisioned API hub in a project that has Apigee proxies, perform this optional step to automatically register the proxies in API hub.

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

Where:

YOUR_PROJECT_ID is the Cloud project ID that you created in Before you begin.
PROJECT_LOCATION: You must use the same location you used to register the host project.

What's next

Now, you are ready to begin using API hub:

Review the roles and permissions required to use API hub
Configure API hub attributes:
- Manage attributes
- Quickstart: Create and edit attributes
Register an API resource:
- Manage API resources
- Quickstart: Register an API
Add an API version:
- Versions overview
- Quickstart: Create an API version

Provision API hub from the command line

Before you begin

Check for the roles

Grant the roles

Summary of steps

Provisioning steps

Step 1: Enable APIs

Permissions required for this task

Step 2: Create the Apigee API hub service identity

Step 3: Configure encryption

CMEK steps

GMEK steps

Step 4: Create the API hub instance

With CMEK

With GMEK

Step 5: (Optional) Create a runtime project attachment

What's next