Objetivos

Al finalizar el tutorial el estudiante estará en capacidad de:

• Configurar y desplegar un API gateway en GCP.
• Configurar el API Gateway para que sirva de punto de acceso para el consumo de una función desplegada en Google Cloud Functions.

Requisitos para desarrollar el tutorial

En particular se utilizarán los siguientes recursos:

1. Contar con una cuenta activa en Google Cloud y con recursos para la creación de servicios. Además, contar con un proyecto creado en el que deberá crear la función. En caso de no tenerlo, a continuación se encuentra el manual para crearlos y/o administrarlos: Crea y administra proyectos | Documentación de Resource Manager | Google Cloud
2. gcloud SDK para acceder a los servicios del proveedor Google Cloud Platform a partir de la consola. En caso de no tenerla instalada puede consultar el siguiente manual de instalación: Instalación de SDK de Cloud | Google Cloud
3. Haber completado el tutorial de Cloud functions. Si no lo ha hecho le sugerimos primero terminarlo dado que usaremos esas funcionen en este tutorial.

El código para este tutorial lo encuentra en el siguiente repositorio de GitHub: GCP API Gateway.

Validación del Identificador del Proyecto

Debe verificar que el proyecto objetivo se encuentra seleccionado tanto el de la consola de google cloud como en la terminal local de su computador.

En google cloud asegúrese de tener seleccionado el proyecto al entrar a console.cloud.google.com

En la terminal ejecute el siguiente comando para verificar que el ID de proyecto corresponde con el se la consola de google cloud:

user@192 ~ % gcloud config get-value project

En el caso que el proyecto sea diferente, ejecute el siguiente comando cambiando PROJECT_ID por el id del proyecto en la consola de GCP.

user@192 ~ % gcloud config set project PROJECT_ID

Habilitación de APIs

Para hacer uso del API Gateway es necesario habilitar tres diferentes APIs los cuales puede tener o no habilitados en su cuenta en el momento.

• API Gateway API
• Service Control API
• Service Management API

Para realizar la activación, debemos dirigirnos a la biblioteca de APIs que nos ofrece Google. Para ellos, nos dirigimos al menú de navegación y buscaremos la opción "API y servicios". Luego seleccionaremos la opción "Biblioteca"

Está opción nos dirigirá a la página de búsqueda de la biblioteca de API de google. En ella podremos encontrar los distintos servicios ofrecidos en GCP y con los que nos podemos integrar. Para nuestro caso, necesitaremos habilitar los APIs mencionados anteriormente. Para ello nos dirigimos a la barra de búsqueda y escribimos los nombres de los tres APIs y los habilitamos.

Habilite aquellos que no tiene instalados dando click en el botón LAUNCH o habilitar.

Creación del API

Antes de crear el API es necesario definir el ID que tendrá. Este API ID debe ser único y definido por usted. Para esto tenga en cuenta los siguientes parámetros.

• Debe tener una longitud máxima de 63 caracteres.
• Debe contener solo letras en minúscula, números o guiones.
• No debe comenzar con un guión.
• No debe contener un guión bajo.

Para este tutorial usaremos el API ID misw4301-api el cual es usado en la ejecución del siguiente comando.

user@192 ~ % gcloud api-gateway apis create API_ID

Haciendo uso del API_ID definido ejecute el siguiente comando.

user@192 ~ % gcloud api-gateway apis create misw4301-api

Este proceso puede tomar unos minutos. Al finalizar verifique que el gateway esté activo. Para ello ejecute:

user@192 ~ % gcloud api-gateway apis describe misw4301-api

El resultado en su terminal debe contener un formato similar al siguiente:

createTime: '2022-02-18T05:50:34.651599035Z'
displayName: misw4301-api
managedService: misw4301-api-0z9bh1jv0ukn2.apigateway.uandes-native.cloud.goog
name: projects/uandes-native/locations/global/apis/misw4301-api
state: ACTIVE
updateTime: '2022-02-18T05:52:13.153528859Z'

