Autentica en el servidor de la API de Kubernetes

En esta página, se describen los métodos de autenticación compatibles cuando se establece una conexión al servidor de la API de Kubernetes en Google Kubernetes Engine (GKE).

Para obtener información sobre la autenticación de cargas de trabajo de Kubernetes a las API de Google Cloud, consulta Workload Identity.

Descripción general

Existen varios métodos para autenticarse en un servidor de API de Kubernetes. En GKE, se recomienda la autenticación OAuth para la autenticación del clúster, que se configura de forma automática para ti.

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

Cómo autenticar usuarios

GKE administra la autenticación de usuario final por ti a través de la herramienta de línea de comandos de gcloud. La herramienta de gcloud autentica a los usuarios en Google Cloud, establece la configuración de Kubernetes, obtiene un token de acceso de OAuth para el clúster y lo mantiene actualizado. Puedes controlar el acceso a tu clúster mediante la administración de identidades y accesos (IAM) o el control de acceso basado en funciones (RBAC) de Kubernetes.

Antes de la integración de GKE mediante OAuth, el certificado x509 aprovisionado previamente o la contraseña estática eran los únicos métodos de autenticación disponibles, pero ya no son las opciones recomendadas y están inhabilitados de forma predeterminada en los clústeres nuevos desde la versión de GKE 1.12 y posteriores. Si usas métodos de autenticación heredados, te recomendamos que desactives estos métodos.

Autentica mediante OAuth

Para autenticarte en tu clúster mediante el método OAuth, realiza lo siguiente:

  1. Accede a la herramienta de gcloud con tus credenciales. Se abrirá un navegador web para completar el proceso de autenticación en Google Cloud:

    gcloud auth login
    
  2. Recupera las credenciales de Kubernetes para un clúster específico:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --zone=COMPUTE_ZONE
    
  3. Ahora estás autenticado. Verifica los resultados mediante el siguiente comando kubectl:

    kubectl cluster-info
    

Autentica servicios

A veces, es posible que debas autenticarte en el servidor de la API de un clúster de GKE desde un servicio sin interacción del usuario (por ejemplo, una secuencia de comandos de canalización de CI/CD). La forma de lograrlo depende del entorno en el que se ejecuta el servicio.

Servicio dentro del mismo clúster de GKE

Si tu servicio se ejecuta en un pod dentro del clúster de GKE al que deseas conectarte, usa una cuenta de servicio de Kubernetes para autenticarte.

  1. Crea una cuenta de servicio de Kubernetes y adjúntala a tu pod. Si tu pod ya tiene una cuenta de servicio de Kubernetes, puedes omitir este paso.

    En nuestro ejemplo, usamos una cuenta de servicio de Kubernetes con el nombre cicd en el espacio de nombres cicd-ns.

  2. Otorga los permisos correctos a la cuenta de servicio de Kubernetes mediante el RBAC de Kubernetes.

    En nuestro ejemplo, otorgamos la función edit en un espacio de nombres prod; sin embargo, en la práctica, debes otorgar una función que se adapte a sus necesidades.

    kubectl create rolebinding cicd \
        --clusterrole=edit \
        --serviceaccount=cicd-ns:cicd \
        --namespace=prod
    
  3. En el entorno de ejecución, cuando tu servicio invoque a kubectl, recibirá las credenciales que configuraste de forma automática.

Servicio dentro de Google Cloud

Si tu servicio se ejecuta dentro de Google Cloud (por ejemplo, una VM de Compute Engine o algún otro clúster de GKE), debes autenticarte en el servidor de la API con las credenciales de la cuenta de servicio de Google disponibles en el entorno.

  1. Asigna una cuenta de servicio de Google a tu entorno de Compute Engine. Si tu servicio se ejecuta dentro de una VM de Compute Engine, asigna una cuenta de servicio de Google a la instancia. Si tu servicio se ejecuta dentro de un clúster de GKE, usa Workload Identity para configurar tu pod a fin de que se ejecute como una cuenta de servicio de Google.

    En nuestro ejemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como la cuenta de servicio de Google.

  2. Otorga a la cuenta de servicio de Google acceso al clúster deseado.

    En el ejemplo, otorgamos la función roles/container.developer de IAM, que proporciona acceso a los objetos de la API de Kubernetes dentro de los clústeres:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
        --role=roles/container.developer
    
  3. Recupera las credenciales del clúster:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --zone=COMPUTE_ZONE
    

    Tu servicio se autenticará de forma automática con la cuenta de servicio de Google configurada en el entorno.

