Trabalhar com repositórios privados do PowerShellGet

O módulo PowerShellGet dá suporte a repositórios diferentes da Galeria do PowerShell. Esses cmdlets proporcionam os cenários a seguir:

  • Dar suporte a um conjunto de módulos do PowerShell confiável e validado previamente para uso em seu ambiente
  • Testar um pipeline de CI/CD que compila os módulos ou scripts do PowerShell
  • Fornecer módulos e scripts do PowerShell para sistemas que não podem acessar a Internet
  • Oferecer scripts e módulos do PowerShell disponíveis apenas para sua organização

Este artigo descreve como configurar um repositório local do PowerShell. O artigo também aborda o módulo OfflinePowerShellGetDeploy disponível na Galeria do PowerShell. Esse módulo contém cmdlets para instalar a versão mais recente do PowerShellGet no seu repositório local.

Tipos de repositório local

Há duas maneiras de criar um PSRepository local: Servidor do NuGet ou compartilhamento de arquivos. Cada tipo tem vantagens e desvantagens:

Servidor do NuGet

Vantagens Desvantagens
Imita a funcionalidade do PowerShellGallery Aplicativo de várias camadas requer planejamento de operações e suporte
O NuGet integra-se ao Visual Studio e a outras ferramentas É necessário realizar o gerenciamento de contas do NuGet e do modelo de autenticação
O NuGet dá suporte a metadados em pacotes .Nupkg A publicação requer manutenção e gerenciamento da chave de API
Fornece pesquisa, administração de pacote, etc.

Comp. de Arquivos

Vantagens Desvantagens
Fácil de configurar, fazer backup e manutenção Nenhuma interface do usuário além do compartilhamento de arquivo básico
Modelo de segurança simples: permissões de usuário no compartilhamento Segurança limitada e sem gravação de quem atualiza o quê
Não há restrições, como substituir itens existentes

O PowerShellGet funciona com qualquer tipo e dá suporte à localização de versões e à instalação de dependências. No entanto, alguns recursos que funcionam com a Galeria do PowerShell não estão disponíveis para servidores NuGet básicos ou compartilhamentos de arquivos. Não há nenhuma diferenciação de scripts, módulos, recursos de DSC ou funcionalidades de função.

Criando um repositório NuGet.Server

O artigo a seguir lista as etapas para configurar seu próprio servidor do NuGet.

Siga as etapas até o ponto de adição de pacotes. As etapas para publicar um pacote são abordadas posteriormente neste artigo.

Para um repositório com base em compartilhamento de arquivo, verifique se os usuários têm permissões para acessar o compartilhamento de arquivos.

Registrando um repositório local

Antes de poder usar um repositório, ele deve ser registrado usando o comando Register-PSRepository. Nos exemplos abaixo, a InstallationPolicy é definida Trustedcomo , na suposição de que você confia em seu próprio repositório.

# Register a NuGet-based server
$registerPSRepositorySplat = @{
    Name = 'LocalPSRepo'
    SourceLocation = 'http://MyLocalNuget/Api/V2/'
    ScriptSourceLocation = 'http://MyLocalNuget/Api/V2'
    InstallationPolicy = 'Trusted'
}
Register-PSRepository @registerPSRepositorySplat

# Register a file share on my local machine
$registerPSRepositorySplat = @{
    Name = 'LocalPSRepo'
    SourceLocation = '\\localhost\PSRepoLocal\'
    ScriptSourceLocation = '\\localhost\PSRepoLocal\'
    InstallationPolicy = 'Trusted'
}
Register-PSRepository @registerPSRepositorySplat

Observe a diferença entre como os dois comandos tratam ScriptSourceLocation. Para um repositório baseado em compartilhamento de arquivo, SourceLocation e ScriptSourceLocation devem corresponder. Para um repositório baseado na Web, eles devem ser diferentes; portanto, neste exemplo à direita "/" é adicionado a SourceLocation.

Ao usar um protocolo de compartilhamento de arquivos, como NFS ou SMB, siga as diretrizes recomendadas para proteger o protocolo. Para obter mais informações sobre como proteger o SMB no Windows, consulte [Aprimoramentos de segurança do SMB][09].

Se você quiser que o PSRepository recém-criado seja o repositório padrão, cancele o registro de todos os outros PSRepositories. Por exemplo:

Unregister-PSRepository -Name PSGallery

Observação

O nome de repositório 'PSGallery' é reservado para uso pela Galeria do PowerShell. Você pode cancelar o registro do PSGallery, mas não pode reutilizar o nome PSGallery para qualquer outro repositório.

Se você precisar restaurar a PSGallery, execute o seguinte comando:

Register-PSRepository -Default

Publicando em um repositório local

Depois de registrar o PSRepository local, é possível publicar em seu PSRepository local. Há dois cenários principais de publicação: publicar seu próprio módulo e publicar um módulo de PSGallery.

Publicando um módulo criado por você

Use Publish-Module e Publish-Script para publicar seu módulo no PSRepository local da mesma maneira que faria com a Galeria do PowerShell.

  • Especifique o local para seu código
  • Forneça uma chave de API
  • Especifique o nome do repositório. Por exemplo, -PSRepository LocalPSRepo

Observação

Você deve criar uma conta no servidor do NuGet e entrar para gerar e salvar a chave de API. Para um compartilhamento de arquivos, use qualquer cadeia de caracteres não vazia para o valor de NuGetApiKey.