Acceda a su consola en GCP y por medio del menú acceda al servicio API Gateway. Allí encontrará que el API ha sido creado.

Archivo de descripción del API

API Gateway requiere que la configuración de los APIs que expone, estén descritos por medio de archivos siguiendo la especificación OpenAPI. Hemos dejado un ejemplo de un archivo de configuración en el repositorio del tutorial.

Archivo especificacion-api.yaml

De este archivo se puede resaltar lo siguiente:

• Línea 4: El nombre y descripción del API.
• Línea 11: Lista de las rutas de nuestro API.
• Línea 12: Ruta que expondremos en nuestro API.
• Línea 17: Ruta interna de donde consume nuestro API.

En este archivo se describen los tipos de respuesta que tiene nuestro API, así como los mecanismos de seguridad que vamos a usar.

Modifique la línea 17 con la ruta de la función function-heroes-listar creada en el tutorial de cloud functions.

Creación de configuración del API

Antes de crear la configuración de API es necesario definir el ID que tendrá. Este CONFIG ID debe ser único y definido por usted. Para esto tenga en cuenta los siguientes parámetros.

• Debe tener una longitud máxima de 63 caracteres.
• Debe contener solo letras en minúscula, números o guiones.
• No debe comenzar con un guión.
• No debe contener un guión bajo.

Para este tutorial usaremos el CONFIG ID misw4301-api-config. Este ID debe usarse en la ejecución del siguiente comando.

user@192 ~ % gcloud api-gateway api-configs create CONFIG_ID --api=API_ID --openapi-spec=API_DEFINITION

• CONFIG_ID: Id de la configuración, para nuestro ejemplo será misw4301-api-config.
• API_ID: Id del API que creamos anteriormente, para nuestro ejemplo será misw4301-api.
• API_DEFINITION: Ruta al archivo de la definición del API, para nuestro ejemplo será especificacion-api.yaml. Suponiendo que el comando se ejecutará en la carpeta donde está el archivo.

Usando los valores correspondientes ejecute el siguiente comando.

user@192 ~ % gcloud api-gateway api-configs create misw4301-api-config --api=misw4301-api --openapi-spec=./especificacion-api.yaml

Este proceso puede demorar varios minutos.

Posteriormente verifique los detalles de la configuración por medio del siguiente comando.

user@192 ~ % gcloud api-gateway api-configs describe misw4301-api-config --api=misw4301-api

Acceda nuevamente a la consola de GCP y en el listado de APIs del servicio API gateway seleccione el API misw4301-api. Seleccione la pestaña CONFIGURACIONES donde encontrará que la configuración ha sido creada.

Con el API y su configuración creados el siguiente paso es la creación del API Gateway, el comando que cumple ese propósito es el siguiente.

user@192 ~ % gcloud api-gateway gateways create GATEWAY_ID --api=API_ID --api-config=CONFIG_ID --location=GCP_REGION

• GATEWAY_ID: Id del gateway, para nuestro ejemplo será misw4301-gateway.
• API_ID: ID del API que creamos anteriormente, para nuestro ejemplo será misw4301-api.
• CONFIG_ID: ID de la configuración del API que creamos anteriormente, para nuestro ejemplo será misw4301-api-config.
• GCP_REGION: Región donde se desplegará el gateway. En nuestro caso será us-central1. En caso de usar otra reunión modificar el comando.

Haciendo uso de los valores definidos en el tutorial, ejecute el siguiente comando.

user@192 ~ % gcloud api-gateway gateways create misw4301-gateway --api=misw4301-api --api-config=misw4301-api-config --location=us-central1

Esto puede tomar algunos minutos.

Cuando finalice ejecute el siguiente comando para ver el detalle del API Gateway.

user@192 ~ % gcloud api-gateway gateways describe misw4301-gateway --location=us-central1

El cual le mostrará un resultado similar al siguiente:

