Serviço de Pull de Desired State ConfigurationDesired State Configuration Pull Service

Aplica-se a: Windows PowerShell 5.0Applies To: Windows PowerShell 5.0

Importante

O Servidor de Recepção (Recurso do Windows Serviço DSC) é um componente compatível com o Windows Server, no entanto, não há planos de oferecer novos recursos ou funcionalidades.The Pull Server (Windows Feature DSC-Service) is a supported component of Windows Server however there are no plans to offer new features or capabilities. É recomendável começar a fazer a transição dos clientes gerenciados para o DSC de Automação do Azure (inclui recursos além do Servidor de Recepção no Windows Server) ou para uma das soluções da comunidade listadas aqui.It is recommended to begin transitioning managed clients to Azure Automation DSC (includes features beyond Pull Server on Windows Server) or one of the community solutions listed here.

O Gerenciador de Configurações Local pode ser gerenciado centralmente por uma solução de Serviço de Pull.Local Configuration Manager can be centrally managed by a Pull Service solution. Ao usar essa abordagem, o nó que está sendo gerenciado é registrado com um serviço e uma configuração é atribuída a ele em configurações de LCM.When using this approach, the node that is being managed is registered with a service and assigned a configuration in LCM settings. A configuração e todos os recursos de DSC necessários como dependências para a configuração são baixados para o computador e usados pelo LCM para gerenciar a configuração.The configuration and all DSC resources needed as dependencies for the configuration are downloaded to the machine and used by LCM to manage the configuration. As informações sobre o estado do computador que está sendo gerenciado são carregadas no serviço para relatório.Information about the state of the machine being managed is uploaded to the service for reporting. Esse conceito é conhecido como "serviço de pull".This concept is referred to as "pull service."

As opções atuais para o serviço de pull incluem:The current options for pull service include:

  • Serviço de Configuração de Estado Desejado da Automação do AzureAzure Automation Desired State Configuration service
  • Um serviço de pull em execução no Windows ServerA pull service running on Windows Server
  • Soluções de software livre mantidas pela comunidadeCommunity maintained open-source solutions
  • Um compartilhamento SMBAn SMB share

A solução recomendada, e a opção com a maioria dos recursos disponíveis, é DSC de Automação do Azure.The recommended solution, and the option with the most features available, is Azure Automation DSC.

O serviço do Azure pode gerenciar nós localmente em datacenters privados ou em nuvens públicas, como AWS e o Azure.The Azure service can manage nodes on-premises in private datacenters, or in public clouds such as Azure and AWS. Para ambientes privados, onde os servidores não podem se conectar diretamente à Internet, considere limitar o tráfego de saída apenas ao intervalo de IPs do Azure publicado (consulte Intervalos de IP de Datacenter do Azure).For private environments where servers cannot directly connect to the Internet, consider limiting outbound traffic to only the published Azure IP range (see Azure Datacenter IP Ranges).

Entre os recursos do serviço online que não estão disponíveis no serviço de pull no Windows Server estão:Features of the online service that are not currently available in the pull service on Windows Server include:

  • Todos os dados são criptografados em trânsito e em repousoAll data is encrypted in transit and at rest
  • Certificados de cliente são criados e gerenciados automaticamenteClient certificates are created and managed automatically
  • Armazenamento de segredos para gerenciar centralmente senhas/credenciais, ou variáveis como nomes de servidor ou cadeias de conexãoSecrets store for centrally managing passwords/credentials, or variables such as server names or connection strings
  • Gerenciar centralmente o nó Configuração do LCMCentrally manage node LCM configuration
  • Atribuir centralmente configurações a nós do clienteCentrally assign configurations to client nodes
  • Alterações na configuração de versão de "grupos canário" para teste antes de chegar à produçãoRelease configuration changes to "canary groups" for testing before reaching production
  • Relatório gráficoGraphical reporting
    • Detalhes de status no nível de granularidade de recursos de DSCStatus detail at the DSC resource level of granularity
    • Mensagens de erro detalhadas de computadores cliente para solução de problemasVerbose error messages from client machines for troubleshooting
  • Integração com o Azure Log Analytics para alertas, tarefas automatizadas, aplicativo para Android/iOS para relatórios e alertasIntegration with Azure Log Analytics for alerting, automated tasks, Android/iOS app for reporting and alerting

