IBM Cloud Docs
Configuración de la API

Configuración de la API

Puede utilizar la API de IBM Cloud® Kubernetes Service para crear y gestionar los 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 IBM Cloud Kubernetes Service 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
Documentación de referencia de API
API de v1: https://containers.cloud.ibm.com/global/swagger-global-api/
API de v2: https://containers.cloud.ibm.com/global/swagger-global-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 de v1: utilice la API de IBM Cloud Kubernetes Service para gestionar los recursos de infraestructura de IBM Cloud, como nodos de trabajador, para los clústeres de Red Hat OpenShift y de Kubernetes de la comunidad.
API de v2: utilice la API de IBM Cloud Kubernetes Servicev2 para gestionar los recursos de infraestructura de IBM Cloud, como nodos de trabajador, para los clústeres de Red Hat OpenShift y de Kubernetes de la comunidad.
API de Kubernetes
API de v1: para utilizar la API de Kubernetes con el objetivo de gestionar recursos de Kubernetes dentro del clúster, como pods y espacios de nombres, consulte Cómo trabajar con un clúster mediante la API de Kubernetes.
API de v2: igual que v1; consulte Cómo trabajar con un clúster mediante la API de Kubernetes.
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 IBM Cloud Kubernetes Service para automatizar la creación, el despliegue y la gestión de clústeres de Kubernetes.

La API de IBM Cloud Kubernetes Service 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 IBM Cloud Kubernetes Service.

Para autenticarse con IBM Cloud Kubernetes Service, 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.

También puede utilizar el archivo JSON swagger de la API para generar un cliente que pueda interactuar con la API como parte de su trabajo de automatización.

ID no federado
  • Generar una clave de API de IBM Cloud: como alternativa al uso del nombre de usuario y la contraseña de IBM Cloud, puede utilizar claves 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.
  • 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.
  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. Si desea ejecutar solicitudes de API de Kubernetes en un clúster, asegúrese de anotar el nombre o el ID del clúster con el que desea trabajar. 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 IBM Cloud Kubernetes Service 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.

Cómo trabajar con el clúster utilizando la API de Kubernetes

Puede utilizar la API Kubernetes para interactuar con su clúster en IBM Cloud Kubernetes Service.

Las instrucciones siguientes requieren acceso a la red pública en el clúster para conectar con el punto final de servicio en la nube público del nodo maestro de Kubernetes.

  1. Siga los pasos de Automatización de despliegues de clústeres con la API para recuperar su señal de acceso de IBM Cloud IAM, la señal de acceso de IAM, el ID del clúster donde desea ejecutar las solicitudes de API de Kubernetes y la región de IBM Cloud Kubernetes Service donde se encuentra el clúster.

  2. Recupere un token de actualización IAM y un token de acceso IAM de IBM Cloud.

    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.
    • cache-control: no-cache
    Cuerpo
    • delegated_refresh_token_expiry: 600
    • receiver_client_ids: kube
    • response_type: delegated_refresh_token
    • refresh_token: Su señal de renovación de IBM Cloud IAM.
    • grant_type: refresh_token

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

    {
    "access_token": <access_token>
    "refresh_token": <delegated_refresh_token>
    }
    
  3. Recupere un ID de IBM Cloud IAM, un acceso de IAM y una señal de renovación de IAM utilizando la señal de renovación delegada del paso anterior. En la salida de la API, puede encontrar el token de ID de IAM en el campo id_token, el token de acceso de IAM en el campo access_token y el token de actualización de IAM en el campo refresh_token.

    POST https://iam.cloud.ibm.com/identity/token
    
    Cabecera
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic a3ViZTprdWJl a3ViZTprdWJl equivale a la autorización codificada en URL para el nombre de usuario kube y la contraseña kube.
    • cache-control: no-cache
    Cuerpo
    • refresh_token: Su señal de renovación delegada de IBM Cloud IAM.
    • grant_type: urn:ibm:params:oauth:grant-type:delegated-refresh-token

    En el ejemplo siguiente se muestra la salida de la solicitud 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,
    "scope": "ibm openid containers-kubernetes"
    }
    
  4. Antes de poder acceder a su clúster con su identidad actual, debe ejecutar la siguiente solicitud.

    POST https://containers.test.cloud.ibm.com/global/v2/applyRBAC
    
    Cabecera
    Authorization: bearer <TOKEN> Su token de acceso IAM en IBM Cloud
    Cuerpo
    cluster: <cluster_name_or_ID>
  5. Ten en cuenta que la sincronización RBAC es asíncrona, así que ejecuta la siguiente petición hasta que se haya sincronizado.

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

