En esta página, se explica cómo instalar y configurar la herramienta de línea de comandos de kubectl
para interactuar con tus clústeres de Google Kubernetes Engine (GKE).
Descripción general
kubectl
es una herramienta de línea de comandos que puedes usar para interactuar con tus clústeres de GKE. Si deseas usar kubectl
con GKE, debes instalar la herramienta y configurarla para que se comunique con tus clústeres. Se requiere una configuración de kubectl
adicional si ejecutas varios clústeres en Google Cloud.
En esta página, se muestra lo siguiente:
- Cómo funciona
kubectl
. - Cómo instalar
kubectl
y cualquier dependencia necesaria: - Cómo configurar un clúster predeterminado para
kubectl
- Cómo ejecutar comandos de
kubectl
en un clúster específico.
Antes de comenzar
Antes de comenzar, asegúrate de haber realizado las siguientes tareas:
- Habilita la API de Google Kubernetes Engine. Habilitar la API de Google Kubernetes Engine
- Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, initialize gcloud CLI. Si ya instalaste gcloud CLI, ejecuta
gcloud components update
para obtener la versión más reciente.
Instale kubectl
Puedes instalar kubectl
mediante la CLI de Google Cloud o un administrador de paquetes externo, como apt
o yum
.
gcloud
Instala el componente
kubectl
:gcloud components install kubectl
Verifica que
kubectl
esté instalado; para ello, comprueba que tenga la versión más reciente:kubectl version --client
apt
Verifica que tienes el repositorio
cloud-sdk
:grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
El resultado es similar al siguiente:
deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main
Si el repositorio
cloud-sdk
no aparece en la lista, instala gcloud CLI.Instala el componente
kubectl
:apt-get update apt-get install -y kubectl
Verifica que
kubectl
esté instalado; para ello, comprueba que tenga la versión más reciente:kubectl version --client
yum
Verifica que tienes el repositorio
cloud-sdk
:yum repolist | grep "google-cloud-sdk"
El resultado es similar a este:
google-cloud-sdk Google Cloud SDK 2,205
Instala el componente
kubectl
:yum install -y kubectl
Verifica que
kubectl
esté instalado; para ello, comprueba que tenga la versión más reciente:kubectl version --client
Instala los complementos obligatorios
kubectl
y otros clientes de Kubernetes requieren un complemento de autenticación, gke-gcloud-auth-plugin
, que usa el framework Complementos de credenciales Client-go para proporcionar tokens de autenticación a fin de comunicarse con los clústeres de GKE.
Antes de que se lance la versión 1.26 de Kubernetes, la CLI de gcloud comenzará a requerir que se instale el objeto binario gke-gcloud-auth-plugin
. Si no está instalado, las instalaciones existentes de kubectl
o de otros clientes personalizados de Kubernetes dejarán de funcionar.
Debes instalar este complemento para usar kubectl
y otros clientes a fin de interactuar con GKE.
Los clientes existentes muestran un mensaje de error si el complemento no está instalado.
Antes de comenzar, verifica si el complemento ya está instalado:
gke-gcloud-auth-plugin --version
Si el resultado muestra información de la versión, omite esta sección.
Puedes instalar el complemento de autenticación con la CLI de gcloud o un administrador de paquetes externo como apt
o yum
.
gcloud
Instala el objeto binario gke-gcloud-auth-plugin
:
gcloud components install gke-gcloud-auth-plugin
apt
Instala el objeto binario gke-gcloud-auth-plugin
:
apt-get install google-cloud-sdk-gke-gcloud-auth-plugin
yum
Instala el objeto binario gke-gcloud-auth-plugin
:
yum install google-cloud-sdk-gke-gcloud-auth-plugin
Verifica la instalación del objeto binario gke-gcloud-auth-plugin
:
Verifica la versión del objeto binario
gke-gcloud-auth-plugin
:gke-gcloud-auth-plugin --version
Actualiza la configuración
kubectl
para usar el complemento:gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Reemplaza lo siguiente:
CLUSTER_NAME
: El nombre de tu clúster.COMPUTE_REGION
: La región de Compute Engine del clúster. Para los clústeres zonales, usa--zone=COMPUTE_ZONE
.
Verifica la configuración:
kubectl get namespaces
El resultado es similar a este:
NAME STATUS AGE default Active 51d kube-node-lease Active 51d kube-public Active 51d kube-system Active 51d
Para obtener más información sobre por qué este complemento es obligatorio, consulta Kubernetes KEP.
Interactúa con kubectl
Kubernetes usa un archivo YAML llamado kubeconfig
para almacenar información de autenticación de clúster para kubectl
. De forma predeterminada, el archivo se guarda en $HOME/.kube/config
.
kubeconfig
contiene un grupo de parámetros de acceso llamado contextos. Cada contexto contiene un clúster de Kubernetes, un usuario y un espacio de nombres predeterminado opcional. kubectl
se refiere a los contextos cuando se ejecutan comandos.
Las siguientes son tareas que puedes completar para configurar kubectl
:
- Elige con qué clúster se comunicará
kubectl
. - Configura un clúster predeterminado para
kubectl
; para ello, establece el contexto actual en el archivokubeconfig
. - Ejecuta los comandos
kubectl
en un clúster específico con la marca--cluster
.
Ver 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 almacenar la información del clúster para kubectl.
Ver el contexto actual de kubectl
El contexto actual es el clúster predeterminado de kubectl
: todos los comandos kubectl
se ejecutan en ese clúster.
Cuando creas un clúster con gcloud container clusters create-auto
, una entrada se agrega de manera automática al archivo kubeconfig
en tu entorno y el contexto actual cambia a ese clúster: Por ejemplo:
gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster
Para ver el contexto actual de kubectl
, ejecuta el siguiente comando:
kubectl config current-context
Almacena información del clúster para kubectl
Cuando creas un clúster con la consola de Google Cloud o la CLI de gcloud desde una computadora diferente, el archivo kubeconfig
de tu entorno no se actualiza.
Además, si un miembro del equipo del proyecto usa CLI de gcloud para crear un clúster desde su computadora, su kubeconfig
se actualiza, pero el tuyo no. 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.
Para generar un contexto kubeconfig
en tu entorno, asegúrate de tener el permiso container.clusters.get
. El rol de IAM con privilegios mínimos que proporciona este permiso es container.clusterViewer
.
A fin de generar un contexto kubeconfig
para un clúster específico, ejecuta el siguiente comando:
gcloud container clusters get-credentials CLUSTER_NAME \
--region=CLUSTER_REGION
Reemplaza lo siguiente:
CLUSTER_NAME
: El nombre de tu clúster.COMPUTE_REGION
: La región de Compute Engine del clúster. Para los clústeres zonales, usa--zone=COMPUTE_ZONE
.
Genera una entrada kubeconfig
con la dirección IP interna de un clúster privado
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.
Los clústeres privados tienen dos direcciones IP independientes del extremo: privateEndpoint
, que es una dirección IP interna, y publicEndpoint
, que es una dirección IP externa.
El campo endpoint
hace referencia a la dirección IP externa, a menos que el acceso público al extremo esté inhabilitado, en cuyo caso se usará la dirección IP privada.
Para los clústeres privados, si prefieres usar la IP interna como extremo, ejecuta el siguiente comando:
gcloud container clusters get-credentials CLUSTER_NAME --internal-ip
Reemplaza CLUSTER_NAME
por el nombre del clúster.
Si ejecutas get-credentials
, se usa la dirección IP especificada en el campo endpoint
de forma predeterminada.
Configura un clúster predeterminado para los comandos de kubectl
Si ya generaste una entrada de 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 CLUSTER_NAME \
--region=COMPUTE_REGION
Reemplaza lo siguiente:
CLUSTER_NAME
: El nombre de tu clúster.COMPUTE_REGION
: La región de Compute Engine del clúster. Para los clústeres zonales, usa--zone=COMPUTE_ZONE
.
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
, ejecuta el siguiente comando:
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
Ejecuta comandos de kubectl
individuales en un clúster específico
Puedes ejecutar comandos kubectl
individuales en un clúster específico con --cluster=CLUSTER_NAME
.
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 us-docker.pkg.dev/my-project/my-repo/my-app:1.0 --cluster my-new-cluster
Soluciona problemas
Para obtener información adicional sobre cómo solucionar problemas, consulta Solución de problemas habituales.
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.
ERROR: No se encontró el gke-gcloud-auth-plugin ejecutable
Si se recibe el siguiente error mientras intentas ejecutar kubectl
o clientes personalizados que interactúan con GKE, instala gke-gcloud-auth-plugin
como se describe en Instrucciones de instalación.
Los mensajes de error son similares a los siguientes:
- Muestra de error
Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found
It looks like you are trying to use a client-go credential plugin that is not installed.
To learn more about this feature, consult the documentation available at:
https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.
- Muestra de error
Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory
ERROR: pánico: no se encontró ningún proveedor de autenticación para el nombre gcp.
El error no Auth Provider found for name "gcp"
se recibe si kubectl
o los clientes personalizados de Kubernetes se compilaron con la versión 1.26 o posterior de Kubernetes client-go
, como se describe en Cómo funciona. Para resolverlo, sigue estos pasos:
Instala
gke-gcloud-auth-plugin
como se describe en las instrucciones de instalación.Actualiza a la versión más reciente de la CLI de gcloud mediante
gcloud components update
.Actualiza el archivo
kubeconfig
:gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Reemplaza lo siguiente:
CLUSTER_NAME
: El nombre de tu clúster.COMPUTE_REGION
: La región de Compute Engine del clúster. Para los clústeres zonales, usa--zone=COMPUTE_ZONE
.
ADVERTENCIA: El complemento de autenticación gcp está obsoleto; usa gcloud en su lugar
Es posible que veas este mensaje de advertencia después de instalar el gke-gcloud-auth-plugin
y ejecutar un comando kubectl
en un clúster de GKE. Este mensaje aparece si tu versión del cliente es anterior a 1.26.
Para indicarle al cliente que use el complemento de autenticación gke-gcloud-auth-plugin
, haz lo siguiente:
Abre tu secuencia de comandos de acceso de shell en un editor de texto:
Bash
vi ~/.bashrc
Zsh
vi ~/.zshrc
Si usas PowerShell, omite este paso.
Configura la siguiente variable del entorno:
Bash
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
Zsh
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
PowerShell
[Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
Aplica la variable en tu entorno:
Bash
source ~/.bashrc
Zsh
source ~/.zshrc
PowerShell
Sal de la terminal y abre una nueva sesión de la terminal.
Actualiza la CLI de gcloud:
gcloud components update
Autentícate en el clúster:
gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
Reemplaza lo siguiente:
CLUSTER_NAME
: El nombre de tu clúster.COMPUTE_REGION
: La región de Compute Engine del clúster. Para los clústeres zonales, usa--zone=COMPUTE_ZONE
.
¿Qué sigue?
- Aprende a autorizar el acceso a los recursos en clústeres de GKE.
- Valida en servicios de Google Cloud desde cargas de trabajo de GKE.
- Lee la hoja de referencia de
kubectl
.
Pruébalo tú mismo
Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de GKE en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
Probar GKE gratis