Serviço de pull de DSC no Windows ServerDSC pull service in Windows Server

É possível configurar um serviço de pull para ser executado no Windows Server.It is possible to configuring a pull service to run on Windows Server. Fique ciente de que a solução de serviço de pull incluída no Windows Server inclui apenas as funcionalidades de armazenamento de configurações/módulos para download e de captura de dados de relatório para o banco de dados.Be advised that the pull service solution included in Windows Server includes only capabilities of storing configurations/modules for download and capturing report data in to database. Ela não inclui muitas das funcionalidades oferecidas pelo serviço no Azure e, portanto, não é uma boa ferramenta para avaliar o modo como o serviço seria usado.It does not include many of the capabilities offered by the service in Azure and so is not a good tool for evaluating how the service would be used.

O serviço de pull oferecido no Windows Server é um serviço Web no IIS que utiliza uma interface OData para disponibilizar arquivos de configuração DSC para nós de destino quando são pedidos por tais nós.The pull service offered in Windows Server is a web service in IIS that uses an OData interface to make DSC configuration files available to target nodes when those nodes ask for them.

Requisitos para usar um servidor de pull:Requirements for using a pull server:

  • Um servidor que execute:A server running:
    • WMF/PowerShell 5.0 ou posteriorWMF/PowerShell 5.0 or greater
    • Função de servidor do IISIIS server role
    • Serviço de DSCDSC Service
  • Idealmente, alguns meios de gerar um certificado para proteger as credenciais passadas para o Gerenciador de Configurações Local (LCM) em nós de destinoIdeally, some means of generating a certificate, to secure credentials passed to the Local Configuration Manager (LCM) on target nodes

A melhor maneira de configurar o Windows Server para hospedar o serviço de pull é usar uma configuração DSC.The best way to configure Windows Server to host pull service is to use a DSC configuration. Um script de exemplo é fornecido abaixo.An example script is provided below.

Sistemas de banco de dados com suporteSupported database systems

WMF 4.0WMF 4.0 WMF 5.0WMF 5.0 WMF 5.1WMF 5.1 WMF 5.1 (Windows Server Insider Preview 17090)WMF 5.1 (Windows Server Insider Preview 17090)
MDBMDB ESENT (padrão), MDBESENT (Default), MDB ESENT (padrão), MDBESENT (Default), MDB ESENT (padrão), SQL Server, MDBESENT (Default), SQL Server, MDB

Começando na versão 17090 do Windows Server Insider Preview, o SQL Server é uma opção compatível com o serviço de pull (Recurso do Windows Serviço de DSC).Starting in release 17090 of Windows Server Insider Preview, SQL Server is a supported option for the Pull Service (Windows Feature DSC-Service). Essa é uma nova opção para dimensionar grandes ambientes de DSC que não foram migrados para o DSC de Automação do Azure.This provides a new option for scaling large DSC environments that have not migrated to Azure Automation DSC.

Observação: o suporte ao SQL Server não será adicionado às versões anteriores do WMF 5.1 (ou mais antigas) e só estará disponível nas versões do Windows Server maiores ou iguais à 17090.Note: SQL Server support will not be added to previous versions of WMF 5.1 (or earlier) and will only be available on Windows Server versions greater than or equal to 17090.

Para configurar o servidor de recepção para usar o SQL Server, defina SqlProvider para $true e SqlConnectionString para uma cadeia de conexão válida do SQL Server.To configure the pull server to use SQL Server, set SqlProvider to $true and SqlConnectionString to a valid SQL Server Connection String. Para obter mais informações, confira Cadeias de conexão SqlClient.For more information, see SqlClient Connection Strings. Para obter um exemplo de configuração do SQL Server com xDscWebService, primeiro leia Usando o recurso xDscWebService e, em seguida, examine Sample_xDscWebServiceRegistration_UseSQLProvider.ps1 no GitHub.For an example of SQL Server configuration with xDscWebService, first read Using the xDscWebService resource and then review Sample_xDscWebServiceRegistration_UseSQLProvider.ps1 on GitHub.

Usando o recurso xDscWebServiceUsing the xDscWebService resource

