Establece el acceso del clúster para kubectl

En esta página, se explica cómo configurar el acceso al clúster para la herramienta de línea de comandos de kubectl en Google Kubernetes Engine.

Descripción general

Si ejecutas varios clústeres dentro de tu proyecto de Google Cloud, debes elegir con qué clúster se comunicará kubectl. Puedes configurar un clúster predeterminado para kubectl si estableces el contexto actual en el archivo kubeconfig de Kubernetes. Además, puedes ejecutar comandos kubectl en un clúster específico con la marca --cluster.

En las siguientes secciones, se explica cómo funciona kubeconfig, cómo configurar un clúster predeterminado para kubectl y cómo ejecutar comandos kubectl individuales en un clúster específico.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Establece la configuración de gcloud predeterminada mediante uno de los siguientes métodos:

  • Usa gcloud init si deseas ver una explicación sobre cómo configurar parámetros predeterminados.
  • Usa gcloud config para establecer el ID, la zona y la región del proyecto de manera individual.

Usa gcloud init

Si recibes el error One of [--zone, --region] must be supplied: Please specify location, completa esta sección.

  1. Ejecuta gcloud init y sigue las instrucciones:

    gcloud init

    Si usas SSH en un servidor remoto, usa la marca --console-only para evitar que el comando abra un navegador:

    gcloud init --console-only
  2. Sigue las instrucciones a fin de autorizar a gcloud para que use tu cuenta de Google Cloud.
  3. Crea una configuración nueva o selecciona una existente.
  4. Elige un proyecto de Google Cloud.
  5. Elige una zona predeterminada de Compute Engine.

Usa gcloud config

  • Establece tu ID del proyecto predeterminado:
    gcloud config set project project-id
  • Si trabajas con clústeres zonales, establece tu zona de procesamiento predeterminada: 
    gcloud config set compute/zone compute-zone
  • Si trabajas con clústeres regionales, establece tu región de procesamiento predeterminada:
    gcloud config set compute/region compute-region
  • Actualiza gcloud a la versión más reciente:
    gcloud components update

Archivo de configuración de Kubernetes

Kubernetes usa un archivo YAML llamado kubeconfig a fin de almacenar información de autenticación de clúster para kubectl. kubeconfig contiene una lista de contextos a los que kubectl se refiere cuando ejecuta comandos. De forma predeterminada, el archivo se guarda en $HOME/.kube/config.

Un contexto es un grupo de parámetros de acceso. Cada contexto contiene un clúster de Kubernetes, un usuario y un espacio de nombres. El contexto actual es el clúster que predeterminado para kubectl: todos los comandos kubectl se ejecutan en ese clúster.

Cuando creas un clúster con gcloud container clusters create, una entrada se agrega de manera automática a kubeconfig en tu entorno y el contexto actual cambia a ese clúster:

gcloud container clusters create my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster

Cuando creas un clúster con Google Cloud Console o gcloud desde una computadora diferente, la kubeconfig de tu entorno no se actualiza. Además, si un miembro del equipo del proyecto usa gcloud para crear un clúster desde su computadora, su kubeconfig se actualiza, pero el tuyo no. Sigue las instrucciones a continuación para agregar estos clústeres a tu kubeconfig local.

Sobre el extremo del clúster

Todos los clústeres tienen un extremo canónico. El extremo expone el servidor de API de Kubernetes que kubectl y otros servicios usan para comunicarse con el plano de control del clúster (instancia principal). La IP del extremo se muestra en Cloud Console en el campo Extremos de la pestaña Detalles del clúster y en el resultado de gcloud container clusters describe en el campo endpoint.

Cuando ejecutes gcloud container clusters get-credentials, verás que el comando obtiene el extremo del clúster como parte de la actualización de kubeconfig.

Los clústeres privados tienen dos direcciones IP independientes del extremo: privateEndpoint, que es una dirección IP interna, y publicEndpoint, que es una externa. El campo endpoint hace referencia a la IP externa, a menos que el acceso público al extremo esté inhabilitado, en cuyo caso se usará la IP privada.

Si ejecutas get-credentials, se usa la IP especificada en el campo endpoint de forma predeterminada. Para los clústeres privados, si prefieres usar la IP interna como extremo, consulta Generar una entrada de kubeconfig mediante la dirección IP interna de un clúster privado.

Acerca de la autenticación para kubectl

