Aprovisiona el concentrador de APIs mediante la CLI

Esta página se aplica a Apigee y Apigee Hybrid.

En esta sección, se describe cómo aprovisionar el concentrador de APIs con la línea de comandos.

Resumen de los pasos

Los pasos de aprovisionamiento son los siguientes:

  1. Verifica si cumples con los requisitos del concentrador de APIs.
  2. Paso 1: Habilitar las APIs. Apigee requiere que habilites varias APIs de Google Cloud.
  3. Paso 2: Definir las variables de entorno. Las variables de entorno ayudan a garantizar la coherencia cuando se ejecutan comandos.
  4. Paso 3: Crear cuenta de servicio y CMEK. Las bibliotecas cliente de Google Cloud usan esta cuenta de servicio para autenticarse con las APIs de Google Cloud. Debido a que la información sobre las APIs internas se puede considerar sensible, Apigee requiere una CMEK para encriptar y desencriptar (proteger) datos en reposo. Las CMEK deben estar en la misma región que la ubicación de la instancia.
  5. Paso 4: Crear una instancia. Una instancia es donde se almacenan tu proyecto y los servicios relacionados.
  6. Verifica el estado de la instancia (opcional). Debido a que la creación de una instancia puede tomar un tiempo, usa este comando para verificar el estado.
  7. Borra la instancia (opcional). Usa este comando si necesitas quitar una instancia.
  8. Verifica el estado de la operación (opcional). Usa este comando para verificar el estado de la operación de larga duración.

Paso 1: Habilitar las APIs

Para usar el centro de APIs, debes habilitar las siguientes API en el proyecto:

  • API Apigee Registry: El centro de APIs interactúa con API Registry para ver y administrar las APIs de tu organización.
  • API de Cloud Key Management Service (KMS): permite que los clientes administren claves de encriptación y realicen operaciones criptográficas con esas claves.
  • API de Service Usage: Habilita los servicios que los consumidores de servicios desean usar en Google Cloud Platform, enumera los servicios disponibles o habilitados o inhabilita los servicios que los consumidores ya no usan.

Puedes usar la IU de la consola de Google Cloud o la CLI para habilitar las APIs.

Consola

Para habilitar las APIs mediante la IU, realiza los siguientes pasos en la consola de Google Cloud:

  1. Habilita la API de Apigee Registry:

    Ir a Habilitar API de Apigee Registry

    Haga clic en Habilitar.

    Google Cloud habilita la API para tu proyecto de Google Cloud.

  2. Habilita la API de Cloud Key Management Service (KMS).

    Ir a Habilitar API de Cloud KMS

    Haga clic en Habilitar.

    Google Cloud habilita la API para tu proyecto de Google Cloud.

  3. Habilita la API de Service Usage:

    Ir a Habilitar API de Service Usage

    Haga clic en Habilitar.

    Google Cloud habilita la API para tu proyecto de Google Cloud.

  4. Para confirmar que habilitaste las APIs, sigue estos pasos:

    Ve a APIs y servicios habilitados

    Las API que acabas de agregar se muestran en la lista de API habilitadas:

    • API de Apigee Registry
    • API de Cloud Key Management Service (KMS)
    • API de Service Usage

gcloud

  1. ejecute el siguiente comando:

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

    En el ejemplo de código anterior, PROJECT_ID es el nombre de tu proyecto de la consola de Google Cloud.

  2. Si deseas verificar tu trabajo, usa el comando services list para mostrar todas las API habilitadas (opcional):

    gcloud services list

    En la respuesta, se muestran todos los servicios habilitados, incluidas las APIs que acabas de habilitar.

Paso 2: Definir las variables de entorno

