Partilhar via

Alterações no comportamento na Configuração de Estado Desejado do PowerShell para configuração de máquina

  • Artigo

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

Está disponível um vídeo passo a passo deste documento.

A configuração da máquina usa a Configuração de Estado Desejado do PowerShell (PSDSC) versão 3 para auditar e configurar máquinas. A configuração DSC define o estado em que a máquina deve estar. Há muitas diferenças notáveis na forma como o DSC é implementado na configuração da máquina.

A configuração da máquina usa a plataforma cruzada do PowerShell 7

A configuração da máquina é projetada para que a experiência de gerenciamento do Windows e Linux possa ser consistente. Em ambos os ambientes de sistema operacional, alguém com conhecimento do PowerShell DSC pode criar e publicar configurações usando habilidades de script.

A configuração da máquina usa apenas o PowerShell DSC versão 3 e não depende da implementação anterior do DSC para Linux ou dos nx* provedores incluídos nesse repositório.

A partir da versão 1.26.33, a configuração da máquina opera no PowerShell 7.1.2 para Windows e no PowerShell 7.2 preview 6 para Linux. A partir da versão 7.2, o módulo PSDesiredStateConfiguration deixou de fazer parte da instalação do PowerShell e passou a ser instalado como um módulo da Galeria do PowerShell.

Várias configurações

A configuração da máquina suporta a atribuição de várias configurações à mesma máquina. Não há etapas especiais necessárias dentro do sistema operacional da extensão de configuração da máquina. Não há necessidade de configurar configurações parciais.

As dependências são gerenciadas por configuração

Quando uma configuração é empacotada usando as ferramentas disponíveis, as dependências necessárias para a configuração são incluídas em um .zip arquivo. As máquinas extraem o conteúdo em uma pasta exclusiva para cada configuração. O agente fornecido pela extensão de configuração da máquina cria uma sessão dedicada do PowerShell para cada configuração. Ele usa um $Env:PSModulePath que limita o carregamento automático do módulo apenas ao caminho onde o pacote foi extraído.

Esta alteração tem múltiplas vantagens:

  • É possível usar diferentes versões de módulos para cada configuração, na mesma máquina.
  • Quando uma configuração não é mais necessária em uma máquina, o agente exclui com segurança toda a pasta onde a configuração foi extraída. Você não precisa gerenciar dependências compartilhadas entre configurações.
  • Não é necessário gerenciar várias versões de qualquer módulo em um serviço central.

Os artefatos são gerenciados como pacotes

O recurso Configuração do Estado de Automação do Azure inclui gerenciamento de artefatos para módulos e scripts de configuração. Uma vez que ambos são publicados no serviço, o script pode ser compilado para o formato MOF. Da mesma forma, o Windows Pull Server também exigia o gerenciamento de configurações e módulos na instância do serviço Web. Por outro lado, a extensão DSC tem um modelo simplificado onde todos os artefatos são empacotados juntos e armazenados em um local acessível a partir da máquina de destino usando uma solicitação HTTPS. O Armazenamento de Blobs do Azure é a opção popular para hospedar os artefatos.

A configuração da máquina usa apenas o modelo simplificado, onde todos os artefatos são empacotados juntos e acessados da máquina de destino por HTTPS. Não há necessidade de publicar módulos, scripts ou compilar no serviço. Uma mudança é que o pacote deve sempre incluir um MOF compilado. Não é possível incluir um arquivo de script no pacote e compilar na máquina de destino.

Tamanho máximo do pacote de configuração personalizada

Na Configuração do Estado de Automação do Azure, as configurações de DSC eram limitadas em tamanho. A configuração da máquina suporta um tamanho total de pacote de 100 MB antes da compressão. Não há limite específico para o tamanho do arquivo MOF dentro do pacote.

O modo de configuração é definido no artefato do pacote

Quando você cria o pacote de configuração, o modo é definido usando as seguintes opções:

  • Audit - Verifica a conformidade de uma máquina. Nenhuma alteração é feita.
  • AuditandSet - Verifica e corrige o estado de conformidade da máquina. As alterações são feitas se a máquina não estiver em conformidade.

O modo é definido no pacote em vez de no serviço Local Configuration Manager porque cada configuração pode ser aplicada com um modo diferente.

Suporte a parâmetros através do Azure Resource Manager

Os parâmetros definidos pela matriz de propriedades configurationParameter nas atribuições de configuração da máquina substituem o texto estático em um arquivo MOF de configuração quando o arquivo é armazenado em uma máquina. Os parâmetros permitem a personalização e um operador controla as alterações da API de serviço sem a necessidade de executar comandos dentro da máquina.

Os parâmetros na Política do Azure que passam valores para atribuições de configuração de máquina devem ser do tipo cadeia de caracteres . Não é possível passar matrizes através de parâmetros, mesmo que o recurso DSC ofereça suporte a matrizes.

