Utilizar a ação de início de sessão do Azure com a CLI do Azure e o PowerShell no Azure Stack Hub

  • Artigo

Pode configurar GitHub Actions para iniciar sessão na instância do Azure Stack Hub, executar o PowerShell e, em seguida, executar um script da CLI do Azure. Pode utilizá-lo como base de um fluxo de trabalho de integração contínua e implementação contínua (CI/CD) para a sua solução com o Azure Stack Hub. Com este fluxo de trabalho, pode automatizar a criação, teste e implementação da sua solução para que se possa concentrar na escrita de código. Por exemplo, ao adicionar outras ações, pode utilizar este fluxo de trabalho juntamente com um modelo do Azure Resource Manager para aprovisionar uma VM, validar um repositório de aplicações e, em seguida, implementar uma aplicação nessa VM sempre que intercalar num ramo específico no GitHub. Por enquanto, este artigo irá ajudá-lo a ser orientado com GitHub Actions e o Azure Stack Hub.

GitHub Actions são fluxos de trabalho compostos por ações que permitem a automatização diretamente dentro do repositório de código. Pode acionar os fluxos de trabalho com eventos no seu processo de desenvolvimento do GitHub. Pode realizar tarefas comuns de automatização de DevOps, como testes, implementação e integração contínua.

Para utilizar GitHub Actions com o Azure Stack Hub, tem de utilizar um principal de serviço (SPN) com requisitos específicos. Neste artigo, irá criar um corredor autoalojado. O GitHub permite-lhe utilizar qualquer computador que possa ser acedido pelo GitHub no seu GitHub Actions. Pode criar uma máquina virtual (VM) como corredora no Azure, no Azure Stack Hub ou noutro local.

Este fluxo de trabalho de exemplo inclui:

  • Instruções sobre como criar e validar o SPN.
  • Configurar um computador principal do Windows 2016 Server como GitHub Actions executor autoalojado para trabalhar com o Azure Stack Hub.
  • Um fluxo de trabalho que utiliza:
    • A ação Início de Sessão do Azure
    • A ação de script do PowerShell

GitHub Actions do Azure Stack Hub

O diagrama seguinte mostra os diferentes ambientes e as respetivas relações.

Ação do Github do Azure Stack Hub Partes da utilização do corredor autoalojado:

  • GitHub Actions alojados no GitHub
  • Corredor autoalojado alojado no Azure
  • Azure Stack Hub

Uma limitação da utilização de GitHub Actions com o Azure Stack Hub é que o processo requer a utilização de um Azure Stack Hub ligado à Web. O fluxo de trabalho é acionado num repositório do GitHub. Pode utilizar o Microsoft Entra ID ou os Serviços Federados do Active Directory (AD FS) como fornecedor de identidade.

Embora isto esteja fora do âmbito deste artigo, o seu corredor autoalojado também pode utilizar uma rede privada virtual para ligar ao Azure Stack Hub atrás de uma firewall.

Obter principal de serviço

Um SPN fornece credenciais baseadas em funções para que os processos fora do Azure possam ligar-se e interagir com recursos. Precisará de um SPN com acesso de contribuidor e os atributos especificados nestas instruções para utilizar com a sua GitHub Actions.

Como utilizador do Azure Stack Hub, não tem permissão para criar o SPN. Terá de pedir este princípio ao operador da cloud. As instruções estão a ser fornecidas aqui para que possa criar o SPN se for um operador da cloud ou se puder validar o SPN se for um programador a utilizar um SPN no seu fluxo de trabalho fornecido por um operador da cloud.

O operador da cloud terá de criar o SPN com a CLI do Azure.

