Recibir eventos de Pub/Sub en un endpoint HTTP privado de un clúster de GKE privado

En este tutorial se muestra cómo crear un endpoint HTTP privado en un clúster privado de Google Kubernetes Engine (GKE) que recibe eventos de mensajes de Pub/Sub mediante Eventarc. Para obtener más información sobre este destino de eventos, consulta Dirigir eventos a un endpoint HTTP interno en una red de VPC.

Los clústeres de GKE privados son un tipo de clúster nativo de nube privada virtual (VPC) en el que los nodos solo tienen direcciones IP internas, lo que significa que los nodos y los pods están aislados de Internet de forma predeterminada. Puedes elegir si quieres que los clientes tengan acceso al plano de control, si quieres que tengan acceso limitado o si quieres que tengan acceso sin restricciones. No puedes convertir un clúster que ya existe y que no es privado en un clúster privado. Para obtener más información, consulta Acerca de los clústeres privados.

Puedes ejecutar los siguientes comandos con la CLI de Google Cloud en tu terminal o en Cloud Shell.

Objetivos

En este tutorial, aprenderás a hacer lo siguiente:

1. Crea una subred de solo proxy en la red VPC predeterminada y una regla de cortafuegos de VPC.
2. Crea un clúster de Autopilot de GKE privado sin acceso de cliente al endpoint público.
3. Crea una instancia de máquina virtual (VM) de Compute Engine en una subred específica de la red VPC.
4. Establece una conexión SSH con la instancia de VM y despliega un servicio de receptor de eventos en la instancia de VM.
5. Despliega una pasarela en tu clúster y un manifiesto HTTPRoute para configurar el enrutamiento del tráfico en Kubernetes a los back-ends de las aplicaciones.
6. Crea un acoplamiento de red que permita que una red de VPC de productor inicie conexiones con una red de VPC de consumidor.
7. Crea un activador de Eventarc que enrute eventos de Pub/Sub al receptor de eventos de tu instancia de VM.
8. Publica un mensaje en un tema de Pub/Sub para generar un evento y consulta el cuerpo del evento en los registros del pod de la aplicación.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• Compute Engine
• Eventarc
• Google Kubernetes Engine
• Pub/Sub
• VPC

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

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.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, Eventarc, GKE, and Pub/Sub APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable compute.googleapis.com container.googleapis.com cloudresourcemanager.googleapis.com eventarc.googleapis.com pubsub.googleapis.com

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, Eventarc, GKE, and Pub/Sub APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable compute.googleapis.com container.googleapis.com cloudresourcemanager.googleapis.com eventarc.googleapis.com pubsub.googleapis.com

1. Actualiza los componentes de Google Cloud CLI:

   gcloud components update

2. Inicia sesión con tu cuenta:

   gcloud auth login

3. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

   Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, una entidad principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación). Para obtener más información, consulta la página Roles y permisos de tu destino de evento.

   Permisos obligatorios

   Para obtener los permisos que necesitas para completar esta guía de inicio rápido, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

   • Administrador de red de Compute (roles/compute.networkAdmin)
   • Administrador de seguridad de Compute (roles/compute.securityAdmin)
   • Administrador de Eventarc (roles/eventarc.admin)
   • Administrador de Kubernetes Engine (roles/container.admin)
   • Usuario con permiso para ver registros (roles/logging.viewAccessor)
   • Administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin)
   • Editor de Pub/Sub (roles/pubsub.publisher)
   • Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
   • Administrador de Uso de Servicio (roles/serviceusage.serviceUsageAdmin)

   Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

   También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

4. Anota la cuenta de servicio predeterminada de Compute Engine, ya que la asociarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio que utiliza Compute Engine y tiene el siguiente formato de correo electrónico: Google Cloud

   PROJECT_NUMBER-compute@developer.gserviceaccount.com

   Sustituye PROJECT_NUMBER por el número de tu proyecto. Google Cloud Puedes encontrar el número de tu proyecto en la página Bienvenido de la consola Google Cloud o ejecutando el siguiente comando:

   gcloud projects describe PROJECT_ID --format='value(projectNumber)'

   En los entornos de producción, te recomendamos que crees una cuenta de servicio y le asignes uno o varios roles de IAM que contengan los permisos mínimos necesarios y que sigas el principio de privilegio mínimo.

5. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril del 2021 o antes para admitir solicitudes push de Pub/Sub autenticadas, asigna el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se asigna de forma predeterminada:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator

Crear una subred de solo proxy

A menos que crees una política de organización que lo prohíba, los proyectos nuevos empiezan con una red predeterminada (una red de VPC de modo automático) que tiene una subred en cada región. Cada red de VPC consta de uno o varios intervalos de direcciones IP denominados subredes. Las subredes son recursos regionales y tienen intervalos de direcciones IP asociados.

1. Usa el comando gcloud compute networks subnets create para crear una subred de solo proxy en la red predeterminada.

   gcloud compute networks subnets create proxy-only-subnet \
       --purpose=REGIONAL_MANAGED_PROXY \
       --role=ACTIVE \
       --region=us-central1 \
       --network=default \
       --range=10.10.10.0/24
   

   Ten en cuenta que una subred con purpose=REGIONAL_MANAGED_PROXY está reservada para los balanceadores de carga basados en Envoy y que range debe proporcionar al menos 64 direcciones IP.

2. Crea una regla de cortafuegos que coincida con el intervalo de la subred de solo proxy y que permita el tráfico en el puerto TCP 8080.

   gcloud compute firewall-rules create allow-proxy-connection \
       --allow tcp:8080 \
       --source-ranges 10.10.10.0/24 \
       --network=default
   

Crear un clúster privado de GKE

Usa el comando gcloud container clusters create-auto para crear un clúster privado de GKE en modo Autopilot que tenga nodos privados y que no tenga acceso de cliente al endpoint público.

En el siguiente ejemplo se crea un clúster de GKE privado llamado private-cluster y una subred llamada my-subnet:

gcloud container clusters create-auto private-cluster \
    --create-subnetwork name=my-subnet \
    --enable-master-authorized-networks \
    --enable-private-nodes \
    --enable-private-endpoint \
    --region=us-central1

Ten en cuenta lo siguiente:

• --enable-master-authorized-networks especifica que el acceso al endpoint público está restringido a los intervalos de direcciones IP que autorices.
• --enable-private-nodes indica que los nodos del clúster no tienen direcciones IP externas.
• --enable-private-endpoint indica que el clúster se gestiona mediante la dirección IP interna del endpoint de la API del plano de control.

La creación del clúster puede tardar varios minutos. Una vez creado el clúster, el resultado debería indicar que su estado es RUNNING.

Crear una instancia de VM en una subred específica

Una instancia de VM de Compute Engine es una máquina virtual alojada en la infraestructura de Google. Los términos instancia de Compute Engine, instancia de VM y VM son sinónimos y se usan indistintamente. Las instancias de VM incluyen clústeres de GKE, instancias del entorno flexible de App Engine y otros Google Cloud productos creados en VMs de Compute Engine.

Usa el comando gcloud compute instances create para crear una instancia de VM de Compute Engine en la subred que has creado anteriormente. Asigna una cuenta de servicio y define el ámbito de acceso de la máquina virtual como cloud-platform.

gcloud compute instances create my-vm \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --zone=us-central1-a \
    --subnet=my-subnet

Para obtener más información, consulta Crear e iniciar una instancia de VM.

Desplegar un receptor de eventos en la VM

Con una imagen prediseñada, us-docker.pkg.dev/cloudrun/container/hello, implementa un servicio en tu VM que escuche en el puerto 80 y que reciba y registre eventos.

1. Establece una conexión SSH con tu instancia de VM ejecutando el siguiente comando:

   gcloud compute ssh my-vm --project=PROJECT_ID --zone=us-central1-a
   

   Una vez que se haya establecido una conexión con el servidor SSH, ejecuta los comandos restantes en tu instancia de VM.

2. Si es necesario, instala kubectl y los complementos necesarios.

3. En tu instancia de VM, usa el comando get-credentials para habilitar kubectl y que funcione con el clúster que has creado.

   gcloud container clusters get-credentials private-cluster \
       --region=us-central1 \
       --internal-ip
   

