Integre o IoT Central com o Azure Pipelines para integração contínua e entrega contínua

Integração contínua e entrega contínua (CI/CD) refere-se ao processo de desenvolvimento e entrega de software em ciclos curtos e frequentes usando pipelines de automação. Este artigo mostra como automatizar a compilação, o teste e a implantação de uma configuração de aplicativo do IoT Central. Essa automação permite que as equipes de desenvolvimento forneçam versões confiáveis com mais frequência.

A integração contínua começa com uma confirmação do seu código para uma ramificação em um repositório de código-fonte. Cada confirmação é mesclada com confirmações de outros desenvolvedores para garantir que nenhum conflito seja introduzido. As alterações são validadas criando uma compilação e executando testes automatizados em relação a essa compilação. Em última análise, esse processo resulta em um artefato, ou pacote de implantação, para implantar em um ambiente de destino. Nesse caso, o destino é um aplicativo do Azure IoT Central.

Assim como o IoT Central faz parte de sua solução de IoT maior, o IoT Central faz parte do seu pipeline de CI/CD. Seu pipeline de CI/CD deve implantar toda a sua solução de IoT e todas as configurações em cada ambiente, desde o desenvolvimento até a produção:

O IoT Central é uma plataforma de aplicativos como um serviço que tem requisitos de implantação diferentes dos componentes de plataforma como serviço . Para o IoT Central, você implanta configurações e modelos de dispositivo. Essas configurações e modelos de dispositivo são gerenciados e integrados ao seu pipeline de liberação usando APIs.

Embora seja possível automatizar a criação de aplicativos do IoT Central, você deve criar um aplicativo em cada ambiente antes de desenvolver seu pipeline de CI/CD.

Usando a API REST do Azure IoT Central, você pode integrar as configurações do aplicativo IoT Central ao seu pipeline de lançamento.

Este guia orienta você pela criação de um novo pipeline que atualiza um aplicativo do IoT Central com base em arquivos de configuração gerenciados no GitHub. Este guia tem instruções específicas para integração com o Azure Pipelines, mas pode ser adaptado para incluir o IoT Central em qualquer pipeline de versão criado usando ferramentas como Tekton, Jenkins, GitLab ou GitHub Actions.

Neste guia, você cria um pipeline que só aplica uma configuração do IoT Central a uma única instância de um aplicativo do IoT Central. Você deve integrar as etapas em um pipeline maior que implante toda a sua solução e a promova, desde o desenvolvimento até o controle de qualidade, a pré-produção e a produção, realizando todos os testes necessários ao longo do caminho.

Atualmente, os scripts não transferem as seguintes configurações entre instâncias do IoT Central: painéis, exibições, configurações personalizadas em modelos de dispositivo, plano de preços, personalizações de UX, imagem do aplicativo, regras, trabalhos agendados, trabalhos salvos e grupos de inscrição.

Atualmente, os scripts não removem as configurações do aplicativo IoT Central de destino que não estão presentes no arquivo de configuração.

Pré-requisitos

Você precisa dos seguintes pré-requisitos para concluir as etapas neste guia:

• Dois aplicativos IoT Central - um para seu ambiente de desenvolvimento e outro para seu ambiente de produção. Para saber mais, consulte Criar um aplicativo do IoT Central.
• Dois Cofres de Chaves do Azure - um para seu ambiente de desenvolvimento e outro para seu ambiente de produção. É uma prática recomendada ter um Cofre de Chaves dedicado para cada ambiente. Para saber mais, consulte Criar um Cofre da Chave do Azure com o portal do Azure.
• Uma conta GitHub GitHub.
• Uma organização Azure DevOps. Para saber mais, consulte Criar uma organização do Azure DevOps.
• PowerShell 7 para Windows, Mac ou Linux. Obtenha o PowerShell.
• Módulo Azure Az PowerShell instalado em seu ambiente do PowerShell 7. Para saber mais, consulte Instalar o módulo Azure Az PowerShell.
• Visual Studio Code ou outra ferramenta para editar arquivos PowerShell e JSON.Obtenha o Visual Studio Code.
• Cliente Git. Faça o download da última versão do Git - Downloads (git-scm.com).

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

  • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Faça o download do código de exemplo

