Instala kubectl y configura el acceso al clúster

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:

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

  1. Instala el componente kubectl:

    gcloud components install kubectl

  2. Verifica que kubectl esté instalado; para ello, comprueba que tenga la versión más reciente:

    kubectl version --client

apt

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

  2. Si el repositorio cloud-sdk no aparece en la lista, instala gcloud CLI.

  3. Instala el componente kubectl:

    apt-get update
apt-get install -y kubectl

  4. Verifica que kubectl esté instalado; para ello, comprueba que tenga la versión más reciente:

    kubectl version --client

yum

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

  2. Instala el componente kubectl:

    yum install -y kubectl

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

  1. Verifica la versión del objeto binario gke-gcloud-auth-plugin:

    gke-gcloud-auth-plugin --version

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

  3. 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 archivo kubeconfig.
  • 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:

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:

  1. Instala gke-gcloud-auth-plugin como se describe en las instrucciones de instalación.

  2. Actualiza a la versión más reciente de la CLI de gcloud mediante gcloud components update.

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

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

  2. 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')

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

  4. Actualiza la CLI de gcloud:

    gcloud components update

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

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