Configurando a API

O Red Hat® OpenShift® on IBM Cloud® compartilha a mesma interface de programação de aplicativos (API) que o IBM Cloud Kubernetes Service, para que seja possível usar os mesmos métodos para criar consistentemente e gerenciar seus clusters Red Hat OpenShift ou Kubernetes da comunidade. Para usar a CLI, consulte Configurando a CLI.

Sobre a API

A API do Red Hat OpenShift on IBM Cloud 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 é compatível com os diferentes provedores de infraestrutura que estão disponíveis para você criar 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 Red Hat OpenShift on IBM Cloud 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 Red Hat OpenShift on IBM Cloud 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 Red Hat OpenShift
v1 API: Para usar a API Red Hat OpenShift para gerenciar os recursos Red Hat OpenShift e Kubernetes no cluster, como pods ou namespaces, você deve fazer login trocando uma chave de API IBM Cloud por um token de acesso Red Hat OpenShift. Consulte Usando uma chave de API para efetuar login em clusters .
API v2: mesma que v1; consulte Usando uma chave de API para efetuar login em clusters.
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 Red Hat OpenShift on IBM Cloud para automatizar a criação, a implementação e o gerenciamento de seus clusters Red Hat OpenShift.

A API do Red Hat OpenShift on IBM Cloud 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 de cabeçalho são necessárias para sua API, consulte a documentação da API Red Hat OpenShift on IBM Cloud.

Para se autenticar com o Red Hat OpenShift on IBM Cloud, 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 IBM Cloud: Como alternativa ao uso do nome de usuário e da senha IBM Cloud, você pode usar as chaves de API IBM Cloud. IBM Cloud As chaves de API dependem da conta 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. A partir da barra de menus, clique em Gerenciar > Acesso (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 de sua saída de 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 IBM Cloud que você recuperou do 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 nessa conta e crie uma chave de API IBM Cloud baseada nessa 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. 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. Consulte a documentação da API Red Hat OpenShift on IBM Cloud para obter uma lista das APIs compatíveis.

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.

Atualização de tokens de acesso ao IAM com a 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 IBM Cloud no campo access_token de sua saída de API.

  2. Continue trabalhando com a documentação da API Red Hat OpenShift on IBM Cloud usando o token da etapa anterior.