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 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.

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.

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 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

Limitaciones

Los siguientes comandos de kubectl no son compatibles con la puerta de enlace que usa el comando gcloud container fleet memberships get-credentials:

attach
cp
exec
port-forward

Compatibilidad de vista previa con los comandos

Los comandos attach, cp y exec (pero no port-forward) son compatibles con el comando beta gcloud beta container fleet memberships get-credentials. Este comando te permite usar una función de vista previa de la puerta de enlace de Connect.

Ten en cuenta los siguientes requisitos:

GKE no es compatible con la vista previa.
Los clústeres deben estar en la versión 1.30 o una posterior.
El cliente kubectl debe estar en la versión 1.29 o posterior. Si usas la versión 1.29, debes configurar la siguiente variable de entorno:
```
export KUBECTL_REMOTE_COMMAND_WEBSOCKETS=true
```
Las versiones de kubectl 1.30 y posteriores no requieren la variable de entorno.

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 y exec. 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 y exec 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 y exec.

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/cp"]
  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 Connect Agent pierda conectividad o no se instale de forma correcta (solo 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.

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.