Vista geral das APIs isoladas do Google Distributed Cloud

As interfaces de programação de aplicações (APIs) isoladas do Google Distributed Cloud (GDC) são interfaces programáticas para os serviços da plataforma GDC. A Google cria as APIs do plano de controlo com base no Kubernetes, usando o modelo de recursos do Kubernetes (KRM). O plano de controlo realiza a gestão de recursos para serviços como a criação, a eliminação e as atualizações.

Os serviços específicos têm estas APIs e as suas próprias APIs de plano de dados, que são baseadas em XML, JSON ou gRPC. Esta página aborda estes serviços nas respetivas secções.

Acerca das APIs GDC

Existem dois tipos de APIs GDC: as baseadas em Kubernetes e as que não são. Muitas APIs GDC são extensões da API Kubernetes de código aberto. Usam recursos personalizados do Kubernetes e dependem do KRM. Estas APIs, como a API Kubernetes, são APIs RESTful baseadas em HTTP, que aceitam e devolvem JSON como predefinição ou em Protobuf. O ponto final da API é o servidor Kubernetes relevante.

Outras APIs GDC baseadas em não Kubernetes, como as APIs de IA pré-preparadas do Vertex, têm os seus próprios pontos finais. Além de suportarem HTTP, algumas destas APIs também podem ser acessíveis através do gRPC, a framework de chamadas de procedimentos remotos de código aberto. Para mais informações sobre APIs específicas, consulte a respetiva documentação dedicada no menu de navegação vertical.

Para aceder às APIs GDC, use as ferramentas da CLI gdcloud ou a consola GDC.

Acerca da API Kubernetes e do KRM

Uma vez que muitas das APIs da GDC são extensões da API Kubernetes e dependem do KRM, a compreensão destes conceitos ajuda a tirar o máximo partido das APIs da GDC.

A API Kubernetes é totalmente declarativa e tudo na API Kubernetes é um recurso que segue o KRM. Os clientes da API, tanto humanos como máquinas, atuam nesses recursos, muitas vezes com operações de criação, leitura, atualização e eliminação (CRUD). A base de dados do Kubernetes armazena o recurso e representa o estado do sistema. O Kubernetes monitoriza continuamente esses recursos e reconcilia o estado real do sistema com o estado desejado. Por exemplo, se atualizar um recurso Deployment para indicar que quer cinco réplicas do seu contentor em vez de quatro, o Kubernetes deteta a alteração no número desejado de réplicas e cria um contentor adicional.

Para a API Kubernetes principal, o Kubernetes realiza a conciliação entre os estados desejados e reais. As extensões da API Kubernetes são recursos personalizados que não fazem parte da API Kubernetes principal. O software personalizado monitoriza e interage continuamente com a API Kubernetes e realiza a conciliação.

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

• Vista 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 de ar são recursos zonais ou recursos globais. Os recursos zonais operam numa única zona de forma independente e uma indisponibilidade zonal pode afetar alguns ou todos os recursos nessa zona. Os recursos globais funcionam com redundância em várias zonas para tolerância a falhas.

O GDC isolado oferece dois níveis de APIs do plano de gestão para criar e gerir os dois tipos de recursos do GDC: APIs globais e APIs zonais.

As APIs globais e zonais são APIs declarativas do Kubernetes servidas em diferentes pontos finais, e os recursos da GDC são representados como recursos personalizados do Kubernetes nos servidores de API. Os servidores da API global partilham um único cluster etcd distribuído por zonas para oferecer uma forte consistência com tolerância a falhas, ao custo de uma latência mais elevada e de consultas de escrita reduzidas por segundo (QPS) em comparação com os servidores da API zonal. Em todas as organizações, um servidor de API de gestão zonal fornece a API zonal para os administradores e os programadores gerirem recursos zonais, e um servidor de API de gestão global fornece a API global para gerir recursos de várias zonas.

Acesso às APIs GDC

As ferramentas da CLI gdcloud e a consola GDC tiram partido das APIs GDC. A Google recomenda que as use para explorar o GDC ou para fazer operações únicas. No entanto, se usar o acesso automático ou programático ao GDC, a Google recomenda que use as APIs GDC diretamente.

Compatibilidade com HTTP e gRPC

