Configuración de la API

Red Hat® OpenShift® on IBM Cloud® comparte la misma interfaz de programación de aplicaciones (API) que IBM Cloud Kubernetes Service, de modo que puede utilizar los mismos métodos para crear y gestionar de forma coherente clústeres de Kubernetes de comunidad o de Red Hat OpenShift. Para utilizar la CLI, consulte Configuración de la CLI.

Acerca de la API

La API de Red Hat OpenShift on IBM Cloud automatiza el suministro y la gestión de los recursos de la infraestructura IBM Cloud para los clústeres para que las apps tengan los recursos de cálculo, de red y de almacenamiento que necesitan para ofrecer servicios a los usuarios.

La API admite los distintos proveedores de infraestructura disponibles para crear clústeres. Para obtener más información, consulte la visión general del proveedor de infraestructura.

Puede utilizar la API de la versión dos (v2) para gestionar tanto los clústeres clásicos como los de VPC. La API v2 se ha diseñado para evitar que se interrumpa la funcionalidad existente siempre que sea posible. Sin embargo, asegúrese de revisar las siguientes diferencias entre la API v1 y la API v2.

Prefijo de punto final de API
API de v1: https://containers.cloud.ibm.com/global/v1
API de v2: https://containers.cloud.ibm.com/global/v2
v3 API: https://containers.cloud.ibm.com/global/v3
Documentación de referencia de API
v1 y v2 API
v3 API.
Estilo de arquitectura de la API
API de v1: Representational State Transfer (REST) que se centra en los recursos con los que interactúa a través de métodos HTTP como GET, POST, PUT, PATCH y DELETE.
API de v2: llamadas de procedimiento remoto (RPC) que se centran en acciones a través de los métodos HTTP GET y POST únicamente.
Plataformas de contenedor admitidas
API v1: utilice la API de Red Hat OpenShift on IBM Cloud para gestionar los recursos de infraestructura de IBM Cloud como, por ejemplo, nodos de trabajador, para los clústeres de Kubernetes de comunidad y Red Hat OpenShift.
API v2: utilice la API de Red Hat OpenShift on IBM Cloud v2 para gestionar los recursos de infraestructura de IBM Cloud como, por ejemplo, los nodos de trabajador para los clústeres de Kubernetes de comunidad y Red Hat OpenShift VPC.
API de Red Hat OpenShift
v1 API: Para utilizar la API Red Hat OpenShift para gestionar recursos Red Hat OpenShift y Kubernetes dentro del clúster, como pods o espacios de nombres, debe iniciar sesión intercambiando una clave de API IBM Cloud por un token de acceso Red Hat OpenShift. Consulte Utilización de una clave de API para iniciar sesión en clústeres.
API v2: Igual que v1; consulte Utilización de una clave de API para iniciar sesión en clústeres.
API soportadas por tipo de infraestructura
API de v1: classic
API de v2: vpc y classic
  • El proveedor vpc está diseñado para dar soporte a varios subproveedores de VPC. El subproveedor de VPC admitido es vpc-gen2, que corresponde a un clúster de VPC para recursos de cálculo de Generación 2.
  • Las solicitudes específicas del proveedor tienen un parámetro path en el URL, como por ejemplo v2/vpc/createCluster. Algunas API solo están disponibles para un proveedor determinado, como por ejemplo GET vlan para clásico o GET vpcs para VPC.
  • Las solicitudes que no dependen del proveedor pueden incluir un parámetro de cuerpo específico del proveedor que especifique, normalmente en JSON, como por ejemplo {"provider": "vpc"}, si desea devolver respuestas solo para el proveedor especificado.
Respuestas de GET
API de v1: el método GET para una colección de recursos (como por ejemplo GET v1/clusters) devuelve los mismos detalles para cada recurso de la lista como un método GET para un recurso individual (como por ejemplo GET v1/clusters/{idOrName}).
API de v2: para devolver las respuestas más rápidamente, el método GET de v2 para una colección de recursos (como por ejemplo GET v2/clusters) devuelve únicamente un subconjunto de información que se detalla en un método GET para un recurso individual (como por ejemplo GET v2/clusters/{idOrName}). Algunas respuestas de lista incluyen una propiedad de proveedores que identifica si el elemento devuelto se aplica a la infraestructura clásica o de VPC. Por ejemplo, la lista GET zones devuelve algunos resultados como mon01 que solo están disponibles en el proveedor de infraestructura clásica, mientras que otros resultados como us-south-01 solo están disponibles en el proveedor de infraestructura de VPC.
Respuestas de clúster, de nodo trabajador y de agrupación de nodos trabajadores
API de v1: las respuestas incluyen solo información específica del proveedor de infraestructura clásica, como las VLAN en las respuestas de trabajador y el clúster de GET.
API de v2: la información devuelta depende del proveedor de infraestructura. Para las respuestas específicas del proveedor, puede especificar el proveedor en la solicitud. Por ejemplo, los clústeres de VPC no devuelven información de VLAN porque no tienen VLAN. En lugar de ello, devuelven información de subred y de red CIDR.

