Administrar cuentas de servicio

Una identidad de servicio en Google Distributed Cloud (GDC) aislado proporciona una identidad dedicada para que las cargas de trabajo o los servicios accedan de forma programática a los recursos y microservicios de manera segura. Son identidades especiales que usan las aplicaciones o las cargas de trabajo, en lugar de una persona, y no se pueden usar para el acceso humano. Al igual que con las cuentas de usuario, otorgas permisos y roles a una identidad de servicio para definir a qué tiene autorización para acceder.

Es posible que observes que se usan dos términos para este concepto. La consola de GDC usa principalmente el término identidad de servicio, mientras que los comandos de gdcloud y las interacciones con la API suelen usar el término cuenta de servicio. Este último refleja el nombre del recurso personalizado subyacente de Kubernetes, ProjectServiceAccount. Ambos términos se refieren a lo mismo: la identidad no humana para tus cargas de trabajo. En este documento, se usa la identidad del servicio como el término principal.

Las identidades de servicio son útiles para administrar la infraestructura de GDC, por ejemplo, para lo siguiente:

Servicios y cargas de trabajo internos de Distributed Cloud para acceder de forma segura a la interfaz de programación de aplicaciones (API) del plano de control de Distributed Cloud. Por ejemplo, los servicios de bases de datos interactúan con las APIs de Kubernetes para crear y borrar bases de datos.
Cargas de trabajo del cliente en Distributed Cloud para acceder a los servicios de Distributed Cloud y realizar llamadas autorizadas a la interfaz de programación de aplicaciones (API). Por ejemplo, las identidades de servicio pueden administrar a un cliente que usa un notebook de Vertex AI Workbench para transcribir archivos de audio con la API de Speech-to-Text.
Cargas de trabajo externas para federar con Distributed Cloud. Por ejemplo, las identidades de servicio pueden administrar una aplicación externa a Distributed Cloud que digitaliza documentos, pero quiere usar la API de reconocimiento óptico de caracteres (OCR) para reemplazar su motor de OCR actual.
Controladores del sistema o servicios de Distributed Cloud para acceder de forma segura a los recursos del cliente o a los clústeres de usuarios Por ejemplo, las identidades de servicio pueden administrar flujos de trabajo de autenticación y autorización en los que los controladores de servicio que se ejecutan en clústeres de administrador deben ejecutar cargas de trabajo dentro de los clústeres de usuario que administran los clientes.

Puedes administrar las cuentas de las identidades de servicio con la consola de GDC, la CLI de gdcloud o la API. Con la CLI de gcloud, la función de identidad de servicio se basa en la API de ProjectServiceAccount global. Dado que los recursos ProjectServiceAccount se configuran de forma global, operan en todas las zonas de tu universo de gdcloud.

Antes de comenzar

Solo puedes crear una identidad de servicio dentro de un proyecto. Para obtener información sobre cómo crear un proyecto, consulta Crea un proyecto.

La administración de identidades de servicio involucra tanto la identidad de servicio (representada por un recurso ProjectServiceAccount) como sus credenciales asociadas (pares de claves públicas y privadas). Para obtener los permisos que necesitas para administrar las identidades de servicio y sus credenciales, pídele al administrador de IAM de la organización o al administrador de IAM del proyecto que te otorgue el rol de administrador de IAM del proyecto (project-iam-admin) en ese proyecto.

Crea una identidad de servicio

La creación de una identidad de servicio incluye la creación de una cuenta y sus credenciales asociadas.

Crear una cuenta

Para crear una cuenta para una identidad de servicio, usa la consola de GDC, la CLI de gdcloud o la API para crear un recurso ProjectServiceAccount en un proyecto.

Console

Accede a la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haz clic en Crear identidad de servicio. Se abrirá la página Detalles de identidad del servicio.
En el campo Nombre de la identidad del servicio, ingresa un nombre para la identidad del servicio. Por ejemplo: testserviceidentity.
Haz clic en Crear.

