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 clústeres de Google Kubernetes Engine (GKE).

Para obtener información sobre la autenticación de cargas de trabajo de Kubernetes a las APIs 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:

  • Habilita la API de Kubernetes Engine.
  • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.

Cómo autenticar usuarios

GKE administra la autenticación de usuario final por ti a través de Google Cloud CLI. La CLI 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.

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.

Puedes autorizar acciones en tu clúster con la administración de identidades y accesos (IAM) o el control de acceso basado en roles (RBAC) de Kubernetes.

Autentica mediante OAuth

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

  1. Accede a la CLI 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. Verifica que estés autenticado:

    kubectl cluster-info
    

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. Para obtener más información sobre cómo configurar la autorización, consulta el control de acceso según la función.

Autenticar aplicaciones

También puedes autenticarte en el servidor de la API desde una aplicación en un pod sin interacción del usuario, como una secuencia de comandos en la canalización de CI/CD. La forma de lograrlo depende del entorno en el que se ejecuta la aplicación.

Aplicación en el mismo clúster

Si tu aplicación se ejecuta en el mismo clúster de GKE, 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 o si deseas usar la cuenta de servicio predeterminada del espacio de nombres, omite este paso.

  2. Usa el RBAC de Kubernetes para otorgar a la cuenta de servicio de Kubernetes los permisos que requiere tu aplicación.

    En el siguiente ejemplo, se otorgan permisos view a los recursos en el espacio de nombres prod a una cuenta de servicio llamada cicd en el espacio de nombres cicd-ns:

    kubectl create rolebinding cicd-secret-viewer \
        --namespace=prod \
        --clusterrole=view \
        --serviceaccount=cicd-ns:cicd
    
  3. En el entorno de ejecución, cuando tu aplicación envía una solicitud a la API de Kubernetes, el servidor de la API autentica las credenciales de la cuenta de servicio.

Aplicaciones dentro de Google Cloud

Si tu aplicación se ejecuta dentro de Google Cloud, pero fuera del clúster de destino (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 IAM disponibles en el entorno.

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

    En los siguientes ejemplos, se usa ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com como la cuenta de servicio de IAM.

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

    En el siguiente ejemplo, se otorga el rol de IAM roles/container.developer, 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
    

    Como alternativa, puedes usar el RBAC para otorgar a la cuenta de servicio de IAM acceso al clúster. Ejecuta el comando kubectl create rolebinding desde las aplicaciones en el mismo clúster y usa --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com en lugar de la marca --service-account.

  3. Recupera las credenciales del clúster:

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

    Tu aplicación se autentica de forma automática mediante la cuenta de servicio de IAM configurada en el entorno.

Aplicaciones en otros entornos

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

  1. Crea una cuenta de servicio de IAM para tu aplicación. Si ya tienes una, omite este paso.

    El siguiente comando crea una cuenta de servicio de IAM llamada ci-cd-pipeline:

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

    El siguiente comando otorga el rol de IAM roles/container.developer a la cuenta de servicio de IAM ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com:

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

    También puedes usar el RBAC para otorgar acceso al clúster a la cuenta de servicio de IAM. Ejecuta el comando kubectl create rolebinding desde Aplicaciones en el mismo clúster y usa --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com en lugar de la marca --service-account.

  3. Crea y descarga una clave para tu cuenta de servicio de IAM. Haz que esté disponible para tu aplicación 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 CLI 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
    
  5. Usa la CLI 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 CLI de 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 CLI 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 IAM para tu aplicación. Si ya tienes una, omite este paso.

    El siguiente comando crea una cuenta de servicio de IAM llamada ci-cd-pipeline:

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

    El siguiente comando otorga el rol de IAM roles/container.developer a la cuenta de servicio de IAM ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com:

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

    También puedes crear un rol de IAM personalizada para obtener un control detallado sobre los permisos que otorgas.

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

    En el siguiente ejemplo, el archivo de claves se llama 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:
        exec:
          apiVersion: client.authentication.k8s.io/v1beta1
          args:
          - --use_application_default_credentials
          command: gke-gcloud-auth-plugin
          installHint: Install gke-gcloud-auth-plugin for kubectl by following
            https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin
          provideClusterInfo: true
    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 aplicación, configura estas variables de entorno:

    export KUBECONFIG=path/to/kubeconfig.yaml
    export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
    
  7. Ahora tu aplicación puede enviar solicitudes a la API de Kubernetes y se autenticará como la cuenta de servicio de IAM.

Métodos de autenticación heredados

Antes de la integración de OAuth con GKE, el certificado X.509 aprovisionado previamente o una contraseña estática eran los únicos métodos de autenticación disponibles, 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 están inhabilitados de forma predeterminada en los clústeres que ejecutan la versión 1.12 de GKE y versiones posteriores. Si usas métodos de autenticación heredados, te recomendamos que los desactives.

Si está habilitado, un usuario con el permiso container.clusters.getCredentials puede recuperar el certificado de cliente y la contraseña estática. 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 certificadora especificada. En GKE, la autoridad certificadora (CA) raíz del clúster firma 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?