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:
- Asegúrate de que habilitaste la API de Google Kubernetes Engine. Habilitar la API de Google Kubernetes Engine
- Asegúrate de que instalaste el SDK de Cloud.
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.
-
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
- Sigue las instrucciones a fin de autorizar a
gcloud
para que use tu cuenta de Google Cloud. - Crea una configuración nueva o selecciona una existente.
- Elige un proyecto de Google Cloud.
- 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:
- Tus credenciales, como se muestra en
gcloud auth list
- Las credenciales predeterminadas de la aplicación, si están configuradas
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?
- Aprende a autorizar el acceso a los recursos en clústeres de GKE.
- Obtén información sobre cómo autenticarte en los servicios de Google Cloud desde cargas de trabajo de Kubernetes con cuentas de servicio de Google Cloud.
- Lee la hoja de referencia de
kubectl
.