Visão geral das APIs do Google Distributed Cloud com isolamento físico

As interfaces de programação de aplicativos (APIs) do Google Distributed Cloud (GDC) com isolamento físico são interfaces programáticas para os serviços da plataforma do GDC. O Google cria as APIs do plano de controle com base no Kubernetes, usando o modelo de recursos do Kubernetes (KRM, na sigla em inglês). O plano de controle realiza o gerenciamento de recursos para serviços como criação, exclusão e atualizações.

Serviços específicos têm essas APIs e as próprias APIs de plano de dados, que são baseadas em XML, JSON ou gRPC. Esta página aborda esses serviços nas respectivas seções.

Sobre as APIs do GDC

Há dois tipos de APIs do GDC: as que são baseadas no Kubernetes e as que não são. Muitas APIs do GDC são extensões da API de código aberto do Kubernetes. Eles usam recursos personalizados do Kubernetes e dependem do KRM. Essas APIs, como a API Kubernetes, são APIs RESTful baseadas em HTTP, que aceitam e retornam JSON como padrão ou em Protobuf. O endpoint de API é o servidor relevante do Kubernetes.

Outras APIs do GDC que não são baseadas no Kubernetes, como as APIs de IA pré-treinadas da Vertex, têm os próprios endpoints. Além de serem compatíveis com HTTP, algumas dessas APIs também podem ser acessadas pelo gRPC, o framework de código aberto para chamada de procedimento remoto. Para mais informações sobre APIs específicas, consulte a documentação dedicada no menu de navegação vertical.

Para acessar as APIs do GDC, use as ferramentas da CLI gdcloud ou o console do GDC.

Sobre a API Kubernetes e o KRM

Como muitas das APIs do GDC são extensões da API Kubernetes e dependem do KRM, entender esses conceitos ajuda você a aproveitar as APIs do GDC ao máximo.

A API Kubernetes é totalmente declarativa, e tudo nela é um recurso que segue o KRM. Os clientes de API, tanto humanos quanto máquinas, atuam nesses recursos, geralmente com operações de criação, leitura, atualização e exclusão (CRUD). O banco de dados do Kubernetes armazena o recurso e representa o estado do sistema. O Kubernetes monitora continuamente esses recursos e reconcilia o estado real do sistema com o estado desejado. Por exemplo, se você atualizar um recurso Deployment para indicar que quer cinco réplicas do contêiner em vez de quatro, o Kubernetes vai detectar a mudança no número desejado de réplicas e criar um contêiner adicional.

Para a API principal do Kubernetes, o Kubernetes realiza a reconciliação entre os estados desejado e real. As extensões da API Kubernetes são recursos personalizados que não fazem parte da API Kubernetes principal. O software personalizado observa e interage continuamente com a API do Kubernetes e realiza a reconciliação.

Para saber mais sobre a API e o modelo de recursos do Kubernetes, leia a documentação oficial do Kubernetes.

• Visão geral da API Kubernetes, em https://kubernetes.io/docs/reference/using-api/
• Conceitos da API Kubernetes, em https://kubernetes.io/docs/reference/using-api/api-concepts/
• O modelo de recursos do Kubernetes (KRM), em https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md

APIs globais e zonais

Os recursos no GDC com isolamento físico são recursos zonais ou recursos globais. Os recursos zonais operam em uma única zona de maneira independente, e uma falha temporária zonal pode afetar alguns ou todos os recursos nessa zona. Os recursos globais operam com redundância em várias zonas para tolerância a falhas.

O GDC com isolamento físico oferece dois níveis de APIs do plano de gerenciamento para criar e gerenciar os dois tipos de recursos do GDC: APIs globais e APIs zonais.

As APIs globais e zonais são APIs declarativas do Kubernetes disponibilizadas em endpoints diferentes, e os recursos do GDC são representados como recursos personalizados do Kubernetes nos servidores de API. Os servidores de API globais compartilham um único cluster etcd distribuído entre zonas para fornecer consistência forte com tolerância a falhas, ao custo de maior latência e consultas de gravação reduzidas por segundo (QPS) em comparação com os servidores de API zonais. Em cada organização, um servidor de API de gerenciamento zonal fornece a API zonal para que administradores e desenvolvedores gerenciem recursos zonais, e um servidor de API global fornece a API global para gerenciar recursos de várias zonas.

Acesso às APIs do GDC

As ferramentas da CLI gdcloud e o console do GDC usam as APIs do GDC. O Google recomenda que você use esses métodos para explorar o GDC ou realizar operações únicas. No entanto, se você usa o acesso automatizado ou programático ao GDC, o Google recomenda usar as APIs do GDC diretamente.