-H "Autorización: $ {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 el URL del punto final de servicio predeterminado para el nodo maestro de Kubernetes mediante la señal de acceso de IAM y el nombre o el ID del clúster. Encontrará el URL en el valor **`masterURL`** de la salida de la API.

   Si solo el punto final de servicio en la nube público o solo el punto final de servicio en la nube privado está habilitado para el clúster, dicho punto final se muestra como `masterURL`. Si tanto el punto final de servicio en la nube público como el privado están habilitados para el clúster, el punto final de servicio en la nube público se muestra de forma predeterminada para el `masterURL`. Para utilizar en su lugar el punto final de servicio en la nube privado, busque el URL en el campo `privateServiceEndpointURL` de la salida.
   {: note}

   ```sh {: codeblock}
   GET https://containers.cloud.ibm.com/global/v2/getCluster?cluster=<cluster_name_or_ID>
Cabecera
  • Authorization: Su señal de acceso de IBM Cloud IAM.
Vía de acceso
  • <cluster_name_or_ID>: el nombre o el ID del clúster que ha recuperado con la API de GET https://containers.cloud.ibm.com/global/v2/classic/getClusters o GET https://containers.cloud.ibm.com/global/v2/vpc/getClusters?provider=vpc-gen2 en Automatización de despliegues de clúster con la API.

En el siguiente ejemplo se muestra la salida correspondiente a una solicitud de punto final de servicio de nube pública.

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

En el siguiente ejemplo se muestra la salida correspondiente a una solicitud de punto final de servicio de nube privada.

...
"etcdPort": "31593",
"masterURL": "https://c2.private.us-south.containers.cloud.ibm.com:30422",
"ingress": {
    ...}
  1. Para utilizar un punto final de servicio de nube privado, primero debe exponer el punto final de servicio de nube privada utilizando una IP de equilibrador de carga que se pueda direccionar desde la conexión VPN a la red privada.

  2. Ejecute solicitudes de API de Kubernetes en el clúster utilizando la señal de ID de IAM que ha recuperado anteriormente. Por ejemplo, liste la versión de Kubernetes que se ejecuta en el clúster.

    Si ha habilitado la verificación de certificados SSL en la infraestructura de prueba de API, asegúrese de inhabilitar esta característica.

    GET <masterURL>/version
    
    Cabecera
    • Authorization: bearer <id_token>
    Vía de acceso
    • <masterURL>: el punto final de servicio del maestro de Kubernetes que ha recuperado en el paso anterior.

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

    {
    "major": "1",
    "minor": "1.32",
    "gitVersion": "v1.32+IKS",
    "gitCommit": "c35166bd86eaa91d17af1c08289ffeab3e71e11e",
    "gitTreeState": "clean",
    "buildDate": "2019-03-21T10:08:03Z",
    "goVersion": "go1.11.5",
    "compiler": "gc",
    "platform": "linux/amd64"
    }
    
  3. Consulte la documentación de la API Kubernetes para encontrar una lista de las API compatibles con la última versión de Kubernetes. Asegúrese de utilizar la documentación de la API que coincida con la versión de Kubernetes del clúster. Si no utiliza la última versión de Kubernetes, añada su versión al final del URL. Por ejemplo, para acceder a la documentación de la API para la versión 1.12, añada v1.12.

Actualización de los tokens de acceso de IAM y obtención de nuevos tokens de actualización 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. Puede utilizar los mismos pasos para obtener una nueva señal de renovación.

Antes de empezar, asegúrese de que tiene una señal de renovación de IBM Cloud IAM o una clave de API de IBM Cloud para solicitar una nueva señal de acceso.

  • Señal de renovación: Siga las instrucciones en Automatización del proceso de creación y gestión de clústeres con la API de IBM Cloud.
  • Clave de API: recupere su clave de API de IBM Cloud tal como se indica a continuación.
    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.

Utilice los pasos siguientes si desea crear una señal de IBM Cloud IAM o si desea obtener una nueva señal de renovación.

  1. Genere una nueva señal de acceso de IBM Cloud IAM utilizando la señal de renovación o la clave de API de IBM Cloud.

    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 cuando se utiliza la señal de renovación
    • grant_type: refresh_token
    • refresh_token: Su señal de renovación de IBM Cloud IAM.
    • bss_account: Su ID de cuenta de IBM Cloud.
    Cuerpo al utilizar la clave de la API IBM Cloud
    • 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
    }
    
    

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

  2. Siga trabajando con la documentación de la API IBM Cloud Kubernetes Service utilizando el token del paso anterior.

Renovación de señales de acceso de IBM Cloud IAM y obtención de nuevas señales de renovación con la CLI

Puede utilizar la línea de mandatos para establecer el contexto del clúster, descargar el archivo kubeconfig para el clúster de Kubernetes y generar una señal de ID de IBM Cloud Identity and Access Management (IAM) y una señal de renovación para proporcionar autenticación.

Puedes utilizar IBM Cloud IAM para cambiar los tiempos de expiración por defecto de tus tokens y sesiones.

Sesión Kubeconfig
Al iniciar una nueva sesión de CLI o después de que caduque la sesión, por ejemplo, después del valor predeterminado de 24 horas, debe restablecer el contexto del clúster.
Señal de ID
Cada señal de ID de IAM que se emite a través de la CLI caduca después de un periodo de tiempo establecido, como, por ejemplo, 20 minutos. Cuando caduca la señal de ID, se envía la señal de renovación al proveedor de señales para renovar la señal de ID. Se renueva la autenticación y puede seguir ejecutando mandatos en el clúster.
Señal para renovación
Las señales de renovación caducan cuando transcurre un periodo tiempo establecido como, por ejemplo, 30 días, o cuando el administrador las revoca. Si la señal de renovación ha caducado, la señal de ID no se puede renovar y no puede continuar ejecutando mandatos en la CLI. Puede obtener una nueva señal de renovación ejecutando ibmcloud ks cluster config --cluster <cluster_name>. Este mandato también renueva la señal de ID.