Usar la pasarela de conexión

En esta página se explica cómo usar la pasarela de conexión para conectarse a un clúster registrado. Antes de leer esta página, asegúrese de que conoce los conceptos que se explican en nuestra página de introducción. En esta guía se da por hecho que el administrador de tu proyecto ya ha configurado la pasarela y te ha asignado los roles y permisos necesarios.

Antes de empezar

  • Asegúrate de que tienes 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 ya están instaladas.

  • Asegúrate de haber inicializado gcloud CLI para usarlo con tu proyecto.

Inicia sesión en tu cuenta de Google Cloud

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

Sigue las instrucciones de Autorizar las herramientas de la CLI de Google Cloud para iniciar sesión en tu cuenta de usuario. La pasarela Connect admite la suplantación de identidad de cuentas de servicio, por lo que, aunque hayas iniciado sesión en tu propia cuenta de usuario, puedes usar una cuenta de servicio para interactuar con los clústeres, como verás en las siguientes secciones.

Selecciona un clúster registrado

Si no sabes el nombre del clúster al que quieres acceder, puedes ver todos los clústeres registrados de tu flota actual ejecutando el siguiente comando:

gcloud container fleet memberships list

En esta lista se muestran todos los clústeres de tu flota, incluidos sus nombres de pertenencia e IDs externos. Cada clúster de una flota tiene un nombre de miembro único. En el caso de los clústeres de GKE, el nombre del grupo de miembros suele coincidir con el nombre que le asignaste al crear el clúster, a menos que el nombre del clúster no fuera único en su proyecto en el momento del registro.

Obtener la pasarela del clúster kubeconfig

Usa el siguiente comando para obtener el kubeconfig que necesitas para interactuar con el clúster especificado:

gcloud container fleet memberships get-credentials MEMBERSHIP_NAME

Sustituye MEMBERSHIP_NAME por el nombre de la pertenencia a la flota de tu clúster.

Este comando devuelve un kubeconfig específico de la pasarela de conexión que te permite conectarte al clúster a través de la pasarela de conexión.

Si quieres usar una cuenta de servicio en lugar de tu propia cuenta, usa gcloud config para asignar a auth/impersonate_service_account la dirección de correo de la cuenta de servicio. Google Cloud

Para obtener la credencial del clúster que se usa para interactuar con la pasarela Connect mediante una cuenta de servicio, ejecuta los siguientes comandos: Ten en cuenta lo siguiente:

  • Clústeres de Google Distributed Cloud (solo software) en hardware desnudo y VMware: el nombre del miembro es el mismo que el del clúster.

  • GKE en AWS: usa gcloud container aws clusters get-credentials.

  • GKE en Azure: uso gcloud container azure clusters get-credentials.

Para obtener más información sobre cómo permitir que los usuarios suplanten la identidad de una cuenta de servicio, consulta el artículo Gestionar el acceso a cuentas de servicio.

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

Sustituye SA_EMAIL_ADDRESS por la dirección de correo de la cuenta de servicio. Puedes consultar más información sobre cómo permitir que los usuarios suplanten la identidad de una cuenta de servicio en el artículo Gestionar el acceso a cuentas de servicio.

Ejecutar comandos en el clúster

Una vez que tengas las credenciales necesarias, podrás ejecutar comandos con kubectl o un go-client como lo harías normalmente en cualquier clúster de Kubernetes. La salida debería tener un aspecto similar al 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 streaming y tienen requisitos adicionales:

  • attach
  • cp
  • exec
  • port-forward

Ten en cuenta los siguientes requisitos:

  • Los clústeres deben tener la versión 1.30 o posterior para los comandos attach, cp y exec, y la versión 1.31 o posterior para el comando port-forward.

  • El cliente kubectl debe tener la versión 1.31 o una posterior.

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

Los usuarios y las cuentas de servicio con el rol de gestión de identidades y accesos roles/gkehub.gatewayAdmin y el permiso cluster-admin ClusterRole tienen los permisos necesarios para ejecutar los comandos attach, cp, exec y port-forward. Si se ha concedido a los usuarios y a las cuentas de servicio un rol de IAM personalizado o un rol de control de acceso basado en roles (RBAC) personalizado, es posible que tengas que conceder permisos adicionales. Consulta las siguientes secciones para obtener más información.

Concede un permiso adicional si es necesario

Se necesita el permiso de gestión de identidades y accesos gkehub.gateway.stream para ejecutar los comandos attach, cp, exec y port-forward a través de la pasarela Connect. Este permiso se incluye en roles/gkehub.gatewayAdmin.

En el caso de los usuarios que no sean propietarios del proyecto o de los usuarios o cuentas de servicio a los que no se les haya concedido roles/gkehub.gatewayAdmin en el proyecto, debe concederles 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 el artículo Crear y gestionar roles personalizados de la documentación de IAM.

Crear y aplicar políticas de RBAC adicionales si es necesario

Los usuarios y las cuentas de servicio con el rol 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

Solución de problemas

