Trabajar con enlaces de servicio para integrar servicios de IBM Cloud con Code Engine

Descubra cómo integrar una instancia de servicio de IBM Cloud con recursos de un proyecto de IBM Cloud® Code Engine mediante el enlace de servicios.

Los enlaces de servicio proporcionan acceso de aplicaciones, trabajos y funciones a los servicios de IBM Cloud.

Si utilizas la CLI para gestionar las vinculaciones de servicio y tienes algunas que se crearon con una versión de la CLI anterior a la 1.27.0, consulta las consideraciones para obtener información sobre cómo sustituir las vinculaciones de servicio que utilizan la implementación anterior. Para aprovechar las últimas mejoras de la CLI, actualiza a la última versión de la CLI de IBM Cloud Code Engine.

¿Qué es el enlace de servicios de IBM Cloud Code Engine?

Al vincular una instancia de servicio a una aplicación o un trabajo de Code Engine, las credenciales de dicha instancia de servicio se añaden automáticamente a las variables de entorno del contenedor de tu aplicación o del trabajo, o al paquete de código de tu función. Para ver el contenido de una credencial de servicio, vaya al panel de control de la instancia de servicio y localice la página Credenciales de servicio. Las credenciales de servicio se muestran como un objeto JSON, que, cuando se enlaza, se añade a la aplicación o al entorno de trabajo.

{
    "apikey": "xxxxxxx",
    "endpoints": "https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints",
    "iam_apikey_description": "Auto-generated for key abcdabcd-abcd-4d8c-78cf-abcdabcdabcd",
    "iam_apikey_name": "my-object-storage-codeengine-credential",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/1176a104ad4241e6b0aa82ed0b60c15c::serviceid:ServiceId-abcdabcd-7ae8-abcd-a219-abcdabcdabcd",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/1176a104ac4241e6b0cb82ed0b60c15c:abcdabcd-abcd-4777-abcd-d330a450c85b::"
}

Para vincular una instancia de servicio a tu carga de trabajo de « Code Engine », primero debes aprovisionar una instancia del servicio. A continuación, utilice la consola de Code Engine o la CLI para enlazar la app, el trabajo o la función a la instancia de servicio de IBM Cloud.

Cuando enlaza una instancia de servicio a una carga de trabajo de Code Engine, Code Engine utiliza un secreto de acceso de servicio para almacenar la credencial de la instancia de servicio de IBM Cloud especificada. Este tipo de secreto es el mecanismo clave en un enlace de servicio que conecta la instancia de servicio de IBM Cloud a una aplicación, trabajo o función de Code Engine determinada. Code Engine crea y gestiona este secreto automáticamente.

¿Qué tipos de servicios puedo enlazar?: Puede añadir cualquier tipo de servicio IBM Cloud que esté habilitado para IBM Cloud Identity and Access Management (IAM) y que utilice credenciales de servicio para la carga de trabajo de aplicación, trabajo o función. Para buscar una lista de servicios de IBM Cloud admitidos, consulte el catálogo de IBM Cloud.
Ya tengo credenciales de servicio para una instancia de servicio de IBM Cloud. ¿Puedo utilizar estas credenciales con enlaces de servicio de Code Engine ?: Sí, puedes vincular una instancia de servicio a las cargas de trabaj Code Engine es utilizando las credenciales de servicio existentes. Desde la consola, puede utilizar las credenciales existentes que ya se utilizan en un enlace de servicio. Para utilizar las credenciales de servicio existentes desde la CLI, especifique la opción --service-credential en ibmcloud ce application bind, ibmcloud ce job bind o el mandato ibmcloud ce function bind y proporcione el nombre de las credenciales de servicio.
¿Qué acceso es necesario para crear enlaces de servicio?: Cada proyecto de « Code Engine » debe configurarse con un conjunto de políticas de acceso de IAM, que autorizan a las vinculaciones de servicio de « Code Engine » a ver las instancias de servicio, así como a ver y crear credenciales de servicio en tu cuenta. Las políticas de IAM se proporcionan al enlace de servicio de Code Engine con un ID de servicio. Para obtener más información, consulte Configuración del acceso para enlaces de servicio.
¿Hay alguna forma de configurar operaciones de enlace de servicio para todos los usuarios de un proyecto?: ¡Sí! Con permisos suficientes, puede utilizar la página Integración en la consola para configurar operaciones de enlace de servicio desde una sola página. Si no tiene permisos suficientes para realizar estas acciones, puede utilizar esta página para ayudarle a comprender los permisos necesarios. Consulte Configuración de valores para todo el proyecto.
Después de enlazar mi carga de trabajo de Code Engine a una instancia de servicio, ¿cuál es la vida de este enlace de servicio?: Cuando crea un enlace entre la carga de trabajo Code Engine y una instancia de servicio, el enlace de servicio está activo siempre que la carga de trabajo Code Engine y la instancia de servicio esté activa, o no haya completado una operación de desenlace para eliminar el enlace de servicio. Si se suprime la instancia de servicio, tendrá que suprimir manualmente el enlace de servicio. Al desenlazar (o eliminar) un enlace de servicio, está suprimiendo la asociación de la app, el trabajo o la función con el secreto de acceso al servicio, de modo que la app, el trabajo o la función ya no tienen acceso al servicio IBM Cloud enlazado anteriormente.

