Como criar artefatos personalizados para o pacote de configuração de computador

  • Artigo

Antes de começar, é uma boa ideia fazer a leitura da página de visão geral da configuração de computador.

A configuração de máquina usa Desired State Configuration (DSC) ao auditar e configurar o Windows e o Linux. A configuração DSC define a condição em que o computador deve estar.

Importante

Os pacotes personalizados que auditam o estado de um ambiente e aplicam configurações estão no status de suporte Disponibilidade Geral (GA). No entanto, as seguintes limitações se aplicam:

Para usar pacotes de configuração de máquina que aplicam configurações, é necessária a extensão de configuração de convidado da VM do Azure versão 1.26.24 ou posterior, ou Arc agent 1.10.0 ou posterior.

O módulo GuestConfiguration está disponível apenas no Ubuntu 18 e posterior. No entanto, o pacote e as políticas produzidas pelo módulo podem ser usadas em qualquer distribuição e versão do Linux com suporte no Azure ou no Arc.

Os pacotes de teste no macOS não estão disponíveis.

Não use informações confidenciais ou segredos em pacotes de conteúdo personalizados.

Use as etapas a seguir para criar sua configuração para gerenciar o estado de um computador que tem ou não o Azure.

Instale o PowerShell 7 e os módulos necessários do PowerShell

Primeiro, siga as etapas em Como configurar um ambiente de criação de configuração de máquina. Essas etapas ajudam você a instalar a versão necessária do PowerShell para o sistema operacional, o módulo GuestConfiguration e o módulo PSDesiredStateConfiguration.

Criar uma configuração

Antes de criar um pacote de configurações, crie e compile uma configuração DSC. Exemplos de configurações estão disponíveis para Windows e Linux.

Importante

Ao compilar as configurações para Windows, use PSDesiredStateConfiguration versão 2.0.7 (a versão estável). Ao compilar configurações para Linux, instale a versão de pré-lançamento 3.0.0.

Esta configuração de exemplo é para computadores Windows. Ela configura o computador para criar a variável de ambiente MC_ENV_EXAMPLE nos escopos Process e Machine. O valor da variável é definido como 'This was set by machine configuration'.

Configuration MyConfig {
    Import-DscResource -Name 'Environment' -ModuleName 'PSDscResources'
    Environment MachineConfigurationExample {
        Name   = 'MC_ENV_EXAMPLE'
        Value  = 'This was set by machine configuration'
        Ensure = 'Present'
        Target = @('Process', 'Machine')
    }
}

MyConfig

Com essa definição salva no arquivo de script MyConfig.ps1, você pode executar o script para compilar a configuração.

. .\MyConfig.ps1

    Directory: C:\dsc\MyConfig

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           5/16/2023 10:39 AM           1080 localhost.mof

A configuração é compilada no arquivo localhost.mof na pasta MyConfig no diretório de trabalho atual. Renomeie localhost.mof para o nome que você quer usar como o nome do pacote, como MyConfig.mof.

Rename-Item -Path .\MyConfig\localhost.mof -NewName MyConfig.mof -PassThru

    Directory: C:\dsc\MyConfig

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           5/16/2023 10:40 AM           1080 MyConfig.mof

Observação

Este exemplo mostra como criar e compilar uma configuração para um computador Windows. Para Linux, você precisa criar um módulo de recurso DSC personalizado usando as classes do PowerShell. O artigo Gravando um recurso com DSC personalizada com classes do PowerShell inclui um exemplo completo de recurso e configuração personalizados, testados com a configuração da máquina.

O restante deste artigo se aplica às configurações definidas para computadores Linux e Windows, exceto quando menciona considerações específicas da plataforma.

Criar um artefato de pacote de configuração

Depois que o MOF é compilado, os arquivos de suporte devem ser empacotados juntos. O pacote fechado é usado pela configuração de computador para criar as definições do Azure Policy.

