Utilisation de liaisons de service pour intégrer des services IBM Cloud à Code Engine

Découvrez comment intégrer une instance de service IBM Cloud à des ressources dans un projet IBM Cloud® Code Engine à l'aide de la liaison de service.

Les liaisons de service fournissent aux applications, aux travaux et aux fonctions un accès aux services IBM Cloud.

Si vous utilisez l'interface de ligne de commande (CLI) pour gérer les liaisons de service et que certaines de ces liaisons ont été créées avec une version de la CLI antérieure à la version 1.27.0, consultez la section « Considérations » pour obtenir des informations sur le remplacement des liaisons de service qui utilisent l'ancienne implémentation. Pour bénéficier des dernières améliorations apportées à l'interface CLI, effectuez la mise à jour vers la dernière version de l'interface CLI d' IBM Cloud Code Engine.

Qu'est-ce qu'une liaison de service IBM Cloud Code Engine ?

La liaison d'une instance de service à une application ou à une tâche Code Engine ajoute automatiquement les informations d'identification de cette instance de service aux variables d'environnement du conteneur de votre application ou de votre tâche, ou au bundle de code de votre fonction. Pour voir le contenu des données d'identification d'un service, accédez au tableau de bord de l'instance de service et localisez la page Données d'identification pour le service. Les données d'identification de service sont affichées sous la forme d'un objet JSON qui, lorsqu'il est lié, est ajouté à l'environnement d'application ou de travail.

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

Pour associer une instance de service à votre charge de travail « Code Engine », vous devez d'abord provisionner une instance de ce service. Utilisez ensuite la console Code Engine ou l'interface de ligne de commande pour lier votre application, votre travail ou votre fonction à votre instance de service IBM Cloud.

Lorsque vous liez une instance de service à une charge de travail Code Engine, Code Engine utilise un secret d'accès au service pour stocker les données d'identification de l'instance de service IBM Cloud spécifiée. Ce type de secret est le mécanisme de clé dans une liaison de service qui connecte l'instance de service IBM Cloud à une application, un travail ou une fonction Code Engine particulière. Code Engine crée et gère ce secret pour vous.

Quels types de services puis-je lier ?
Vous pouvez ajouter tout type de service IBM Cloud activé pour IBM Cloud Identity and Access Management (IAM) et qui utilise des données d'identification de service pour votre application, votre travail ou votre charge de travail de fonction. Pour obtenir la liste des services IBM Cloud pris en charge, voir le catalogue IBM Cloud.
J'ai déjà des données d'identification de service pour une instance de service IBM Cloud. Puis-je utiliser ces données d'identification avec des liaisons de service Code Engine ?
Oui, vous pouvez associer une instance de service à des charges de travail d' Code Engine s en utilisant les identifiants de service existants. A partir de la console, vous pouvez utiliser des données d'identification existantes qui sont déjà utilisées dans une liaison de service. Pour utiliser des données d'identification de service existantes à partir de l'interface de ligne de commande, spécifiez l'option --service-credential dans ibmcloud ce application bind, ibmcloud ce job bind ou dans la commande ibmcloud ce function bind et indiquez le nom de vos données d'identification de service.
Quel accès est requis pour créer des liaisons de service?
Chaque projet Code Engine doit être configuré avec un ensemble de politiques d'accès IAM, qui autorisent les liaisons de service Code Engine à consulter les instances de service, ainsi qu'à consulter et à créer des informations d'identification de service dans votre compte. Les règles IAM sont fournies à la liaison de service Code Engine avec un ID de service. Pour plus d'informations, voir Configuration de l'accès pour les liaisons de service.
Existe-t-il un moyen de configurer des opérations de liaison de service pour tous les utilisateurs d'un projet?
Oui. Avec des droits suffisants, vous pouvez utiliser la page Intégration de la console pour configurer des opérations de liaison de service à partir d'une seule page. Si vous ne disposez pas des droits suffisants pour effectuer ces actions, vous pouvez utiliser cette page pour vous aider à comprendre les droits requis. Voir Configuration des paramètres à l'échelle du projet.
Après avoir lié ma charge de travail Code Engine à une instance de service, quelle est la durée de vie de cette liaison de service?
Lorsque vous créez une liaison entre votre charge de travail Code Engine et une instance de service, la liaison de service est active tant que la charge de travail Code Engine et que l'instance de service est active, ou que vous n'avez pas effectué d'opération d'annulation de liaison pour supprimer la liaison de service. Si l'instance de service est supprimée, vous devrez supprimer manuellement la liaison de service. Lorsque vous déliez (ou retirez) une liaison de service, vous supprimez l'association de l'application, du travail ou de la fonction avec le secret d'accès au service de sorte que l'application, le travail ou la fonction n'ait plus accès au service IBM Cloud précédemment lié.

