Microsoft.AVS.Management Functional Testing Pipeline

This project provides a publicly available functional testing pipeline for the Microsoft.AVS.Management repository. You can use this as a template for continuous integration testing for scenarios that require running an Azure VMware Solution (AVS) environment.

Table of Contents

• Setup
  • Configuring Azure
  • Configuring the pipeline
  • Connecting the two
  • Local development (optional)
• Execution
• Additional Resources
• Contributing
• License
• Code of Conduct
• Security
• Support

Overview of important files in this repository:

File/folder	Description
Tests/Tests.cs	C# file containing the functional tests
azure-pipelines.yml	Azure Pipelines definition file
main.bicep	Bicep template for deploying an AVS private cloud
adds_install.ps1	ADDS setup and installation script for AD/LDAP

You can find functional tests for the following Run Commands in this repository:

• Get-CloudAdminGroups
• New-LDAPIdentitySource (not LDAPS)
• RemoveExternalIdentitySources

Setup

To use this project, you need to have the following installed:

• .NET 7.0 or later
• Azure CLI
• Visual Studio Code
• Visual Studio 2022 or later

After installing all of those, please clone this repository to your local machine and open it in your choice of IDE.

Configuring Azure

In order to run the tests, you will need to have an AVS Private Cloud deployed in your Azure Subscription.

Please have your desired subscription ID ready for the next steps. If you don't have your subscription set up, please follow these steps to set it up.

You can check your AVS quotas here. If you don't have enough quota to deploy an AVS private cloud, please follow these steps to request an increase.

After making sure you have enough quota on your desired subscription, please follow these steps:

1. Log into Azure in your default browser on your local machine.
2. Navigate to project folder in terminal and run az login. This will log you in to your Azure account.
3. Run az account set --subscription <subscription_id>. This will set the subscription you want to use for your pipeline. Please replace <subscription_id> with your subscription ID mentioned above.
4. Change up the main.bicep to fit your needs. You can change the location, name, tags, cloud version, etc. (click here to learn more about Bicep). After changing and saving the file please run az bicep build --file main.bicep to build your main.json file. Please verify your main.json got changed accordingly by checking the file.

Configuring the pipeline

1. Open azure-pipelines.yml and update the azureSubscription and resourceGroupName variables with your own Azure subscription and resource group name.
2. Create a new Azure DevOps project or open an existing one.
3. Make a new repository in your Azure DevOps project, or a new GitHub repository, and push your code to it (GitHub repository can be private).
4. Push the cloned and modified repository to the new Azure DevOps repository or GitHub repository.
5. Create a new Azure DevOps pipeline by navigating to Pipelines section in your new DevOps project, and follow the instructions to connect it to your repository.
6. Select the azure-pipelines.yml file as the pipeline configuration file.
7. Click on Edit then click on Variables. Add the following variables that are used for setting up the AD/LDAP for New-LDAPIdentitySource run command:
   • LDAPusername (must not contain any special characters or be longer than 20 characters)
   • LDAPpassword (please adhere to the password requirements outlined here)

Connecting the two

1. Connect your Azure DevOps project to your Azure subscription.
   • Go to your Azure DevOps project, click on the Project Settings and then click on Service Connections.
   • Click on New service connection and select Azure Resource Manager.
   • Select Service principal (automatic) and follow the instructions to create a new service principal.
2. Connect your Azure DevOps project to your Azure Resource Manager (ARM) resource group.
   • Go to your Azure DevOps project, click on the Project Settings and then click on Service Connections.
   • Click on New service connection and select GitHub or Azure DevOps Repository.

After completing these steps, you should be able to run the pipeline. Please double check both connections show up under service connections in your project settings.

The Service Principal secrets have an expiration date and will need to be updated when they expire! To check the expiration date of your secrets, go to your Azure DevOps project, click on the Project Settings, and then click on Service Connections. You will see a list of connections, including the ones you have set up. Click on your ARM connection (cloud icon) button next to the variable you want to check, and then click on Manage Service Principal. On the new page, click on Client credentials and you will see the expiration date of your secret under Expires. To update the secret, click on New client secret and follow the instructions.