El uso de variables de entorno garantiza la coherencia y facilita el seguimiento de la documentación en pasos posteriores.

  1. Define las siguientes variables de entorno y reemplaza las variables dinámicas por tus valores reales: 
    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

    Aquí:

    • TOKEN es el token que autentica y autoriza tus llamadas a las API de Apigee Registry. Debe pasarse en los encabezados de autenticación como un token del portador. Ten en cuenta que el token vence después de un período y, cuando lo hace, puedes volver a generarlo con el mismo comando. Para obtener más información, consulta la página de referencia del comando print-access-token.
    • KEY_RING_NAME es el nombre del llavero de claves que usarás para identificar tu llavero de claves de encriptación.
    • KEY_NAME es el nombre de la clave que usarás para identificar la clave de encriptación del concentrador de API.
    • PROJECT_ID es el ID del proyecto de Cloud que creaste como parte de los requisitos previos.

    • RUNTIME_LOCATION es la ubicación física en la que se encuentra la instancia de Apigee Registry que crearás más tarde. La clave CMEK debe estar en la misma región que la ubicación del entorno de ejecución.

    • CMEK_KEY_ID es el ID de tu clave de encriptación administrada por el cliente. Por el momento, no se admite la rotación de claves.

      El ID de clave tiene la siguiente sintaxis (similar a una ruta de archivo):

      projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
  2. (Opcional) Para verificar su trabajo, repita los valores que acaba de configurar. Ten en cuenta que cuando quieras usar una variable en tus comandos, deberás colocar un signo de dólar ($) antes del nombre de la variable. 
    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

Paso 3: Crear una cuenta de servicio y CMEK

En esta sección, se describe cómo crear una cuenta de servicio y un llavero de claves y una clave de encriptación.

  1. Crea una cuenta de servicio por producto y por proyecto de Apigee Registry para tu proyecto:

    gcloud beta services identity create --service=apigeeregistry.googleapis.com --project=$PROJECT_ID

    La cuenta de servicio que se muestra es similar a la siguiente:

    service-755582297973@gcp-sa-apigeeregistry.iam.gserviceaccount.com

  2. Coloca la cuenta de servicio creada en una variable:

    export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT

  3. Crea una CMEK con KMS mediante los pasos que se describen a continuación o usa una clave de KMS existente. La clave CMEK debe estar en la misma región que la ubicación del entorno de ejecución.

    1. Crea un llavero de claves:

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

    2. Crea una clave:

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

    3. Verifica que se haya creado la clave. La creación de la clave puede tardar unos minutos en completarse. Si este comando muestra una lista vacía, espera y vuelve a intentarlo. Cuando aparezca la clave, puedes continuar con el siguiente paso:

      gcloud kms keys list \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID

      La clave que se muestra es similar a la siguiente:

      projects/my-project/locations/us-west1/keyRings/my-key-ring-name/cryptoKeys/my-key-name

    4. Coloca la clave creada en una variable:

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

  4. Otorga permiso a la cuenta de servicio en la 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

  5. Verifica que tu cuenta de servicio tenga el permiso roles/cloudkms.cryptoKeyEncrypterDecrypter en la CMEK.

    gcloud kms keys get-iam-policy $CMEK_KEY_ID

Paso 4: Crear instancia

En esta sección, crearás una sola instancia del concentrador de API. Solo puede haber una instancia por proyecto.

Solicitud de muestra

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"'"
  }
}'

Respuesta de muestra

{
  "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
}

Errores comunes: datos de entrada incorrectos

Código de estado HTTP: 400 Bad Request
Mensaje de error: Instance is a singleton, and instance_id must be set to "default".
Causa posible: Establecer instance_id en un valor que no sea default.
Solución: Usa default como tu instance_id.
Código de estado HTTP: 400 Bad Request
Mensaje de error: global is not a supported location to create Instance.
Causa posible: Configurar global como ubicación.
Solución: Usa una de las ubicaciones de entorno de ejecución compatibles que se mencionaron antes.
Código de estado HTTP: 401 Unauthorized
Mensaje de error: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
Causa posible: Token de autenticación inválido.
Solución: El token de solicitud puede tener un formato incorrecto o vencido. Vuelve a generar el token de autenticación mediante la ejecución de token="$(gcloud auth print-access-token)" y pasa Authorization: Bearer ${token} como encabezado.
Código de estado HTTP: 403 PERMISSION_DENIED
Mensaje de error: Location RUNTIME_LOCATION is not found or access is unauthorized.
Causa posible: Establecer una ubicación no compatible.
Solución: Usa una de las ubicaciones de entorno de ejecución compatibles que se mencionaron antes.
Código de estado HTTP: 400 Bad Request
Mensaje de error: Instance.config.cmek_key_name must be provided to create Instance.
Causa posible: cmek_key_name no se proporciona en los datos.
Solución: Proporciona el nombre de CMEK. Consulta Crea cuentas de servicio y CMEK para obtener instrucciones detalladas.
Código de estado HTTP: 400 Bad Request
Mensaje de error: Invalid key format: a valid key should be in the form of projects/PROJECT/locations/us-central1/keyRings/KEYRING/cryptoKeys/CRYPTOKEY.
Causa posible: cmek_key_name tiene un formato incorrecto.
Solución: Corrige el formato de clave.
Código de estado HTTP: 400 Bad Request
Mensaje de error: CMEK key location needs to match the location of instance creation.
Causa posible: CMEK se encuentra en una ubicación diferente.
Solución: Corrige la ubicación de las CMEK.
Código de estado HTTP: 400 Bad Request
Mensaje de error: Apigee Registry service account must have roles/cloudkms.cryptoKeyEncrypterDecrypter permission on the CMEK key.
Causa posible: La cuenta de servicio de Apigee carece de permiso en las CMEK. Ten en cuenta que solo sabemos que la cuenta de servicio no tiene el permiso necesario. Es probable que la clave no exista, pero no podemos saberlo.
Solución: Verifica que la clave exista y que la cuenta de servicio de Apigee Registry tenga el permiso requerido en la clave.