Accès à une instance de service liée à partir d'une charge de travail Code Engine

Code Engine fournit des variables d'environnement permettant d'accéder aux instances de service liées à votre charge de travail Code Engine avec les méthodes CE_SERVICES et PREFIX.

  • La variable d'environnement CE_SERVICES est une variable d'environnement unique qui contient toutes les informations de liaison de service sous forme d'objet JSON.

  • Code Engine crée également plusieurs variables d'environnement pour votre liaison de service, qui sont basées sur les variables des données d'identification du service pour votre instance de service. Pour distinguer ces variables d'environnement multiples pour votre liaison de service, vous pouvez utiliser un PREFIX de sorte que ces variables d'environnement utilisent le même préfixe. Si vous ne spécifiez pas de préfixe personnalisé, Code Engine génère automatiquement un préfixe.

Si votre application, votre tâche ou votre fonction doit communiquer avec un service lié via un réseau privé et que ce service dispose à la fois de points de terminaison private et direct (comme IBM Cloud Object Storage ), il faut alors utiliser les points de terminaison direct.

CE_SERVICESvariable d'environnement

La variable d'environnement CE_SERVICES contient des informations que vous pouvez utiliser pour interagir avec une instance de service. Cette variable d'environnement pointe vers un objet JSON qui contient des paires clé-valeur. Ces paires clé-valeur représentent chaque type de service associé à votre application, tâche ou fonction. La clé (key) est le nom du type de service, par exemple, cloud-object-storage, et la valeur (value) est un tableau de données d'identification pour les instances de service liées de ce type.

L'exemple suivant illustre une variable de type « 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éthode de préfixe

Avec la méthode de préfixe, pour chaque variable de données d'identification contenue dans un objet de données d'identification de service, cette variable est fournie individuellement à votre environnement en utilisant la syntaxe de variable d'environnement commune composée de majuscules séparées par un tiret, par exemple, VARIABLE_NAME.

Par défaut, le nom de la variable est le nom du service, suivi du nom de la variable de données d'identification. Par exemple, une variable d' IBM Cloud Object Storage s relative aux identifiants de service, nommée « apikey », est disponible dans une variable d'environnement appelée « CLOUD_OBJECT_STORAGE_APIKEY ». L'exemple illustré ci-après illustre les variables d'environnement qui sont créées pour une liaison d'instance de service 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

Par défaut, si plusieurs instances du même type sont liées à une seule application, Code Engine ajoute un index au nom du service, par exemple CLOUD_OBJECT_STORAGE_2_APIKEY.

Chaque liaison de service peut être configurée pour utiliser un préfixe de variable d'environnement personnalisé. Si vous utilisez la console, vous pouvez éventuellement indiquer un préfixe lorsque vous créez la liaison de service. Si vous utilisez l'interface de ligne de commande, utilisez l'option --prefix avec app bind, job bind ou la commande function bind.

Que devrais-je considérer si j'ai des liaisons de service qui utilisent la mise en œuvre précédente ?