A maneira mais fácil de configurar um servidor de recepção Web é usar o recurso xDscWebService, incluído no módulo xPSDesiredStateConfiguration.The easiest way to set up a web pull server is to use the xDscWebService resource, included in the xPSDesiredStateConfiguration module. As etapas a seguir explicam como usar o recurso em uma configuração que configure o serviço Web.The following steps explain how to use the resource in a configuration that sets up the web service.

  1. Chame o cmdlet Install-Module para instalar o módulo xPSDesiredStateConfiguration.Call the Install-Module cmdlet to install the xPSDesiredStateConfiguration module. Observação: Install-Module está incluído no módulo PowerShellGet, que está incluído no PowerShell 5.0.Note: Install-Module is included in the PowerShellGet module, which is included in PowerShell 5.0. É possível baixar o módulo PowerShellGet para o PowerShell 3.0 e 4.0 em Visualização de Módulos do PowerShell do PackageManagement.You can download the PowerShellGet module for PowerShell 3.0 and 4.0 at PackageManagement PowerShell Modules Preview.
  2. Obtenha um certificado SSL para o servidor de Pull de DSC de uma Autoridade de Certificação confiável, seja de dentro de sua organização ou de uma autoridade pública.Get an SSL certificate for the DSC Pull server from a trusted Certificate Authority, either within your organization or a public authority. O certificado recebido da autoridade geralmente está no formato PFX.The certificate received from the authority is usually in the PFX format. Instale o certificado no nó que se tornará o servidor de recepção de DSC na localização padrão, que deve ser CERT:\LocalMachine\My.Install the certificate on the node that will become the DSC Pull server in the default location, which should be CERT:\LocalMachine\My. Anote a impressão digital do certificado.Make a note of the certificate thumbprint.
  3. Selecione um GUID a ser usado como a Chave de Registro.Select a GUID to be used as the Registration Key. Para gerar um, usando o PowerShell, insira o seguinte no prompt do PS e pressione enter: '[guid]::newGuid()' ou 'New-Guid'.To generate one using PowerShell enter the following at the PS prompt and press enter: '[guid]::newGuid()' or 'New-Guid'. Essa chave será usada por nós de cliente como uma chave compartilhada para autenticação durante o registro.This key will be used by client nodes as a shared key to authenticate during registration. Para obter mais informações, confira a seção Chave de registro abaixo.For more information, see the Registration Key section below.
  4. No ISE do PowerShell, inicie (F5) o script de configuração a seguir (incluído na pasta Exemplos do módulo xPSDesiredStateConfiguration como Sample_xDscWebServiceRegistration.ps1).In the PowerShell ISE, start (F5) the following configuration script (included in the Examples folder of the xPSDesiredStateConfiguration module as Sample_xDscWebServiceRegistration.ps1). Esse script configura o servidor de pull.This script sets up the pull server.
configuration Sample_xDscWebServiceRegistration
{
    param
    (
        [string[]]$NodeName = 'localhost',

        [ValidateNotNullOrEmpty()]
        [string] $certificateThumbPrint,

        [Parameter(HelpMessage='This should be a string with enough entropy (randomness) to protect the registration of clients to the pull server.  We will use new GUID by default.')]
        [ValidateNotNullOrEmpty()]
        [string] $RegistrationKey   # A guid that clients use to initiate conversation with pull server
    )

    Import-DSCResource -ModuleName xPSDesiredStateConfiguration

    Node $NodeName
    {
        WindowsFeature DSCServiceFeature
        {
            Ensure = "Present"
            Name   = "DSC-Service"
        }

        xDscWebService PSDSCPullServer
        {
            Ensure                  = "Present"
            EndpointName            = "PSDSCPullServer"
            Port                    = 8080
            PhysicalPath            = "$env:SystemDrive\inetpub\PSDSCPullServer"
            CertificateThumbPrint   = $certificateThumbPrint
            ModulePath              = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules"
            ConfigurationPath       = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration"
            State                   = "Started"
            DependsOn               = "[WindowsFeature]DSCServiceFeature"
            RegistrationKeyPath     = "$env:PROGRAMFILES\WindowsPowerShell\DscService"
            AcceptSelfSignedCertificates = $true
            Enable32BitAppOnWin64   = $false
        }

        File RegistrationKeyFile
        {
            Ensure          = 'Present'
            Type            = 'File'
            DestinationPath = "$env:ProgramFiles\WindowsPowerShell\DscService\RegistrationKeys.txt"
            Contents        = $RegistrationKey
        }
    }
}
  1. Execute a configuração, passando a impressão digital do certificado SSL como o parâmetro certificateThumbPrint e uma chave de Registro GUID como o parâmetro RegistrationKey:Run the configuration, passing the thumbprint of the SSL certificate as the certificateThumbPrint parameter and a GUID registration key as the RegistrationKey parameter:
