Esta página se ha traducido con Cloud Translation API.

Descripción general de las APIs de Google Distributed Cloud con air gap

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

Algunos 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 tratan estos servicios en sus respectivas secciones.

Acerca de las APIs de GDC

Hay 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 RESTful basadas en HTTP que aceptan y devuelven JSON como formato predeterminado o en Protobuf. El endpoint de la API es el servidor de Kubernetes correspondiente.

Otras APIs de GDC que no se basan en Kubernetes, como las APIs de IA preentrenada de Vertex, tienen sus propios endpoints. Además de admitir HTTP, se puede acceder a algunas de estas APIs mediante gRPC, el framework de llamadas a procedimientos remotos de código abierto. Para obtener más información sobre APIs concretas, consulta la documentación correspondiente 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.

Información sobre la API de Kubernetes y el KRM

Como muchas de las APIs de GDC son extensiones de la API de Kubernetes y dependen de KRM, conocer estos conceptos te ayudará a aprovechar al máximo las APIs de GDC.

La API de Kubernetes es totalmente declarativa y todo lo que hay 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 monitoriza 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 el número de réplicas que quieres y crea un contenedor adicional.

En el caso de 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 principal de Kubernetes. El software personalizado monitoriza continuamente la API de Kubernetes e 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, 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 de zona

Los recursos de los centros de datos de Google aislados por aire son recursos de zona o recursos globales. Los recursos de zona operan en una única zona de forma independiente, y una interrupción de la zona puede afectar a algunos o a todos los recursos de esa zona. Los recursos globales funcionan con redundancia en varias zonas para ofrecer tolerancia a fallos.

GDC air-gapped ofrece dos niveles de APIs del plano de gestión para crear y gestionar ambos tipos de recursos de GDC: APIs globales y APIs zonales.

Tanto las APIs globales como las de zona son APIs declarativas de Kubernetes que se sirven en diferentes endpoints, y los recursos de GDC se representan como recursos personalizados de Kubernetes en los servidores de APIs. Los servidores de la API global comparten un único clúster de etcd distribuido en zonas para proporcionar una coherencia sólida con tolerancia a fallos, 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 todas las organizaciones, un servidor de API de gestión zonal proporciona la API zonal a los administradores y desarrolladores para que gestionen los recursos zonales, y un servidor de API de gestión global proporciona la API global para gestionar los recursos multizona.

Acceso a las APIs de GDC

Tanto las herramientas de la CLI de gdcloud como la consola de GDC utilizan las APIs de GDC. Google recomienda que los uses para explorar GDC o para realizar operaciones puntuales. Sin embargo, si utilizas el acceso automatizado o programático a GDC, Google te 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 de cliente de Kubernetes. Algunas APIs de GDC que no son de Kubernetes tienen una interfaz gRPC, que ofrece un mejor rendimiento y usabilidad. Google también proporciona bibliotecas de cliente para las APIs de GDC que no se basan en Kubernetes. Para obtener más información sobre gRPC, visita https://grpc.io/.

Encriptado TLS

Todas las APIs de GDC aceptan solicitudes que usen el cifrado de Seguridad en la capa de transporte (TLS).

Si usas una de las bibliotecas de cliente de Kubernetes o GDC, la biblioteca se encarga del cifrado en tránsito.
Si usas tu propio cliente HTTP o gRPC, debes autenticarte con GDC, lo que requiere TLS. En el caso de gRPC, sigue las instrucciones de la guía de autenticación de gRPC, disponible en https://grpc.io/docs/guides/auth/.

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

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

Acceder 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 su ubicación y las credenciales para acceder a él. Consulta la sección Iniciar sesión para saber cómo acceder a esas credenciales.

Consulta tu configuración actual de kubectl y 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 REST con un cliente HTTP, como curl o wget, o con un navegador:

Confía en kubectl para gestionar la autenticación usándolo en modo proxy.
Gestionar 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 gestiona la autenticación.

Al ejecutar kubectl en modo proxy, se usa la ubicación del servidor de la API almacenada y se verifica la identidad del servidor de la API mediante 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 el proxy kubectl esté en funcionamiento, 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"
    }
  ]
}

Ejecutar sin proxy de kubectl

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

Lista todos los clústeres de Kubernetes 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}'

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

Define el servidor de la API haciendo referencia al nombre del clúster de Kubernetes:

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

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

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

Define 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 añadiendo el encabezado HTTP Authorization: Bearer $TOKEN, como se muestra en el siguiente ejemplo:

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

El resultado debería ser similar al siguiente:

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