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, el borrado y las actualizaciones.

Los servicios específicos tienen estas APIs y sus propias APIs del plano de datos, que se basan en XML, JSON o gRPC. En esta página, se abarcan 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 se basan en el KRM. Estas APIs, como la API de Kubernetes, son APIs de RESTful basadas en HTTP que aceptan y muestran JSON como valor predeterminado 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 preentrenada de Vertex, tienen sus propios extremos. Además de admitir HTTP, es posible que se pueda 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 se basan en el KRM, comprender estos conceptos te ayudará a aprovechar al máximo las APIs de GDC.

La API de Kubernetes es completamente declarativa, y todo en la API de Kubernetes es un recurso que sigue el KRM. Los clientes de la API, tanto humanos como de 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 observa continuamente esos recursos y reconcilia el estado real del sistema con el estado deseado. Por ejemplo, si actualizas un recurso Deployment para indicar que deseas 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.

En el caso de la API principal de Kubernetes, Kubernetes realiza la reconciliación entre los estados deseados y reales. Las extensiones de la API de Kubernetes son recursos personalizados que no forman parte de la API principal de Kubernetes. El software personalizado observa continuamente la API de Kubernetes, interactúa con ella y realiza la reconciliación.

Para obtener más información sobre la API de Kubernetes y el modelo de recursos de Kubernetes, consulta 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 en 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 la tolerancia a fallas.

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 global comparten un solo clúster de etcd distribuido en las zonas para proporcionar una coherencia sólida con tolerancia a fallas, a costa de una latencia más alta y una reducción de las consultas de escritura por segundo (QPS) en comparación con los servidores de la API zonal. 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 de administración global proporciona la API global para administrar los recursos de varias zonas.

Acceso a las APIs de GDC

Las herramientas de la CLI de gdcloud y la consola de GDC aprovechan las APIs de GDC. Google recomienda que las uses para explorar GDC o para realizar operaciones únicas. Sin embargo, si usas acceso automático 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, ve a https://grpc.io/.

Encriptación TLS

Todas las APIs de GDC aceptan solicitudes con la encriptación de 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, lo 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 clientes existentes, en especial los que proporciona Google, para interactuar con las APIs de GDC. Crear tu propio cliente de API es una tarea ardua de ingeniería de software 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.

Acceso 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 Acceder para obtener información sobre cómo obtener acceso 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 extremos de API disponibles para todas las APIs de servicio en GDC aislado, puedes generar descripciones de API según la especificación de OpenAPI en formato JSON. Puedes ver el JSON generado para los extremos de la API en herramientas como Swagger.

Completa los siguientes pasos para generar las descripciones de los extremos de la API del plano de administración y de datos 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

Las siguientes son 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 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 ejecuta 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. Haz una lista de todos los clústeres de Kubernetes posibles a los que tienes acceso, ya que tu archivo kubeconfig podría 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 secreto para contener un token para 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 propague el secreto con un token:

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

6. Establece el valor del token:

   TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
       -o jsonpath='{.data.token}' | base64 --decode)
   

7. Para acceder a la API, usa el token con una herramienta como curl. Para ello, agrega 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 este:

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