# To find the Thumbprint for an installed SSL certificate for use with the pull server list all certificates in your local store
# and then copy the thumbprint for the appropriate certificate by reviewing the certificate subjects
dir Cert:\LocalMachine\my

# Then include this thumbprint when running the configuration
Sample_xDSCPullServer -certificateThumbprint 'A7000024B753FA6FFF88E966FD6E19301FAE9CCC' -RegistrationKey '140a952b-b9d6-406b-b416-e0f759c9c0e4' -OutputPath c:\Configs\PullServer

# Run the compiled configuration to make the target node a DSC Pull Server
Start-DscConfiguration -Path c:\Configs\PullServer -Wait -Verbose

Chave de RegistroRegistration Key

Para permitir que os nós clientes sejam registrados no servidor para poderem usar nomes de configuração em vez de uma ID de configuração, uma chave de registro que foi criada pela configuração acima é salva em um arquivo chamado RegistrationKeys.txt em C:\Program Files\WindowsPowerShell\DscService.To allow client nodes to register with the server so that they can use configuration names instead of a configuration ID, a registration key that was created by the above configuration is saved in a file named RegistrationKeys.txt in C:\Program Files\WindowsPowerShell\DscService. A chave de registro funciona como um segredo compartilhado usado durante o registro inicial pelo cliente com o servidor de pull.The registration key functions as a shared secret used during the initial registration by the client with the pull server. O cliente gerará um certificado autoassinado, que será usado para realizar uma autenticação exclusiva no servidor de recepção depois que o registro for concluído com êxito.The client will generate a self-signed certificate that is used to uniquely authenticate to the pull server once registration is successfully completed. A impressão digital do certificado é armazenada localmente e associada à URL do servidor de pull.The thumbprint of this certificate is stored locally and associated with the URL of the pull server.

Observação: não há suporte para chaves do registro no PowerShell 4.0.Note: Registration keys are not supported in PowerShell 4.0.

Para configurar um nó para ser autenticado no servidor de recepção, a chave de registro deverá estar na metaconfiguração do nó de destino que será registrado nesse servidor de recepção.In order to configure a node to authenticate with the pull server, the registration key needs to be in the metaconfiguration for any target node that will be registering with this pull server. Observe que a RegistrationKey na metaconfiguração abaixo é removida depois de o computador de destino ser registrado com sucesso, e o valor “140a952b-b9d6-406b-b416-e0f759c9c0e4” deve corresponder ao valor armazenado no arquivo RegistrationKeys.txt no servidor pull.Note that the RegistrationKey in the metaconfiguration below is removed after the target machine has successfully registered, and that the value '140a952b-b9d6-406b-b416-e0f759c9c0e4' must match the value stored in the RegistrationKeys.txt file on the pull server. Sempre trate o valor da chave do registro com segurança, porque o conhecimento permite que qualquer computador de destino seja registrado com o servidor de pull.Always treat the registration key value securely, because knowing it allows any target machine to register with the pull server.

[DSCLocalConfigurationManager()]
configuration Sample_MetaConfigurationToRegisterWithLessSecurePullServer
{
    param
    (
        [ValidateNotNullOrEmpty()]
        [string] $NodeName = 'localhost',

        [ValidateNotNullOrEmpty()]
        [string] $RegistrationKey, #same as the one used to setup pull server in previous configuration

        [ValidateNotNullOrEmpty()]
        [string] $ServerName = 'localhost' #node name of the pull server, same as $NodeName used in previous configuration
    )

    Node $NodeName
    {
        Settings
        {
            RefreshMode        = 'Pull'
        }

        ConfigurationRepositoryWeb CONTOSO-PullSrv
        {
            ServerURL          = "https://$ServerName`:8080/PSDSCPullServer.svc" # notice it is https
            RegistrationKey    = $RegistrationKey
            ConfigurationNames = @('ClientConfig')
        }

        ReportServerWeb CONTOSO-PullSrv
        {
            ServerURL       = "https://$ServerName`:8080/PSDSCPullServer.svc" # notice it is https
            RegistrationKey = $RegistrationKey
        }
    }
}