gdcloud

Crea una cuenta:

gdcloud iam service-accounts create NAME \
    --project=PROJECT

Reemplaza los siguientes valores:

NAME: Es el nombre del ProjectServiceAccount. El nombre debe ser único dentro del espacio de nombres del proyecto.
PROJECT: Es el proyecto en el que se creará la identidad del servicio. Si gdcloud init ya está configurado, omite la marca --project.

Este comando crea un ProjectServiceAccount en el espacio de nombres del proyecto en el servidor de la API de Management.

API

Crea un archivo YAML de recurso personalizado ProjectServiceAccount, como my-project-sa.yaml:
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
Reemplaza las siguientes variables:
- NAME: Es el nombre del recurso ProjectServiceAccount. El nombre debe ser único dentro del espacio de nombres del proyecto.
- PROJECT: Es el proyecto en el que se creará la identidad del servicio.
- ALGORITHM: Es el algoritmo de la clave. Solo se admiten claves ES256.
- KEY_ID: Es el identificador único de la clave. El ID se usa para determinar con qué clave se realizará la verificación.
- BASE64_ENCODED_KEY: Es la clave pública codificada en Base64 en formato PEM con la que se realizará la verificación. Se espera que la clave privada que se usa para generar esta clave pública esté en formato PEM de ECDSA P256.
- START_TIME: Es la hora de inicio en la que la clave se vuelve válida, como 2025-02-07T00:59:34Z.
- EXPIRATION_TIME: Es la hora de vencimiento de la clave, como 2026-02-07T00:59:34Z.
Aplica el recurso personalizado ProjectServiceAccount al servidor de la API global:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
Reemplaza la variable GLOBAL_API_SERVER_KUBECONFIG por la ruta de acceso al archivo kubeconfig del servidor de la API global.

Crear credenciales

Para permitir que una carga de trabajo o aplicación se autentique como la identidad del servicio (representada por la cuenta que creaste), debes generar credenciales. La creación de credenciales implica generar un par de claves criptográficas privadas y públicas, y asociar la clave pública con la identidad del servicio.

Para crear credenciales para una identidad de servicio, usa la consola de GDC, la CLI de gdcloud o la API.

Console

Accede a la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haz clic en el nombre de la identidad de servicio que deseas agregar a la clave.
Haz clic en Crear clave nueva.
La nueva clave aparecerá en la lista Claves y un diálogo confirmará que creaste la clave correctamente.

gdcloud

El comando gdcloud crea un archivo JSON de credenciales predeterminadas de la aplicación y un par de claves públicas y privadas:

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Reemplaza los siguientes valores:

APPLICATION_DEFAULT_CREDENTIALS_FILENAME: Es el nombre del archivo JSON.
PROJECT : Selecciona el proyecto para el que se creará la clave. Si gdcloud init ya está configurado, puedes omitir la marca --project.
NAME: Es el nombre de la identidad del servicio para la que se agregará la clave.
CA_CERTIFICATE_PATH: Opcional: Es la ruta de acceso al certificado de la autoridad certificadora (CA) para verificar el extremo de autenticación. Si no especificas esta ruta de acceso, se usarán los certificados de CA del sistema. Debes instalar la CA en los certificados de CA del sistema.

Distributed Cloud agrega la clave pública a las claves ProjectServiceAccount que usas para verificar los tokens web JSON (JWT) que firma la clave privada. La clave privada se escribe en el archivo JSON de las credenciales predeterminadas de la aplicación.

En el siguiente ejemplo, se muestra el archivo JSON de las credenciales predeterminadas de la aplicación:

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

En este ejemplo, se usan los siguientes valores:

project: Es el espacio de nombres del proyecto en la organización.
private_key_id: Es el ID asignado a la clave.
private_key: Es la clave privada de ECDSA P256 en formato PEM que genera la CLI.
name: Es el nombre de la identidad del servicio.
ca_cert_path: Es la ruta de acceso al certificado de la autoridad certificadora (CA) que se usa para verificar el extremo de autenticación.
token_uri: Es la dirección del extremo de autenticación.