Local development (optional)

While not necessary, you can run the tests locally to make sure they work before running them in the pipeline.

To do so, you need to set up the following environment variables in your terminal (naming is important):

• SUBSCRIPTIONID=$(az account show --query 'id' -o tsv) - keep in mind that this will set the subscription ID to the one you are currently using, so if you want to use a different subscription, you need to set it manually. Keep the $() syntax and do not add parenthesis around the command.
• <NAME>="<VALUE>" - do this for each variable that is defined the in the Variables class in Tests.cs

Setting Environment Variables on Windows:

1. Open PowerShell.
2. Run the following command for each variable: [Environment]::SetEnvironmentVariable("<VARIABLE_NAME>", <VALUE>, "User"), replacing variable names and values with the ones mentioned above.
3. Verify that the environment variables are set by printing them out.

Setting Environment Variables on Linux or macOS or WSL:

1. Open the Terminal.
2. Enter nano ~/.bash_profile if you are using Bash and nano ~/.zshrc for ZSH.
3. Add the following line for each variable to the file: export <VARIABLE_NAME>=<VALUE>, replacing variable names and values with the ones mentioned above.
4. Press Ctrl + S to save, then Ctrl + X to exit nano and save the file. If you encounter any problems with nano, you can use different text editors, such as Vim or Emacs, to do the same.
5. Type source ~/.bash_profile or source ~/.zshrc to reload the environment variables (or open a new terminal session).
6. Verify that the environment variables are set by printing them out.

To execute the tests:

1. Navigate to the Tests folder in your terminal.
2. Run the tests by selecting the Run Tests option from the Test menu in Visual Studio or by running the dotnet test command in your terminal. This will restore the NuGet packages and build the project, then run the tests.

In the case of WSL, you might get time out-of-sync errors when running AZ commands. To fix this, please run sudo hwclock -s in your terminal to sync your time with the hardware clock.

Execution

Execution of the pipeline can be triggered in the following ways:

• By pushing changes to the main branch. The pipeline will run automatically and execute the tests.
• By creating a pull request. The pipeline will run automatically and execute the tests.
• By manually running the pipeline. You can do this by going to your Azure DevOps project, clicking on Pipelines, and then clicking on Run pipeline. You will be prompted to select the branch you want to run the pipeline on. Select main and click on Run.
• By running the pipeline as a cronjob. You can do this by going to your Azure DevOps project, clicking on Pipelines, and then clicking on Run pipeline. You will be prompted to select the branch you want to run the pipeline on. Select main and click on Run. Then click on Triggers and select Scheduled. You can then set up the schedule you want to run the pipeline on.

After executing the pipeline, you should be able to see the results in the Tests tab of your pipeline run, with any failed tests highlighted in red. You can also see the results of the pipeline run in the Runs tab of your pipeline.

Notes:

• Initial deployment of the AVS private cloud and other resources can take up to 5-6 hours, therefore the pipeline run can take up to 6 hours to complete. After the initial deployment, the pipeline run should take less than 5 minutes to complete, per successful run.
• Since the initial deployment is the only one that is needed for AD/LDAP seed scripting, for each run after the initial deployment you can set the isFirstRun variable to false in the azure-pipelines.yml file. This will skip the initial ADDS setup steps.
• You can modify the adds_install.ps1 script to fit your needs. You can add/modify users, groups, etc.
• If anything breaks, please retry with system.debug turned on. This will increase the logging and will help you understand what went wrong. For quick iterative development, local development is recommended. You can set up another branch in your repository to which you can push your code, so that you can execute the pipeline manually to test your code without merging into main.

Additional Resources

• .NET Official Tutorials
• Azure CLI documentation
• Azure DevOps documentation
• Azure DevOps Pipelines documentation
• Bicep documentation
• Azure DevOps Pipelines YAML schema reference
• Pipeline Scheduling
• NUnit documentation
• NuGet documentation
• Azure .NET SDK documentation
• Configure external identity source for vCenter Server - Azure VMware Solution | Microsoft Learn
• Azure VMware Solution: A comprehensive guide to LDAPS identity integration

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party’s policies.