Acceso a una instancia de servicio enlazada desde una carga de trabajo de Code Engine

Code Engine proporciona variables de entorno para acceder a las instancias de servicio enlazadas a la carga de trabajo de Code Engine con los métodos CE_SERVICES y PREFIX.

La variable de entorno CE_SERVICES es una única variable de entorno que contiene toda la información de enlace de servicio como un objeto JSON.
Code Engine también crea varias variables de entorno para el enlace de servicio, que se basan en las variables de la credencial de servicio para la instancia de servicio. Para distinguir estas variables de entorno múltiples para el enlace de servicio, puede utilizar un PREFIX de modo que estas variables de entorno utilicen el mismo prefijo. Si no especifica un prefijo personalizado, Code Engine genera automáticamente un prefijo.

Si tu aplicación, tarea o función desea comunicarse con un servicio vinculado mediante una red privada y el servicio dispone tanto de puntos de conexión private como direct (como, por ejemplo, IBM Cloud Object Storage ), entonces deben utilizarse los puntos de conexión direct.

Variable de entorno de `CE_SERVICES`

La variable de entorno CE_SERVICES contiene información que puede utilizar para interactuar con una instancia de servicio. Esta variable de entorno apunta a un objeto JSON que contiene pares de clave y valor. Estos pares clave-valor representan cada tipo de servicio vinculado a tu aplicación, tarea o función. El valor de key es el nombre del tipo de servicio, como por ejemplo cloud-object-storage, y value es una matriz de credenciales para las instancias de servicio enlazadas de ese tipo.

El siguiente ejemplo ilustra una variable de tipo « CE_SERVICES ».

{
  "appid": [
    {
      "credentials": {
        "apikey": "xxxxxx",
        "appidServiceEndpoint": "https://us-south.appid.cloud.ibm.com",
        "clientId": "abcdabcd-xxxxxxxx",
        "discoveryEndpoint": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxxxx/.well-known/openid-configuration",
        "iam_apikey_description": "Auto-generated for key crn:v1:bluemix:public:appid:us-south:a/abcdabcd719f45b98a931f6e20db1bd8:xxxxxxxx:resource-key:abcdabcd-xxxxxxxx",
        "iam_apikey_name": "ce-service-access-abcd",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/abcdabcd719f45b98a931f6e20db1bd8::serviceid:ServiceId-6d7087e5-0611-4240-9e46-af8a4c15cba4",
        "managementUrl": "https://us-south.appid.cloud.ibm.com/management/v4/xxxxxxxx",
        "oauthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxxxx",
        "profilesUrl": "https://us-south.appid.cloud.ibm.com",
        "secret": "abcdabcdYTAtZmU0MC00YTQ1LTliY2YtMDk0ODg0NDMyNDgw",
        "tenantId": "xxxxxxxx",
        "version": 4
      },
      "name": "App ID-yn",
      "plan": "c0258a22-160a-403b-845d-1588ad61204c",
      "resourcekey_name": "ce-service-access-abcd",
      "resourcekey_id": "abcdabcd-xxxxxxxx"
    }
  ],
  "cloud-object-storage": [
    {
      "credentials": {
        "apikey": "xxxxxx",
        "endpoints": "https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints",
        "iam_apikey_description": "Auto-generated for key crn:v1:bluemix:public:cloud-object-storage:global:a/abcdabcd719f45b98a931f6e20db1bd8:abcdabcd-34b3-4edf-95b7-abcdabcdabcd:resource-key:abcdabcd-96e0-46ef-b805-31288524f194",
        "iam_apikey_name": "ce-service-access-c5yn1",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/abcdabcd719f45b98a931f6e20db1bd8::serviceid:ServiceId-ee6394cb-f203-4c3c-9152-ac886a3f66bb",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/abcdabcd719f45b98a931f6e20db1bd8:abcdabcd-34b3-4edf-95b7-abcdabcdabcd::"
      },
      "name": "Cloud Object Storage-56",
      "plan": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "resourcekey_name": "ce-service-access-c5yn1",
      "resourcekey_id": "abcdabcd-96e0-46ef-b805-31288524f194"
    }
  ]
}

Método Prefix

Con el método de prefijo, para cada variable de credencial de un objeto de credencial de servicio, dicha variable se proporciona individualmente en el entorno utilizando la sintaxis común de variables de entorno de mayúsculas separadas por guiones bajos, como en el caso de VARIABLE_NAME.