Os fragmentos de código seguintes são escritos para um computador Windows com a linha de comandos do PowerShell com a CLI do Azure. Se estiver a utilizar a CLI num computador Linux e o bash, remova a extensão de linha ou substitua-a por um \.

  1. Prepare os valores dos seguintes parâmetros utilizados para criar o SPN:

    Parâmetro Exemplo Descrição
    endpoint-resource-manager "https://management.orlando.azurestack.corp.microsoft.com" O ponto final de gestão de recursos.
    sufixo-storage-endpoint "orlando.azurestack.corp.microsoft.com" O sufixo de ponto final para contas de armazenamento.
    sufixo-keyvault-dns ".vault.orlando.azurestack.corp.microsoft.com" O sufixo dns do serviço Key Vault.
    endpoint-active-directory-graph-resource-id "https://graph.windows.net/" O ID de recurso do Active Directory.
    endpoint-sql-management https://notsupported O ponto final de gestão do sql server. Defina esta opção como https://notsupported
    perfil 09-09-2020-01-hybrid Perfil a utilizar para esta cloud.

  2. Abra a sua ferramenta de linha de comandos, como Windows PowerShell ou Bash e inicie sessão. Utilize o seguinte comando:

    az login

  3. Utilize o register comando para um novo ambiente ou o update comando se utilizar um ambiente existente. Utilize o seguinte comando.

    az cloud register `
    -n "AzureStackUser" `
    --endpoint-resource-manager "https://management.<local>.<FQDN>" `
    --suffix-storage-endpoint ".<local>.<FQDN>" `
    --suffix-keyvault-dns ".vault.<local>.<FQDN>" `
    --endpoint-active-directory-graph-resource-id "https://graph.windows.net/" `
    --endpoint-sql-management https://notsupported  `
    --profile 2020-09-01-hybrid

  4. Obtenha o ID da subscrição e o grupo de recursos que pretende utilizar para o SPN.

  5. Crie o SPN com o seguinte comando com o ID da subscrição e o grupo de recursos:

    az ad sp create-for-rbac --name "myApp" --role contributor `
    --scopes /subscriptions/{subscription-id}/resourceGroups/{resource-group} `
    --sdk-auth

  6. Verifique o objeto JSON resultante. Irá utilizar o objeto JSON para criar o segredo no seu repositório do GitHub que contém a sua ação. O objeto JSON deve ter os seguintes atributos:

    {
  "clientId": <Application ID for the SPN>,
  "clientSecret": <Client secret for the SPN>,
  "subscriptionId": <Subscription ID for the SPN>,
  "tenantId": <Tenant ID for the SPN>,
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com/",
  "resourceManagerEndpointUrl": "https://management.<FQDN>",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://notsupported",
  "galleryEndpointUrl": "https://providers.<FQDN>:30016/",
  "managementEndpointUrl": "https://management.<FQDN>"
}

Adicionar principal de serviço ao repositório

Pode utilizar segredos do GitHub para encriptar informações confidenciais a utilizar nas suas ações. Irá criar um segredo para conter o SPN para que a ação possa iniciar sessão na instância do Azure Stack Hub.

Aviso

O GitHub recomenda que não utilize corredores autoalojados com forks de repositórios públicos do seu repositório público que executem código perigoso no seu computador de execução autoalojado ao criar um pedido Pull que executa o código num fluxo de trabalho. Para obter mais informações, consulte "Acerca dos corredores autoalojados".

  1. Abra ou crie um repositório do GitHub. Se precisar de orientação sobre como criar um repositório no GitHub, pode encontrar instruções nos documentos do GitHub.
  2. Defina o seu repositório como privado.
    1. Selecione Definições>Alterar visibilidade do repositório.
    2. Selecione Tornar privado.
    3. Escreva o nome do seu repositório.
    4. Selecione Compreendo, altere a visibilidade do repositório.
  3. Selecione Definições.
  4. Selecione Segredos.
  5. Selecione Novo segredo do repositório. Adicionar o seu segredo de GitHub Actions
  6. Atribua um nome ao segredo AZURE_CREDENTIALS.
  7. Cole o objeto JSON que representa o SPN.
  8. Selecione Add secret (Adicionar segredo).