Servicio en otros entornos

Si tu servicio se autentica desde un entorno fuera de Google Cloud, no tendrá acceso a las credenciales de la cuenta de servicio de Google administrada. A fin de recuperar las credenciales del clúster, deberás crear una cuenta de servicio de Google, descargar su clave y usarla en el entorno de ejecución para recuperar las credenciales del clúster con la herramienta de gcloud.

  1. Crea una cuenta de servicio de Google para tu servicio. Si ya tienes una, puedes omitir este paso.

    En nuestro ejemplo, creamos una cuenta de servicio con el nombre ci-cd-pipeline:

    gcloud iam service-accounts create ci-cd-pipeline
    
  2. Otorga a la cuenta de servicio de Google acceso a tu clúster.

    En el ejemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como la cuenta de servicio de Google y otorgamos la función roles/container.developer de IAM, que proporciona acceso a los objetos de la API de Kubernetes dentro de los clústeres:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
        --role=roles/container.developer
    

    Otorgamos acceso mediante IAM. También puedes otorgar este acceso mediante el RBAC de Kubernetes para obtener un control más detallado.

  3. Crea y descarga una clave para tu cuenta de servicio de Google. Haz que esté disponible para tu servicio en el entorno de ejecución:

    gcloud iam service-accounts keys create gsa-key.json \
        --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
    
  4. En el entorno de ejecución en el que se ejecuta tu servicio, autentícate en la herramienta de gcloud con la clave de tu cuenta de servicio de Google:

    gcloud auth activate-service-account ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
        --key-file=gsa-key.json
    

    Esta acción requiere que se instale la herramienta de gcloud en tu entorno. Para obtener información sobre cómo instalar la herramienta de gcloud, consulta Instala el SDK de Cloud. Si no puedes instalar la herramienta de gcloud en tu entorno, consulta la sección Entornos sin gcloud.

  5. Usa la herramienta de gcloud para recuperar las credenciales del clúster:

    gcloud config set project PROJECT_ID
    gcloud container clusters get-credentials CLUSTER_NAME \
        --zone=COMPUTE_ZONE
    

Entornos sin gcloud