API

Genera el par de claves pública y privada. En los siguientes comandos, se usa openssl como ejemplo, que es una herramienta común para este propósito.
```
openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
openssl ec -in "key.pem" -pubout > "pub.pem"
```

Codifica la clave pública en base64 y recupera su ID de clave:

KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
BASE64_ENCODED_KEY=$(cat pub.pem | base64)

Crea o actualiza el archivo YAML del recurso personalizado ProjectServiceAccount, incluida la información de la clave generada en el paso anterior:
```
apiVersion: resourcemanager.global.gdc.goog/v1
kind: ProjectServiceAccount
metadata:
  name: NAME
  namespace: PROJECT
spec:
  keys:
  - algorithm: ALGORITHM
  id: KEY_ID
  key: BASE64_ENCODED_KEY
  validAfter: "START_TIME"
  validBefore: "EXPIRATION_TIME"
```
Reemplaza las siguientes variables:
- NAME: Es el nombre del recurso ProjectServiceAccount. El nombre debe ser único dentro del espacio de nombres del proyecto.
- PROJECT: Es el proyecto en el que creas la clave.
- ALGORITHM: Es el algoritmo de la clave. Solo se admiten claves ES256.
- KEY_ID: Es el identificador único de la clave. El ID se usa para determinar con qué clave se realizará la verificación.
- BASE64_ENCODED_KEY: Es la clave pública codificada en Base64 en formato PEM con la que se realizará la verificación. Se espera que la clave privada que se usa para generar esta clave pública esté en formato PEM de ECDSA P256.
- START_TIME: Es la hora de inicio en la que la clave se vuelve válida, como 2025-02-07T00:59:34Z.
- EXPIRATION_TIME: Es la hora de vencimiento de la clave, como 2026-02-07T00:59:34Z.
Aplica el recurso personalizado ProjectServiceAccount al servidor de la API global:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
Reemplaza la variable GLOBAL_API_SERVER_KUBECONFIG por la ruta de acceso al archivo kubeconfig del servidor de la API global.
Crea el archivo JSON de credenciales predeterminadas de la aplicación que contiene la clave privada. Asegúrate de que la variable KEY_ID del archivo JSON esté configurada con el mismo valor que la variable KEY_ID que usaste en la especificación de ProjectServiceAccount.
```
cat <<EOF > "key_file.json"
{
  "format_version": "1",
  "name": "NAME",
  "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
  "private_key_id": "KEY_ID",
  "project": "PROJECT",
  "token_uri": "AUTH_URL",
  "type": "gdch_service_account"
}
EOF
```
Reemplaza las siguientes variables:
- NAME: Es el nombre de la identidad del servicio.
- KEY_ID: Es el identificador único de la clave. El ID se usa para determinar con qué clave se debe realizar la verificación y debe coincidir con el valor KEY_ID que se usa en la especificación ProjectServiceAccount.
- PROJECT: Es el espacio de nombres del proyecto en la organización.
- AUTH_URL: Es la dirección del extremo de autenticación.

Para obtener detalles sobre cómo usar el archivo de claves generado para autenticar la CLI de gcloud como esta identidad de servicio, consulta la sección Autoriza una identidad de servicio con una clave.

Cómo ver las identidades de servicio

En esta sección, se describe cómo ver las identidades de tu servicio y sus claves públicas asociadas.

Cómo ver una lista de identidades de servicio

Para ver una lista de las identidades de servicio dentro de un proyecto, usa la consola de GDC o la CLI de gdcloud.

Console

Accede a la consola de GDC.
Selecciona un proyecto.
En el menú de navegación, haz clic en Identidad y acceso > Identidades de servicio para ver la lista de identidades de servicio del proyecto.

gdcloud

Enumera las cuentas de identidad de servicio en un proyecto:

gdcloud iam service-accounts list \
    --project=PROJECT

