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 es compatible con los distintos proveedores de infraestructura disponibles para que puedas 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 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 encabezado se necesita para tu API, consulta la documentación de la API de 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.

ID no federado
  • Generar una clave API de IBM Cloud: como alternativa al uso del nombre de usuario y la contraseña de IBM Cloud, puede utilizar claves API de IBM Cloud. Las claves 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.
  • 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. Sustituye TOKEN por el token IAM de IBM Cloud que has obtenido del campo access_token de la salida de la 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 clústeres de otras cuentas, inicia sesión en esta cuenta y crea una clave de API de 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
}

    Puedes encontrar el token IAM IBM Cloud en el campo y access_token el token de actualización en el campo refresh_token de la salida de tu 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

Puedes usar la API Kubernetes para interactuar con tu 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 descritos en Automatización de implementaciones de clústeres con la API para obtener su token de acceso de IAM de IBM Cloud, su clave de API de IBM Cloud, el ID del clúster en el que desea realizar las solicitudes de la API de Kubernetes y la región de IBM Cloud Kubernetes Service en la que se encuentra su clúster.

  2. Recupere un ID de IAM, un acceso de IAM y un token de actualización de IAM de IBM Cloud utilizando la clave de API de IBM Cloud. En la salida de la API, encontrarás el token de identificación de IAM en el campo id_token, el token de acceso de IAM en el access_token campo y el token de actualización de IAM en el refresh_token campo.

    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 con URL para el nombre de usuario y kube la contraseña kube.
    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_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"
}

    Alternativamente, utilizando el comando CLI ibmcloud ks cluster config --cluster <cluster_name> --output json se mostrará el id_token y el refresh_token.

  3. Antes de poder acceder a su clúster con su identidad actual, debe ejecutar la siguiente solicitud.

    POST https://containers.cloud.ibm.com/global/v2/applyRBAC
    Cabecera
    Authorization: bearer <TOKEN> Tu token de acceso IAM de IBM Cloud
    Cuerpo
    cluster: <cluster_name_or_ID>

  4. 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.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.

    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": {
    ...}

  2. 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.

  3. 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>/api
    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.

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

  4. Consulta la documentación de la API Kubernetes para encontrar una lista de las API compatibles con la última versión 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 tokens de acceso de IAM mediante 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 la salida de su API.

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