O cmdlet New-GuestConfigurationPackage cria um pacote. Os módulos exigidos pela configuração devem estar disponíveis em $Env:PSModulePath para o ambiente de desenvolvimento, para que os comandos no módulo possam adicioná-los ao pacote.

Parâmetros do cmdlet New-GuestConfigurationPackage ao criar um conteúdo do Windows:

  • Nome: o nome do pacote da configuração de computador.
  • Configuração: caminho completo do documento com a configuração DSC compilada.
  • Caminho: caminho da pasta de saída. Esse parâmetro é opcional. Caso não seja especificado, o pacote será criado no diretório atual.
  • Tipo: (Audit, AuditandSet) determina se a configuração deve apenas auditar ou se a configuração deve alterar o estado do computador se ele não estiver com o estado desejado. O padrão é Audit.

Esta etapa não requer elevação. O parâmetro Force é usado para substituir pacotes existentes se você executar o comando mais de uma vez.

Os comandos a seguir criam um artefato de pacote:

# Create a package that will only audit compliance
$params = @{
    Name          = 'MyConfig'
    Configuration = './MyConfig/MyConfig.mof'
    Type          = 'Audit'
    Force         = $true
}
New-GuestConfigurationPackage @params

# Create a package that will audit and apply the configuration (Set)
$params = @{
    Name          = 'MyConfig'
    Configuration = './MyConfig/MyConfig.mof'
    Type          = 'AuditAndSet'
    Force         = $true
}
New-GuestConfigurationPackage @params

Um objeto é retornado com o Nome e o Caminho do pacote criado.

Name     Path
----     ----
MyConfig C:\dsc\MyConfig.zip

Conteúdo esperado de um artefato de configuração de computador

O pacote fechado é usado pela configuração de computador para criar as definições do Azure Policy. O pacote consiste em:

  • A configuração de DSC compilada como um MOF
  • Pasta dos módulos
    • Módulo GuestConfiguration
    • Módulo DscNativeResources
    • Módulos de recursos DSC exigidos pelo MOF
  • Um arquivo de meta configuração que armazena o pacotetype e version

O cmdlet PowerShell cria o arquivo do pacote .zip. Nenhuma pasta de nível de raiz ou de versão é necessária. O formato do pacote deve ser um arquivo .zip e não pode exceder o tamanho total de 100 MB quando descompactado.

Você pode expandir o arquivo para inspecioná-lo usando o cmdlet Expand-Archive.

Expand-Archive -Path .\MyConfig.zip -DestinationPath MyConfigZip

Você pode obter o tamanho total do pacote descompactado com o PowerShell.

Get-ChildItem -Recurse -Path .\MyConfigZip |
    Measure-Object -Sum Length |
    ForEach-Object -Process {
        $Size = [math]::Round(($_.Sum / 1MB), 2)
        "$Size MB"
    }

Estender a configuração de computador com ferramentas de terceiros

Os pacotes de artefato para a configuração de computador podem ser estendidos para incluir ferramentas de terceiros. A extensão da configuração de computador exige o desenvolvimento de dois componentes.

  • Um recurso Desired State Configuration que trata todas as atividades relacionadas ao gerenciamento da ferramenta de terceiros
    • Instalar
    • Invoke
    • Converter saída
  • Conteúdo no formato correto para a ferramenta consumir nativamente

O recurso DSC requer desenvolvimento personalizado se uma solução da comunidade ainda não existir. As soluções da comunidade podem ser descobertas pesquisando na Galeria do PowerShell a marca GuestConfiguration.

Observação

A extensibilidade da configuração de computador é um cenário "traga sua própria licença". Verifique se você atende aos termos e condições de quaisquer ferramentas de terceiros antes do uso.

Após a instalação do recurso DSC no ambiente de desenvolvimento, use o parâmetro FilesToInclude para New-GuestConfigurationPackage a fim de incluir o conteúdo da plataforma de terceiros no artefato de conteúdo.

Próxima etapa

Testar um pacote de configuração de máquina personalizado