Configurando a API

É possível usar a API do IBM Cloud® Kubernetes Service para criar e gerenciar seus clusters Kubernetes da comunidade ou Red Hat OpenShift. Para usar a CLI, consulte Configurando a CLI.

Sobre a API

A API do IBM Cloud Kubernetes Service automatiza o fornecimento e o gerenciamento de recursos da infraestrutura do IBM Cloud para seus clusters para que seus apps tenham os recursos de cálculo, rede e armazenamento que eles precisam para atender seus usuários.

A API oferece suporte aos diversos provedores de infraestrutura disponíveis para a criação de clusters. Para obter mais informações, consulte visão geral do provedor de infraestrutura.

É possível usar a API de versão dois (v2) para gerenciar os clusters clássicos e VPC. A API v2 foi projetada para evitar a quebra da funcionalidade existente quando possível. No entanto, certifique-se de revisar as diferenças a seguir entre as APIs da v1 e da v2.

Prefixo do terminal de API
API v1: https://containers.cloud.ibm.com/global/v1
API v2: https://containers.cloud.ibm.com/global/v2
v3 API: https://containers.cloud.ibm.com/global/v3
Docs de referência da API
v1 e v2 API
v3 API.
Estilo arquitetural da API
API v1: Representational State Transfer (REST) focada em recursos com os quais você interage através de métodos HTTP, tais como GET, POST, PUT, PATCH e DELETE.
API v2: chamada de procedimento remoto (RPC) focada em ações apenas por meio dos métodos HTTP GET e POST.
Plataformas de contêiner suportadas
API v1: use a API IBM Cloud Kubernetes Service para gerenciar recursos de infraestrutura da IBM Cloud, como nós do trabalhador, para clusters da comunidade Kubernetes e Red Hat OpenShift.
API v2: use a API IBM Cloud Kubernetes Service v2 para gerenciar recursos de infraestrutura da IBM Cloud, como nós do trabalhador, para clusters da comunidade Kubernetes e VPC Red Hat OpenShift.
API do Kubernetes
API v1: para utilizar a API de Kubernetes para gerenciar os recursos do Kubernetes dentro do cluster, como pods ou espaços de nomes, consulte Trabalhando com o cluster usando a API de Kubernetes.
API v2: a mesma que v1; consulte Trabalhando com o cluster usando a API de Kubernetes.
APIs suportadas por tipo de infraestrutura
API v1: classic
API v2: vpc e classic
  • O provedor vpc foi projetado para suportar diversos subprovedores do VPC. O subprovedor VPC suportado é vpc-gen2, que corresponde a um cluster de VPC para recursos de computação de Geração 2.
  • As solicitações específicas do provedor têm um parâmetro de caminho na URL, como v2/vpc/createCluster. Algumas APIs estão disponíveis apenas para um provedor específico, como GET vlan para o clássico ou GET vpcs para a VPC.
  • As solicitações neutras quanto ao provedor podem incluir um parâmetro de corpo específico de provedor especificado por você, geralmente em JSON, como {"provider": "vpc"}, a fim de retornar respostas apenas para o provedor especificado.
Respostas de GET
API v1: o método GET para uma coleção de recursos (como GET v1/clusters) retorna os mesmos detalhes para cada recurso na lista que um método GET para um recurso individual (como GET v1/clusters/{idOrName}).
API v2: para retornar respostas mais rápido, o método v2 GET para uma coleção de recursos (como GET v2/clusters) retorna apenas um subconjunto de informações que é detalhado em um método GET para um recurso individual (como GET v2/clusters/{idOrName}). Algumas respostas da lista incluem uma propriedade dos provedores para identificar se o item retornado se aplica à infraestrutura clássica ou à do VPC. Por exemplo, a lista GET zones retorna alguns resultados, como mon01, que estão disponíveis somente no provedor de infraestrutura clássica, e us-south-01, que estão disponíveis somente no provedor de infraestrutura de VPC.
Respostas do cluster, do nó do trabalhador e do conjunto de trabalhadores
API v1: as respostas incluem apenas informações específicas para o provedor de infraestrutura clássica, como as VLANs no cluster GET e respostas do trabalhador.
API v2: as informações que são retornadas variam de acordo com o provedor de infraestrutura. Para essas respostas específicas do provedor, é possível especificar o provedor em sua solicitação. Por exemplo, clusters de VPC não retornam informações de VLAN já que não possuem VLANs. Em vez disso, eles retornam informações de sub-rede e de rede CIDR.

Automatizando implementações de cluster com a API

É possível usar a API do IBM Cloud Kubernetes Service para automatizar a criação, a implementação e o gerenciamento de seus clusters Kubernetes.

