Trabalhando com ligações de serviço para integrar os serviços IBM Cloud com Code Engine

Descubra como integrar uma instância de serviço IBM Cloud aos recursos em um projeto do IBM Cloud® Code Engine usando a ligação de serviço.

As ligações de serviços fornecem aos aplicativos, tarefas e funções acesso aos serviços do IBM Cloud.

Se você estiver usando a CLI para trabalhar com ligações de serviço e tiver ligações de serviço criadas com uma versão da CLI anterior à 1.27.0, consulte as considerações para obter informações sobre como substituir as ligações de serviço que utilizam a implementação anterior. Para aproveitar as melhorias mais recentes da CLI, atualize para a versão mais recente da CLI do IBM Cloud Code Engine.

O que é ligação de serviços do IBM Cloud Code Engine?

Ao vincular uma instância de serviço a um aplicativo ou tarefa do Code Engine, as credenciais dessa instância de serviço são adicionadas automaticamente às variáveis de ambiente do contêiner do seu aplicativo ou da tarefa, ou ao pacote de código da sua Função. Para ver os conteúdos de uma credencial de serviço, acesse o painel para a instância de serviço e localize a página Credenciais de serviço. As credenciais de serviço são mostradas como um objeto JSON e, quando ligadas, são incluídas no ambiente do aplicativo ou da tarefa.

