Esta página foi traduzida pela API Cloud Translation.

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). 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 APIs de plano de dados próprias, 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. Eles usam recursos personalizados do Kubernetes e dependem do KRM. Essas APIs, como a do Kubernetes, são APIs RESTful baseadas em HTTP, aceitando e retornando JSON como padrão ou em Protobuf. O endpoint de API é o servidor Kubernetes relevante.

Outras APIs do GDC não baseadas no Kubernetes, como as APIs de IA pré-treinadas da Vertex, têm endpoints próprios. 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 do 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 máquinas, 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 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 principal do Kubernetes. 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 (link em inglês)

APIs globais e zonais

Os recursos no GDC isolado por air-gap são zonais ou globais. Os recursos zonais operam em uma única zona de forma independente, e uma falha temporária 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 isolado por air-gap oferece dois níveis de APIs do plano de gerenciamento para criar e gerenciar os dois tipos de recursos do GDC: APIs globais e zonais.

As APIs globais e zonais são APIs declarativas do Kubernetes veiculadas em diferentes endpoints, 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 em várias zonas para oferecer consistência forte com tolerância a falhas, ao custo de maior latência e redução de consultas de gravação por segundo (QPS) em comparação com os servidores de API zonais. Em todas as organizações, 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 multizonais.

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 essas ferramentas para explorar o GDC ou fazer operações únicas. No entanto, se você usa 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 ler 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 para você.
Se você estiver usando seu próprio cliente HTTP ou gRPC, faça a autenticação com o GDC, que exige TLS. Para o gRPC, siga as instruções no guia de autenticação do gRPC em https://grpc.io/docs/guides/auth/.

Acessar a API Kubernetes e APIs baseadas no Kubernetes

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

Acessar com o 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 local e das credenciais de acesso. Consulte a seção Fazer login para saber como acessar essas credenciais.

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

kubectl config view

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 no kubectl para processar a autenticação usando-o no modo de proxy.
Faça a autenticação por conta própria.

Executar o kubectl proxy

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 do 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 "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 de proxy, transmita um token de autenticação diretamente para o servidor de API.

Liste todos os clusters do Kubernetes 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}'

Exporte o nome do cluster do Kubernetes com que você quer interagir da saída anterior:
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Defina o servidor da API referente ao nome do cluster do Kubernetes:

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

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

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

Defina o valor do token:

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

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"
    }
  ]
}