Todos los clústeres de GKE están configurados para aceptar identidades de usuario y cuenta de servicio de Google Cloud, mediante la validación de las credenciales que presenta kubectl y la recuperación de la dirección de correo electrónico asociada con la identidad del usuario o la cuenta de servicio. Como resultado, las credenciales de esas cuentas deben incluir el alcance de OAuth userinfo.email para autenticarse de forma correcta.

Cuando usas gcloud a fin de configurar el kubeconfig de tu entorno para un clúster nuevo o existente, gcloud le da a kubectl las mismas credenciales que usa gcloud. Por ejemplo, si usas gcloud auth login, tus credenciales personales se proporcionan a kubectl, incluido el alcance userinfo.email. Esto permite que el clúster de GKE autentique el cliente kubectl.

De forma alternativa, puedes elegir configurar kubectl para usar las credenciales de una cuenta de servicio de Google Cloud, mientras se ejecuta en una instancia de Compute Engine. Sin embargo, de forma predeterminada, el alcance userinfo.email no se incluye en las credenciales que crean las instancias de Compute Engine. Por lo tanto, debes agregar este alcance de forma explícita, mediante el uso de la marca --scopes cuando se crea la instancia de Compute Engine.

Una vez que los usuarios o las cuentas de servicio de Google Cloud se autentican, también deben estar autorizados para realizar cualquier acción en un clúster de GKE. Consulta Control de acceso según la función para obtener más información sobre cómo configurar la autorización.

Para obtener información sobre los métodos de autenticación compatibles cuando te conectas al servidor de la API de Kubernetes, consulta Autentícate en el servidor de la API de Kubernetes.

Visualiza el contexto actual de kubectl

Para ver el contexto actual de kubectl, ejecuta el siguiente comando:

kubectl config current-context

Visualiza kubeconfig

Para ver kubeconfig en tu entorno, ejecuta el siguiente comando:

kubectl config view

El comando muestra una lista de todos los clústeres para los cuales se generaron entradas de kubeconfig. Si aparece un clúster de GKE, puedes ejecutar comandos kubectl en tu entorno actual. De lo contrario, debes generar una entrada kubeconfig para el clúster.

Genera una entrada kubeconfig

Para ejecutar comandos kubectl en un clúster creado en Cloud Console, desde otra computadora o si lo hace otro miembro del proyecto, debes generar una entrada kubeconfig en tu entorno.

Ejecuta este comando para generar una entrada kubeconfig:

gcloud container clusters get-credentials cluster-name

En el ejemplo anterior, cluster-name es el nombre del clúster.

Este comando requiere que tengas el permiso container.clusters.get. La función de IAM con privilegios mínimos que proporciona este permiso es container.clusterViewer.

La entrada kubeconfig contiene una de las siguientes opciones:

Genera una entrada kubeconfig con la dirección IP interna de un clúster privado

Cuando ejecutas get-credentials, puedes especificar --internal-ip para escribir la dirección IP interna de un clúster privado en kubeconfig:

gcloud container clusters get-credentials --internal-ip cluster-name

Configura un clúster predeterminado para los comandos kubectl

Si ya generaste una entrada kubeconfig para los clústeres, puedes cambiar el contexto actual de kubectl a ese clúster mediante la ejecución del siguiente comando:

gcloud container clusters get-credentials

Por ejemplo, considera un proyecto con dos clústeres, my-cluster y my-new-cluster. El contexto actual es my-new-cluster, pero deseas ejecutar todos los comandos de kubectl en my-cluster. Para cambiar el contexto actual de my-new-cluster a my-cluster, debes ejecutar el siguiente comando:

gcloud container clusters get-credentials my-cluster

Ejecuta comandos kubectl individuales en un clúster específico

Puedes ejecutar comandos kubectl individuales en un clúster específico si pasas el nombre del clúster como aparece en kubeconfig como el argumento para la marca --cluster.

Por ejemplo, considera un entorno con dos clústeres, my-cluster y my-new-cluster, en el que el contexto actual es my-cluster. Quieres implementar una aplicación en my-new-cluster, pero no deseas cambiar el contexto actual. Para implementar la aplicación en my-new-cluster sin cambiar el contexto actual, debes ejecutar el siguiente comando:

kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster

Soluciona problemas

Permisos de autenticación insuficientes

Cuando ejecutas gcloud container clusters get-credentials, recibes el siguiente error:

ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.

Este error se produce porque se intenta acceder a la API de Kubernetes Engine desde una VM de Compute Engine que no tiene el permiso cloud-platform. Si deseas obtener instrucciones a fin de cambiar los permisos en tu instancia de VM de Compute Engine, consulta Crea y habilita cuentas de servicio para instancias.

¿Qué sigue?