Suporte a HTTP e gRPC

A maioria das APIs do GDC oferece uma interface HTTP JSON que você chama diretamente. As APIs baseadas no Kubernetes usam as bibliotecas de cliente do Kubernetes. Algumas APIs do GDC que não são do Kubernetes têm uma interface gRPC, que oferece melhor desempenho e usabilidade. O Google também fornece bibliotecas de cliente para APIs do GDC que não são baseadas no Kubernetes. Para saber mais sobre o gRPC, acesse https://grpc.io/.

Criptografia TLS

Todas as APIs do GDC aceitam solicitações que usam a criptografia Transport Layer Security (TLS).

• Se você estiver usando uma das bibliotecas de cliente do Kubernetes ou do GDC, ela vai processar a criptografia em trânsito para você.
• Se você estiver usando seu próprio cliente HTTP ou gRPC, será necessário autenticar com o GDC, que requer TLS. Para gRPC, siga as instruções no guia de autenticação do gRPC em https://grpc.io/docs/guides/auth/.

Observação: o GDC recomenda que você use clientes atuais, especialmente os fornecidos pelo Google, para interagir com as APIs do GDC. Criar seu próprio cliente de API é uma tarefa árdua de engenharia de software que, se feita incorretamente, pode levar a comportamentos imprevistos nos sistemas que são difíceis de diagnosticar.

Acessar a API Kubernetes e as APIs baseadas no Kubernetes

A CLI kubectl do Kubernetes é a principal maneira de trabalhar diretamente com a API Kubernetes e qualquer API baseada no Kubernetes.

Acesso com kubectl

Ao acessar a API Kubernetes pela primeira vez, use a ferramenta de linha de comando do Kubernetes, kubectl.

Para acessar um cluster, você precisa das informações de localização e das credenciais de acesso. Consulte a seção Fazer login para saber como acessar essas credenciais.

Examine a configuração atual do kubectl e veja os clusters aos quais você tem acesso:

kubectl config view

Gerar descrições endpoint de API

Para ver uma lista de endpoints de API disponíveis para todas as APIs de serviço no GDC com isolamento físico, gere descrições de API seguindo a especificação OpenAPI no formato JSON. É possível visualizar o JSON gerado para os endpoints de API em ferramentas como o Swagger.

Siga as etapas abaixo para gerar as descrições de endpoint da API do plano de gerenciamento e de dados no formato JSON:

1. Crie um servidor proxy entre seu ambiente e o servidor da API Management:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   Substitua MANAGEMENT_API_SERVER pelo caminho para o arquivo kubeconfig do servidor de API de gerenciamento. Para mais informações, consulte Recursos do servidor de API Zonal Management.

2. Faça o download da lista de descrições de endpoint de API no 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. Abra o arquivo k8s_swagger.json gerado em uma ferramenta como o Swagger para ver as descrições do endpoint de API.

Acesso direto à API com um cliente HTTP

Veja a seguir maneiras de acessar diretamente a API REST com um cliente HTTP, como curl, wget ou um navegador:

• Use o kubectl no modo proxy para que ele processe a autenticação.
• Processar a autenticação por conta própria.

Executar o proxy kubectl

O comando kubectl proxy executa kubectl em um modo em que ele atua como um proxy reverso. Esse comando se conecta ao apiserver e gerencia a autenticação.

A execução de kubectl no modo de proxy usa o local armazenado do servidor de API e verifica a identidade do servidor de API usando um certificado. Esse método protege contra ataques de interceptação (MITM).

O exemplo a seguir mostra como usar o comando kubectl proxy:

kubectl proxy --port=8080 &

Depois que o proxy kubectl estiver em execução, você poderá explorar a API com curl, wget ou um navegador, conforme mostrado abaixo:

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

Executar sem o proxy kubectl

Se você não quiser executar kubectl no modo de proxy, transmita um token de autenticação diretamente para o servidor de API.

1. Liste todos os clusters do Kubernetes possíveis a que você tem acesso, já que o arquivo kubeconfig pode ter vários contextos:

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

2. Exporte o nome do cluster do Kubernetes com que você quer interagir da saída anterior:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. Defina o servidor de API que se refere ao nome do cluster do Kubernetes:

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

4. Crie um secret para armazenar um token para a conta de serviço padrão:

   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. Aguarde o controlador de token preencher o secret com um token:

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

6. Defina o valor do token:

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

7. Para acessar a API, use o token com uma ferramenta como curl adicionando o cabeçalho HTTP Authorization: Bearer $TOKEN, conforme mostrado no exemplo a seguir:

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

   O resultado será o seguinte:

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