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

As interfaces de programação de aplicativos (APIs) isoladas do Google Distributed Cloud (GDC) são interfaces programáticas para os serviços da plataforma 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 do 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 baseadas no Kubernetes e as que não são. Muitas APIs do GDC são extensões da API Kubernetes de código aberto. Elas 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 do Kubernetes relevante.

Outras APIs do GDC não baseadas no Kubernetes, como as APIs de IA pré-treinadas da Vertex, têm os próprios endpoints. Além de oferecer suporte a HTTP, algumas dessas APIs também podem ser acessadas pelo gRPC, o framework de chamada de procedimento remoto de código aberto. 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 ao máximo as APIs do GDC.

A API Kubernetes é totalmente declarativa, e tudo nela é um recurso que segue o KRM. Os clientes de API, humanos e de máquina, agem nesses recursos, geralmente com operações de criação, leitura, atualização e exclusão (CRUD, na sigla em inglês). 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 detectará a mudança no número desejado de réplicas e criará um contêiner adicional.

Para a API Kubernetes principal, 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 monitora e interage continuamente com a API Kubernetes e realiza a reconciliação.

Para saber mais sobre a API Kubernetes 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 globais. Os recursos zonais operam em uma única zona de forma independente, e uma interrupção zonal pode afetar alguns ou todos os recursos dessa 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 veiculadas 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 administradores e desenvolvedores gerenciarem recursos zonais, e um servidor de API de gerenciamento 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 aproveitam as APIs do GDC. O Google recomenda que você os use para explorar o GDC ou para fazer operações únicas. No entanto, se você usar acesso automatizado ou programático ao GDC, o Google recomenda que você use as APIs do GDC diretamente.

Suporte a HTTP e gRPC

A maioria das APIs do GDC fornece uma interface HTTP JSON que você chama diretamente. As APIs baseadas no Kubernetes usam as bibliotecas de cliente do Kubernetes. Algumas APIs do GDC não 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 usando a criptografia Transport Layer Security (TLS).

• Se você estiver usando uma das bibliotecas de cliente do Kubernetes ou do GDC, a biblioteca vai processar a criptografia em trânsito.
• Se você estiver usando seu próprio cliente HTTP ou gRPC, será necessário fazer a autenticação com o GDC, que exige 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 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 do cluster e das credenciais para acessá-lo. Consulte a seção Fazer login para saber como acessar essas credenciais.

Examine sua configuração kubectl atual e confira os clusters a que você tem acesso:

kubectl config view

Gerar descrições endpoint de API

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

Conclua as etapas a seguir para gerar as descrições de endpoints 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 de gerenciamento:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

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

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 conferir as descrições de endpoint de API.

Acesso direto à API com um cliente HTTP

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

• Confie em kubectl para processar a autenticação usando-o no modo proxy.
• Faça a autenticação.

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 proxy usa o local do servidor da API armazenado e verifica a identidade do servidor da API usando um certificado. Esse método protege contra ataques man-in-the-middle (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 proxy, poderá transmitir um token de autenticação diretamente para o servidor da 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 na saída anterior:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. Defina o servidor da 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 da 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 | grep -E '^token' >/dev/null; do
     echo "waiting for token..." >&2
     sleep 1
   done
   

6. Defina o valor do token:

   TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
       -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á assim:

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