4. Usa un comando de Kubernetes, kubectl create deployment, para desplegar una aplicación en el clúster.

   kubectl create deployment hello-app \
       --image=us-docker.pkg.dev/cloudrun/container/hello
   

   De esta forma, se crea un despliegue llamado hello-app. El pod de la implementación ejecuta la imagen de contenedor hello.

5. Después de desplegar la aplicación, puedes exponerla al tráfico creando un servicio de Kubernetes. Ejecuta el siguiente comando:kubectl expose

   kubectl expose deployment hello-app \
       --type ClusterIP \
       --port 80 \
       --target-port 8080
   

   Deberías ver service/hello-app exposed en la salida.

   Puedes ignorar los mensajes similares al siguiente:

   E0418 14:15:33.970933    1129 memcache.go:287] couldn't get resource list for metrics.k8s.io/v1beta1: the server is currently unable to handle the request
   

Configurar el enrutamiento del tráfico de Kubernetes

Un recurso Gateway representa un plano de datos que enruta el tráfico en Kubernetes. Una puerta de enlace puede representar muchos tipos diferentes de balanceo de carga y de enrutamiento en función de la GatewayClass de la que derive. Para obtener más información, consulta el artículo sobre implementación de pasarelas. Se implementa un manifiesto HTTPRoute para crear rutas y enviar tráfico a los back-ends de las aplicaciones.

1. Despliega una pasarela en tu clúster.

   kubectl apply -f - <<EOF
   kind: Gateway
   apiVersion: gateway.networking.k8s.io/v1beta1
   metadata:
     name: internal-http
   spec:
     gatewayClassName: gke-l7-rilb
     listeners:
     - name: http
       protocol: HTTP
       port: 80
   EOF
   

   Ten en cuenta lo siguiente:

   • gatewayClassName: gke-l7-rilb especifica el GatewayClass del que deriva este Gateway. gke-l7-rilb corresponde al balanceador de carga de aplicación interno.
   • port: 80 especifica que la puerta de enlace solo expone el puerto 80 para escuchar el tráfico HTTP.

2. Valida que la pasarela se haya implementado correctamente. Puede que tarde unos minutos en desplegar todos sus recursos.

   kubectl describe gateways.gateway.networking.k8s.io internal-http
   

   El resultado debería ser similar al siguiente:

   Name:         internal-http
   Namespace:    default
   ...
   API Version:  gateway.networking.k8s.io/v1beta1
   Kind:         Gateway
   ...
   Spec:
     Gateway Class Name:  gke-l7-rilb
     Listeners:
       Allowed Routes:
         Namespaces:
           From:  Same
       Name:      http
       Port:      80
       Protocol:  HTTP
   Status:
     Addresses:
       Type:   IPAddress
       Value:  10.36.172.5
   ...
   Events:
     Type    Reason  Age                From                   Message
     ----    ------  ----               ----                   -------
     Normal  ADD     80s                sc-gateway-controller  default/internal-http
     Normal  UPDATE  20s (x3 over 80s)  sc-gateway-controller  default/internal-http
     Normal  SYNC    20s                sc-gateway-controller  SYNC on default/internal-http was a success
   

3. Despliega un manifiesto HTTPRoute para enrutar el tráfico HTTP al hello-app servicio en el puerto 80.

   kubectl apply -f - <<EOF
   kind: HTTPRoute
   apiVersion: gateway.networking.k8s.io/v1beta1
   metadata:
     name: hello-app-route
   spec:
     parentRefs:
     - kind: Gateway
       name: internal-http
     rules:
     - backendRefs:
       - name: hello-app
         port: 80
   EOF
   

Crear un archivo adjunto de red

Una vinculación de red es un recurso que permite que una red de VPC de un productor inicie conexiones con una red de VPC de un consumidor a través de una interfaz de Private Service Connect.

Para publicar eventos, Eventarc usa el archivo adjunto de red para establecer una conexión con el endpoint HTTP interno alojado en una red VPC.

Puedes crear una vinculación de red que acepte automáticamente las conexiones de cualquier interfaz de Private Service Connect que haga referencia a la vinculación de red. Crea el adjunto de red en la misma red y región que contenga el servicio de destino HTTP.

gcloud compute network-attachments create my-network-attachment \
    --region=us-central1 \
    --subnets=my-subnet\
    --connection-preference=ACCEPT_AUTOMATIC