Sample_MetaConfigurationToRegisterWithLessSecurePullServer -RegistrationKey $RegistrationKey -OutputPath c:\Configs\TargetNodes

Observação: a seção ReportServerWeb permite que dados de relatório sejam enviados ao servidor pull.Note: The ReportServerWeb section allows reporting data to be sent to the pull server.

A falta da propriedade ConfigurationID no arquivo de metaconfiguração significa implicitamente que esse servidor pull dá suporte à versão V2 do protocolo de servidor pull, de modo que um registro inicial é necessário.The lack of the ConfigurationID property in the metaconfiguration file implicitly means that pull server is supporting the V2 version of the pull server protocol so an initial registration is required. Por outro lado, a presença de uma ConfigurationID significa que a versão V1 do protocolo do servidor de pull é usada e não há nenhum processamento de registro.Conversely, the presence of a ConfigurationID means that the V1 version of the pull server protocol is used and there is no registration processing.

Observação: em um cenário de PUSH, existe um bug na versão atual que exige a definição de uma propriedade ConfigurationID no arquivo de metaconfiguração para nós que nunca foram registrados em um servidor recepção.Note: In a PUSH scenario, a bug exists in the current release that makes it necessary to define a ConfigurationID property in the metaconfiguration file for nodes that have never registered with a pull server. Isso forçará o uso do protocolo de Servidor de Pull V1 e evitará mensagens de falha de registro.This will force the V1 Pull Server protocol and avoid registration failure messages.

Colocando configurações e recursosPlacing configurations and resources

Após a instalação do servidor pull ser concluída, as pastas definidas pelas propriedades ConfigurationPath e ModulePath na configuração do servidor pull são onde você colocará módulos e configurações que estarão disponíveis para pull pelos nós de destino.After the pull server setup completes, the folders defined by the ConfigurationPath and ModulePath properties in the pull server configuration are where you will place modules and configurations that will be available for target nodes to pull. Esses arquivos precisam estar em um formato específico para que o servidor de recepção processe-os corretamente.These files need to be in a specific format in order for the pull server to correctly process them.

Formato de pacote do módulo de recursos DSCDSC resource module package format

Cada módulo de recurso precisa ser compactado e nomeado de acordo com o seguinte padrão {Module Name}_{Module Version}.zip.Each resource module needs to be zipped and named according to the following pattern {Module Name}_{Module Version}.zip. Por exemplo, um módulo chamado xWebAdminstration com uma versão do módulo correspondente a 3.1.2.0 seria nomeado 'xWebAdministration_3.2.1.0.zip'.For example, a module named xWebAdminstration with a module version of 3.1.2.0 would be named 'xWebAdministration_3.2.1.0.zip'. Cada versão de um módulo deve estar contido em um único arquivo zip.Each version of a module must be contained in a single zip file. Como há apenas uma única versão de um recurso em cada arquivo zip, não há suporte para o formato do módulo adicionado ao WMF 5.0 com suporte para várias versões de módulo em um único diretório.Since there is only a single version of a resource in each zip file, the module format added in WMF 5.0 with support for multiple module versions in a single directory is not supported. Isso significa que antes de empacotar módulos de recursos DSC para uso com o servidor de pull, você precisará fazer uma pequena alteração na estrutura de diretórios.This means that before packaging up DSC resource modules for use with pull server you will need to make a small change to the directory structure. O formato padrão dos módulos contendo o recurso DSC no WMF 5.0 é '{Pasta do Módulo}{{Versão do Módulo}\DscResources{{Pasta do Recurso DSC}'.The default format of modules containing DSC resource in WMF 5.0 is '{Module Folder}{Module Version}\DscResources{DSC Resource Folder}'. Antes de realizar o empacotamento para o servidor de recepção, remova a pasta {Module version} para que o caminho se torne '{Module Folder}\DscResources{DSC Resource Folder}'.Before packaging up for the pull server, remove the {Module version} folder so the path becomes '{Module Folder}\DscResources{DSC Resource Folder}'. Com essa alteração, compacte a pasta conforme descrito acima e coloque esses arquivos zip na pasta ModulePath.With this change, zip the folder as described above and place these zip files in the ModulePath folder.