Para começar, bifurque o repositório GitHub do IoT Central CI/CD e, em seguida, clone a bifurcação para a máquina local:

1. Para bifurcar o repositório GitHub, abra o repositório GitHub do IoT Central CI/CD e selecione Fork.

2. Clone sua bifurcação do repositório para sua máquina local abrindo uma janela de console ou bash e executando o seguinte comando.

   git clone https://github.com/{your GitHub username}/iot-central-CICD-sample
   

Criar um principal de serviço

Embora o Azure Pipelines possa se integrar diretamente a um cofre de chaves, um pipeline precisa de uma entidade de serviço para algumas interações dinâmicas do cofre de chaves, como buscar segredos para destinos de exportação de dados.

Para criar uma entidade de serviço com escopo para sua assinatura:

1. Execute o seguinte comando para criar uma nova entidade de serviço:

   az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor
   

2. Anote a senha, o appId e o locatário conforme precisar desses valores mais tarde.

3. Adicione a senha da entidade de serviço como um segredo chamado SP-Password ao cofre da chave de produção:

   az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}
   

4. Dê permissão à entidade de serviço para ler segredos do cofre de chaves:

   az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}
   

Gerar tokens de API do IoT Central

Neste guia, seu pipeline usa tokens de API para interagir com seus aplicativos do IoT Central. Também é possível usar uma entidade de serviço.

Nota

Os tokens da API do IoT Central expiram após um ano.

Conclua as etapas a seguir para seus aplicativos IoT Central de desenvolvimento e produção.

1. No aplicativo IoT Central, selecione Permissões e, em seguida , Tokens de API.

2. Selecione Novo.

3. Dê um nome ao token, especifique a organização de nível superior em seu aplicativo e defina a função como Administrador do aplicativo.

4. Anote o token de API do seu aplicativo IoT Central de desenvolvimento. Você usá-lo mais tarde quando você executa o script IoTC-Config.ps1 .

5. Salve o token gerado do aplicativo IoT Central de produção como um segredo chamado API-Token para o cofre da chave de produção:

   az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'
   

Gerar um arquivo de configuração

Essas etapas produzem um arquivo de configuração JSON para seu ambiente de desenvolvimento com base em um aplicativo existente do IoT Central. Você também baixa todos os modelos de dispositivo existentes do aplicativo.

1. Execute o seguinte script do PowerShell 7 na cópia local do repositório do IoT Central CI/CD:

   cd .\iot-central-CICD-sample\PowerShell\
   .\IoTC-Config.ps1
   

2. Siga as instruções para entrar na sua conta do Azure.

3. Depois de entrar, o script exibe o menu de opções de configuração do IoTC. O script pode gerar um arquivo de configuração de um aplicativo existente do IoT Central e aplicar uma configuração a outro aplicativo do IoT Central.

4. Selecione a opção 1 para gerar um arquivo de configuração.

5. Insira os parâmetros necessários e pressione Enter:

   • O token de API que você gerou para seu aplicativo IoT Central de desenvolvimento.
   • O subdomínio do seu aplicativo IoT Central de desenvolvimento.
   • Digite .. \Config\Dev como a pasta para armazenar o arquivo de configuração e os modelos de dispositivo.
   • O nome do cofre da chave de desenvolvimento.

6. O script cria uma pasta chamada IoTC Configuration na pasta Config\Dev em sua cópia local do repositório. Esta pasta contém um arquivo de configuração e uma pasta chamada Modelos de Dispositivo para todos os modelos de dispositivo em seu aplicativo.

Modificar o arquivo de configuração

Agora que você tem um arquivo de configuração que representa as configurações para sua instância de aplicativo IoT Central de desenvolvimento, faça as alterações necessárias antes de aplicar essa configuração à sua instância de aplicativo IoT Central de produção.