apiConfig: projects/938717691071/locations/global/apis/misw4301-api/configs/misw4301-api-config
createTime: '2022-02-18T06:01:38.720708359Z'
defaultHostname: misw4301-gateway-bz8o9y2n.uc.gateway.dev
displayName: misw4301-gateway
name: projects/uandes-native/locations/us-central1/gateways/misw4301-gateway
state: ACTIVE
updateTime: '2022-02-18T06:04:10.895718573Z'

Acceda a su consola de GCP y en la pestaña PUERTAS DE ENLACE encontrará el gateway ha sido creado con su respectiva URL.

Haga uso de Postman para probar que la URL del gateway responde correctamente.

No olvide que debe usar la ruta /heroes/listar, la cual fue configurada en el archivo especificacion-api.yaml.

Suponga que posterior al aprovisionamiento deseamos que nuestro API gateway ofrezca otro endpoint apuntando a otra función que hemos desplegado. Cómo pudo observar, cuando creamos nuestro API Gateway le definimos una configuración, para poder agregar un nuevo endpoint es necesario definir una nueva configuración y actualizar el API Gateway para que haga uso de la nueva configuración.

En el repositorio encontrará un segundo archivo de configuración de API con el nombre especificacion-api-update.yaml. Este archivo contiene ahora dos rutas, la configurada anteriormente y una nueva que apunta a la función function-heroes-detalle.

Modifique la línea 17 como la configuró en el paso anterior y la línea 28 con la ruta de la función function-heroes-detalle creada en el tutorial de cloud functions.

A continuación, cree la nueva configuración de API por medio del siguiente comando. Tenga presente que se requiere que la nueva configuración tenga un CONFIG_ID distinto al que usamos previamente. En este tutorial usaremos misw4301-api-up-config.

user@192 ~ % gcloud api-gateway api-configs create misw4301-api-up-config --api=misw4301-api --openapi-spec=./especificacion-api-update.yaml

Esto puede tardar varios minutos.

Acceda nuevamente a la consola de GCP y en el listado de APIs del servicio API gateway seleccione el API misw4301-api. Seleccione la pestaña CONFIGURACIONES donde encontrará que se encuentran ambas configuraciones.

Por último, debemos actualizar el API Gateway para que haga uso de nuestra nueva configuración. El comando que se usa para este propósito es el siguiente.

user@192 ~ % gcloud api-gateway gateways update GATEWAY_ID --location=GCP_REGION --api-config=CONFIG_ID : --api=API_ID

Utilizando los IDs previamente definidos, ejecute el siguiente comando.

user@192 ~ % gcloud api-gateway gateways update misw4301-gateway --location=us-central1 --api-config=misw4301-api-up-config --api=misw4301-api

Haga uso de su cliente de postman para verificar que la función function-heroes-detalle ahora está respondiendo por medio de la ruta <ruta-gateway>/heroes/detalle.

Para evitar costos asociados a los componentes creados en este tutorial, elimine el api gateway. Para ello ejecute los siguientes comandos en el orden en que se presentan:

user@192 ~ % gcloud api-gateway gateways delete misw4301-gateway --location=us-central1

user@192 ~ % gcloud api-gateway api-configs delete misw4301-api-up-config --api=misw4301-api

user@192 ~ % gcloud api-gateway api-configs delete misw4301-api-config --api=misw4301-api

user@192 ~ % gcloud api-gateway apis delete misw4301-api

¡Éxitos en el desarrollo del tutorial y nos vemos en una próxima oportunidad!

[1] Cloud API Gateway | Google Cloud. (s. f.). Google Cloud. https://cloud.google.com/api-gateway

[2] Implementa desde Cloud Console | Documentación de Creación de API gateway | Google Cloud. (s. f.). Google Cloud. https://cloud.google.com/api-gateway/docs/about-dev-env

[2] Guía de inicio Rápido | Google Cloud. (s. f.). https://cloud.google.com/api-gateway/docs/quickstarts