Use New-DscChecksum {module zip file} para criar um arquivo de soma de verificação para o módulo recém-adicionado.Use New-DscChecksum {module zip file} to create a checksum file for the newly added module.

Formato MOF de configuraçãoConfiguration MOF format

Um arquivo MOF de configuração precisa ser emparelhado com um arquivo de soma de verificação para que um LCM em um nó de destino possa validar a configuração.A configuration MOF file needs to be paired with a checksum file so that an LCM on a target node can validate the configuration. Para criar uma soma de verificação, chame o cmdlet New-DscChecksum.To create a checksum, call the New-DscChecksum cmdlet. O cmdlet usa um parâmetro Path que especifica a pasta na qual se encontra o MOF de configuração.The cmdlet takes a Path parameter that specifies the folder where the configuration MOF is located. O cmdlet cria um arquivo de soma de verificação chamado ConfigurationMOFName.mof.checksum, em que ConfigurationMOFName é o nome do arquivo MOF de configuração.The cmdlet creates a checksum file named ConfigurationMOFName.mof.checksum, where ConfigurationMOFName is the name of the configuration mof file. Se houver mais de um arquivo MOF de configuração na pasta especificada, será criada uma soma de verificação para cada configuração na pasta.If there are more than one configuration MOF files in the specified folder, a checksum is created for each configuration in the folder. Coloque os arquivos MOF e os arquivos de soma de verificação associados na pasta ConfigurationPath.Place the MOF files and their associated checksum files in the ConfigurationPath folder.

Observação: se alterar o arquivo MOF de configuração de qualquer forma, você também deverá recriar o arquivo de soma de verificação.Note: If you change the configuration MOF file in any way, you must also recreate the checksum file.

FerramentasTooling

Para facilitar a configuração, validação e gerenciamento do servidor de pull, as ferramentas a seguir são incluídas como exemplos na versão mais recente do módulo xPSDesiredStateConfiguration:In order to make setting up, validating and managing the pull server easier, the following tools are included as examples in the latest version of the xPSDesiredStateConfiguration module:

  1. Um módulo que ajudará com empacotamento de módulos de recursos DSC e arquivos de configuração para uso no servidor de pull.A module that will help with packaging DSC resource modules and configuration files for use on the pull server. PublishModulesAndMofsToPullServer.psm1.PublishModulesAndMofsToPullServer.psm1. Exemplos abaixo:Examples below:

        # Example 1 - Package all versions of given modules installed locally and MOF files are in c:\LocalDepot
         $moduleList = @('xWebAdministration', 'xPhp')
         Publish-DSCModuleAndMof -Source C:\LocalDepot -ModuleNameList $moduleList
    
         # Example 2 - Package modules and mof documents from c:\LocalDepot
         Publish-DSCModuleAndMof -Source C:\LocalDepot -Force
    
  2. Um script que valida o Servidor de Pull está configurado corretamente.A script that validates the pull server is configured correctly. PullServerSetupTests.ps1.PullServerSetupTests.ps1.

Soluções da comunidade para o Serviço de PullCommunity Solutions for Pull Service

A comunidade de DSC criou várias soluções para implementar o protocolo de serviço de pull.The DSC community has authored multiple solutions to implement the pull service protocol. Para ambientes locais, elas oferecem funcionalidades de serviço de pull e uma oportunidade de retribuir à comunidade, contribuindo com melhorias incrementais.For on-premises environments, these offer pull service capabilities and an opportunity to contribute back to the community with incremental enhancements.

Configuração do cliente de pullPull client configuration

Os tópicos a seguir descrevem em detalhes a configuração de clientes de pull:The following topics describe setting up pull clients in detail:

Consulte tambémSee also