Criar a VM e instalar os pré-requisitos

  1. Crie o seu corredor autoalojado.

    Estas instruções criam um corredor como uma VM do Windows no Azure. Se precisar de se ligar ao Azure Stack Hub alojado num datacenter, poderá necessitar de uma ligação VPN. Pode encontrar instruções sobre como ativar a ligação na secção Instalar as Ferramentas do Azure Stack Hub no seu corredor autoalojado que pode necessitar de uma ligação VPN.

  2. Utilize uma ligação remota para ligar ao servidor do Windows 2016 com o endereço IP do servidor, o nome de utilizador e a palavra-passe que definiu ao criar o computador.

  3. Instale o Chocolatey. O Chocolatey é um gestor de pacotes para Windows que pode utilizar para instalar e gerir dependências a partir da linha de comandos. A partir de uma linha de comandos elevada do PowerShell, escreva:

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

  4. Instale o PowerShell Core. A partir de uma linha de comandos elevada do PowerShell, escreva:

    choco install powershell-core

  5. Instalar a CLI do Azure. A partir de uma linha de comandos elevada do PowerShell, escreva:

    choco install azure-cli

  6. Instale o PowerShell do Azure Stack Hub. A partir de uma linha de comandos elevada do PowerShell, escreva:

    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Install-Module -Name Az.BootStrapper -Force -AllowPrerelease
Install-AzProfile -Profile 2020-09-01-hybrid -Force
Install-Module -Name AzureStack -RequiredVersion 2.0.2-preview -AllowPrerelease

    Para obter mais informações sobre como utilizar os módulos Az do Azure Stack Hub, veja Instalar o módulo Az do PowerShell para o Azure Stack Hub.

  7. Reinicie o computador. A partir de uma linha de comandos elevada do PowerShell, escreva:

    shutdown /r

  8. Adicione a máquina como um corredor autoalojado ao seu repositório do GitHub. Pode encontrar instruções sobre como adicionar um corredor autoalojado nos documentos do GitHub. Para obter mais informações, consulte Adicionar corredores autoalojados.

    O corredor está a ouvir

  9. Quando terminar, verifique se o serviço está em execução e a escutar o seu serviço. Verifique novamente ao correr /run.cmd a partir do diretório do corredor.

Opcional: Instalar as Ferramentas do Azure Stack Hub no seu corredor autoalojado

As instruções neste artigo não requerem acesso às Ferramentas do Azure Stack Hub, mas à medida que desenvolve o seu próprio fluxo de trabalho, poderá ter de utilizar as ferramentas. As seguintes instruções podem ajudá-lo a instalar as ferramentas no seu corredor autoalojado do Windows. Para obter mais informações sobre as Ferramentas do Azure Stack Hub, veja Transferir as Ferramentas do Azure Stack Hub a partir do GitHub. Estas instruções partem do princípio de que instalou o gestor de pacotes Chocolatey.

  1. Instale o Git.

    choco install git

  2. A partir de uma linha de comandos elevada do PowerShell, escreva:

    # Change directory to the root directory.
cd \

# Download the tools archive.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 
invoke-webrequest `
  https://github.com/Azure/AzureStack-Tools/archive/az.zip `
  -OutFile az.zip

# Expand the downloaded files.
expand-archive az.zip `
  -DestinationPath . `
  -Force

# Change to the tools directory.
cd AzureStack-Tools-az

  3. Se precisar que o seu corredor se ligue à sua instância do Azure Stack Hub, pode utilizar o PowerShell. Pode encontrar as instruções no artigo Ligar ao Azure Stack Hub com o PowerShell.

Criar um corredor autoalojado

Pode configurar um corredor autoalojado no GitHub Docs. Um corredor autoalojado pode ser executado em qualquer computador que se possa ligar ao GitHub. Pode optar por utilizar um corredor autoalojado se tiver uma tarefa de automatização no seu fluxo de trabalho que necessite de dependências extensas, requisitos de licenciamento específicos, como um dongle USB para uma licença de software ou outras necessidades específicas do computador ou software. O computador pode ser um computador físico, uma VM ou um contentor. Pode colocar o corredor no seu datacenter ou na cloud.

Neste artigo, vai utilizar uma VM do Windows alojada no Azure que será configurada com requisitos específicos do PowerShell do Azure Stack Hub.

Para obter instruções sobre como configurar e ligar o seu corredor autoalojado ao seu repositório, consulte o GitHub Docs, "Acerca dos corredores autoalojados".