{
    "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 uma instância de serviço à sua carga de trabalho do Code Engine, é necessário primeiro provisionar uma instância do serviço. Em seguida, use o console do Code Engine ou a CLI para ligar seu app, tarefa ou função à sua instância de serviço do IBM Cloud.

Ao ligar uma instância de serviço a uma carga de trabalho do Code Engine, o Code Engine usa um segredo de acesso de serviço para armazenar a credencial da instância de serviço especificada do IBM Cloud. Esse tipo de segredo é o mecanismo principal em uma ligação de serviços que conecta a instância de serviço do IBM Cloud a um determinado app, tarefa ou função do Code Engine. Code Engine cria e gerencia esse segredo para você.

Que tipos de serviços posso ligar?
É possível incluir qualquer tipo de serviço do IBM Cloud que está ativado para o IBM Cloud Identity and Access Management (IAM) e que usa credenciais de serviço para sua carga de trabalho de aplicativo, tarefa ou função. Para localizar uma lista de serviços do IBM Cloud suportados, consulte o catálogo do IBM Cloud.
Eu já tenho credenciais de serviço para uma instância de serviço do IBM Cloud. Posso usar essas credenciais com ligações de serviços do Code Engine?
Sim, é possível vincular uma instância de serviço a cargas de trabalh Code Engine es usando as credenciais de serviço existentes. A partir do console, é possível utilizar credenciais existentes que já são usadas em uma ligação de serviço. Para usar as credenciais de serviço existentes por meio da CLI, especifique a opção --service-credential no comando ibmcloud ce application bind, ibmcloud ce job bind ou ibmcloud ce function bind e forneça o nome de suas credenciais de serviço.
Que acesso é necessário para criar ligações de serviço?
Cada projeto do Code Engine deve ser configurado com um conjunto de políticas de acesso do IAM, que autorizam as ligações de serviço do Code Engine a visualizar instâncias de serviço e a visualizar e criar credenciais de serviço em sua conta. As políticas do IAM são fornecidas para a ligação de serviços do Code Engine com um ID de serviço. Para obter mais informações, consulte Configurando o acesso para ligações de serviço.
Há uma maneira de configurar operações de ligação de serviços para todos os usuários em um projeto?
Sim! Com permissões suficientes, é possível usar a página Integração no console para configurar operações de ligação de serviços de uma única página. Se você não tiver permissões suficientes para executar essas ações, será possível usar essa página para ajudar a entender as permissões necessárias. Consulte Definindo Configurações do Projeto.
Após ligar minha carga de trabalho do Code Engine a uma instância de serviço, qual é a vida dessa ligação de serviços?
Ao criar uma ligação entre a carga de trabalho do Code Engine e uma instância de serviço, a ligação de serviço estará ativa, desde que a carga de trabalho do Code Engine e a instância de serviço estejam ativas ou você não tenha concluído uma operação de desvinculação para remover a ligação de serviço. Se a instância de serviço for excluída, será necessário excluir manualmente a ligação de serviços Ao desvincular (ou remover) uma ligação de serviço, você está excluindo a associação do app, da tarefa ou da função com o segredo de acesso de serviço, de modo que o app, a tarefa ou a função não tenha mais acesso ao serviço IBM Cloud ligado anteriormente

Acessando uma instância de serviço ligada por meio de uma carga de trabalho do Code Engine

Code Engine fornece variáveis de ambiente para acessar instâncias de serviço que estão ligadas a sua carga de trabalho do Code Engine com os métodos CE_SERVICES e PREFIX.

  • A variável de ambiente CE_SERVICES é uma única variável de ambiente que contém todas as informações de ligação de serviço como um objeto JSON.

  • Code Engine também cria diversas variáveis de ambiente para a sua ligação de serviço, que são baseadas nas variáveis na credencial de serviço para sua instância de serviço. Para distinguir essas variáveis de ambiente múltipla para a sua ligação de serviço, você pode usar um PREFIX tal que essas variáveis de ambiente usam o mesmo prefixo. Se você não especificar um prefixo personalizado, Code Engine automaticamente gera um prefixo.

Se o seu aplicativo, tarefa ou função precisar se comunicar com um serviço vinculado por meio de uma rede privada e o serviço tiver pontos de extremidade tanto no formato private quanto no formato direct (como IBM Cloud Object Storage ), então os pontos de extremidade direct devem ser utilizados.

CE_SERVICESVariável de ambiente

A variável de ambiente CE_SERVICES contém informações que podem ser usadas para interagir com uma instância de serviço. Essa variável de ambiente aponta para um objeto JSON que contém pares chave-valor. Esses pares chave-valor representam cada tipo de serviço vinculado ao seu aplicativo, tarefa ou função. A key é o nome do tipo de serviço, como cloud-object-storage e o value é uma matriz de credenciais para instâncias de serviço de limite desse tipo.

O exemplo a seguir ilustra uma variável do 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 de prefixo

Com o método de prefixo, para cada variável de credencial em um objeto de credencial de serviço, essa variável é fornecida individualmente para seu ambiente usando a sintaxe de variável de ambiente comum de letras maiúsculas separadas por sublinhados, tal como VARIABLE_NAME.

Por padrão, o nome de variável é o nome do serviço, seguido pelo nome de variável de credencial. Por exemplo, uma variável de credenciais do serviço IBM Cloud Object Storage chamada apikey está disponível em uma variável de ambiente chamada CLOUD_OBJECT_STORAGE_APIKEY. O exemplo a seguir mostra as variáveis de ambiente criadas para uma ligação de instância de serviço do 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

Por padrão, se mais de uma instância do mesmo tipo for ligada a um único aplicativo, o Code Engine anexará um índice ao nome do serviço, como CLOUD_OBJECT_STORAGE_2_APIKEY.

Cada ligação de serviço pode ser configurada para usar um prefixo variável de ambiente personalizado. Se você estiver usando o console, você pode opcionalmente fornecer um prefixo quando você criar a ligação de serviço. Se você estiver usando a CLI, use a opção --prefix com o app bind, o job bind ou o comando function bind.

O que devo considerar se tenho ligações de serviço que usam a implementação anterior?

A CLI 1.27.0 apresentou uma implementação de ligação de serviço melhorada, que é usada para todas as ligações que são criadas com esta versão ou mais recente. Ligações de serviço que foram criadas com uma versão da CLI antes da CLI 1.27.0 estão usando a implementação de ligação de serviço anterior. Aplicativos, tarefas e funções que possuem ligações a serviços que utilizam a implementação anterior continuam a funcionar normalmente no que diz respeito ao acesso aos serviços vinculados. No entanto, se você deseja mudar as ligações de serviço que usam a implementação anterior, considere as informações a seguir.

  • Não é possível ter uma combinação de ligações de serviço da implementação anterior e da implementação aprimorada para o mesmo aplicativo, tarefa ou função. Antes de adicionar novas ligações de serviço a um aplicativo, tarefa ou função que já possua ligações de serviço que utilizem a implementação anterior, é necessário desligar todas essas ligações de serviço. Em seguida, é possível recriá-las com a implementação melhorada e incluir novas ligações de serviço.
  • Não é possível desvincular individualmente essas ligações de serviço. Deve-se remover todas elas usando o comando app unbind --all ou job unbind --all.
  • Se você estiver trabalhando com cargas de trabalho de Função, sua função usará automaticamente a implementação mais recente de ligações de serviço...

Para aproveitar os aprimoramentos mais recentes e continuar a gerenciar as ligações de serviço para seus apps e tarefas facilmente, atualize para a versão da CLI mais recente do IBM Cloud Code Engine e substitua as ligações de serviço que usam a implementação anterior.

Como posso substituir uma ligação de serviços que usa a implementação anterior?

Se o seu aplicativo ou tarefa tiver ligações de serviço que utilizem a implementação anterior e você quiser adicionar novas ligações de serviço ao seu aplicativo ou tarefa, é necessário primeiro remover as ligações que utilizam a implementação anterior antes de criar novas ligações. É possível recriar essas ligações de serviços existentes se necessário.

É possível que seu aplicativo não esteja totalmente funcional durante o processo de desvinculação e revinculação.

  1. Para verificar se seu aplicativo ou trabalho utiliza a implementação anterior das ligações de serviço, execute o app get ou job get. Se for utilizada a implementação anterior de vinculação de serviço, a saída deste comando fornece as informações e os comandos que você deve usar para vincular outro serviço ao aplicativo ou à tarefa. Por exemplo,

    ibmcloud ce app get --name myapp

    Exemplo de saída

    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

    Da mesma forma, se você estiver trabalhando com tarefas, execute o comando ibmcloud ce job get --name JOB_NAME para descobrir se ligações descontinuadas são usadas com sua tarefa.

  2. Desvincule as ligações de serviços existentes que usam a implementação anterior. A opção --all especifica para desvincular todas as instâncias de serviço para este aplicativo.

    ibmcloud ce app unbind --name APP_NAME --all

    Da mesma forma, se você estiver trabalhando com tarefas, execute o comando ibmcloud ce job unbind --name JOB_NAME --all para desvincular todas as instâncias de serviço para a sua tarefa.

  3. Criar novas ligações. Para criar novas ligações, execute o comando ibmcloud ce app bind ou ibmcloud ce job bind. Para substituir a ligação de serviços que usou a implementação anterior, use os comandos fornecidos na saída dos comandos app get ou job get. Por exemplo, para recriar uma ligação existente por meio do aplicativo Code Engine, myapp, para a instância de serviço do IBM Cloud Object Storage, myobjectstorage,

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

    Da mesma forma, se você estiver trabalhando com tarefas, execute o comando ibmcloud ce job bind --name JOB_NAME ---service-instance SERVICE_INSTANCE --prefix PREFIX.

    Repita essa etapa para cada ligação que você deseja recriar.

  4. (opcional) Executar o comando app get ou job get novamente. Desta vez, observe que a saída do comando não exibe as informações sobre ligações de serviço com uma implementação anterior. Por exemplo,

    ibmcloud ce app get --name myapp

    Exemplo de saída

    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óximas etapas

Antes de poder ligar uma instância de serviço a um app, tarefa ou carga de trabalho do Code Engine, deve-se configurar o acesso para ligações. Veja Configurando o acesso para ligações de serviço.