A API do IBM Cloud Kubernetes Service requer informações do cabeçalho que devem ser fornecidas na solicitação de API e que podem variar, dependendo da API que você deseja usar. Para determinar quais informações do cabeçalho são necessárias para a API, consulte a Documentação da API do IBM Cloud Kubernetes Service.

Para se autenticar com o IBM Cloud Kubernetes Service, deve-se fornecer um token do IBM Cloud Identity and Access Management (IAM) que é gerado com suas credenciais do IBM Cloud e que inclui o ID da conta do IBM Cloud em que o cluster foi criado. Dependendo da maneira que você autenticar com o IBM Cloud, será possível escolher entre as opções a seguir para automatizar a criação de seu token do IBM Cloud IAM.

ID não federado
  • Gerar uma chave de API do IBM Cloud: Como alternativa ao uso do nome de usuário e da senha do IBM Cloud, você pode usar as chaves de API do IBM Cloud. As chaves de API do IBM Cloud estão vinculadas à conta do IBM Cloud para a qual foram geradas. Não é possível combinar a chave de API da IBM Cloud com um ID de conta diferente no mesmo token IAM da IBM Cloud. Para acessar os clusters que foram criados com uma conta diferente daquela na qual a sua chave API do IBM Cloud é baseada; deve-se efetuar login na conta para gerar uma nova chave API.
  • Nome do usuário e senha da IBM Cloud: é possível seguir as etapas neste tópico para automatizar totalmente a criação de seu token de acesso do IBM Cloud IAM.
