Proteger el tráfico de un servicio con la CLI de gcloud

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

Sigue estos pasos para desplegar una nueva API que acceda a un servicio de backend en funciones de Cloud Run mediante la CLI de Google Cloud. En esta guía de inicio rápido también se describe cómo usar una clave de API para proteger tu backend frente a accesos no autorizados.

Antes de empezar

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

    Ir al panel de control

  2. Confirma que la facturación está habilitada en tu proyecto.

    Habilitar la facturación

  3. Asegúrate de que Google Cloud CLI se ha descargado e instalado en tu máquina.

    Descargar gcloud CLI

  4. Actualiza los componentes de gcloud:

    gcloud components update

  5. Define el proyecto predeterminado. Sustituye PROJECT_ID por el ID de tu proyecto. Google Cloud 

    gcloud config set project PROJECT_ID

Habilitar los servicios necesarios

API Gateway requiere que habilites los siguientes servicios de Google:

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

Para confirmar que los servicios necesarios están habilitados, sigue estos pasos:

gcloud services list

Si no ves los servicios necesarios, 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 los servicios de gcloud.

Desplegar un backend de API

API Gateway se encuentra delante de un servicio de backend implementado y gestiona todas las solicitudes entrantes. En esta guía de inicio rápido, API Gateway dirige las llamadas entrantes a un backend de función de Cloud Run llamado helloGET que contiene la siguiente funció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 para usar la CLI de Google Cloud para descargar el código de ejemplo de Cloud Run functions y desplegar el servicio de backend de Cloud Run functions.

Crear una API

Ahora ya puedes crear tu API en API Gateway.

  1. Introduce el siguiente comando, donde:

    • API_ID especifica el nombre de tu API. Consulta los requisitos de ID de API para ver las directrices de nomenclatura de las APIs.
    • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.
    gcloud api-gateway apis create API_ID --project=PROJECT_ID

    Por ejemplo:

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

  2. Una vez completado el proceso, 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 devuelve 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'

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

Crear una configuración de API

Para poder usar API Gateway y gestionar el tráfico a tu backend de API implementado, necesitas 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 de API Gateway que elijas. La especificación de OpenAPI que se usa en esta guía de inicio rápido contiene instrucciones de enrutamiento a nuestro backend de función de Cloud Run:

# 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 mediante la CLI de gcloud, sigue estos pasos:

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

  2. Copia y pega el contenido de la especificación de OpenAPI que se muestra arriba en el archivo que acabas de crear.

  3. Edita el archivo de la siguiente manera:

    1. En el campo title, sustituye API_ID por el nombre de tu API y optional-string por una breve descripción de tu elección. El valor de este campo se usa al generar claves de API que conceden acceso a esta API.
    2. En el campo address, sustituye GCP_REGION por la Google Cloud región de la función implementada y PROJECT_ID por el nombre de tu Google Cloud proyecto.

  4. Introduce el siguiente comando, donde:

    • CONFIG_ID especifica el nombre de la configuración de la API.
    • API_ID especifica el nombre de tu API.
    • API_DEFINITION especifica el nombre del archivo de la especificación de OpenAPI.
    • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.
    • SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens de back-ends con la autenticación configurada. Para obtener más información, consulta el artículo Configurar 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 posteriores. Crear una configuración de API compleja puede tardar hasta diez minutos en completarse correctamente.

  5. Una vez creada la configuración de la API, puede ver sus detalles ejecutando este 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

    En el resultado se muestran los detalles de la configuración de la API, incluidos el nombre y el estado, como se muestra 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'

Crear una pasarela

Ahora, despliega la configuración de la API en una pasarela. Al desplegar una configuración de API en una pasarela, se define una URL externa que los clientes de la API pueden usar para acceder a tu API.

Ejecuta el siguiente comando para desplegar la configuración de 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 pasarela.
  • API_ID especifica el nombre de la API de API Gateway asociada a esta pasarela.
  • CONFIG_ID especifica el nombre de la configuración de API desplegada en la pasarela.

  • GCP_REGION es la Google Cloud región de la pasarela implementada.

  • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.

Por ejemplo:

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

Cuando se haya completado correctamente, usa el siguiente comando para ver los detalles de la pasarela:

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 devuelve 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'

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

Probar el despliegue de la API

Ahora puedes enviar solicitudes a tu API mediante la URL generada al desplegar tu gateway.

Introduce el siguiente comando curl, donde:

  • DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la pasarela implementada.
  • hello es la ruta 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!

Has creado y desplegado correctamente una API Gateway.

Proteger el acceso mediante una clave de API

Para proteger el acceso a tu backend de API, genera una clave de API asociada a tu proyecto y concédele acceso para llamar a tu API. Consulta más información en el artículo Restringir el acceso a las APIs con claves de API.

Si aún no tienes una clave de API asociada al proyecto Google Cloud que estás usando en esta guía de inicio rápido, puedes añadir una siguiendo los pasos que se indican en Crear una clave de API.

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

  1. Habilita la compatibilidad con claves de API en tu servicio. Introduce el siguiente comando, donde:
    • MANAGED_SERVICE_NAME especifica el nombre del servicio gestionado que se creó al implementar la API. Puedes verlo en la propiedad Managed Service, que aparece con el comando gcloud apigee-gateway apis describe.
    • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.
    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 ha usado para crear la configuración de tu API de forma que incluya instrucciones para aplicar una política de seguridad de validación de claves de API a todo el tráfico. Añade el tipo security y securityDefinitions, tal 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 que se transmita como parámetro de consulta llamado key al solicitar acceso a todas las rutas definidas en la especificación.
  3. Crea una configuración de API con la especificación de OpenAPI modificada mediante el siguiente comando: 
    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 pasarela 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

Probar tu clave de API

Una vez que hayas creado y desplegado la API modificada, prueba a hacer una solicitud.

Introduce el siguiente comando curl, donde:

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

Por ejemplo: 

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

Debería producirse 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, introduce el siguiente comando curl, donde:

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

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

¡Enhorabuena! Has protegido correctamente tu backend de API con API Gateway. Ahora puedes empezar a incorporar nuevos clientes de la API generando claves de API adicionales.

Limpieza

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

También puedes eliminar el Google Cloud proyecto que has usado en este tutorial.

Siguientes pasos