Automatización de despliegues de clústeres con la API

Puede utilizar la API de Red Hat OpenShift on IBM Cloud para automatizar la creación, el despliegue y la gestión de clústeres de Red Hat OpenShift.

La API de Red Hat OpenShift on IBM Cloud precisa de información de cabecera que debe proporcionar en su solicitud de la API y que depende del tipo de API utilizado. Para determinar qué información de cabecera es necesaria para su API, consulte la documentación de la API Red Hat OpenShift on IBM Cloud.

Para autenticarse con Red Hat OpenShift on IBM Cloud, debe especificar su señal de IBM Cloud Identity and Access Management (IAM) que se genera con las credenciales de IBM Cloud y que incluye el ID de la cuenta de IBM Cloud en la que se ha creado el clúster. Dependiendo de la forma en que se autentique con IBM Cloud, puede elegir entre las siguientes opciones para automatizar la creación de la señal de IBM Cloud IAM.

ID no federado
  • Generar una clave API IBM Cloud: Como alternativa al uso del nombre de usuario y la contraseña de IBM Cloud, puede utilizar las claves API de IBM Cloud. IBM Cloud Las claves API dependen de la cuenta IBM Cloud para la que se generan. No puede combinar la clave de API de IBM Cloud con un ID de cuenta diferente en la misma señal de IBM Cloud IAM. Para acceder a los clústeres que se han creado con una cuenta distinta de aquella en la que se basa la clave de API de IBM Cloud, debe iniciar una sesión en la cuenta para generar una nueva clave de API.
  • Nombre de usuario y contraseña de IBM Cloud: Puede seguir los pasos de este tema para automatizar por completo la creación de la señal de acceso de IBM Cloud IAM.