1. Crie uma cópia da pasta Dev criada anteriormente e chame-a de Produção.

2. Abra IoTC-Config.json na pasta Produção usando um editor de texto.

3. O arquivo tem várias seções. No entanto, se seu aplicativo não usar uma configuração específica, essa seção será omitida do arquivo:

   {
     "APITokens": {
       "value": [
         {
           "id": "dev-admin",
           "roles": [
             {
               "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
             }
           ],
           "expiry": "2023-05-31T10:47:08.53Z"
         }
       ]
     },
     "data exports": {
       "value": [
         {
           "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
           "displayName": "All telemetry to blob storage",
           "enabled": false,
           "source": "telemetry",
           "destinations": [
             {
               "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
             }
           ],
           "status": "notStarted"
         }
       ]
     },
     "device groups": {
       "value": [
         {
           "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
           "displayName": "MXCHIP Getting Started Guide - All devices"
         },
         {
           "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
           "displayName": "RS40 Occupancy Sensor - All devices"
         },
         {
           "id": "dd87877d-9465-410b-947e-64167a7a1c39",
           "displayName": "Cascade 500 - All devices"
         },
         {
           "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
           "displayName": "Simulated devices"
         }
       ]
     },
     "organizations": {
       "value": []
     },
     "roles": {
       "value": [
         {
           "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
           "displayName": "Builder"
         },
         {
           "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
           "displayName": "Administrator"
         },
         {
           "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
           "displayName": "Operator"
         }
       ]
     },
     "destinations": {
       "value": [
         {
           "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
           "displayName": "Blob destination",
           "type": "blobstorage@v1",
           "authorization": {
             "type": "connectionString",
             "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
             "containerName": "dataexport"
           },
           "status": "waiting"
         }
       ]
     },
     "file uploads": {
       "connectionString": "FileUpload",
       "container": "fileupload",
       "sasTtl": "PT1H"
     },
     "jobs": {
       "value": []
     }
   }
   

4. Se seu aplicativo usa uploads de arquivos, o script cria um segredo no cofre da chave de desenvolvimento com o valor mostrado na connectionString propriedade. Crie um segredo com o mesmo nome no cofre da chave de produção que contenha a cadeia de conexão para sua conta de armazenamento de produção. Por exemplo:

   az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
   

5. Se seu aplicativo usa exportações de dados, adicione segredos para os destinos ao cofre de chaves de produção. O arquivo de configuração não contém nenhum segredo real para o seu destino, os segredos são armazenados no seu cofre de chaves.

6. Atualize os segredos no arquivo de configuração com o nome do segredo no cofre de chaves.

   Tipo de destino	Imóvel a alterar
   Fila do Service Bus	connectionString
   Tópico do Service Bus	connectionString
   Azure Data Explorer	clientSecret
   Armazenamento de Blobs do Azure	connectionString
   Hubs de Eventos	connectionString
   Webhook Sem Auth	N/A

   Por exemplo:

   "destinations": {
     "value": [
       {
         "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
         "displayName": "Blob destination",
         "type": "blobstorage@v1",
         "authorization": {
           "type": "connectionString",
           "connectionString": "Storage-CS",
           "containerName": "dataexport"
         },
         "status": "waiting"
       }
     ]
   }
   

7. Para carregar a pasta Configuration no repositório GitHub, execute os seguintes comandos na pasta IoTC-CICD-howto .

    git add Config
    git commit -m "Adding config directories and files"
    git push
   

Criar um pipeline