Reemplaza PROJECT por el ID del proyecto.

Consulta una lista de claves públicas para una identidad de servicio

Enumera las claves públicas registradas con una cuenta de identidad de servicio en el proyecto:

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Reemplaza lo siguiente:

PROJECT: Es el ID del proyecto.
NAME: Es el nombre de la cuenta de identidad de servicio que se usará.

Otorga permisos para identidades de servicio

Para otorgar permisos a una identidad de servicio, asígnale uno o más roles creando vinculaciones de roles con la consola de GDC o la CLI de gdcloud.

Console

Accede a la consola de GDC.
Selecciona un proyecto.
En el menú de navegación, selecciona Identidad y acceso > Acceso.
En la lista Miembro, haz clic en Agregar miembro. Verás la página Usuarios y roles.
Selecciona Identidad de servicio en la lista Tipo de miembro.
En la lista Identidad del servicio, selecciona la identidad del servicio a la que deseas asignar una vinculación de rol.
En la lista Rol, selecciona el rol que deseas asignar a la identidad del servicio, como Creador de copias de seguridad.
Opcional: Para agregar otro rol, haz clic en Agregar otro rol. Selecciona el rol adicional.
Haz clic en Agregar.

gdcloud

Puedes vincular la cuenta de identidad del servicio a roles dentro del espacio de nombres del proyecto o a roles en un espacio de nombres diferente.

Vincula la cuenta a un rol dentro del espacio de nombres del proyecto:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
Reemplaza lo siguiente:
- PROJECT: Es el proyecto en el que se creará la vinculación del rol. Si gdcloud init ya está configurado, puedes omitir la marca --project.
- ROLE: Es el rol predefinido que se asignará a la cuenta. Especifica los roles en el formato Role/name, donde Role es el tipo de Kubernetes IAMRole y name es el nombre del rol predefinido. Por ejemplo, para asignar el rol de visualizador del proyecto, establece el rol en IAMRole/project-viewer.
- NAME: Es el nombre de la cuenta de identidad de servicio que se usará.
Vincula la cuenta a un rol dentro de un espacio de nombres diferente:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
Reemplaza lo siguiente:
- ROLE: Es el rol predefinido que se asignará a la cuenta. Especifica los roles en el formato Role/name, donde Role es el tipo de Kubernetes IAMRole y name es el nombre del rol predefinido. Por ejemplo, para asignar el rol de visualizador del proyecto, establece el rol en IAMRole/project-viewer.
- ROLE_NAMESPACE: Es el espacio de nombres del rol que se vinculará con la cuenta, además del espacio de nombres del proyecto.
- NAME: Es el nombre de la cuenta de identidad de servicio que se usará.

Autentica y usa una identidad de servicio

Para configurar gdcloud y otras herramientas para que operen como una identidad de servicio, primero debes autenticarte en gdcloud con el archivo de claves de la identidad de servicio. Una vez que te autentiques, puedes usar las credenciales de la identidad del servicio para generar tokens o archivos kubeconfig.

Autoriza una identidad de servicio con una clave

El comando gdcloud auth activate-service-account autentica la CLI de gcloud con una identidad de servicio. Esto te permite realizar acciones en los recursos de Distributed Cloud con los permisos de la cuenta de identidad del servicio en lugar de una cuenta de usuario.

Autoriza una identidad de servicio con una clave:

Crea un archivo de clave de credenciales si aún no tienes uno.
Activa la identidad del servicio ejecutando el siguiente comando:
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
Reemplaza KEY_FILE por la ruta de acceso al archivo de claves de credenciales, que suele estar en formato JSON.

Después de la activación correcta, gdcloud usa las credenciales de la identidad del servicio en lugar de las credenciales del usuario.

Imprime un token de identidad para la identidad del servicio

Después de autorizar una identidad de servicio, puedes imprimir un token de identidad para ella. Puedes usar este token como token del portador para autenticar solicitudes HTTP. Esto significa que el token otorga a cualquier parte que lo posea acceso a los servicios definidos en el parámetro AUDIENCES.