Si tienes problemas para conectarte a un clúster a través de la pasarela, tú o tu administrador podéis comprobar si se da alguno de los siguientes problemas habituales.

  • El servidor no tiene un tipo de recurso: puede que veas este mensaje de error cuando falle el comando kubectl get ns. Este error puede deberse a varios motivos. Ejecuta tus comandos de kubectl en modo detallado para ver más información. Por ejemplo, kubectl get ns -v 10.
  • No se encuentran conexiones activas para el clúster(proyecto: 12345, pertenencia: my-cluster): puede ver este error cuando Connect Agent pierde la conectividad o no se ha instalado correctamente (solo en clústeres externos a Google Cloud ). Para solucionar este problema, debe 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 conexión para solucionar los problemas de conectividad.
  • No se ha encontrado la URL solicitada en este servidor: puede ver este error cuando el kubeconfig contiene una dirección de servidor incorrecta. Asegúrate de que la versión de la CLI de Google Cloud que estás usando sea la más reciente y vuelve a intentar generar la kubeconfig de la pasarela. No edites manualmente el archivo kubeconfig, ya que esto provocará errores inesperados.
  • La identidad del usuario no tiene permisos suficientes para usar la API de la pasarela: necesitas el rol roles/gkehub.gatewayAdmin roles/gkehub.gatewayReader o roles/gkehub.gatewayEditor para usar la API. Para obtener más información, consulta la sección Conceder roles de gestión de identidades y accesos a usuarios de la guía de configuración de la pasarela.
  • El agente de Connect no tiene autorización para enviar las solicitudes del usuario: el agente de Connect debe tener permiso para reenviar solicitudes en tu nombre, lo que se especifica mediante una política de suplantación de identidad en el clúster. Consulta un ejemplo de cómo añadir un usuario al rol gateway-impersonate en la guía de configuración de la pasarela.
  • La identidad del usuario no tiene permisos de control de acceso basado en roles suficientes para realizar la operación: debes tener los permisos adecuados en el clúster para ejecutar las operaciones que elijas. Consulta un ejemplo de cómo añadir un usuario al ClusterRole adecuado en la sección Configurar la autorización RBAC de la guía de configuración de la pasarela.
  • La identidad del usuario no tiene permisos suficientes para realizar la operación al usar Grupos de Google o asistencia de terceros: consulta Recoger registros del servicio de identidad de GKE 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 de solución de problemas de Connect para asegurarte de que tu clúster esté conectado.
  • No se ha encontrado el ejecutable gke-gcloud-auth-plugin o No se ha encontrado ningún proveedor de autenticación con el nombre gcp: las versiones 1.26 y posteriores de kubectl pueden mostrar este error debido a los cambios en la autenticación de kubectl a partir de la versión 1.26 de GKE. Instala gke-gcloud-auth-plugin y vuelve a ejecutar gcloud container fleet memberships get-credentials MEMBERSHIP_NAME con la última versión de la CLI de Google Cloud.

  • Las conexiones a la pasarela fallan con versiones anteriores de la CLI de Google Cloud: en los clústeres de GKE, el agente de Connect ya no es necesario para que la pasarela funcione, por lo que no se instala de forma predeterminada durante el registro de la pertenencia. Las versiones anteriores de la CLI de Google Cloud (399.0.0 y anteriores) dan por hecho que el agente de Connect está en el clúster. Si intentas usar la pasarela con estas versiones anteriores, puede que no funcione en los clústeres registrados con una versión más reciente de la CLI de Google Cloud. Para solucionar este problema, actualice su cliente de CLI de Google Cloud a una versión más reciente o vuelva a ejecutar el comando de registro de la suscripción con la marca --install-connect-agent.

  • El tamaño de los grupos devueltos en el grupo gke-security-groups supera el límite de tamaño de encabezado HTTP de 8 KB. Reorganiza la jerarquía de grupos y vuelve a intentarlo: aunque no hay un límite estricto en el número de grupos, los nombres de grupo largos pueden provocar que la solicitud supere el límite de tamaño del encabezado HTTP de 8 KB y generar errores que pueden requerir que reestructures la jerarquía de grupos.

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

El error devuelto al ejecutar el comando suele ser un error genérico 400 Bad Request que no es lo suficientemente claro como para depurar el problema. Para obtener mensajes de error más detallados, usa la versión 1.32 o posterior del cliente 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 registro 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:

Para solucionar algunos de los mensajes de error habituales que puedes recibir del comando kubectl exec -v 4 ..., consulta la siguiente sección.

Faltan permisos de gestión de identidades y accesos

Si el mensaje de error contiene generic::permission_denied: Permission'gkehub.gateway.stream' denied on resource, puede que no se te hayan concedido los permisos de IAM necesarios para ejecutar el comando. Para usar esta función, los usuarios deben tener el permiso de gestión de identidades y accesos gkehub.gateway.stream, que se incluye de forma predeterminada en el rol roles/gkehub.gatewayAdmin. Consulta las instrucciones en la sección de permisos de gestión de identidades y accesos.

Faltan permisos de RBAC obligatorios

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

Mensaje de error generic::resource_exhausted: se ha agotado la cuota de active_streams de la pasarela

Hay un límite de cuota de 10 emisiones activas por proyecto de host de flota. Se define en la cuota de connectgateway.googleapis.com/active_streams. Consulta el artículo Ver y gestionar cuotas para obtener instrucciones sobre cómo gestionar tus cuotas.

Mensaje de error generic::failed_precondition: error encountered within the cluster (error encontrado en el clúster)

Si aparece el error generic::failed_precondition: error encountered within the cluster, consulta 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 el agente de Connect es failed to create the websocket connection....

Mensaje de error generic::failed_precondition: connection to Agent failed/terminated (Se ha producido un error o se ha terminado la conexión con el agente)

Si aparece este error inmediatamente al ejecutar el comando, significa que hay un problema con la conexión del clúster a Google. Consulta la guía general para solucionar problemas para obtener más información.

Si se produce este error después de que la sesión esté activa durante unos 20 o 30 minutos, se trata de una limitación prevista por motivos de seguridad. La conexión debe restablecerse.

Siguientes pasos

  • Consulta un ejemplo de cómo usar la pasarela Connect como parte de tu automatización de DevOps en nuestro tutorial Integración con Cloud Build.