De forma predeterminada, el nombre de la variable es el nombre del servicio, seguido del nombre de la variable de credencial. Por ejemplo, una variable de credenciales del servicio « IBM Cloud Object Storage » denominada « apikey » está disponible en una variable de entorno llamada « CLOUD_OBJECT_STORAGE_APIKEY ». En el ejemplo siguiente se muestran las variables de entorno que se crean para un enlace de instancia de servicio de IBM Cloud Object Storage.

CLOUD_OBJECT_STORAGE_APIKEY=xxxxxx
CLOUD_OBJECT_STORAGE_ENDPOINTS=https://control.cloud-object-storage.cloud.ibm.com/v2/endpoints
CLOUD_OBJECT_STORAGE_IAM_APIKEY_DESCRIPTION=Auto-generated for key abcdabcd-abcd-abcd-abcd-abcdabcdabcd
CLOUD_OBJECT_STORAGE_IAM_APIKEY_NAME=my-object-storage-codeengine-credential
CLOUD_OBJECT_STORAGE_IAM_ROLE_CRN=crn:v1:bluemix:public:iam::::serviceRole:Manager
CLOUD_OBJECT_STORAGE_IAM_SERVICEID_CRN=crn:v1:bluemix:public:iam-identity::a/1176a104ad4441e6b0aa92ed0b60b15c::serviceid:ServiceId-abcdabcd-abcd-abcd-8b41-531fc64e640e
CLOUD_OBJECT_STORAGE_RESOURCE_INSTANCE_ID=crn:v1:bluemix:public:cloud-object-storage:global:a/1176a104ad4441e6b0aa92ed0b60b15c:11179ac4-abcd-4887-abcd-d330a430abcd::
CLOUD_OBJECT_STORAGE_SERVICENAME=my-object-storage

De forma predeterminada, si hay más de una instancia del mismo tipo enlazada a una sola aplicación, Code Engine añade un índice al nombre de servicio, como por ejemplo CLOUD_OBJECT_STORAGE_2_APIKEY.

Cada enlace de servicio se puede configurar para utilizar un prefijo de variable de entorno personalizado. Si está utilizando la consola, opcionalmente puede proporcionar un prefijo al crear el enlace de servicio. Si utiliza la CLI, utilice la opción --prefix con app bind, job bind o el mandato function bind.

¿Qué debo tener en cuenta si tengo enlaces de servicio que utilizan la implementación anterior?

La CLI 1.27.0 ha introducido una implementación de enlace de servicio mejorada, que se utiliza para todos los enlaces que se crean con esta versión o una posterior. Los enlaces de servicio que se han creado con una versión de CLI anterior a CLI 1.27.0 utilizan la implementación de enlace de servicio anterior. Las aplicaciones, los trabajos y las funciones que cuentan con enlaces a servicios que utilizan la implementación anterior siguen funcionando con normalidad en lo que respecta al acceso a los servicios vinculados. Sin embargo, si desea cambiar los enlaces de servicio que utilizan la implementación anterior, tenga en cuenta la siguiente información.

No es posible combinar enlaces de servicio de una implementación anterior con los de una implementación mejorada para la misma aplicación, tarea o función. Antes de poder añadir nuevas conexiones de servicio a una aplicación, un trabajo o una función que ya cuente con conexiones de servicio que utilicen la implementación anterior, debes desvincular todas esas conexiones de servicio. A continuación, puede volver a crearlos con la implementación mejorada y añadir nuevos enlaces de servicio.
No puede desenlazar individualmente estos enlaces de servicio. Debe eliminarlos todos utilizando el mandato app unbind --all o job unbind --all.
Si está trabajando con cargas de trabajo de función, la función utiliza automáticamente la última implementación de enlaces de servicio.

Para aprovechar las últimas mejoras y continuar gestionando los enlaces de servicio para sus aplicaciones y trabajos de forma sencilla, actualice a la última versión de CLI de IBM Cloud Code Engine y sustituya los enlaces de servicio que utilizan la implementación anterior.

¿Cómo puedo sustituir un enlace de servicio que utiliza la implementación anterior?

Si tu aplicación o tarea tiene enlaces de servicio que utilizan la implementación anterior y deseas añadir nuevos enlaces de servicio a tu aplicación o tarea, debes eliminar primero los enlaces que utilizan la implementación anterior antes de crear los nuevos. Puede volver a crear esos enlaces de servicio existentes si es necesario.

Es posible que la aplicación no esté totalmente operativa durante el proceso de eliminar y volver a crear los enlaces.

Para saber si tu aplicación o trabajo utiliza la implementación anterior de los enlaces de servicio, ejecuta el comando app get o job get comando . Si se utiliza la implementación anterior de la vinculación del servicio, la salida de este comando proporciona la información y los comandos que debe utilizar para vincular otro servicio a la aplicación o al trabajo. Por ejemplo:

