Descripción general de las APIs de Google Distributed Cloud aislado

Las interfaces de programación de aplicaciones (APIs) aisladas de Google Distributed Cloud (GDC) son interfaces programáticas para los servicios de la plataforma de GDC. Google compila las APIs del plano de control sobre Kubernetes con el modelo de recursos de Kubernetes (KRM). El plano de control realiza la administración de recursos para servicios, como la creación, la eliminación y las actualizaciones.

Los servicios específicos tienen estas APIs y sus propias APIs de plano de datos, que se basan en XML, JSON o gRPC. En esta página, se abordan estos servicios en sus respectivas secciones.

Acerca de las APIs de GDC

Existen dos tipos de APIs de GDC: las que se basan en Kubernetes y las que no. Muchas APIs de GDC son extensiones de la API de Kubernetes de código abierto. Usan recursos personalizados de Kubernetes y dependen del KRM. Estas APIs, como la de Kubernetes, son APIs de RESTful basadas en HTTP, que aceptan y devuelven JSON de forma predeterminada o en Protobuf. El extremo de API es el servidor de Kubernetes pertinente.

Otras APIs de GDC que no se basan en Kubernetes, como las APIs de IA previamente entrenadas de Vertex, tienen sus propios extremos. Además de admitir HTTP, también se puede acceder a algunas de estas APIs a través de gRPC, el framework de llamadas de procedimiento remoto de código abierto. Para obtener más información sobre APIs específicas, consulta su documentación dedicada en el menú de navegación vertical.

Para acceder a las APIs de GDC, usa las herramientas de la CLI de gdcloud o la consola de GDC.

Acerca de la API de Kubernetes y el KRM

Como muchas de las APIs de GDC son extensiones de la API de Kubernetes y dependen del KRM, comprender estos conceptos te ayuda a aprovechar las APIs de GDC en toda su extensión.

La API de Kubernetes es completamente declarativa, y todo lo que contiene es un recurso que sigue el KRM. Los clientes de API, tanto humanos como máquinas, actúan sobre esos recursos, a menudo con operaciones de creación, lectura, actualización y eliminación (CRUD). La base de datos de Kubernetes almacena el recurso y representa el estado del sistema. Kubernetes supervisa continuamente esos recursos y concilia el estado real del sistema con el estado deseado. Por ejemplo, si actualizas un recurso Deployment para indicar que quieres cinco réplicas de tu contenedor en lugar de cuatro, Kubernetes detecta el cambio en la cantidad deseada de réplicas y crea un contenedor adicional.

Para la API principal de Kubernetes, Kubernetes realiza la conciliación entre los estados deseados y reales. Las extensiones de la API de Kubernetes son recursos personalizados que no forman parte de la API de Kubernetes principal. El software personalizado supervisa de forma continua la API de Kubernetes, interactúa con ella y realiza la conciliación.

Para obtener más información sobre la API de Kubernetes y el modelo de recursos de Kubernetes, lee la documentación oficial de Kubernetes.

• Descripción general de la API de Kubernetes, en https://kubernetes.io/docs/reference/using-api/
• Conceptos de la API de Kubernetes, en https://kubernetes.io/docs/reference/using-api/api-concepts/
• El modelo de recursos de Kubernetes (KRM), en https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

APIs globales y zonales

Los recursos de GDC aislado son recursos zonales o globales. Los recursos zonales operan dentro de una sola zona de forma independiente, y una interrupción zonal puede afectar a algunos o a todos los recursos de esa zona. Los recursos globales operan con redundancia en varias zonas para ofrecer tolerancia a errores.

GDC aislado ofrece dos niveles de APIs del plano de administración para crear y administrar ambos tipos de recursos de GDC: APIs globales y APIs zonales.

Las APIs globales y zonales son APIs declarativas de Kubernetes que se entregan en diferentes extremos, y los recursos de GDC se representan como recursos personalizados de Kubernetes en los servidores de la API. Los servidores de la API globales comparten un solo clúster de etcd distribuido en las zonas para proporcionar una coherencia sólida con tolerancia a errores, a costa de una latencia más alta y consultas de escritura por segundo (QPS) reducidas en comparación con los servidores de la API zonales. En cada organización, un servidor de la API de administración zonal proporciona la API zonal para que los administradores y desarrolladores administren los recursos zonales, y un servidor de la API global proporciona la API global para administrar los recursos de varias zonas.

Acceso a las APIs de GDC

Tanto las herramientas de la CLI de gdcloud como la consola de GDC aprovechan las APIs de GDC. Google recomienda que los uses para explorar GDC o realizar operaciones únicas. Sin embargo, si usas el acceso automatizado o programático a GDC, Google recomienda que uses las APIs de GDC directamente.

Compatibilidad con HTTP y gRPC

La mayoría de las APIs de GDC proporcionan una interfaz HTTP JSON a la que llamas directamente. Las APIs basadas en Kubernetes usan las bibliotecas cliente de Kubernetes. Algunas APIs de GDC que no son de Kubernetes tienen una interfaz de gRPC, que proporciona un mejor rendimiento y usabilidad. Google también proporciona bibliotecas cliente para las APIs de GDC que no se basan en Kubernetes. Para obtener más información sobre gRPC, visita https://grpc.io/.