Se recomienda usar la herramienta gcloud para recuperar credenciales de clúster, ya que este método es resistente a los eventos de clúster, como la Rotación de IP o la rotación de credenciales de un plano de control. Sin embargo, si no puedes instalar la herramienta de gcloud en tu entorno, puedes crear un archivo kubeconfig estático para autenticarte en el clúster:

  1. Crea una cuenta de servicio de Google para tu servicio. Si ya tienes una, puedes omitir este paso.

    En nuestro ejemplo, creamos una cuenta de servicio con el nombre ci-cd-pipeline:

    gcloud iam service-accounts create ci-cd-pipeline
    
  2. Otorga a la cuenta de servicio de Google acceso a tu clúster.

    En el ejemplo, usamos ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como la cuenta de servicio de Google y otorgamos la función roles/container.developer de IAM, que proporciona acceso a los objetos de la API de Kubernetes dentro de los clústeres:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
        --role=roles/container.developer
    

    Otorgamos acceso mediante IAM. También puedes otorgar este acceso mediante el RBAC de Kubernetes para obtener un control más detallado.

  3. Crea y descarga una clave para tu cuenta de servicio de Google.

    En nuestro ejemplo, el archivo de claves tiene el nombre gsa-key.json:

    gcloud iam service-accounts keys create gsa-key.json \
        --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
    
  4. Obtén los valores endpoint y clusterCaCertificate para tu clúster:

    gcloud container clusters describe CLUSTER_NAME \
        --zone=COMPUTE_ZONE \
         --format="value(endpoint)"
    
    gcloud container clusters describe CLUSTER_NAME \
        --zone=COMPUTE_ZONE \
        --format="value(masterAuth.clusterCaCertificate)"
    
  5. Crea un archivo kubeconfig.yaml que contenga lo siguiente:

    apiVersion: v1
    kind: Config
    clusters:
    - name: CLUSTER_NAME
      cluster:
        server: https://endpoint
        certificate-authority-data: masterAuth.clusterCaCertificate
    users:
    - name: ci-cd-pipeline-gsa
      user:
        auth-provider:
          name: gcp
    contexts:
    - context:
        cluster: CLUSTER_NAME
        user: ci-cd-pipeline-gsa
      name: CLUSTER_NAME-ci-cd
    current-context: CLUSTER_NAME-ci-cd
    

    Reemplaza lo siguiente:

    • CLUSTER_NAME: El nombre de tu clúster.
    • endpoint: El valor que obtuviste para endpoint del paso anterior.
    • masterAuth.clusterCaCertificate: El valor que obtuviste para clusterCaCertificate del paso anterior (no necesitas decodificar el certificado codificado en base64).
  6. Implementa kubeconfig.yaml y gsa-key.json junto con tu servicio en el entorno. En el entorno de ejecución en el que se ejecuta tu servicio, configura estas variables de entorno:

    export KUBECONFIG=path/to/kubeconfig.yaml
    export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
    
  7. Tu servicio ahora puede invocar a kubectl y se autenticará como la cuenta de servicio de Google.

Métodos de autenticación heredados

Antes de la integración de GKE en OAuth, los únicos métodos de autenticación disponibles eran un certificado x509 generado una sola vez o una contraseña estática, pero ya no se recomiendan y deben inhabilitarse. Estos métodos presentan una superficie de ataque más amplia para el compromiso del clúster y se inhabilitaron de forma predeterminada desde la versión 1.12 de GKE. Si estás usando métodos de autenticación heredados, te recomendamos que los desactives. La autenticación con una contraseña estática es obsoleta y se quitó a partir de la versión 1.19 de GKE.

Si los habilitas, el usuario puede recuperar el certificado de cliente y la contraseña estática con el permiso container.clusters.getCredentials. Ten en cuenta que las funciones roles/container.admin, roles/owner y roles/editor tienen este permiso, por lo que se recomienda usarlas con cuidado. Obtén más información sobre las funciones de IAM en GKE.

Inhabilita la autenticación con una contraseña estática

Una contraseña estática es una combinación de nombre de usuario y contraseña que el servidor de la API valida. En GKE, este método de autenticación se conoce como autenticación básica.

Para actualizar un clúster existente y quitar la contraseña estática, ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME --no-enable-basic-auth

Inhabilita la autenticación con un certificado de cliente

Con la autenticación del certificado, un cliente presenta un certificado que el servidor de API verifica con la autoridad certificada especificada. En GKE, la autoridad certificada (CA) raíz del clúster firma los certificados de cliente.

La autenticación del certificado de cliente tiene implicaciones en la autorización para el servidor de la API de Kubernetes. Si la autorización heredada del Control de acceso basado en atributos (ABAC) está habilitada en el clúster, de forma predeterminada, los certificados de cliente pueden autenticarse y realizar cualquier acción en el servidor de la API. Por otro lado, con el control de acceso basado en funciones (RBAC), habilitado, los certificados de cliente deben tener autorización específica para los recursos de Kubernetes.

Para crear un clúster sin generar un certificado de cliente, usa la marca --no-issue-client-certificate:

gcloud container clusters create CLUSTER_NAME --no-issue-client-certificate

Por el momento, no hay manera de quitar un certificado de cliente de un clúster existente. Para dejar de usar la autenticación del certificado de cliente en un clúster existente, asegúrate de tener el RBAC habilitado en el clúster y de que el certificado de cliente no tenga ninguna autorización en el clúster.

¿Qué sigue?