Skip to content

Latest commit

 

History

History
169 lines (108 loc) · 9.27 KB

GettingStarted.md

File metadata and controls

169 lines (108 loc) · 9.27 KB

1. Getting started

Note: If you are only intersted in exporting your Microsoft Azure tenant configuration with Microsoft365DSC and you do not want to configure your tenants, please refer to Export your Azure Tenant Configuration.

1.0.1. ⚠️ You must be a local administrator one the machine you run the setup scripts on.

1.1. Forking or importing the Project

For this project to work it is required to change the content of some files. Hence, it is required to create yourself a writable copy of the project. Either you do a fork on GitHub or you import the content of this project into a project you host on a developer platform or code management solution of your choice.

This guide expects you have created a new project on Azure DevOps and imported the content from here. Alternatively, you can create a fork on GitHub, but then some scripts won't work and you have to make the required tasks manually.

1.2. Cloning the Project

⚠️ Do not download the project as a Zip file. The build process will not work if you don't clone the project.

Clone the project in Visual Studio Code Source Control Activity Bar or use the command git.exe. With the following command you clone the Git repository to your local machine. Please change the link according to your fork / project on your code management solution.

git clone https://github.com/raandree/Microsoft365DscWorkshop.git C:\Git

1.3. Test the Build and Download Dependencies

After having cloned the project to your development machine, please open the solution in Visual Studio Code. In the PowerShell prompt, call the build script:

.\build.ps1 -UseModuleFast

This build process takes around 5 minutes to complete. Most of the time is used to download the required dependencies defined in the file RequiredModules.psd1.

Please verify the artifacts created by the build pipeline, for example the MOF files in the MOF.

ℹ️ The MOF folder is not part of the project. It is created by the build process. If your don't find it after having run the build, something went wrong and you probably see errors in the console output of the build process.

1.4. Set your Azure Tenant Details

This solution can configure as many Azure tenants as you want. You configure the tenants your want to control in the .\source\Azure.yml file. The file contains a usual setup, a dev, test and prod tenant.

For each environment / tenant, please update the settings AzTenantId, AzTenantName and AzSubscriptionId. The AzApplicationId and AzApplicationSecret will be handled by the setup scripts called very soon. Remove the environments you do not need.

The file can look like this for example if you want to configure only one tenant:

Environments:
  Dev:
    AzTenantId: b246c1af-87ab-41d8-9812-83cd5ff534cb
    AzTenantName: MngEnvMCAP576786.onmicrosoft.com
    AzSubscriptionId: 9522bd96-d34f-4910-9667-0517ab5dc595
    Identities:
    - Name: M365DscSetupApplication
      ApplicationId: <AutoGeneratedLater>
      ApplicationSecret: <AutoGeneratedLater>
    - Name: M365DscLcmCertApplication
      ApplicationId: <AutoGeneratedLater>
      CertificateThumbprint: <AutoGeneratedLater>

1.5. Run the Lab Setup Scripts

All the script to setup the environment are in the folder lab.

1.5.1. 00 Prep.ps1

⚠️ Please do not reuse the session you ran the build script in. Please kill the old PowerShell session and start a new one.

⚠️ This script may kill the PowerShell session when setting local policies required for AutomatedLab. In this case, just restart it.

Call the script .\lab\00 Prep.ps1. It installs required modules on your machine.

1.5.2. Initialize the session (LabInit)

After the preparation script finished, we have all modules and dependencies on the machine to get going. Please run the build script again, but this time just only for initializing the shell:

.\build.ps1 -Tasks labinit

1.5.3. 10 Setup App Registrations.ps1

The script 10 Setup App Registrations.ps1 creates an app in each tenant defined in the Azure.yml file. Then it assigns these apps very high privileges as they are used to setup the required VMs (Azure DevOps build agents) and the managed identities with the required permissions for Microsoft365DSC. For each app, a service principal is created in Exchange Online.

ℹ️ After the project setup is completed, the apps can be deleted. The script 98 Cleanup App Registrations.ps1 helps with that.

The App ID and the encrypted secrets are shown on the console in case you want to copy them and also written encrypted to the Azure.yml file. The file is then committed and pushed to the code repository.

⚠️ The password for encrypting the app secret is taken from the Datum.yml file. This is not a secure solution and only meant to be used in a proof of concept. For any production related tenant, the pass phrase should be replaced by a certificate.

1.5.4. 20 Create Agent VMs.ps1

The script 20 Create Agent VMs.ps1 creates one VM in each tenant. It then assigns a Managed Identity to each VM and gives that managed identity the required permissions to control the Azure tenant with Microsoft365DSC. Later we connect that VM to Azure DevOps as a build agent. It will be used later to build the DSC configuration and push it to the respective Azure tenant.

For creating the VMs, we use AutomatedLab. All the complexity of that task is handled by that AutomatedLab. The script should run 20 to 30 minutes.

⚠️ Before running the script 20 Create Agent VMs.ps1, please set a password for the build workers in the file AzureDevOps.yml by replacing the placeholder <Password> with your desired password. If you forget this or your chosen password does not have the necessary complexity, you will get an error later.

BuildAgents:
  UserName: worker
  Password: Somepass1

Running the script 20 Create Agent VMs.ps1 takes about half an hour, depending on how many tenants you have configured. Time to grab a coffee.

1.5.5. 30 Setup AzDo Project.ps1

This script prepares the Azure DevOps project. The parameters are in the file AzureDevOps.yml.

OrganizationName: <OrganizationName>
PersonalAccessToken: <PersonalAccessToken>
ProjectName: Microsoft365DscWorkshop
AgentPoolName: DSC

If you are ok with the name of the new agent pool, you don't have to change anything here. The script 30 Setup AzDo Project.ps1 will ask for the required information and update the file AzureDevOps.yml for you.

  1. Please create an Personal Access Token (PAT) for your Azure DevOps organization with the required access level to manage / create the project. Copy the PAT to the clipboard.

  2. Then call the script 30 Setup AzDo Project.ps1

& '.\30 Setup AzDo Project.ps1'

The script will:

  • Ask for Azure DevOps organization name.
  • Ask for the Azure DevOps project name.
  • Ask for the Azure DevOps personal access token.
  • Update the file AzureDevOps.yml according to the data you provided.
  • Creates an agent pool named DSC.
  • Disables non-required features in the project.
  • Creates build environments as defined in Azure.yml file.
  • Creates the pipelines for full build, apply and test.

Please inspect the project. You should see the new environments as well as the new agent pool and the pipelines now.

1.5.6. 31 Agent Setup.ps1

The script 31 Agent Setup.ps1 connects to each build worker VM created in the previous step. It installs

  • PowerShell 7
  • Git
  • VSCode. After that it installs
  • Azure DevOps Build Agent
  • Latest PowerShellGet and NuGet package provider
  • Then the Azure Build Agent is connected to the specified Azure DevOps Organization and is added to the DSC agent pool.
  • A self-signed client authentication certificate is created on the build agent. The certificate's thumbprint is written to the Azure.yml file.

Please check the DSC Azure DevOps Agent Pool to see if the new worker appears there. Please also check its capabilities. There should be a capability named BuildEnvironment with the value of the respective environment.

1.6. Running the Pipeline

The script 30 Setup AzDo Project.ps1 has created these pipelines:

  • M365DSC push

    Only this pipeline has triggers for continuous integration and is executed every time something is committed to the main branch. The pipeline creates the artifacts, applies them to the configured tenants and tests whether the configuration could be applied successfully. The next three pipelines are these steps individually.

  • M365DSC test

  • M365DSC apply

  • M365DSC build