Usar la puerta de enlace de conexión

En esta página, se explica cómo usar la puerta de enlace de Connect para conectarse a un clúster registrado. Antes de leer esta guía, debes familiarizarte con los conceptos de nuestra descripción general. En la guía, se da por sentado que el administrador de tu proyecto ya configuró la puerta de enlace y te otorgó las funciones y los permisos necesarios.

Antes de comenzar

  • Asegúrate de tener instaladas las siguientes herramientas de línea de comandos:

    • La versión más reciente de Google Cloud CLI, la herramienta de línea de comandos para interactuar con Google Cloud.
    • kubectl

    Si usas Cloud Shell como entorno de shell para interactuar con Google Cloud, estas herramientas están instaladas.

  • Asegúrate de haber inicializado la CLI de gcloud para usarla en tu proyecto.

Accede a tu cuenta de Google Cloud

Puedes usar tu propia cuenta de Google Cloud o una cuenta de servicio de Google Cloud para interactuar con clústeres conectados a través de la API de puerta de enlace.

Sigue las instrucciones de la página sobre cómo autorizar las herramientas de Google Cloud CLI para acceder a tu cuenta de usuario. La puerta de enlace de Connect admite el robo de identidad de cuentas de servicio, por lo que, incluso si accediste a tu propia cuenta de usuario, puedes usar una cuenta de servicio para interactuar con clústeres, como verás en las siguientes secciones.

Selecciona un clúster registrado

Si no conoces el nombre del clúster al que deseas acceder, puedes ver todos los clústeres registrados de tu flota actual mediante la ejecución del siguiente comando:

gcloud container fleet memberships list

Mediante esta acción, se enumeran todos los clústeres de tu flota, incluidos los nombres de las membresías y los ID externos. Cada clúster de una flota tiene un nombre de membresía único. Para los clústeres de GKE, el nombre de la membresía suele coincidir con el nombre que le asignaste cuando creaste el clúster, a menos que el nombre del clúster no fuera único dentro de su proyecto durante el registro.

Obtén el kubeconfig de la puerta de enlace del clúster

Usa el siguiente comando a fin de obtener kubeconfig para interactuar con el clúster especificado y reemplaza MEMBERSHIP_NAME por el nombre de membresía de la flota de tu clúster. Mediante este comando, se muestra una kubeconfig específica de la puerta de enlace de Connect especial con la que puedes conectarte al clúster a través de la puerta de enlace.

# Fetch cluster credential used to interact with Connect gateway
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Si deseas usar una cuenta de servicio en lugar de tu propia cuenta de Google Cloud, usa gcloud config para establecer auth/impersonate_service_account en la dirección de correo electrónico de la cuenta de servicio. Puedes obtener más información para permitir que los usuarios suplanten la identidad de una cuenta de servicio en Administra el acceso a las cuentas de servicio.

# Fetch cluster credential used to interact with Connect gateway, using a service account
gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Ejecuta comandos en el clúster

Una vez que tengas las credenciales necesarias, podrás ejecutar comandos mediante kubectl o go-client, como lo harías con cualquier clúster de Kubernetes. La respuesta debería ser similar a la siguiente:

# Get namespaces in the Cluster.
kubectl get namespaces
NAME              STATUS   AGE
default           Active   59d
gke-connect       Active   4d

Los siguientes comandos de kubectl no son compatibles con la puerta de enlace:

  • exec
  • proxy
  • port-forward
  • attach

Soluciona problemas

Si tienes problemas para conectarte a un clúster mediante la puerta de enlace, tú o tu administrador pueden comprobar si tienen los siguientes problemas habituales.

  • El servidor no tiene un tipo de recurso: Es posible que veas este mensaje de error cuando un comando simple como kubectl get ns falla. Existen varios motivos posibles para este error. Ejecuta los comandos de kubectl en modo de verbosidad para ver más detalles, por ejemplo, kubectl get ns -v 10.
  • Cannot find active connection for cluster(project: 12345, member: my-cluster): Es posible que veas este error cuando el agente de Connect pierda conectividad o no esté instalado correctamente. Para resolver este problema, debes verificar si el espacio de nombres gke-connect existe en el clúster. De lo contrario, consulta Registra un clúster con Google Cloud CLI. Si el espacio de nombres gke-connect existe en el clúster, consulta la página de solución de problemas de Connect para solucionar los problemas de conectividad.
  • La URL solicitada no se encontró en este servidor: Es posible que veas este error cuando kubeconfig contenga una dirección de servidor incorrecta. Asegúrate de que la versión de Google Cloud CLI que uses sea la versión más reciente y vuelve a generar la puerta de enlace kubeconfig. No edites el archivo kubeconfig de forma manual, ya que podría causar errores inesperados.
  • La identidad del usuario no tiene suficientes permisos para usar la API de la puerta de enlace: necesitas la función roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader o roles/gkehub.gatewayEditor a fin de usar la API. Consulta Otorga funciones de IAM a los usuarios en la guía de configuración de la puerta de enlace para obtener más detalles.
  • El agente de Connect no está tiene autorización para enviar las solicitudes del usuario: se debe permitir que el agente de Connect reenvíe las solicitudes en tu nombre, lo cual se especifica mediante una política de robo de identidad en el clúster. Consulta Configura la autorización de RBAC en la guía de configuración de la puerta de enlace para ver un ejemplo de cómo agregar un usuario al rol gateway-impersonate.
  • La identidad del usuario no tiene suficientes permisos de RBAC para realizar la operación: debes tener los permisos adecuados en el clúster para ejecutar las operaciones seleccionadas. Consulta Configura la autorización de RBAC en la guía de configuración de la puerta de enlace para ver un ejemplo de cómo agregar un usuario al ClusterRole adecuado.
  • La identidad del usuario no tiene permisos suficientes para realizar la operación cuando se usan Grupos de Google o la asistencia de terceros: Consulta Recopila registros de GKE Identity Service para obtener instrucciones sobre cómo inspeccionar los registros relacionados con la información de identidad.
  • El agente de Connect no está en buen estado: Consulta la página Soluciona problemas de Connect para asegurarte de que el clúster esté conectado.
  • executable gke-gcloud-auth-plugin not found o no se encontró ningún proveedor de autenticación para el nombre gcp: kubectl versiones 1.26 y posteriores pueden mostrar este error debido a cambios en la autenticación de kubectl a partir de GKE v1.26. Instala gke-gcloud-auth-plugin y vuelve a ejecutar gcloud container fleet memberships get-credentials MEMBERSHIP_NAME con la versión más reciente de Google Cloud CLI.
  • Las conexiones a la puerta de enlace fallan con versiones anteriores de Google Cloud CLI: En los clústeres de GKE, ya no se requiere el agente de Connect para que la puerta de enlace funcione, por lo que no se instala de forma predeterminada durante el registro de la membresía. Las versiones anteriores de Google Cloud CLI (399.0.0 y anteriores) suponen la existencia del agente de Connect en el clúster. Si intentas usar la puerta de enlace con estas versiones anteriores, es posible que falle en clústeres registrados con una versión más reciente de Google Cloud CLI. Para resolver este problema, actualiza tu cliente de Google Cloud CLI a una versión más reciente o vuelve a ejecutar el comando de registro de membresía con la marca --install-connect-agent.

Próximos pasos

  • Consulta un instructivo sobre cómo integrar con Cloud Build para ver un ejemplo de cómo usar la puerta de enlace de Connect con parte de tu automatización de DevOps.