Conjunto de gatilhos de fora da máquina

Um desafio em versões anteriores do DSC tem sido corrigir desvios em escala sem muito código personalizado e dependência de conexões remotas WinRM. A configuração de convidado resolve esse problema. Os usuários da configuração da máquina têm controle sobre a correção de desvio através da remediação sob demanda.

A sequência inclui o método Get

Quando a configuração da máquina audita ou configura uma máquina, a mesma sequência de eventos é usada para Windows e Linux. A mudança notável no comportamento é que o Get método é chamado pelo serviço para retornar detalhes sobre o estado da máquina.

  1. O agente é executado Test primeiro para determinar se a configuração está no estado correto.
  2. Se o pacote estiver definido como Audit, o valor booleano retornado pela função determinará se o status do Gerenciador de Recursos do Azure para a Atribuição de Convidado deve ser Compliant ou NonCompliant.
  3. Se o pacote estiver definido como AuditandSet, o valor booleano determinará se a máquina deve ser corrigida aplicando a configuração usando o Set método. Se o Test método retornar $false, Set será executado. Se Test retornar $true, então Set não é executado.
  4. Por fim, o provedor é executado para retornar o estado atual de cada configuração para que os detalhes estejam disponíveis tanto sobre por que uma máquina não é compatível quanto para confirmar se o estado atual é Get compatível.

Requisitos especiais para Obter

O método DSC tem requisitos especiais para a configuração da máquina que não foram necessários para o DSC Get .

  • A tabela de hash retornada deve incluir uma propriedade chamada Reasons.
  • A propriedade Reasons deve ser uma matriz.
  • Cada item na matriz deve ser uma tabela de hash com chaves chamadas Code e Phrase.
  • Nenhum valor além da tabela de hash deve ser retornado.

A propriedade Reasons é usada pelo serviço para padronizar como as informações de conformidade são apresentadas. Você pode pensar em cada item em Razões como uma mensagem sobre como o recurso é ou não compatível. A propriedade é uma matriz porque um recurso pode estar fora de conformidade por mais de um motivo.

As propriedades Code e Phrase são esperadas pelo serviço. Ao criar um recurso personalizado, defina o texto que você gostaria de mostrar como o motivo pelo qual o recurso não é compatível como o valor de Frase. O código tem requisitos de formatação específicos para que os relatórios possam exibir claramente informações sobre o recurso usado para fazer a auditoria. Esta solução torna a configuração do convidado extensível. Qualquer comando pode ser executado, desde que a saída possa ser retornada como um valor de cadeia de caracteres para a propriedade Phrase .

  • Código (string): O nome do recurso, repetido e, em seguida, um nome curto sem espaços como um identificador para o motivo. Estes três valores devem ser delimitados por dois pontos sem espaços.
    • Um exemplo seria registry:registry:keynotpresent
  • Frase (string): Texto legível por humanos para explicar por que a configuração não é compatível.
    • Um exemplo seria The registry key $key isn't present on the machine.
$reasons = @()
$reasons += @{
  Code   = 'Name:Name:ReasonIdentifer'
  Phrase = 'Explain why the setting is not compliant'
}
return @{
    reasons = $reasons
}

Ao usar ferramentas de linha de comando para obter informações que retornam no Get, você pode achar que a ferramenta retorna uma saída que você não esperava. Embora você capture a saída no PowerShell, a saída também pode ter sido gravada com erro padrão. Para evitar esse problema, considere redirecionar a saída para null.

A classe incorporada da propriedade Reasons

Em recursos baseados em script (somente Windows), a classe Reasons é incluída no arquivo MOF de esquema da seguinte maneira.

[ClassVersion("1.0.0.0")]
class Reason
{
  [Read] String Phrase;
  [Read] String Code;
};

[ClassVersion("1.0.0.0"), FriendlyName("ResourceName")]
class ResourceName : OMI_BaseResource
{
  [Key, Description("Example description")] String Example;
  [Read, EmbeddedInstance("Reason")] String Reasons[];
};

Em recursos baseados em classe (Windows e Linux), a classe Reason é incluída no módulo PowerShell da seguinte maneira. O Linux diferencia maiúsculas de minúsculas, portanto, o in e P o C in Code Phrase devem ser capitalizados.

enum ensure {
  Absent
  Present
}

class Reason {
  [DscProperty()]
  [string] $Code

  [DscProperty()]
  [string] $Phrase
}

[DscResource()]
class Example {

  [DscProperty(Key)]
  [ensure] $ensure

  [DscProperty()]
  [Reason[]] $Reasons

  [Example] Get() {
    # return current current state
  }

  [void] Set() {
    # set the state
  }

  [bool] Test() {
    # check whether state is correct
  }
}