Para obtener más información, consulta Acerca de los archivos adjuntos de red.

Crear un activador de Eventarc

Crea un activador de Eventarc que cree un tema de Pub/Sub y enrute los eventos al receptor de eventos desplegado en la VM cuando se publique un mensaje en el tema de Pub/Sub.

1. Obtén la dirección de la pasarela.

   GATEWAY_ADDRESS=$(kubectl get gateways.gateway.networking.k8s.io internal-http -o=jsonpath="{.status.addresses[0].value}")
   

2. Crea un activador.

   gcloud eventarc triggers create my-trigger \
       --location=us-central1 \
       --destination-http-endpoint-uri="http://$GATEWAY_ADDRESS:80/" \
       --network-attachment="projects/PROJECT_ID/regions/us-central1/networkAttachments/my-network-attachment" \
       --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
       --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
   

   Sustituye PROJECT_NUMBER por el número de tu proyecto. Google Cloud Puedes encontrar el número de tu proyecto en la página Bienvenido de la consola Google Cloud o ejecutando el siguiente comando:

   gcloud projects describe PROJECT_ID --format='value(projectNumber)'
   

Para obtener más información sobre cómo configurar el activador, consulta Dirigir eventos a un endpoint HTTP interno en una red de VPC.

Generar y ver un evento de tema de Pub/Sub

Puedes generar un evento publicando un mensaje en un tema de Pub/Sub.

1. Busca y define el tema de Pub/Sub como variable de entorno.

   export MY_TOPIC=$(gcloud eventarc triggers describe my-trigger \
       --location=us-central1 \
       --format='value(transport.pubsub.topic)')
   

2. Publica un mensaje en el tema de Pub/Sub para generar un evento.

   gcloud pubsub topics publish $MY_TOPIC --message "Hello World"
   

   El activador de Eventarc dirige el evento al endpoint HTTP interno del clúster privado de GKE.

3. Consulta los registros de Pod de la aplicación y verifica la entrega de eventos.

   POD_NAME=$(kubectl get pod --selector app=hello-app --output=name)
   kubectl logs $POD_NAME
   

   El cuerpo del evento debe ser similar al siguiente:

   2024/04/18 20:31:43 Hello from Cloud Run! The container started successfully and is listening for HTTP requests on $PORT
   {"severity":"INFO","eventType":"google.cloud.pubsub.topic.v1.messagePublished","message":"Received event of type google.cloud.pubsub.topic.v1.messagePublished.
   Event data: Hello World","event":{"specversion":"1.0","id":"10935738681111260","source":"//pubsub.googleapis.com/projects/my-project/topics/eventarc-us-central1-my-trigger-224","type":"google.cloud.pubsub.topic.v1.messagePublished","datacontenttype":"application/json","time":"2024-04-18T20:40:03Z","data":
   {"message":{"data":"SGVsbG8gV29ybGQ=","messageId":"10935738681111260","publishTime":"2024-04-18T20:40:03Z"}}}}
   

Has desplegado correctamente un servicio de receptor de eventos en un endpoint HTTP interno de un clúster privado de GKE, has creado un activador de Eventarc, has generado un evento desde Pub/Sub y has confirmado que el activador ha dirigido el evento al endpoint de destino según lo previsto.

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Eliminar recursos concretos

1. Elimina el activador de Eventarc:
     gcloud eventarc triggers delete my-trigger --location=us-central1

2. Sal de la VM y, a continuación, elimina la instancia de VM:
     gcloud compute instances delete my-vm --zone=us-central1-a

3. Elimina el archivo adjunto de la red:
     gcloud compute network-attachments delete my-network-attachment --region=us-central1

4. Elimina la regla de cortafuegos:
     gcloud compute firewall-rules delete allow-proxy-connection

5. Elimina el clúster:
     gcloud container clusters delete private-cluster --region=us-central1
     

6. Delete the subnet:

     gcloud compute networks subnets delete proxy-only-subnet --region=us-central1

Siguientes pasos

• Recibir eventos de Pub/Sub en un endpoint HTTP interno de una red VPC
• Gestionar activadores de Eventarc
• Ver todos los proveedores y destinos de eventos