Protege el tráfico a un servicio con gcloud CLI

En esta página, se muestra cómo implementar una API en API Gateway para proteger el tráfico a un servicio de backend.

Sigue los pasos que se indican a continuación para implementar una API nueva y acceder a un servicio de backend en Cloud Functions con Google Cloud CLI. En esta guía de inicio rápido, también se describe cómo usar una clave de API para proteger tu backend contra accesos no autorizados.

Antes de comenzar

  1. En la consola de Google Cloud, ve a la página Panel y selecciona o crea un proyecto de Google Cloud.

    Ir a la página Panel

  2. Confirma que la facturación esté habilitada para tu proyecto.

    Aprende a habilitar la facturación

  3. Asegúrate de que Google Cloud CLI esté descargado y instalado en tu máquina.

    Descarga la CLI de gcloud

  4. Actualiza los componentes de gcloud:

    gcloud components update
  5. Configura el proyecto predeterminado. Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

    gcloud config set project PROJECT_ID

Habilita los servicios obligatorios

API Gateway requiere que habilites los siguientes servicios de Google:

Nombre Título
apigateway.googleapis.com API de API Gateway
servicemanagement.googleapis.com API de Service Management
servicecontrol.googleapis.com API de Service Control

Para confirmar que los servicios obligatorios están habilitados, haz lo siguiente:

gcloud services list

Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Para obtener más información sobre los servicios de gcloud, consulta Servicios de gcloud.

Implementa un backend de API

API Gateway se posiciona frente a un servicio de backend implementado y controla todas las solicitudes entrantes. En esta guía de inicio rápido, API Gateway enruta las llamadas entrantes a un backend de Cloud Function llamado helloGET que contiene la función que se muestra a continuación:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Sigue los pasos de la Guía de inicio rápido: Usa Google Cloud CLI para descargar el código de muestra de Cloud Functions y, luego, implementar el servicio de backend de Cloud Function.

Crea una API

Ahora estás listo para crear tu API en API Gateway.

  1. Ingresa el siguiente comando, en el que sucede lo siguiente:

    • API_ID especifica el nombre de tu API. Consulta los requisitos del ID de API para conocer los lineamientos sobre nombres de API.
    • PROJECT_ID especifica el nombre del proyecto de Google Cloud.
    gcloud api-gateway apis create API_ID --project=PROJECT_ID

    Por ejemplo:

    gcloud api-gateway apis create my-api --project=my-project
  2. Cuando el proceso finalice con éxito, puedes usar el siguiente comando para ver los detalles de la nueva API:

    gcloud api-gateway apis describe API_ID --project=PROJECT_ID

    Por ejemplo:

    gcloud api-gateway apis describe my-api --project=my-project

    Este comando muestra lo siguiente:

      createTime: '2020-02-29T21:52:20.297426875Z'
      displayName: my-api
      managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
      name: projects/my-project/locations/global/apis/my-api
      state: ACTIVE
      updateTime: '2020-02-29T21:52:20.647923711Z'

Observa el valor de la propiedad managedService. Este valor se usa para habilitar tu API en un paso posterior.

Crea una configuración de API

Antes de que se pueda usar API Gateway para administrar el tráfico al backend de tu API implementada, necesita una configuración de API.

Puedes crear una configuración de API con una especificación de OpenAPI que contenga anotaciones especializadas para definir el comportamiento deseado de API Gateway. La especificación de OpenAPI que se usa para esta guía de inicio rápido contiene instrucciones de enrutamiento a nuestro backend de Cloud Function:

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Para subir esta especificación de OpenAPI y crear una configuración de API con gcloud CLI, haz lo siguiente:

  1. Desde la línea de comandos, crea un archivo nuevo llamado openapi2-functions.yaml.

  2. Copia y pega el contenido de la especificación de OpenAPI que se mostró antes en el archivo recién creado.

  3. Edita el archivo de la siguiente manera:

    1. En el campo title, reemplaza API_ID por el nombre de tu API y reemplaza optional-string por una breve descripción de tu elección. El valor de este campo se usa cuando se crean claves de API que otorgan acceso a esta API.
    2. En el campo address, reemplaza GCP_REGION por la región de GCP de la función implementada y PROJECT_ID por el nombre de tu proyecto de Google Cloud.
  4. Ingresa el siguiente comando, en el que sucede lo siguiente:

    • CONFIG_ID especifica el nombre de la configuración de tu API.
    • API_ID especifica el nombre de tu API.
    • API_DEFINITION especifica el nombre de archivo de la especificación de OpenAPI.
    • PROJECT_ID especifica el nombre del proyecto de Google Cloud.
    • SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens para backends con autenticación configurada. Para obtener más información, consulta Configura una cuenta de servicio.
    gcloud api-gateway api-configs create CONFIG_ID \
      --api=API_ID --openapi-spec=API_DEFINITION \
      --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    Por ejemplo:

    gcloud api-gateway api-configs create my-config \
      --api=my-api --openapi-spec=openapi2-functions.yaml \
      --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com

    Esta operación puede tardar varios minutos en completarse, ya que la configuración de la API se propaga a los sistemas descendentes. La creación de una configuración de API compleja podría tardar hasta diez minutos en completarse de forma correcta.

  5. Después de crear la configuración de la API, puedes ver sus detalles mediante la ejecución del siguiente comando:

    gcloud api-gateway api-configs describe CONFIG_ID \
      --api=API_ID --project=PROJECT_ID

    Por ejemplo:

    gcloud api-gateway api-configs describe my-config \
      --api=my-api --project=my-project

    El resultado muestra los detalles de configuración de tu API, incluidos el nombre y el estado, tal como se indica en el siguiente ejemplo:

    createTime: '2020-02-07T18:17:01.839180746Z'
    displayName: my-config
    gatewayConfig:
    backendConfig:
      googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
    name: projects/my-project/locations/global/apis/my-api/configs/my-config
    serviceRollout:
    rolloutId: 2020-02-07r0
    state: ACTIVE
    updateTime: '2020-02-07T18:17:02.173778118Z'