Corredor autoalojado ligado

Anote o nome e as etiquetas do seu corredor autoalojado. O fluxo de trabalho neste artigo irá chamá-lo com a etiqueta self-hosted.

Adicionar o fluxo de trabalho ao seu repositório

Crie um novo fluxo de trabalho com o yaml nesta secção para criar o fluxo de trabalho.

  1. Abra o seu repositório do GitHub.

  2. Selecione Ações.

  3. Criar um novo fluxo de trabalho.

    • Se este for o seu primeiro fluxo de trabalho, selecione configurar um fluxo de trabalho manualmente em Escolher um modelo de fluxo de trabalho.
    • Se tiver fluxos de trabalho existentes, selecione Novo fluxo de> trabalhoConfigurar um fluxo de trabalho manualmente.

  4. No caminho, atribua o nome ao ficheiro workflow.yml.

  5. Copie e cole o yml do fluxo de trabalho.

    on: [push]

env:
  ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'

jobs: 
  azurestack-test:
    runs-on: self-hosted
    steps:

      - name: Login to AzureStack with Az Powershell
        uses: azure/login@releases/v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          environment: 'AzureStack'
          enable-AzPSSession: true

      - name: Run Az PowerShell Script Against AzureStack
        uses: azure/powershell@v1
        with:
          azPSVersion: '3.1.0'
          inlineScript: |
            hostname
            Get-AzContext
            Get-AzResourceGroup

      - name: Login to AzureStack with CLI
        uses: azure/login@releases/v1
        with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}
          environment: 'AzureStack'
          enable-AzPSSession: false

      - name: Run Azure CLI Script Against AzureStack
        run: |
          hostname
          az group list --output table

  6. Selecione Start commit (Iniciar consolidação).

  7. Adicione o título da consolidação e os detalhes opcionais e, em seguida, selecione Consolidar novo ficheiro.

Quando a ação for executada, verifique se foi executada com êxito.

  1. Abra o seu repositório do GitHub. Pode acionar o fluxo de trabalho ao enviar para o repositório.

  2. Selecione Ações.

  3. Selecione o nome da consolidação em Todos os fluxos de trabalho.

    Rever o resumo da consolidação

  4. Selecione o nome da tarefa, azurestack-test.

    Rever detalhes de consolidação

  5. Expanda as secções para rever os valores devolvidos para os comandos do PowerShell e da CLI.

Notas sobre o ficheiro de fluxo de trabalho e a ação:

  • O fluxo de trabalho contém uma única tarefa chamada azurestack-test.
  • Um evento push aciona o fluxo de trabalho.
  • A ação utiliza um corredor autoalojado que foi configurado no repositório e é chamado pela etiqueta do corredor no fluxo de trabalho com a linha : runs on: self-hosted.
  • O fluxo de trabalho contém três ações.
  • A primeira ação chama a ação De início de sessão do Azure para iniciar sessão com o PowerShell Com GitHub Actions para o Azure, pode criar fluxos de trabalho que pode configurar no seu repositório para criar, testar, empacotar, lançar e implementar no Azure. Esta ação utiliza as credenciais do SPN do Azure Stack para ligar e abrir uma sessão no ambiente do Azure Stack Hub. Pode encontrar mais informações sobre como utilizar a ação no GitHub, Ação de Início de Sessão do Azure.
  • A segunda ação utiliza Azure PowerShell. A ação utiliza os módulos do Az PowerShell e funciona com clouds do Government e do Azure Stack Hub. Depois de executar este fluxo de trabalho, reveja a tarefa para validar que o script recolheu os grupos de recursos no seu ambiente do Azure Stack Hub. Para obter mais informações, veja Ação Azure PowerShell
  • A terceira ação utiliza a CLI do Azure para iniciar sessão e ligar ao Azure Stack Hub para recolher grupos de recursos. Para obter mais informações, veja Ação da CLI do Azure.
  • Para obter mais informações sobre como trabalhar com GitHub Actions e um corredor autoalojado, veja a documentação do GitHub Actions.

Passos seguintes