ID federado
  • **Gerar uma chave de API da IBM Cloud: as chaves de API da **IBM Cloud são dependentes da conta da IBM Cloud para a qual elas são geradas. Não é possível combinar a chave de API da IBM Cloud com um ID de conta diferente no mesmo token IAM da IBM Cloud. Para acessar os clusters que foram criados com uma conta diferente daquela na qual a sua chave API do IBM Cloud é baseada; deve-se efetuar login na conta para gerar uma nova chave API.
  • Usar senha descartável: se você se autenticar com a IBM Cloud usando uma senha descartável, não será possível automatizar totalmente a criação do token IAM da IBM Cloud porque a recuperação do passcode descartável exigirá interação manual com o navegador da web. Para automatizar totalmente a criação de seu token do IBM Cloud IAM, deve-se criar uma chave de API do IBM Cloud.
  • Chave de API: Para gerar sua chave de IBM Cloud Chave de API, faça o seguinte.
    1. Na barra de menus, clique em Gerenciar > Acessar (IAM).
    2. Clique na página Usuários e, em seguida, selecione você mesmo.
    3. Na área de janela Chaves de API, clique em Criar uma chave de API do IBM Cloud.
    4. Insira um Nome e uma Descrição para sua chave API e clique em Criar.
    5. Clique em Mostrar para ver a chave API que foi gerado para você.
    6. Copie a chave de API para que seja possível usá-la para recuperar seu novo token de acesso do IBM Cloud IAM.

  1. Crie seu token de acesso do IBM Cloud IAM. As informações do corpo incluídas em sua solicitação variam com base no método de autenticação do IBM Cloud usado.

    POST https://iam.cloud.ibm.com/identity/token
    Cabeçalho
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= em que Yng6Yng= é igual à autorização codificada por URL para o nome de usuário bx e a senha bx.
    Corpo para o nome do usuário e a senha do IBM Cloud
    • grant_type: password
    • username: o seu nome do usuário do IBM Cloud.
    • password: sua senha do IBM Cloud.
    Corpo para chaves API do IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: sua chave de API do IBM Cloud
    Corpo para senha única do IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: O IBM Cloud senha descartável. Execute ibmcloud login --sso e siga as instruções em sua saída da CLI para recuperar sua senha descartável usando o navegador da web.

    O exemplo a seguir mostra a saída para a solicitação anterior.

    {
"access_token": "<iam_access_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1493747503
"scope": "ibm openid"
}

    Você pode encontrar o token IAM “ IBM Cloud ” no campo “ access_token ” da saída da API. Anote o token do IBM Cloud IAM para recuperar informações adicionais do cabeçalho nas próximas etapas.

  2. Recupere o ID da conta do IBM Cloud com a qual deseja trabalhar. Substitua TOKEN pelo token IAM do IBM Cloud que você obteve no campo access_token da saída da API na etapa anterior. Em sua saída de API, é possível localizar o ID de sua conta do IBM Cloud no campo resources.metadata.guid.

    GET https://accounts.cloud.ibm.com/coe/v2/accounts
    Cabeçalho
    • Content-Type: application/json
    • Authorization: bearer TOKEN
    • Accept: application/json

    O exemplo a seguir mostra a saída da solicitação anterior.

    {
"next_url": null,
"total_results": 5,
"resources": [
    {
        "metadata": {
            "guid": "<account_ID>",
            "url": "/coe/v2/accounts/<account_ID>",
            "created_at": "2016-09-29T02:49:41.842Z",
            "updated_at": "2018-08-16T18:56:00.442Z",
            "anonymousId": "1111a1aa1a1111a1aa11aa11111a1111"
        },
        "entity": {
            "name": "<account_name>",

  3. Gere um novo token do IBM Cloud IAM que inclua suas credenciais do IBM Cloud e o ID da conta com a qual deseja trabalhar.

    Se você usar uma chave de API do IBM Cloud, deverá usar o ID da conta do IBM Cloud para a qual a chave de API foi criada. Para acessar clusters em outras contas, faça login nesta conta e crie uma chave de API do IBM Cloud baseada nesta conta.

    POST https://iam.cloud.ibm.com/identity/token
    Cabeçalho
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= em que Yng6Yng= é igual à autorização codificada por URL para o nome de usuário bx e a senha bx.
    Corpo para o nome do usuário e a senha do IBM Cloud
    • grant_type: password
    • username: o seu nome do usuário do IBM Cloud.
    • password: sua senha do IBM Cloud.
    • bss_account: o ID da conta do IBM Cloud que você recuperou na etapa anterior.
    Corpo para chaves API do IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: sua chave de API do IBM Cloud.
    • bss_account: o ID da conta do IBM Cloud que você recuperou na etapa anterior.
    Corpo para senha única do IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: sua senha do IBM Cloud.
    • bss_account: o ID da conta do IBM Cloud que você recuperou na etapa anterior.

    O exemplo a seguir mostra a saída da solicitação de API.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503
}

    Você pode encontrar o token IAM “ IBM Cloud ” no campo “ access_token ” e o token de atualização no campo “ refresh_token ” da saída da API.

  4. Liste todos os clusters clássicos ou VPC em sua conta. Para executar solicitações de API do Kubernetes com relação a um cluster, certifique-se de anotar o nome ou o ID do cluster com o qual deseja trabalhar. Exemplo de solicitação para listar clusters Classic.

    GET https://containers.cloud.ibm.com/global/v2/classic/getClusters
    Cabeçalho
    Authorization: bearer <iam_token>

    Comando de exemplo para listar clusters de VPC

    GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
    Cabeçalho
    Authorization: o token de acesso IAM da IBM Cloud (bearer <iam_token>).

  5. Revise a Documentação da API do IBM Cloud Kubernetes Service para localizar uma lista de APIs suportadas.

Ao usar a API para automação, certifique-se de contar com as respostas da API, não com arquivos dentro dessas respostas. Por exemplo, o arquivo de configuração do Kubernetes para o contexto de cluster está sujeito a mudanças, portanto, não construa automação baseada em conteúdos específicos desse arquivo ao usar a chamada GET /v1/clusters/{idOrName}/config.

Trabalhando com seu cluster usando a API do Kubernetes

É possível usar a API do Kubernetes para interagir com o cluster no IBM Cloud Kubernetes Service.

As instruções a seguir requerem acesso à rede pública em seu cluster para se conectar ao terminal em serviço de nuvem pública do principal do Kubernetes.

  1. Siga as etapas descritas no artigo “Automatizando implantações de cluster com a API” para obter seu token de acesso IAM do IBM Cloud, sua chave de API do IBM Cloud, o ID do cluster no qual você deseja executar as solicitações da API Kubernetes e a região IBM Cloud Kubernetes Service na qual seu cluster está localizado.

  2. Recupere um ID de IAM IBM Cloud, acesso de IAM e token de atualização de IAM usando a chave de API IBM Cloud. Na saída da sua API, você pode encontrar o token de identificação do IAM no campo id_token, o token de acesso do IAM no campo access_token e o token de atualização do IAM no campo refresh_token.

    POST https://iam.cloud.ibm.com/identity/token
    Cabeçalho
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl corresponde à autorização codificada como “ URL ” para o nome de usuário kube e a senha kube.
    Corpo
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: sua chave de API do IBM Cloud.

    O exemplo a seguir mostra a saída para a solicitação de API anterior.

    {
"access_token": "<iam_access_token>",
"id_token": "<iam_id_token>",
"refresh_token": "<iam_refresh_token>",
"token_type": "Bearer",
"expires_in": 3600,
"expiration": 1553629664,
"refresh_token_expiration": 1761334993,
"scope": "ibm openid containers-kubernetes"
}

    Como alternativa, o comando ibmcloud ks cluster config --cluster <cluster_name> --output json da CLI exibirá id_token e refresh_token.

  3. Antes de poder acessar seu cluster com sua identidade atual, você deve executar a seguinte solicitação.

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    Cabeçalho
    Authorization: bearer <TOKEN> Seu token de acesso do IAM do IBM Cloud
    Corpo
    cluster: <cluster_name_or_ID>

  4. Observe que a sincronização do RBAC é assíncrona, portanto, execute a solicitação a seguir até que ela seja sincronizada.

    GET https://containers.cloud.ibm.com/global/v2/getRBACStatus?cluster=<cluster_name_or_ID>

-H "Authorization: ${BEARER2} " ``` Header : Authorization: bearer <TOKEN> Your IBM Cloud IAM access token

Example response. Ensure the output shows `synchronized:true`.

```json {: screen}
{"synchronized":true,"error":false}
```

  1. Recupere a URL do terminal em serviço padrão para seu mestre do Kubernetes usando o token de acesso do IAM e o nome ou o ID de seu cluster. É possível localizar a URL no masterURL de sua saída de API.

    Se somente o terminal em serviço de nuvem pública ou somente o terminal em serviço de nuvem privada estiver ativado para seu cluster, esse terminal será listado para masterURL. Se os terminais em serviço de nuvem pública e privada estiverem ativados para seu cluster, por padrão, o terminal em serviço de nuvem pública será listado para masterURL. Em vez disso, para usar o terminal em serviço de nuvem privada, localize a URL no campo privateServiceEndpointURL da saída.

    GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
    Cabeçalho
    • Authorization: seu token de acesso do IBM Cloud IAM.
    Caminho
    • <cluster_name_or_ID>: o nome ou ID do cluster recuperado com a API GET https://containers.cloud.ibm.com/global/v2/classic/getClusters ou GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 em Automatizando implementações de cluster com a API.

    O exemplo a seguir mostra a saída para uma solicitação de terminal de serviço de nuvem pública.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

    O exemplo a seguir mostra a saída para uma solicitação de terminal de serviço de nuvem privada.

    ...
"etcdPort": "31593",
"masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}

  2. Para usar um terminal em serviço de nuvem privada, primeiro deve-se expor o terminal em serviço de nuvem privada usando um IP de balanceador de carga que seja roteável da conexão VPN para a rede privada.

  3. Execute solicitações de API do Kubernetes com relação ao seu cluster usando o token de ID do IAM recuperado anteriormente. Por exemplo, liste a versão do Kubernetes executada em seu cluster.

    Se você tiver ativado a verificação de certificado SSL em sua estrutura de teste de API, certifique-se de desativar esse recurso.

    GET <masterURL>/api
    Cabeçalho
    • Authorization: bearer <id_token>
    Caminho
    • <masterURL>: o terminal em serviço do principal do Kubernetes recuperado na etapa anterior.

    O exemplo a seguir mostra a saída da solicitação de API anterior.

    {
	"kind": "APIVersions",
	"versions": [
		"v1"
	],
	"serverAddressByClientCIDRs": [
		{
			"clientCIDR": "0.0.0.0/0",
			"serverAddress": "xxx.xx.x.x:xxxx"
		}
	]
 }

  4. Revise a Documentação da API do Kubernetes para localizar uma lista de APIs suportadas para a versão mais recente do Kubernetes. Certifique-se de usar a documentação da API que corresponda à versão do Kubernetes de seu cluster. Se não usar a versão mais recente do Kubernetes, anexe sua versão no final da URL. Por exemplo, para acessar a documentação da API para a versão 1.12, inclua v1.12.

Atualização de tokens de acesso IAM por meio da API

Cada token de acesso do IBM Cloud Identity and Access Management (IAM) que é emitido por meio da API expira após uma hora. Seu token de acesso deve ser atualizado regularmente para garantir o acesso à API do IBM Cloud.

Antes de começar, certifique-se de que você tenha uma chave de API IBM Cloud que possa ser usada para solicitar um novo token de acesso.

Use as etapas a seguir se quiser obter um novo token IAM IBM Cloud.

  1. Gere um novo token de acesso IAM IBM Cloud usando a chave de API IBM Cloud.

    POST https://iam.cloud.ibm.com/identity/token
    Cabeçalho
    • Content-Type: application/x-www-form-urlencoded
    Corpo
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: sua chave de API do IBM Cloud.

    O exemplo a seguir mostra a saída da solicitação de API anterior.

    {
    "access_token": "<iam_token>",
    "refresh_token": "<iam_refresh_token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expiration": 1493747503,
    "scope": "ibm openid"
}

    Você pode encontrar seu novo token IAM do IBM Cloud no campo “ access_token ” da saída da API.

  2. Continue trabalhando com a Documentação da API do IBM Cloud Kubernetes Service usando o token da etapa anterior.