ID federado
  • Generar una clave de API de IBM Cloud: las claves de API de IBM Cloud dependen de la cuenta de IBM Cloud para la que se generan. No puede combinar la clave de API de IBM Cloud con un ID de cuenta diferente en la misma señal de IBM Cloud IAM. Para acceder a los clústeres que se han creado con una cuenta distinta de aquella en la que se basa la clave de API de IBM Cloud, debe iniciar una sesión en la cuenta para generar una nueva clave de API.
  • Utilizar un código de acceso de un solo uso: si se autentica con IBM Cloud utilizando un código de acceso de un solo uso, no puede automatizar completamente la creación de la señal de IBM Cloud IAM porque la recuperación de su código de acceso de un solo uso requiere una interacción manual con el navegador web. Para automatizar por completo la creación de la señal de IBM Cloud IAM, debe crear en su lugar una clave de API de IBM Cloud.
  • Clave API: Para generar su IBM Cloud API key haga lo siguiente.
    1. En la barra de menús, pulse Gestionar > Acceso (IAM).
    2. Pulse la página Usuarios y, a continuación, selecciónese usted mismo.
    3. En el panel Claves de API, pulse Crear una clave de API de IBM Cloud.
    4. Especifique un Nombre y una Descripción para la clave de API y, a continuación, pulse Crear.
    5. Pulse Mostrar para ver la clave de API generada en su nombre.
    6. Copie la clave de API de forma que la pueda utilizar para recuperar su señal de acceso de IBM Cloud IAM.

  1. Cree la señal de acceso de IBM Cloud IAM. La información del cuerpo incluida en la solicitud varía en función del método de autenticación de IBM Cloud que utilice.

    POST https://iam.cloud.ibm.com/identity/token
    Cabecera
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= donde Yng6Yng= equivale a la autorización de codificación URL para el nombre de usuario bx y la contraseña bx.
    Cuerpo para el nombre de usuario y la contraseña de IBM Cloud
    • grant_type: password
    • username: su nombre de usuario de IBM Cloud.
    • password: Su contraseña de IBM Cloud.
    Cuerpo para las claves de API de IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: Su clave de API de IBM Cloud
    Cuerpo para el código de acceso único de IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: Su código de acceso puntual de IBM Cloud. Ejecute ibmcloud login --sso y siga las instrucciones de la salida de la CLI para recuperar el código de acceso puntual mediante su navegador web.

    El ejemplo siguiente muestra la salida de la petición anterior.

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

    Puede encontrar el token IAM de IBM Cloud en el campo access_token de la salida de su API. Anote la señal de IBM Cloud IAM para recuperar información de cabecera adicional en los pasos siguientes.

  2. Recupere el ID de la cuenta de IBM Cloud con la que desee trabajar. Sustituya TOKEN por el token de IAM IBM Cloud que recuperó del campo access_token de la salida de su API en el paso anterior. En la salida de la API, puede encontrar el ID de su cuenta de IBM Cloud en el campo resources.metadata.guid.

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

    El ejemplo siguiente muestra la salida de la petición 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. Genere una nueva señal de IBM Cloud IAM que incluya sus credenciales de IBM Cloud y el ID de la cuenta con el que desea trabajar.

    Si utiliza una clave de API de IBM Cloud, debe utilizar el ID de cuenta de IBM Cloud y la clave de API se ha creado para la misma. Para acceder a los clústeres de otras cuentas, inicie sesión en esta cuenta y cree una clave API IBM Cloud basada en esta cuenta.

    POST https://iam.cloud.ibm.com/identity/token
    Cabecera
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic Yng6Yng= donde Yng6Yng= equivale a la autorización de codificación URL para el nombre de usuario bx y la contraseña bx.
    Cuerpo para el nombre de usuario y la contraseña de IBM Cloud
    • grant_type: password
    • username: su nombre de usuario de IBM Cloud.
    • password: Su contraseña de IBM Cloud.
    • bss_account: el ID de cuenta de IBM Cloud que ha recuperado en el paso anterior.
    Cuerpo para las claves de API de IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: Su clave de API de IBM Cloud.
    • bss_account: el ID de cuenta de IBM Cloud que ha recuperado en el paso anterior.
    Cuerpo para el código de acceso único de IBM Cloud
    • grant_type: urn:ibm:params:oauth:grant-type:passcode
    • passcode: su código de acceso de IBM Cloud.
    • bss_account: el ID de cuenta de IBM Cloud que ha recuperado en el paso anterior.

    El ejemplo siguiente muestra la salida de la petición de API.

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

    Puede encontrar el token IAM de IBM Cloud en el campo access_token y el token de actualización en el campo refresh_token de la salida de su API.

  4. Obtenga una lista de todos los clústeres clásicos o de VPC de su cuenta. Solicitud de ejemplo para listar clústeres clásicos.

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

    Mandato de ejemplo para listar clústeres de VPC.

    GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2
    Cabecera
    Authorization: la señal de acceso de IBM Cloud IAM (bearer <iam_token>).

  5. Consulte la documentación de la API Red Hat OpenShift on IBM Cloud para obtener una lista de las API compatibles.

Cuando utilice la API para la automatización, asegúrese de basarse en las respuestas de la API, no en los archivos de dichas respuestas. Por ejemplo, el archivo de configuración de Kubernetes del contexto de clúster está sujeto a cambios, por lo que no debe basar la automatización en ningún contenido específico de este archivo al utilizar la llamada GET /v1/clusters/{idOrName}/config.

Actualización de los tokens de acceso IAM con la API

Cada señal de acceso de IBM Cloud Identity and Access Management (IAM) que se emite mediante la API caduca transcurrida una hora. Debe renovar la señal de acceso de forma periódica para garantizar el acceso a la API de IBM Cloud.

Antes de empezar, asegúrese de que dispone de una clave de API IBM Cloud que pueda utilizar para solicitar un nuevo token de acceso.

Siga los siguientes pasos si desea obtener un nuevo token IAM de IBM Cloud.

  1. Genere un nuevo token de acceso IAM de IBM Cloud utilizando la clave API de IBM Cloud.

    POST https://iam.cloud.ibm.com/identity/token
    Cabecera
    • Content-Type: application/x-www-form-urlencoded
    Cuerpo
    • grant_type: urn:ibm:params:oauth:grant-type:apikey
    • apikey: Su clave de API de IBM Cloud.

    En el ejemplo siguiente se muestra la salida de la solicitud de API anterior.

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

    Puede encontrar su nuevo token IAM de IBM Cloud en el campo access_token de su salida API.

  2. Siga trabajando con la documentación de la API Red Hat OpenShift on IBM Cloud utilizando el token del paso anterior.