Como criar artefatos de pacote de configuração de máquina personalizados

Artigo
02/14/2024

Antes de começar, é uma boa ideia ler a página de visão geral da configuração da máquina.

A configuração da máquina usa a Configuração de Estado Desejado (DSC) ao auditar e configurar o Windows e o Linux. A configuração DSC define a condição em que o computador deverá estar.

Importante

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

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 o agente Arc 1.10.0 ou posterior.

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

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

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

Use as etapas a seguir para criar sua própria configuração para gerenciar o estado de uma máquina Azure ou não-Azure.

Instalar 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 seu sistema operacional, o módulo GuestConfiguration e o módulo PSDesiredStateConfiguration.

Criar uma configuração

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

Importante

Ao compilar 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.

Este exemplo de configuração é para máquinas Windows. Ele configura a máquina para criar a MC_ENV_EXAMPLE variável de ambiente nos escopos Process e Machine . O valor da variável define 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 MyConfig.ps1 script, 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 localhost.mof no arquivo na MyConfig pasta no diretório de trabalho atual. Renomeie localhost.mof para o nome que você deseja 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

Nota

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

O restante deste artigo se aplica a configurações definidas para máquinas Linux e Windows, exceto quando menciona considerações específicas da plataforma.

Criar um artefato de pacote de configuração

Uma vez que o MOF é compilado, os arquivos de suporte devem ser empacotados juntos. O pacote concluído é usado pela configuração da máquina para criar as definições de Política do Azure.

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

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

Nome: nome do pacote de configuração da máquina.
Configuração: Caminho completo do documento de configuração DSC compilado.
Caminho: Caminho da pasta de saída. Este parâmetro é opcional. Se não for 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 da máquina se estiver fora do estado desejado. A predefiniçã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 máquina

O pacote concluído é usado pela configuração da máquina para criar as definições de Política do Azure. O pacote é composto por:

A configuração DSC compilada como um MOF
Pasta Módulos
- Módulo GuestConfiguration
- Módulo DscNativeResources
- Módulos de recursos DSC exigidos pelo MOF
Um arquivo de metaconfiguração que armazena o pacote type e version

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

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

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

Você pode obter o tamanho total do pacote não compactado com o PowerShell.

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

Estendendo a configuração da máquina com ferramentas de terceiros

Os pacotes de artefatos para configuração de máquina podem ser estendidos para incluir ferramentas de terceiros. A extensão da configuração da máquina requer o desenvolvimento de dois componentes.

Um recurso de Configuração de Estado Desejado que lida com todas as atividades relacionadas ao gerenciamento da ferramenta de terceiros
- Instalar
- Invocar
- Converter saída
Conteúdo no formato correto para a ferramenta consumir nativamente

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

Nota

A extensibilidade de configuração da máquina é um cenário de "traga sua própria licença". Certifique-se de que cumpriu os termos e condições de quaisquer ferramentas de terceiros antes de utilizar.

Depois que o recurso DSC tiver sido instalado no ambiente de desenvolvimento, use o parâmetro FilesToInclude para incluir conteúdo para New-GuestConfigurationPackage a plataforma de terceiros no artefato de conteúdo.

Próximo passo

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

Partilhar via