Se usó la API de Cloud Translation para traducir esta página.

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 explican 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 devuelven JSON como formato 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 previamente entrenadas 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

Dado que muchas de las APIs de GDC son extensiones de la API de Kubernetes y dependen del 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 ella es un recurso que sigue el KRM. Los clientes de la 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 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 por sí mismo. Las extensiones de la API de Kubernetes son recursos personalizados que no forman parte de la API principal de Kubernetes. El software personalizado supervisa y, de forma continua, interactúa con la API de Kubernetes y realiza la conciliació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 aislada del aire 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 air-gapped 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.

Tanto las APIs globales como las zonales son APIs declarativas de Kubernetes que se publican 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 todas las zonas para proporcionar una coherencia sólida con tolerancia a fallas, a costa de una mayor latencia y una menor cantidad de consultas de escritura por segundo (QPS) en comparación con los servidores de la API zonal. En cada organización, un servidor de API de administración zonal proporciona la API zonal para que los administradores y desarrolladores administren los recursos zonales, y un servidor de API de administración global proporciona la API global para administrar los recursos multizonales.

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 utilizas 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 puedes llamar 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 seguridad de la capa de transporte (TLS).

Si usas una de las bibliotecas cliente de Kubernetes o de 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/.

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

La CLI de kubectl de Kubernetes es la principal forma 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 y las credenciales correspondientes. Consulta la sección Acceder 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

Acceso directo a la API con un cliente HTTP

A continuación, se indican algunas 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 de proxy.
Controlar la autenticación por tu cuenta

Ejecuta kubectl proxy

El comando kubectl proxy ejecuta kubectl en un modo en el que actúa como 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 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 ejecute el proxy 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.

Enumera todos los clústeres de Kubernetes a los que puedes acceder, 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}'

Exporta el nombre del clúster de Kubernetes con el que deseas interactuar desde el resultado anterior:
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Establece 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}")

Crea un secreto para guardar 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

Espera a que el controlador de tokens complete 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

Establece el valor del token:

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

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 este:

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