CLI 1.27.0 a introduit une implémentation de liaison de service améliorée, qui est utilisée pour toutes les liaisons créées avec cette version ou ultérieure. Les liaisons de service qui ont été créées avec une version de l'interface de ligne de commande avant CLI 1.27.0 utilisent l'implémentation de liaison de service précédente. Les applications, les tâches et les fonctions dont les liaisons de service utilisent l'implémentation précédente continuent de fonctionner normalement en ce qui concerne l'accès aux services liés. Toutefois, si vous souhaitez modifier les liaisons de service qui utilisent la mise en œuvre précédente, examinez les informations suivantes.

  • Il n'est pas possible de combiner des liaisons de service issues d'une implémentation antérieure et d'une implémentation améliorée pour une même application, une même tâche ou une même fonction. Avant de pouvoir ajouter de nouvelles liaisons de service à une application, une tâche ou une fonction dont les liaisons de service utilisent l'implémentation précédente, vous devez supprimer toutes ces liaisons de service. Vous pouvez ensuite les recréer avec l'implémentation améliorée et ajouter de nouvelles liaisons de service.
  • Vous ne pouvez pas annuler la liaison individuelle de ces liaisons de service. Vous devez les supprimer tous à l'aide de la commande**app unbind --all** ou**job unbind --all**.
  • Si vous utilisez des charges de travail de fonction, votre fonction utilise automatiquement la dernière implémentation des liaisons de service.

Pour bénéficier des dernières améliorations et continuer à gérer facilement les liaisons de service pour vos applications et vos travaux, mettez à jour la dernière version de l'interface CLI IBM Cloud Code Engine et remplacez les liaisons de service qui utilisent l'implémentation précédente.

Comment remplacer une liaison de service qui utilise la mise en oeuvre précédente ?

Si votre application ou votre tâche comporte des liaisons de service utilisant l'implémentation précédente et que vous souhaitez ajouter de nouvelles liaisons de service à votre application ou à votre tâche, vous devez d'abord supprimer les liaisons utilisant l'implémentation précédente avant de créer les nouvelles liaisons. Vous pouvez recréer ces liaisons de service existantes si nécessaire.

Il se peut que votre application ne soit pas entièrement fonctionnelle pendant le processus d'annulation de liaison et de redéfinition des accès.

  1. Pour savoir si votre application ou votre tâche utilise l'ancienne implémentation des liaisons de service, exécutez la commande app get ou job get commande. Si vous utilisez l'implémentation précédente de la liaison de service, la sortie de cette commande fournit les informations nécessaires ainsi que les commandes à utiliser pour lier un autre service à l'application ou à la tâche. Par exemple :

    ibmcloud ce app get --name myapp

    Exemple de sortie

    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 même, si vous travaillez avec des travaux, exécutez la commande ibmcloud ce job get --name JOB_NAME pour déterminer si des liaisons obsolètes sont utilisées avec votre travail.

  2. Déconnectez les liaisons de service existantes qui utilisent la mise en œuvre précédente. L'option --all spécifie de déconnecter toutes les instances de service pour cette application.

    ibmcloud ce app unbind --name APP_NAME --all

    De même, si vous travaillez avec des travaux, exécutez la commande ibmcloud ce job unbind --name JOB_NAME --all pour annuler la liaison de toutes les instances de service pour votre travail.

  3. Créez de nouvelles liaisons. Pour créer de nouvelles liaisons, exécutez la commande ibmcloud ce app bind ou ibmcloud ce job bind. Pour remplacer la liaison de service qui a utilisé l'implémentation précédente, utilisez les commandes fournies dans la sortie des commandes app get ou job get. Par exemple, pour recréer une liaison existante à partir de l'application Code Engine , myapp, vers l'instance de service IBM Cloud Object Storage , myobjectstorage,

    ibmcloud ce app bind --name myapp --service-instance myobjectstorage --prefix CLOUD_OBJECT_STORAGE

    De même, si vous travaillez avec des travaux, exécutez la commande ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX.

    Répétez cette étape pour chaque liaison que vous souhaitez recréer.

  4. (Facultatif) Exécutez à nouveau la commande app get ou job get. Cette fois, remarquez que la sortie de la commande n'affiche pas les informations sur les liaisons de service avec une implémentation ancienne. Par exemple :

    ibmcloud ce app get --name myapp

    Exemple de sortie

    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

Etapes suivantes

Avant de pouvoir lier une instance de service à une application, un travail ou une charge de travail Code Engine, vous devez configurer l'accès pour les liaisons. Voir Configuration de l'accès pour les liaisons de service.