Imprime un token de identidad para la cuenta de identidad de servicio especificada:

gdcloud auth print-identity-token --audiences=AUDIENCES

Reemplaza AUDIENCES por el destinatario o servicio previsto para el que se generó el token. Solo se puede especificar un público.

Genera el archivo kubeconfig

Después de autorizar una identidad de servicio, puedes generar un archivo kubeconfig para autenticarte en los clústeres.

Configura la propiedad core/organization_console_url de gdcloud:
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
Reemplaza GDC_URL por la URL de tu organización.
Genera el archivo kubeconfig para acceder a un clúster con la identidad del servicio activa:
- Para un clúster zonal:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  Reemplaza lo siguiente:
  - KUBECONFIG_PATH: Es la ruta de acceso en la que deseas guardar el archivo kubeconfig generado.
  - CLUSTER_NAME: Es el nombre del clúster zonal.
    
    Nota: La lista de nombres de clústeres está disponible en la URL de configuración de acceso:
    https://GDC_URL/.well-known/login-config.
  - ZONE: Es el nombre de la zona en la que se encuentra el clúster.
- Para el servidor de la API global, haz lo siguiente:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  Reemplaza KUBECONFIG_PATH por la ruta de acceso en la que deseas guardar el archivo kubeconfig generado.

Se genera un archivo kubeconfig configurado para autenticarse como la identidad del servicio. A continuación, se muestra un ejemplo de un archivo YAML:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

Borra una identidad de servicio

Después de borrar una identidad de servicio, se borran el objeto ProjectServiceAccount y sus claves públicas asociadas, las claves privadas existentes dejan de ser válidas y las aplicaciones ya no tienen acceso a los recursos del proyecto a través de esa identidad de servicio.

Para borrar una identidad de servicio, usa la consola de GDC o la CLI de gdcloud.

Console

Accede a la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Selecciona la casilla de verificación de la identidad de servicio que deseas borrar.
Haz clic en Borrar.
Aparecerá el diálogo de confirmación. En el campo Confirm by typing the following below, ingresa remove.
Haz clic en Borrar.

gdcloud

Ejecuta el siguiente comando para borrar una identidad de servicio:

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Reemplaza lo siguiente:

NAME: Es el nombre de la cuenta de identidad del servicio que se borrará.
PROJECT: Es el ID del proyecto.

Borrar credenciales

Si deseas inhabilitar un par de claves específico sin borrar toda la cuenta de identidad del servicio, puedes borrar su clave pública de la cuenta de identidad del servicio. Esta acción invalida la clave privada correspondiente.

Para borrar la clave pública, usa la consola de GDC o la CLI de gdcloud.

Console

Accede a la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haz clic en el nombre de la identidad del servicio que tiene la clave que deseas borrar.
Haz clic en Borrar.
En el diálogo de confirmación, haz clic en Borrar.

gdcloud

Quita la clave pública con el ID de clave de una cuenta de identidad de servicio en el proyecto:

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

Reemplaza lo siguiente:

KEY_ID: Es el identificador único de la clave.
PROJECT: Es el ID del proyecto.
NAME: Es el nombre de la cuenta de identidad del servicio.

Administrar cuentas de servicio Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Crea una identidad de servicio

Crear una cuenta

Console

gdcloud

API

Crear credenciales

Console

gdcloud

API

Cómo ver las identidades de servicio

Cómo ver una lista de identidades de servicio

Console

gdcloud

Consulta una lista de claves públicas para una identidad de servicio

Otorga permisos para identidades de servicio

Console

gdcloud

Autentica y usa una identidad de servicio

Autoriza una identidad de servicio con una clave

Imprime un token de identidad para la identidad del servicio

Genera el archivo kubeconfig

Borra una identidad de servicio

Console

gdcloud

Borrar credenciales

Console

gdcloud

Administrar cuentas de servicio