ibmcloud ce app get --name myapp

Salida de ejemplo

Run 'ibmcloud ce application events -n myapp' to get the system events of the application instances.
Run 'ibmcloud ce application logs -f -n myapp' to follow the logs of the application instances.
OK
This application uses a previous service binding implementation.
Your application will continue to function normally.
To bind an additional service to this application, delete and re-create those service bindings with the improved implementation.
Your application might not be fully functional during the process of unbinding and rebinding.
Re-create the existing service bindings by issuing the following commands:
(1) Remove all existing service bindings from this application.
ibmcloud ce application unbind --name myapp -all
(2) Bind the services again.
ibmcloud ce application bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE
Name:               myapp
ID:                 abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:       myproject
Project ID:         01234567-abcd-abcd-abcd-abcdabcd1111
Age:                2m4s
Created:            2021-09-09T14:01:02-04:00
URL:                https://myapp.abcdabcdabc.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.abcdabcdabc.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:     Application deployed successfully
[...]
Service Bindings:
Service Instance    Service Type           Environment Variable Prefix
myobjectstorage     cloud-object-storage   CLOUD_OBJECT_STORAGE

De forma similar, si está trabajando con trabajos, ejecute el mandato ibmcloud ce job get --name JOB_NAME para descubrir si se utilizan enlaces en desuso con un trabajo dado.

Desenlace los enlaces de servicio existentes que utilizan la implementación anterior. La opción --all sirve para eliminar los enlaces de todas las instancias de servicio de esta aplicación.
```
ibmcloud ce app unbind --name APP_NAME --all
```
De forma similar, si está trabajando con trabajos, ejecute el mandato ibmcloud ce job unbind --name JOB_NAME --all para eliminar los enlaces de todas las instancias de servicio de su trabajo.
Crear enlaces nuevos. Para crear enlaces nuevos, ejecute el mandato ibmcloud ce app bind o ibmcloud ce job bind. Para sustituir el enlace de servicio que se utilizaba en la implementación anterior, utilice los mandatos que se proporcionan en la salida de los mandatos app get o job get. Por ejemplo, para volver a crear un enlace existente desde la aplicación Code Engine, myapp, a la instancia de servicio de IBM Cloud Object Storage, myobjectstorage,
```
ibmcloud ce app bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE
```
De forma similar, si está trabajando con trabajos, ejecute el mandato ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX.

Repita este paso para cada enlace que desee volver a crear.

(opcional) Vuelva a ejecutar el mandato app get o job get. Esta vez, observe que la salida del mandato no muestra la información sobre los enlaces de servicio con una implementación anterior. Por ejemplo:

ibmcloud ce app get --name myapp

Salida de ejemplo

Run 'ibmcloud ce application events -n myapp' to get the system events of the application instances.
Run 'ibmcloud ce application logs -f -n myapp' to follow the logs of the application instances.
OK
Name:               myapp
ID:                 abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:       myproject
Project ID:         01234567-abcd-abcd-abcd-abcdabcd1111
Age:                2m4s
Created:            2021-09-09T14:01:02-04:00
URL:                https://myapp.abcdabcdabc.us-south.codeengine.appdomain.cloud
Cluster Local URL:  http://myapp.abcdabcdabc.svc.cluster.local
Console URL:        https://cloud.ibm.com/codeengine/project/us-south/01234567-abcd-abcd-abcd-abcdabcd1111/application/myapp/configuration
Status Summary:     Application deployed successfully
[...]
Service Bindings:
Name                                         ID                                    Service Instance      Service Type          Role / Credential  Environment Variable Prefix
myapp-app-ce-service-binding-abcde          abcde5d3-dfc3-4f52-b133-b869b5eabcde   my-object-storage    cloud-object-storage   Writer             CLOUD_OBJECT_STORAGE

Próximos pasos

Para poder enlazar una instancia de servicio a una carga de trabajo de app, trabajo o función de Code Engine, debe configurar el acceso para los enlaces. Consulte Configuración del acceso para enlaces de servicio.

Trabajar con enlaces de servicio para integrar servicios de IBM Cloud con Code Engine

Trabajar con enlaces de servicio para integrar servicios de IBM Cloud con Code Engine

¿Qué es el enlace de servicios de IBM Cloud Code Engine?

Acceso a una instancia de servicio enlazada desde una carga de trabajo de Code Engine

Variable de entorno de CE_SERVICES

Método Prefix

¿Qué debo tener en cuenta si tengo enlaces de servicio que utilizan la implementación anterior?

¿Cómo puedo sustituir un enlace de servicio que utiliza la implementación anterior?

Próximos pasos

Variable de entorno de `CE_SERVICES`