Se usó la API de Cloud Translation para traducir esta página.

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 página, asegúrate de estar familiarizado 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 Google Cloud cuenta o una Google Cloud cuenta de servicio para interactuar con clústeres conectados a través de la API de Gateway.

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 que especificaste:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Reemplaza MEMBERSHIP_NAME por el nombre de la membresía de 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.

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.

Para recuperar la credencial del clúster que se usa para interactuar con la puerta de enlace de Connect a través de una cuenta de servicio, ejecuta los siguientes comandos: Ten en cuenta lo siguiente:

Clústeres de Google Distributed Cloud (solo software) en Bare Metal y VMware: El nombre de la membresía es el mismo que el nombre del clúster.
GKE en AWS: Usa gcloud container aws clusters get-credentials.
GKE en Azure: Usa gcloud container azure clusters get-credentials.

Puedes obtener más información para permitir que los usuarios actúen en nombre de una cuenta de servicio en Administra el acceso a las cuentas de servicio.

gcloud config set auth/impersonate_service_account SA_EMAIL_ADDRESS
gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Reemplaza SA_EMAIL_ADDRESS por la dirección de correo electrónico de la cuenta de servicio. Puedes obtener más información para permitir que los usuarios actúen en nombre de una cuenta de servicio en Administra el acceso a las cuentas de servicio.

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

Comandos kubectl exec/cp/attach/port-forward

Los siguientes comandos de kubectl son comandos de transmisión y tienen requisitos adicionales:

attach
cp
exec
port-forward

Ten en cuenta los siguientes requisitos:

Los clústeres deben estar en la versión 1.30 o una posterior para los comandos attach, cp y exec, y en la versión 1.31 o una posterior para el comando port-forward.
El cliente kubectl debe estar en la versión 1.31 o posterior.

Para verificar tu versión de cliente, consulta el resultado del comando kubectl version. Para instalar una versión más reciente de kubectl, consulta Instala herramientas.

Los usuarios y las cuentas de servicio con el rol de IAM roles/gkehub.gatewayAdmin y cluster-admin ClusterRole tienen los permisos necesarios para ejecutar los comandos attach, cp, exec y port-forward. Si a los usuarios y a las cuentas de servicio se les otorgó un rol de IAM personalizado o un rol de RBAC personalizado, es posible que debas otorgar permisos adicionales. Consulta las siguientes secciones para obtener más información.

Otorga un permiso adicional si es necesario

Se requiere el permiso de IAM gkehub.gateway.stream para ejecutar los comandos attach, cp, exec y port-forward a través de la puerta de enlace de Connect. Este permiso se incluye en roles/gkehub.gatewayAdmin.

En el caso de los usuarios que no son propietarios del proyecto, o para usuarios o cuentas de servicio a los que no se les otorgó roles/gkehub.gatewayAdmin en el proyecto, debes otorgarles roles/gkehub.gatewayAdmin o crear un rol personalizado que incluya los otros roles necesarios y el permiso gkehub.gateway.stream. Para obtener información sobre cómo crear un rol personalizado, consulta Crea y administra roles personalizados en la documentación de IAM.

Crea y aplica políticas de RBAC adicionales si es necesario

Los usuarios y las cuentas de servicio con cluster-admin ClusterRole tienen los permisos necesarios para ejecutar los comandos attach, cp, exec y port-forward.

Como mínimo, se necesitan las siguientes reglas para ejecutar los comandos:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: stream-role
  namespace: NAMESPACE  # Specify the namespace