Se o recurso tiver propriedades necessárias, essas propriedades também deverão ser retornadas em Get paralelo com a classe Reason . Se Reason não estiver incluído, o serviço incluirá um comportamento "catch-all" que compara os valores inseridos e Get os valores retornados pelo Get, e fornece uma comparação detalhada como Reason.

Nomes de configuração

O nome da configuração personalizada deve ser consistente em todos os lugares. Estes elementos devem ter o mesmo nome:

  • O .zip arquivo para o pacote de conteúdo
  • O nome da configuração no arquivo MOF
  • O nome da atribuição de configuração da máquina no modelo do Azure Resource Manager

Executando comandos no Windows PowerShell

A execução de módulos do Windows no PowerShell pode ser obtida usando o padrão abaixo em seus recursos DSC. O padrão abaixo define temporariamente o para executar o PSModulePath Windows PowerShell em vez do PowerShell para descobrir os módulos necessários disponíveis no Windows PowerShell. Este exemplo é um trecho adaptado do recurso DSC usado no recurso DSC interno do Secure Web Server .

Esse padrão define temporariamente o caminho de execução do PowerShell para ser executado a partir do Windows PowerShell e descobre o cmdlet necessário, que neste caso é Get-WindowsFeature. A saída do comando é retornada e, em seguida, padronizada para requisitos de compatibilidade. Depois que o cmdlet for executado, $env:PSModulePath será redefinido para o caminho original.

# The Get-WindowsFeature cmdlet needs to be run through Windows PowerShell
# rather than through PowerShell, which is what the Policy engine runs.
$null = Invoke-Command -ScriptBlock {
    param ([string]$FileName)

    $InitialPSModulePath   = $env:PSModulePath
    $WindowsPSFolder       = "$env:SystemRoot\System32\WindowsPowershell\v1.0"
    $WindowsPSExe          = "$WindowsPSFolder\powershell.exe"
    $WindowsPSModuleFolder = "$WindowsPSFolder\Modules"
    $GetFeatureScriptBlock = {
        param([string]$FileName)

        if (Get-Command -Name Get-WindowsFeature -ErrorAction SilentlyContinue) {
            Get-WindowsFeature -Name Web-Server |
                ConvertTo-Json |
                Out-File $FileName
        } else {
            Add-Content -Path $FileName -Value 'NotServer'
        }
    }

    try {
        # Set env variable to include Windows Powershell modules so we can find
        # the Get-WindowsFeature cmdlet.
        $env:PSModulePath = $WindowsPSModuleFolder
        # Call Windows PowerShell to get the info about the Web-Server feature
        & $WindowsPSExe -command $WindowsFeatureScriptBlock -args $FileName
    } finally {
        # Reset the env variable even if there's an error.
        $env:PSModulePath = $InitialPSModulePath
    }
}

Recursos comuns do DSC não estão disponíveis durante a visualização pública da configuração da máquina

Durante a visualização pública, a configuração da máquina não suporta a especificação de dependências entre máquinas usando WaitFor* recursos. Não é possível que uma máquina observe e espere que outra máquina atinja um estado antes de progredir.

A manipulação de reinicialização não está disponível na versão de visualização pública da configuração da máquina, incluindo, o $global:DSCMachineStatus não está disponível. As configurações não são capazes de reinicializar um nó durante ou no final de uma configuração.

Problemas de compatibilidade conhecidos com módulos suportados

O módulo PsDscResources na Galeria do PowerShell e o módulo PSDesiredStateConfiguration que acompanha o Windows são suportados pela Microsoft e têm sido um conjunto de recursos comumente usado para DSC. Até que o módulo PSDscResources seja atualizado para DSCv3, esteja ciente dos seguintes problemas de compatibilidade conhecidos.

  • Não use recursos do módulo PSDesiredStateConfiguration que acompanha o Windows. Em vez disso, mude para PSDscResources.
  • Não use o WindowsFeature, , WindowsFeatureSetWindowsOptionalFeaturee WindowsOptionalFeatureSet recursos em PsDscResources. Há um problema conhecido ao carregar o módulo DISM no PowerShell 7.1.3 no Windows Server que requer uma atualização.

Os nx* recursos para Linux que foram incluídos no repositório DSC para Linux foram escritos em uma combinação das linguagens C e Python. Como o caminho a seguir para o DSC no Linux é usar o PowerShell, os recursos existentes nx* não são compatíveis com o DSCv3. Até que um novo módulo contendo recursos suportados para Linux esteja disponível, é necessário criar recursos personalizados.

Coexistência com DSC versão 3 e versões anteriores

DSC versão 3 na configuração da máquina pode coexistir com versões mais antigas instaladas no Windows e Linux. As implementações são separadas. No entanto, não há deteção de conflitos nas versões DSC, portanto, não tente gerenciar as mesmas configurações.

Próximos passos