Compartilhar via

Integrar o IoT Central ao Azure Pipelines para integração contínua e entrega contínua

  • Artigo

A CI/CD (integração contínua e entrega contínua) refere-se ao processo de desenvolvimento e entrega de software em ciclos curtos e frequentes com o uso de pipelines de automação. Este artigo mostra como automatizar o build, 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 um commit do código em um branch de um repositório de código-fonte. Cada commit é mesclado com os commits de outros desenvolvedores a fim de garantir que nenhum conflito seja introduzido. As alterações são então validadas criando um build e executando testes automatizados nesse build. Esse processo, em última análise, 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 da sua solução de IoT mais ampla, o IoT Central faz parte do pipeline de CI/CD. O pipeline de CI/CD deve implantar toda a solução de IoT e todas as configurações em cada ambiente, do desenvolvimento à produção:

Diagrama que mostra os estágios de um pipeline de CI/CD típico.

O IoT Central é uma plataforma como serviço de aplicativo que tem requisitos de implantação diferentes dos componentes da plataforma como serviço. Para o IoT Central, você implanta configurações e modelos de dispositivo. Essas configurações e esses modelos de dispositivo são gerenciados e integrados ao pipeline de lançamento por meio de 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 de aplicativo do IoT Central ao pipeline de lançamento.

Este guia descreve como criar um pipeline que atualiza um aplicativo do IoT Central com base em arquivos de configuração gerenciados no GitHub. Ele traz instruções específicas para a integração ao Azure Pipelines, mas pode ser adaptado para incluir o IoT Central em qualquer pipeline de lançamento criado com ferramentas como o Tekton, o Jenkins, o GitLab ou o GitHub Actions.

Neste guia, você criará um pipeline que só aplica uma configuração do IoT Central a uma instância individual de um aplicativo do IoT Central. Você deve integrar as etapas em um pipeline maior que implanta toda a sua solução e a promove do desenvolvimento, passando pela garantia de qualidade e pela pré-produção à produção, executando todos os testes necessários ao longo do caminho.

Atualmente, os scripts não transferem as seguintes configurações entre as 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 registro.

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

Pré-requisitos

Você precisa dos seguintes pré-requisitos para seguir as etapas deste artigo:

Baixe o código de exemplo

Para começar, crie um fork do repositório GitHub de CI/CD do IoT Central e clone o fork no computador local:

  1. Para criar um fork do repositório do GitHub, abra o repositório GitHub de CI/CD do IoT Central e selecione Criar fork.

  2. Clone o fork do repositório no computador local abrindo um console ou uma janela do Bash e executando o comando a seguir.

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

Criar uma entidade 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 busca de 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 entidade de serviço:

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

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

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

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

  4. Conceda à entidade de serviço permissã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, o pipeline usará tokens de API para interagir com os aplicativos do IoT Central. Também é possível usar uma entidade de serviço.

Observação

Os tokens de API do IoT Central vencem após um ano.

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

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

  2. Selecione Novo.

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

  4. Anote o token de API do aplicativo de desenvolvimento do IoT Central. Você o usará mais tarde quando executar o script IoTC-Config.ps1.

  5. Salve o token gerado do aplicativo de produção do IoT Central como um segredo chamado API-Token no cofre de chaves 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

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

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

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

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

  3. Depois que você se conectar, o script exibirá o menu de opções Configuração de IoTC. O script pode gerar um arquivo de configuração com base em 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 gerado para o aplicativo de desenvolvimento do IoT Central.
    • O subdomínio do aplicativo de desenvolvimento do IoT Central.
    • Insira ..\Config\Dev como a pasta usada para armazenar o arquivo de configuração e os modelos de dispositivo.
    • O nome do cofre de chaves de desenvolvimento.

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

Modificar o arquivo de configuração

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

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

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

  3. O arquivo tem várias seções. No entanto, se o 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 o aplicativo usar uploads de arquivo, o script criará um segredo no cofre de chaves de desenvolvimento com o valor mostrado na propriedade connectionString. Crie um segredo com o mesmo nome no seu cofre de chaves de produção que contenha a cadeia de conexão da 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 o aplicativo usar 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 segredos reais o destino: os segredos são armazenados no cofre de chaves.

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

    Tipo de destino Propriedade a ser alterada
    Fila do Barramento de Serviço connectionString
    Tópico do Barramento de Serviço connectionString
    Azure Data Explorer clientSecret
    Armazenamento do Blobs do Azure connectionString
    Hubs de Eventos connectionString
    Webhook sem autenticação N/D

    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 Configuração no repositório GitHub, execute os comandos a seguir 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 projeto.
  3. Dê um nome e uma descrição opcional ao projeto e selecione Criar.
  4. Na página Boas-vindas ao projeto, selecione Pipelines e Criar Pipeline.
  5. Selecione GitHub como o local do código.
  6. Selecione Autorizar AzurePipelines para permitir que o Azure Pipelines acesse sua conta do GitHub.
  7. Na página Selecionar um repositório, escolha o fork do repositório GitHub de CI/CD do IoT Central.
  8. Quando precisar 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 será exibido para você editá-lo.

Criar um grupo de variáveis

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

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

  2. Selecione + Variable group.

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

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

  5. Escolha sua assinatura do Azure e a autorize. Em seguida, selecione o nome do cofre de chaves 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 do aplicativo de produção. Você chamou esse segredo de API-Token quando o criou.
    • A senha da entidade de serviço criada. Você chamou esse segredo de SP-Password quando o criou.

  8. Selecione OK.

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

Configurar seu pipeline

Agora, configure o pipeline para efetuar push das alterações de configuração para o aplicativo do IoT Central:

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

  2. Substitua o conteúdo do YAML do pipeline pelo YAML a seguir. A configuração pressupõe que o cofre de chaves de produção contenha:

    • O token de API do aplicativo de produção do IoT Central em um segredo chamado API-Token.
    • A senha da entidade de serviço em um segredo chamado SP-Password.

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

    Você fez uma anotação da -AppId e da -TenantId quando criou a 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 Salvar e executar.

  4. O arquivo YAML é salvo no repositório GitHu; ou seja, você precisa fornecer uma mensagem de commit e selecionar Salvar e executar novamente.

Seu pipeline foi colocado na fila. Pode levar alguns minutos para que ele seja executado.

Na primeira vez que você executar seu pipeline, você precisará fornecer permissões para que o pipeline acesse sua assinatura e o cofre de chaves. Selecione Permitir e Permitir novamente para cada recurso.

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

Promover alterações de desenvolvimento para produção

Agora que você tem um pipeline funcional, poderá gerenciar suas instâncias do IoT Central diretamente usando alterações de configuração. Carregue novos modelos de dispositivo na pasta Modelos de Dispositivo e faça alterações diretamente no arquivo de configuração. Essa abordagem permite tratar a configuração do aplicativo do IoT Central da mesma forma que qualquer outro código.

Próxima etapa

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