1. Abra sua organização do Azure DevOps em um navegador da Web acessando https://dev.azure.com/{your DevOps organization}
2. Selecione Novo projeto para criar um novo projeto.
3. Dê ao seu projeto um nome e uma descrição opcional e, em seguida, selecione Criar.
4. Na página Bem-vindo ao projeto, selecione Pipelines e, em seguida, Create Pipeline.
5. Selecione GitHub como o local do seu código.
6. Selecione Autorizar AzurePipelines para autorizar o Azure Pipelines a acessar sua conta do GitHub.
7. Na página Selecione um repositório, selecione sua bifurcação do repositório GitHub do IoT Central CI/CD.
8. Quando solicitado a fazer logon no GitHub e fornecer permissão para o Azure Pipelines acessar o repositório, selecione Aprovar e instalar.
9. Na página Configurar seu pipeline, selecione Pipeline inicial para começar. O azure-pipelines.yml é exibido para você editar.

Criar um grupo de variáveis

Uma maneira fácil de integrar segredos do cofre de chaves em um pipeline é por meio de grupos variáveis. Use um grupo de variáveis para garantir que os segredos certos estejam disponíveis para seu script de implantação. Para criar um grupo de variáveis:

1. Selecione Biblioteca na seção Pipelines do menu à esquerda.

2. Selecione + Grupo de variáveis.

3. Insira keyvault como o nome do seu grupo de variáveis.

4. Habilite a alternância para vincular segredos de um cofre de chaves do Azure.

5. Selecione sua assinatura do Azure e autorize-a. Em seguida, selecione o nome do cofre da chave de produção.

6. Selecione Adicionar para começar a adicionar variáveis ao grupo.

7. Adicione os seguintes segredos:

   • A chave de API do IoT Central para seu aplicativo de produção. Você chamou esse segredo API-Token quando o criou.
   • A senha da entidade de serviço criada anteriormente. Você chamou esse segredo SP-Password quando o criou.

8. Selecione OK.

9. Selecione Salvar para salvar o grupo de variáveis.

Configure seu pipeline

Agora, configure o pipeline para enviar por push alterações de configuração para seu aplicativo IoT Central:

1. Selecione Pipelines na seção Pipelines do menu à esquerda.

2. Substitua o conteúdo do seu pipeline YAML pelo seguinte YAML. A configuração pressupõe que o cofre da chave de produção contém:

   • O token de API para seu aplicativo IoT Central de produção em um segredo chamado API-Token.
   • Sua senha principal de serviço em um segredo chamado SP-Password.

   Substitua os valores para -AppName e -KeyVault pelos valores apropriados para suas instâncias de produção.

   Você anotou o e -TenantId quando criou sua -AppId entidade de serviço.

   trigger:
   - master
   variables:
   - group: keyvault
   - name: buildConfiguration
     value: 'Release'
   steps:
   - task: PowerShell@2
     displayName: 'IoT Central'
     inputs:
       filePath: 'PowerShell/IoTC-Task.ps1'
       arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
       pwsh: true
       failOnStderr:  true
   

3. Selecione Guardar e executar.

4. O arquivo YAML é salvo no repositório GitHub, então você precisa fornecer uma mensagem de confirmação e, em seguida, selecionar Salvar e executar novamente.

Seu pipeline está na fila. Pode demorar alguns minutos até ser executado.

Na primeira vez que executar o pipeline, você será solicitado a conceder permissões para que o pipeline acesse sua assinatura e acesse seu cofre de chaves. Selecione Permitir e, em seguida, Permitir novamente para cada recurso.

Quando o trabalho de pipeline for concluído com êxito, entre no aplicativo IoT Central de produção e verifique se a configuração foi aplicada conforme o esperado.

Promover mudanças do desenvolvimento à produção

Agora que você tem um pipeline em funcionamento, pode gerenciar suas instâncias do IoT Central diretamente usando alterações de configuração. Você pode carregar novos modelos de dispositivo na pasta Modelos de dispositivo e fazer alterações diretamente no arquivo de configuração. Essa abordagem permite que você trate a configuração do seu aplicativo IoT Central da mesma forma que qualquer outro código.

Próximo passo

Agora que você sabe como integrar as configurações do IoT Central em seus pipelines de CI/CD, uma próxima etapa sugerida é aprender a gerenciar e monitorar aplicativos do IoT Central.