rules:
- apiGroups: ["*"]
  resources: ["pods/exec", "pods/attach", "pods/portforward"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: stream-rolebinding
  namespace: NAMESPACE  # Specify the namespace
roleRef:
   apiGroup: "rbac.authorization.k8s.io"
   kind: Role
   name: stream-role
subjects:
- kind: User
  name: EMAIL # Specify the user that should have stream access
  namespace: NAMESPACE  # Specify the namespace

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 el comando 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.
No se pueden encontrar conexiones activas para el clúster(proyecto: 12345, membresía: my-cluster): Es posible que veas este error cuando el agente de Connect pierda la conectividad o no esté instalado correctamente (solo para clústeres fuera de Google Cloud ). Para resolver este problema, debes verificar si el espacio de nombres gke-connect existe en el clúster. 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 el rol roles/gkehub.gatewayAdmin, roles/gkehub.gatewayReader o roles/gkehub.gatewayEditor a fin de usar la API. Consulta Otorga roles de IAM a 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 suficientes permisos para realizar la operación cuando se usan Grupos de Google o asistencia de terceros: Consulta Recopila registros del servicio de identidad de GKE para obtener instrucciones para inspeccionar los registros relacionados. a 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.
no se econtró gke-gcloud-auth-plugin ejecutable o no se encontró ningún proveedor de autenticación para el nombre gcp: las versiones 1.26 y posteriores de kubectl pueden mostrar este error debido a cambios en kubectl autenticación 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 necesita 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 versiones anteriores) suponen la existencia del agente de Connect en el clúster. Intentar usar la puerta de enlace con estas versiones anteriores puede fallar en clústeres registrados con una versión más reciente de Google Cloud CLI. Para solucionar 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.
El tamaño de los grupos que se muestran en el grupo gke-security-groups supera el límite de tamaño del encabezado HTTP de 8 KB. Reorganiza la jerarquía de grupos y vuelve a intentarlo: Si bien no hay un límite estricto en la cantidad de grupos, los nombres de grupos largos pueden hacer que la solicitud supere el límite de tamaño del encabezado HTTP de 8 KB y generar errores que podrían requerir que reestructures la jerarquía de grupos.

Solución de problemas de kubectl exec/cp/attach/port-forward

El error que se muestra cuando se ejecuta el comando suele ser un error genérico 400 Bad Request que no es lo suficientemente claro como para depurar el problema. Para devolver mensajes de error más detallados, usa la versión 1.32 o posterior del cliente de kubectl para ejecutar el comando con un nivel de detalle 4 o superior, por ejemplo: kubectl exec -v 4 ....

En los registros devueltos, busca el que contenga las siguientes respuestas:

Para el comando kubectl exec/cp/attach: RemoteCommand fallback:
Para el comando kubectl port-forward: fallback to secondary dialer from primary dialer err:

En la siguiente sección, se explica cómo solucionar algunos de los mensajes de error comunes que podrías recibir del comando kubectl exec -v 4 ....

Permisos de IAM faltantes

Si el mensaje de error contiene generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, es posible que no se te hayan otorgado los permisos de IAM necesarios para ejecutar el comando. Esta función requiere que los usuarios tengan el permiso de IAM gkehub.gateway.stream, que se incluye de forma predeterminada en el rol roles/gkehub.gatewayAdmin. Consulta la sección de permisos de IAM para obtener instrucciones.

Faltan permisos obligatorios de RBAC

Si el mensaje de error contiene ...generic::failed_precondition: failed to connect to the cluster's API Server with response (status=403 Forbidden..., indica que te faltan permisos de RBAC. Necesitas un conjunto de permisos de RBAC en el clúster para ejecutar estos comandos de kubectl. Para obtener más información sobre cómo configurar los permisos de RBAC necesarios, consulta Crea y aplica políticas de RBAC adicionales si es necesario.

Mensaje de error generic::resource_exhausted: Se agotó la cuota de active_streams de la puerta de enlace

Existe un límite de cuota de 10 transmisiones activas por proyecto host de flota. Esto se define en la cuota de connectgateway.googleapis.com/active_streams. Consulta Visualiza y administra cuotas para obtener instrucciones sobre cómo administrar tus cuotas.

Mensaje de error generic::failed_precondition: Se produjo un error en el clúster

Si recibes el error generic::failed_precondition: error encountered within the cluster, verifica los registros de Connect Agent en el clúster para identificar la causa subyacente:

kubectl logs -n gke-connect -l app=gke-connect-agent --tail -1

El registro que debes buscar en Connect Agent es failed to create the websocket connection....

Mensaje de error generic::failed_precondition: Falló o se interrumpió la conexión con el agente

Si encuentras este error inmediatamente cuando ejecutas el comando, hay un problema con la conexión del clúster a Google. Para obtener más información, consulta la guía general de solución de problemas.

Si encuentras este error después de que la sesión esté activa durante unos 20 a 30 minutos, se trata de una limitación esperada por motivos de seguridad. Se debe restablecer la conexión.

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.