A maioria das APIs GDC oferece uma interface HTTP JSON que chama diretamente. As APIs baseadas no Kubernetes usam as bibliotecas cliente do Kubernetes. Algumas APIs GDC não Kubernetes têm uma interface gRPC, que oferece um desempenho e uma usabilidade melhorados. A Google também fornece bibliotecas cliente para APIs GDC que não se baseiam no Kubernetes. Para ler mais acerca do gRPC, aceda a https://grpc.io/.

Encriptação TLS

Todas as APIs GDC aceitam pedidos através da encriptação Transport Layer Security (TLS).

• Se estiver a usar uma das bibliotecas de cliente do Kubernetes ou GDC, a biblioteca processa a encriptação em trânsito por si.
• Se estiver a usar o seu próprio cliente HTTP ou gRPC, tem de fazer a autenticação com o GDC, o que requer TLS. Para o gRPC, siga as instruções no guia de autenticação do gRPC em https://grpc.io/docs/guides/auth/.

Nota: a GDC recomenda que use clientes existentes, especialmente os fornecidos pela Google, para interagir com as APIs da GDC. A criação do seu próprio cliente da API é uma tarefa árdua de engenharia de software que, se for feita incorretamente, pode levar a comportamentos imprevistos nos seus sistemas que são difíceis de diagnosticar.

Aceda à API Kubernetes e às APIs baseadas no Kubernetes

A kubectlCLI do Kubernetes é a principal forma de trabalhar diretamente com a API Kubernetes e quaisquer APIs baseadas no Kubernetes.

Aceda com o kubectl

Quando aceder à API Kubernetes pela primeira vez, use a ferramenta de linha de comandos do Kubernetes, kubectl.

Para aceder a um cluster, precisa das informações de localização do cluster e das credenciais para aceder ao mesmo. Consulte a secção Iniciar sessão para saber como aceder a essas credenciais.

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

kubectl config view

Gere descrições de pontos finais da API

Para ver uma lista de pontos finais da API disponíveis para todas as APIs de serviços no GDC isolado, pode gerar descrições de APIs seguindo a especificação OpenAPI no formato JSON. Pode ver o JSON gerado para os pontos finais da API em ferramentas como o Swagger.

Conclua os passos seguintes para gerar as descrições dos pontos finais da API de gestão e do plano de dados no formato JSON:

1. Crie um servidor proxy entre o seu ambiente e o servidor da API de gestão:

   kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
   

   Substitua MANAGEMENT_API_SERVER pelo caminho para o ficheiro kubeconfig do servidor da API de gestão. Para mais informações, consulte o artigo Recursos do servidor da API de gestão zonal.

2. Transfira a lista de descrições de pontos finais da 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 ficheiro k8s_swagger.json gerado numa ferramenta como o Swagger para ver as descrições dos pontos finais da API.

Acesso direto à API com um cliente HTTP

Seguem-se formas de aceder diretamente à API REST com um cliente HTTP, como o curl, o wget ou um navegador:

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

Execute o proxy kubectl

O comando kubectl proxy executa o kubectl num modo em que funciona como um proxy inverso. Este comando estabelece ligação ao apiserver e gere a autenticação.

A execução do kubectl no modo proxy usa a localização do servidor da API armazenada e valida a identidade do servidor da API através de um certificado. Este método protege contra ataques do tipo man-in-the-middle (MITM).

O exemplo seguinte mostra como usar o comando kubectl proxy:

kubectl proxy --port=8080 &

Assim que o proxy kubectl estiver em execução, pode 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 não quiser executar o kubectl no modo proxy, pode transmitir um token de autenticação diretamente para o servidor da API.

1. Liste todos os clusters do Kubernetes possíveis aos quais tem acesso, uma vez que o seu ficheiro 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 o qual quer interagir a partir do resultado anterior:

   export CLUSTER_NAME="CLUSTER_NAME"
   

3. Defina o servidor da API que faz referência ao nome do cluster Kubernetes:

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

4. Crie um segredo para guardar um token para a conta de serviço predefinida:

   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 que o controlador de tokens preencha o segredo 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 aceder à API, use o token com uma ferramenta como curl adicionando o cabeçalho HTTP Authorization: Bearer $TOKEN, conforme mostrado no exemplo seguinte:

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

   O resultado é semelhante ao seguinte:

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