Exemplos:

# Publish to a NuGet Server repository using my NuGetAPI key
$publishModuleSplat = @{
    Path = 'c:\projects\MyModule'
    Repository = 'LocalPsRepo'
    NuGetApiKey = $nuGetApiKey
}
Publish-Module @publishModuleSplat

Importante

Para garantir a segurança, as chaves de API não devem ser codificadas em scripts. Use um sistema seguro de gerenciamento de chaves. Ao executar um comando manualmente, as chaves de API não devem ser passadas como texto sem formatação para evitar que ele seja registrado, o Read-Host cmdlet pode ser usado para passar com segurança o valor da chave de API.

# Publish to a file share repo - the NuGet API key must be a non-blank string
$publishModuleSplat = @{
    Path = 'c:\projects\MyModule'
    Repository = 'LocalPsRepo'
    NuGetApiKey = 'AnyStringWillDo'
}
Publish-Module @publishModuleSplat

Publicando um módulo de PSGallery

Para publicar um módulo do PSGallery em seu PSRepository local, você pode usar o Save-Package cmdlet .

  • Especifique o nome do pacote
  • Especifique 'NuGet' como o provedor
  • Especifique o local de PSGallery como a origem (https://www.powershellgallery.com/api/v2)
  • Especifique o caminho para seu repositório local

Exemplo:

# Publish from the PSGallery to your local Repository
$savePackageSplat = @{
    Name = 'PackageName'
    ProviderName = 'NuGet'
    Source = 'https://www.powershellgallery.com/api/v2'
    Path = '\\localhost\PSRepoLocal\'
}
Save-Package @savePackageSplat

Se o PSRepository local for baseado na Web, ele exigirá uma etapa adicional que use nuget.exe para publicar. Consulte a documentação para usar nuget.exe.

Instalando o PowerShellGet em um sistema desconectado

Implantar o PowerShellGet é difícil em ambientes que exigem que os sistemas sejam desconectados da Internet. O PowerShellGet tem um processo de inicialização que instala a versão mais recente na primeira vez que ele é usado. O módulo OfflinePowerShellGetDeploy na Galeria do PowerShell fornece cmdlets que dão suporte a esse processo de inicialização.

Para iniciar uma implantação offline, você precisa:

  • Baixar e instalar o OfflinePowerShellGetDeploy em seu sistema conectado à Internet e seus sistemas desconectados
  • Baixe o PowerShellGet e suas dependências no sistema conectado à Internet usando o cmdlet Save-PowerShellGetForOffline
  • Copie o PowerShellGet e suas dependências do sistema conectado à Internet para o sistema desconectado
  • Use Install-PowerShellGetOffline no sistema desconectado para colocar o PowerShellGet e suas dependências nas pastas apropriadas

Os seguintes comandos usam Save-PowerShellGetForOffline para colocar todos os componentes em uma pasta f:\OfflinePowerShellGet

# Requires -RunAsAdministrator
#Download the OfflinePowerShellGetDeploy to a location that can be accessed
# by both the connected and disconnected systems.
Save-Module -Name OfflinePowerShellGetDeploy -Path 'F:\' -Repository PSGallery
Import-Module F:\OfflinePowerShellGetDeploy

# Put PowerShellGet somewhere locally
Save-PowerShellGetForOffline -LocalFolder 'F:\OfflinePowerShellGet'

Neste ponto, você deve tornar o conteúdo de F:\OfflinePowerShellGet disponível para seus sistemas desconectados. Execute o cmdlet Install-PowerShellGetOffline para instalar o PowerShellGet no sistema desconectado.

Observação

É importante que você não execute o PowerShellGet na sessão do PowerShell antes de executar esses comandos. Depois que o PowerShellGet for carregado na sessão, os componentes não poderão ser atualizados. Se você iniciar o PowerShellGet por engano, saia e reinicie o PowerShell.

Import-Module F:\OfflinePowerShellGetDeploy
Install-PowerShellGetOffline -LocalFolder 'F:\OfflinePowerShellGet'

Depois de executar esses comandos, você está pronto para publicar o PowerShellGet em seu repositório local.

# Publish to a NuGet Server repository using my NuGetAPI key
$publishModuleSplat = @{
    Path = 'F:\OfflinePowershellGet'
    Repository = 'LocalPsRepo'
    NuGetApiKey = $nuGetApiKey
}
Publish-Module @publishModuleSplat

Importante

Para garantir a segurança, as chaves de API não devem ser embutidas em código em scripts. Use um sistema seguro de gerenciamento de chaves. Ao executar um comando manualmente, as chaves de API não devem ser passadas como texto sem formatação para evitar que ele seja registrado, o Read-Host cmdlet pode ser usado para passar com segurança o valor da chave de API.

# Publish to a file share repo - the NuGet API key must be a non-blank string
$publishModuleSplat = @{
    Path = 'F:\OfflinePowerShellGet'
    Repository = 'LocalPsRepo'
    NuGetApiKey = 'AnyStringWillDo'
}
Publish-Module @publishModuleSplat

Usar soluções de Empacotamento para hospedar repositórios do PowerShellGet

Você também pode usar soluções de empacotamento como o Azure Artifacts para hospedar um repositório público ou privado do PowerShellGet. Para obter mais informações e instruções, confira a documentação do Azure Artifacts.