Encriptación TLS

Todas las APIs de GDC aceptan solicitudes con la encriptación de la seguridad de la capa de transporte (TLS).

• Si usas una de las bibliotecas cliente de Kubernetes o GDC, la biblioteca controla la encriptación en tránsito por ti.
• Si usas tu propio cliente HTTP o gRPC, debes autenticarte con GDC, que requiere TLS. Para gRPC, sigue las instrucciones de la guía de autenticación de gRPC en https://grpc.io/docs/guides/auth/.

Nota: GDC recomienda que uses los clientes existentes, en especial los que proporciona Google, para interactuar con las APIs de GDC. Crear tu propio cliente de API es una tarea de ingeniería de software ardua que, si se realiza de forma incorrecta, puede generar comportamientos imprevistos en tus sistemas que son difíciles de diagnosticar.

Accede a la API de Kubernetes y a las APIs basadas en Kubernetes

La CLI de Kubernetes kubectl es la forma principal de trabajar directamente con la API de Kubernetes y cualquier API basada en Kubernetes.

Accede con kubectl

Cuando accedas a la API de Kubernetes por primera vez, usa la herramienta de línea de comandos de Kubernetes, kubectl.

Para acceder a un clúster, necesitas la información de ubicación del clúster y las credenciales para acceder a él. Consulta la sección Accede para obtener información sobre cómo acceder a esas credenciales.

Examina tu configuración actual de kubectl y consulta los clústeres a los que tienes acceso:

kubectl config view

Genera descripciones de extremo de API

Para ver una lista de los endpoints de API disponibles para todas las APIs de servicio en GDC aislado, puedes generar descripciones de APIs siguiendo la especificación de OpenAPI en formato JSON. Puedes ver el JSON generado para los endpoints de API en herramientas como Swagger.

Completa los siguientes pasos para generar las descripciones de los endpoints de la API del plano de datos y de administración en formato JSON:

1. Crea un servidor proxy entre tu entorno y el servidor de la API de administración:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   Reemplaza MANAGEMENT_API_SERVER por la ruta de acceso al archivo kubeconfig del servidor de la API de administración. Para obtener más información, consulta Recursos del servidor de la API de Management zonal.

2. Descarga la lista de descripciones de extremo de API en formato JSON:

   curl -s http://127.0.0.1:8001/openapi/v2 | jq 'if .paths then .paths = (.paths
       | with_entries(select(.key | contains(".private") | not))) else . end' > k8s_swagger.json
   

3. Abre el archivo k8s_swagger.json generado en una herramienta como Swagger para ver las descripciones de extremo de API.

Acceso directo a la API con un cliente HTTP

A continuación, se muestran formas de acceder directamente a la API de REST con un cliente HTTP, como curl, wget o un navegador:

• Confía en kubectl para controlar la autenticación usándolo en modo proxy.
• Controla la autenticación por tu cuenta.

Ejecuta el proxy de kubectl

El comando kubectl proxy ejecuta kubectl en un modo en el que actúa como un proxy inverso. Este comando se conecta a apiserver y administra la autenticación.

Cuando se ejecuta kubectl en modo de proxy, se usa la ubicación almacenada del servidor de la API y se verifica la identidad del servidor de la API con un certificado. Este método protege contra los ataques de intermediario (MITM).

En el siguiente ejemplo, se muestra cómo usar el comando kubectl proxy:

kubectl proxy --port=8080 &

Una vez que se esté ejecutando el proxy de kubectl, puedes explorar la API con curl, wget o un navegador, como se muestra a continuación:

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

Ejecuta sin el proxy de kubectl

Si no quieres ejecutar kubectl en modo proxy, puedes pasar un token de autenticación directamente al servidor de la API.

1. Enumera todos los clústeres de Kubernetes posibles a los que tienes acceso, ya que tu archivo kubeconfig puede tener varios contextos:

   kubectl config view \
       -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
   

2. Exporta el nombre del clúster de Kubernetes con el que deseas interactuar desde el resultado anterior:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. Configura el servidor de la API que hace referencia al nombre del clúster de Kubernetes:

   APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")
   

4. Crea un Secret para almacenar un token de la cuenta de servicio predeterminada:

   kubectl apply -n NAMESPACE -f - <<EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: default-token
     annotations:
       kubernetes.io/service-account.name: default
   type: kubernetes.io/service-account-token
   EOF
   

5. Espera a que el controlador de tokens complete el Secret con un token:

   while ! kubectl describe secret default-token -n NAMESPACE | grep -E '^token' >/dev/null; do
     echo "waiting for token..." >&2
     sleep 1
   done
   

6. Establece el valor del token:

   TOKEN=$(kubectl get secret default-token -n NAMESPACE \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. Para acceder a la API, usa el token con una herramienta como curl agregando el encabezado HTTP Authorization: Bearer $TOKEN, como se muestra en el siguiente ejemplo:

   curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"
   

   El resultado es similar a lo siguiente:

   {
     "kind": "APIVersions",
     "versions": [
       "v1"
     ],
     "serverAddressByClientCIDRs": [
       {
         "clientCIDR": "0.0.0.0/0",
         "serverAddress": "10.0.1.149:443"
       }
     ]
   }