Errores comunes: mal estado

Código de estado HTTP: 400 Bad Request
Mensaje de error:

Si la instancia está activa, haz lo siguiente:

Instance is ACTIVE at SOME_LOCATION. It cannot be created again.

Si la instancia no tiene un estado activo, sucede lo siguiente:

Instance has state STATE at SOME_LOCATION. It cannot be created.
Causa posible: Llamar a esta API cuando una instancia ya está presente o se está creando en alguna ubicación.
Solución: Ignora el error si esta API se activa por error. Si es una llamada legítima y, en efecto, deseas crear una instancia en esta ubicación, primero llama a DeleteInstance, en la ubicación de la instancia actual.

Obtener instancia

En esta sección, se describe cómo obtener detalles (región, estado, etc.) sobre la instancia del entorno de ejecución del concentrador de API asociado con tu proyecto.

Solicitud de muestra

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

Respuesta de muestra: creación de instancia en curso

{
  "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""
  }
}

Respuesta de muestra: creación de instancia completa

{
  "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."
}

Errores comunes

Código de estado HTTP: 404 Not Found
Mensaje de error: Resource was not found.
Causa posible: Llama a esta API en una ubicación en la que no existe una instancia.
Solución: Llama a la API de CreateInstance antes de llamar a la API de GetInstance en la ubicación en la que deseas crear la instancia. Si se creó la instancia, pero no conoces la ubicación, llama a la API de CreateInstance en cualquier ubicación, lo que falla con un mensaje que proporciona una sugerencia sobre la ubicación de la instancia.

Borrar instancia

En esta sección, se describe cómo borrar una instancia.

Solicitud de muestra

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

Respuesta de muestra

{
  "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
}

Errores comunes

Código de estado HTTP: 404 Not Found
Mensaje de error: Resource was not found.
Causa posible: Llama a esta API en una ubicación en la que no existe una instancia.
Solución: Llama a DeleteInstance solo en la ubicación en la que la instancia es ACTIVE o FAILED.
Código de estado HTTP: 400 Bad Request
Mensaje de error: Instance must be ACTIVE or FAILED to be deleted. Current state: STATE.
Causa posible: Llamar a esta API en una ubicación en la que el estado de la instancia no es ACTIVE ni FAILED.
Solución: Llama a DeleteInstance solo en la ubicación en la que la instancia es ACTIVE o FAILED.

Obtener operación

En esta sección, se describe cómo verificar el estado de la operación. Cuando las operaciones tardan mucho tiempo en completarse (LRO), la API muestra un ID de operación. Si se llama a GetOperation con el ID de la operación, se muestra el estado de la operación.

Solicitud de muestra

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

En el ejemplo anterior, OPERATION_ID es un valor que se muestra para las LRO como se explica en Crea una instancia y tiene el formato operation-1650479361714-5dd1a2c1068bf-464fac6b-18eeb734.

Respuesta de muestra: creación de instancia en curso

{
  "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
}

Respuesta de muestra: creación de instancia completa

{
  "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."
  }
}

Respuesta de muestra: eliminación de instancia completa

{
  "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"
  }
}

Próximos pasos

Consulta Pasos siguientes para obtener algunas sugerencias sobre cómo comenzar a usar el concentrador de APIs.