Skip to content

Commit

Permalink
Update reademe, build and module
Browse files Browse the repository at this point in the history
fixes #12
  • Loading branch information
paule96 committed Jul 6, 2020
1 parent dcbcd95 commit 72992d4
Show file tree
Hide file tree
Showing 3 changed files with 185 additions and 146 deletions.
88 changes: 60 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,35 @@
# Introduction
xTfsDscAgent is a Powershell Desire-State Module to install an configure a TFS / VSTS Build Agents.
# Introduction

xTfsDscAgent is a Powershell Desire-State Module to install an configure a TFS / VSTS Build Agents.
You can use this to automate the provisinig of new Agents as you need it.

# Getting Started

To start it is helpful to know about DSC and know how it works. [Here](https://docs.microsoft.com/en-us/powershell/dsc/overview) is a good documentation for this.

To write a config for your agent you must import this Module in your configuratoin.
After this you can use the xTfsDscAgent to configure the agents. In the following table you can see what parameters we currently support:

| Parameter | Requiered | Desciprion |
| --------- | --------- | ---------- |
| Agentfolder| true | The folder in this the agent will install. This is the key for DSC tho identify is the agent currently there|
| Ensure | true | This is a default DSC Parameter, that describe if the configuration must add or remove the agent. |
| serverUrl | true | This is the url for the VSTS or TFS server. Importent: only input the server url! Dont add the collection name or somethink like this! |
| AgentVersion | false | The Agentversion you want to install and configure. The default is latest. |
| AgentPool | false | The AgentPool the agent joins after installation. The default is default |
| AgentName | false | Here you can define a custom name for the agent. The Default is 'default-' and a Guid |
| AgentAuth | false | This is a option to use all supported auth-options for TFS or VSTS. The Default is 'Integrated'. (This you must change for VSTS!) |
| AgentRunAsService | false | This is a option to run the agent in a windows service. This option only works on windows! The defualt is false.
| WorkFolder |false | Here you can set a custom path. In this Path the Agent will do the work from the build and release jobs from VSTS / TFS. The default option is '_work' in the agentfolder. |
| AgentUser | true | You you must enter the credetials of the service account that have acess to register new agents and run builds. The password is only needed for some auth mechanics! See the TFS Agent doucmentation for this. |
| UserToken | false | Here you can paste a PAT. This is only use for PAT auth! Default is empty |
| ReplaceAgent | false | This define is the registrion can override exsisting registions with the same agent name. The default is false |
After this you can use the xTfsDscAgent to configure the agents. In the following table you can see what parameters we currently support:

| Parameter | Requiered | Desciprion |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agentfolder | true | The folder in this the agent will install. This is the key for DSC tho identify is the agent currently there |
| Ensure | true | This is a default DSC Parameter, that describe if the configuration must add or remove the agent. |
| serverUrl | true | This is the url for the VSTS or TFS server. Importent: only input the server url! Dont add the collection name or somethink like this! |
| AgentVersion | false | The Agentversion you want to install and configure. The default is latest. |
| AgentPool | false | The AgentPool the agent joins after installation. The default is default |
| AgentName | false | Here you can define a custom name for the agent. The Default is 'default-' and a Guid |
| AgentAuth | false | This is a option to use all supported auth-options for TFS or VSTS. The Default is 'Integrated'. (This you must change for VSTS!) |
| AgentRunAsService | false | This is a option to run the agent in a windows service. This option only works on windows! The defualt is false. |
| WorkFolder | false | Here you can set a custom path. In this Path the Agent will do the work from the build and release jobs from VSTS / TFS. The default option is '\_work' in the agentfolder. |
| AgentUser | true | You you must enter the credetials of the service account that have acess to register new agents and run builds. The password is only needed for some auth mechanics! See the TFS Agent doucmentation for this. |
| UserToken | false | Here you can paste a PAT. This is only use for PAT auth! Default is empty |
| ReplaceAgent | false | This define is the registrion can override exsisting registions with the same agent name. The default is false |
| filePath | false | Define a path to a downloaded agent ZIP file is. It's recommended to use this option in offline environments. (or in proxy environments) |

# Example

Important: First install this powershell module in a psmodule path!
Here you can see a example for a config for a agent:
Here you can see a example for a config for a agent:

```PS
Configuration sampleConfig {
Expand All @@ -35,30 +38,40 @@ Configuration sampleConfig {
[Parameter(Mandatory = $true)]
[ValidateNotNullOrEmpty()]
[PsCredential] $agentCredential
)
Import-DscResource -ModuleName xTfsDscAgent -ModuleVersion 1.0.1
)
Import-DscResource -ModuleName xTfsDscAgent -ModuleVersion 1.0.1
Node $AllNodes.Where{$_.Role -eq 'TfsAgent'}.NodeName
{
xTfsDscAgent agent {
AgentFolder = "C:\Agent\"
Ensure = "Present"
serverUrl = "https://tfs201801.home01.local/"
AgentPool = "default"
AgentUser = $agentCredential
serverUrl = "https://tfs201801.home01.local/"
AgentPool = "default"
AgentUser = $agentCredential
}
xTfsDscAgent offlineagent {
AgentFolder = "C:\OfflineAgent\"
Ensure = "Present"
serverUrl = "https://tfs201801.home01.local/"
AgentPool = "default"
AgentUser = $agentCredential
filePath = "\\shareserver\setups\agent.zip"
}
LocalConfigurationManager {
CertificateID = $node.Thumbprint
}
}
}
```

To run this config you must save this in a file with the name sampleConfig.ps1.
After this you can run the config like any other dsc config:

```PS
$ConfigData = @{
AllNodes = @(
Expand All @@ -84,12 +97,31 @@ Start-DscConfiguration .\mofs -Verbose -Wait
```

# Build and Test
TODO: Describe and show how to build your code and run the tests.

To build the project run the `build.ps1` in the root folder. It will automatically increase the module version number. So you can easy update in your test and dev environment if your changes work.
After this you have a `out` folder with the module in it. This folder you can add to your powershell environment to test the resource. You can do this with the following lines:

```powershell
$path = Join-Path $pwd.Path -ChildPath "out";
if ($env:PSModulePath -notlike "*$path*") {
$env:PSModulePath = $env:PSModulePath + "$([System.IO.Path]::PathSeparator)$path";
}
```

After this you can compile your configuration with your own version of xTfsDscAgent.

## Tests

Don't use them currently is better for you. If you really want use them you need a TFS / Azure DevOps installation and must changes the lines that referee to it in the test file. Then you must set two user environment variables with username and password to login at the TFS / Azure DevOps Server.

So just don't use them. I will rewrite them sometime in the feature.

# Contribute
TODO: Explain how other users and developers can contribute to make your code better.

TODO: Explain how other users and developers can contribute to make your code better.

If you want to learn more about creating good readme files then refer the following [guidelines](https://www.visualstudio.com/en-us/docs/git/create-a-readme). You can also seek inspiration from the below readme files:

- [ASP.NET Core](https://github.com/aspnet/Home)
- [Visual Studio Code](https://github.com/Microsoft/vscode)
- [Chakra Core](https://github.com/Microsoft/ChakraCore)
2 changes: 1 addition & 1 deletion build.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ $psdData.ModuleVersion = $versionParts -join ".";

Update-ModuleManifest -ModuleVersion $psdData.ModuleVersion -Path ($psdDictionary + "\" + $psdFileName);

$outModuleFolder = ".\out\" + $psdData.ModuleVersion;
$outModuleFolder = ".\out\xTfsDscAgent\" + $psdData.ModuleVersion;
$dscFolderName = "xTfsDscAgent" + "_" + $psdData.ModuleVersion;
$outDSCFolder = ".\out\" + $dscFolderName;
mkdir ($outModuleFolder) -Force -Verbose;
Expand Down
241 changes: 124 additions & 117 deletions src/xtfsDscAgent/xTfsDscAgent.psd1
Original file line number Diff line number Diff line change
@@ -1,125 +1,132 @@
#
# Module manifest for module 'PSGet_xTfsDscAgent'
# Module manifest for module 'xTfsDscAgent'
#
# Generated by: Paul
#
# Generated on: 3/17/2018
# Generated on: 06.07.2020
#

@{

# Script module or binary module file associated with this manifest.
RootModule = 'xTfsDscAgent.psm1'

# Version number of this module.
ModuleVersion = '1.0.73'

# Supported PSEditions
# CompatiblePSEditions = @()

# ID used to uniquely identify this module
GUID = '129bb685-dcb9-4e78-b172-d831d621b74e'

# Author of this module
Author = 'Paul'

# Company or vendor of this module
CompanyName = 'Unknown'

# Copyright statement for this module
Copyright = '(c) 2017 Paul. Alle Rechte vorbehalten.'

# Description of the functionality provided by this module
Description = 'DSC Resource for TFS Agent'

# Minimum version of the Windows PowerShell engine required by this module
# PowerShellVersion = ''

# Name of the Windows PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the Windows PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# CLRVersion = ''

# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()

# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()

# Variables to export from this module
# VariablesToExport = @()

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
DscResourcesToExport = 'xTfsDscAgent'

# List of all modules packaged with this module
# ModuleList = @()

# List of all files packaged with this module
# FileList = @()

# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

PSData = @{

# Tags applied to this module. These help with module discovery in online galleries.
# Tags = @()

# A URL to the license for this module.
# LicenseUri = ''

# A URL to the main website for this project.
# ProjectUri = ''

# A URL to an icon representing this module.
# IconUri = ''

# ReleaseNotes of this module
# ReleaseNotes = ''

# External dependent modules of this module
# ExternalModuleDependencies = ''

} # End of PSData hashtable

} # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}
# Script module or binary module file associated with this manifest.
RootModule = 'xTfsDscAgent.psm1'

# Version number of this module.
ModuleVersion = '1.0.76'

# Supported PSEditions
# CompatiblePSEditions = @()

# ID used to uniquely identify this module
GUID = '129bb685-dcb9-4e78-b172-d831d621b74e'

# Author of this module
Author = 'Paul'

# Company or vendor of this module
CompanyName = 'Unknown'

# Copyright statement for this module
Copyright = '(c) 2017 Paul. Alle Rechte vorbehalten.'

# Description of the functionality provided by this module
Description = 'DSC Resource for TFS Agent'

# Minimum version of the PowerShell engine required by this module
# PowerShellVersion = ''

# Name of the PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# ClrVersion = ''

# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()

# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()

# Variables to export from this module
# VariablesToExport = @()

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
# DscResourcesToExport = @()

# List of all modules packaged with this module
# ModuleList = @()

# List of all files packaged with this module
# FileList = @()

# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

PSData = @{

# Tags applied to this module. These help with module discovery in online galleries.
# Tags = @()

# A URL to the license for this module.
# LicenseUri = ''

# A URL to the main website for this project.
# ProjectUri = ''

# A URL to an icon representing this module.
# IconUri = ''

# ReleaseNotes of this module
# ReleaseNotes = ''

# Prerelease string of this module
# Prerelease = ''

# Flag to indicate whether the module requires explicit user acceptance for install/update/save
# RequireLicenseAcceptance = $false

# External dependent modules of this module
# ExternalModuleDependencies = @()

} # End of PSData hashtable

} # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}

0 comments on commit 72992d4

Please sign in to comment.