Crea una puerta de enlace

Ahora implementa la configuración de la API en una puerta de enlace. Cuando se implementa una configuración de API en una puerta de enlace, se define una URL externa que los clientes de API pueden usar para acceder a tu API.

Ejecuta el comando siguiente para implementar la configuración de la API que acabas de crear en API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

Donde:

  • GATEWAY_ID especifica el nombre de la puerta de enlace.
  • API_ID especifica el nombre de la API de API Gateway asociada a esta puerta de enlace.
  • CONFIG_ID especifica el nombre de la configuración de la API implementada en la puerta de enlace.
  • GCP_REGION es la región de Google Cloud para la puerta de enlace implementada.

  • PROJECT_ID especifica el nombre del proyecto de Google Cloud.

Por ejemplo:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1 --project=my-project

Cuando finalice con éxito, usa el siguiente comando para ver los detalles de la puerta de enlace:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Por ejemplo:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 --project=my-project

Este comando muestra lo siguiente:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Observa el valor de la propiedad defaultHostname. Esta es la parte del nombre de host de la URL de la puerta de enlace que usarás para probar la implementación en el siguiente paso.

Cómo probar tu implementación de API

Ahora puedes enviar solicitudes a tu API con la URL generada al momento de implementar la puerta de enlace.

Ingresa el siguiente comando curl, donde:

  • DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
  • hello es la ruta de acceso especificada en la configuración de tu API.
curl https://DEFAULT_HOSTNAME/hello

Por ejemplo:

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

El resultado es el siguiente:

Hello World!

Creaste e implementaste una API Gateway con éxito.

Protege el acceso mediante una clave de API

Para proteger el acceso al backend de tu API, genera una clave de API asociada con tu proyecto y otórgale acceso a esa clave para llamar a tu API. Consulta Cómo restringir el acceso a la API con claves de API para obtener más información.

Si aún no tienes una clave de API asociada con el proyecto de Google Cloud que usas en esta guía de inicio rápido, puedes agregar una mediante los pasos que se indican en Crea una clave de API.

Para proteger el acceso a tu puerta de enlace con una clave de API, sigue estos pasos:

  1. Habilita la compatibilidad con la clave de API para tu servicio. Ingresa el siguiente comando, en el que sucede lo siguiente:
    • MANAGED_SERVICE_NAME especifica el nombre del servicio administrado que se creó cuando implementaste la API. Esto se puede ver en la propiedad de servicio administrado que aparece con el comando gcloud apigee-gateway apis describe.
    • PROJECT_ID especifica el nombre del proyecto de Google Cloud.
    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
    Por ejemplo:
    gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
  2. Modifica la especificación de OpenAPI que se usó para crear la configuración de tu API de modo que incluya instrucciones para aplicar una política de seguridad de validación de la clave de API en todo el tráfico. Agrega el tipo security y securityDefinitions como se muestra a continuación:
      # openapi2-functions.yaml
      swagger: '2.0'
      info:
        title: API_ID optional-string
        description: Sample API on API Gateway with a Google Cloud Functions backend
        version: 1.0.0
      schemes:
        - https
      produces:
        - application/json
      paths:
        /hello:
          get:
            summary: Greet a user
            operationId: hello
            x-google-backend:
              address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
            security:
            - api_key: []
            responses:
              '200':
                description: A successful response
                schema:
                  type: string
      securityDefinitions:
        # This section configures basic authentication with an API key.
        api_key:
          type: "apiKey"
          name: "key"
          in: "query"
    securityDefinition configura tu API para que requiera una clave de API pasada como un parámetro de consulta llamado key cuando se solicita acceso a todas las rutas de acceso definidas en la especificación.
  3. Usa el siguiente comando para crear una nueva configuración de API con la especificación de OpenAPI modificada:
    gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID --openapi-spec=NEW_API_DEFINITION \
    --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
    Por ejemplo:
    gcloud api-gateway api-configs create my-config-key \
      --api=my-api --openapi-spec=openapi2-functions.yaml \
      --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
  4. Ejecuta el siguiente comando para actualizar tu puerta de enlace existente con la nueva configuración de API:
    gcloud api-gateway gateways update GATEWAY_ID \
      --api=API_ID --api-config=NEW_CONFIG_ID \
      --location=GCP_REGION --project=PROJECT_ID
    Por ejemplo:
    gcloud api-gateway gateways update my-gateway \
      --api=my-api --api-config=my-config-key \
      --location=us-central1 --project=my-project

Cómo probar tu clave de API

Una vez que hayas creado e implementado la API modificada, intenta enviarle una solicitud.

Ingresa el siguiente comando curl, donde:

  • DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
  • hello es la ruta de acceso especificada en la configuración de tu API.
curl https://DEFAULT_HOSTNAME/hello

Por ejemplo:

curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Esto debería mostrar el siguiente error:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Ahora, ingresa el siguiente comando curl, donde:

  • DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
  • hello es la ruta de acceso especificada en la configuración de tu API.
  • API_KEY especifica la clave de API que creaste en el paso anterior.
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Ahora deberías ver Hello World! en la respuesta de tu API.

¡Felicitaciones! Protegiste correctamente el backend de tu API con una API Gateway. Ahora puedes comenzar a integrar nuevos clientes de API mediante la generación de claves de API adicionales.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta guía de inicio rápido, puedes hacer lo siguiente:

Como alternativa, también puedes borrar el proyecto de Google Cloud que se usó para este instructivo.

¿Qué sigue?