Fixing Azure DevOps VMSS Connection Bug With Projects Containing Spaces

Jul 25, 2025 by gitftunila 72 views

[BUG] Cannot Connect VMSS to Agent Pool When Project Contains Space

Introduction

This article addresses a critical bug encountered when connecting a Virtual Machine Scale Set (VMSS) to an Agent Pool in Azure DevOps, specifically when the Azure DevOps project name contains a space. This issue prevents the TeamServicesAgentLinux extension from provisioning correctly, resulting in agents failing to connect to the pool. We will delve into the details of the problem, the error messages, and potential workarounds.

Problem Description

The core issue arises when attempting to link a VMSS with the TeamServicesAgentLinux extension to an Agent Pool within an Azure DevOps project that has a space in its name. The extension fails to provision on the VMSS instances, leaving the Agent Pool empty and non-functional. This problem is particularly impactful for organizations relying on VMSS for scalable and automated agent deployment in their CI/CD pipelines. The presence of a space in the project name seems to disrupt the extension's ability to correctly identify and connect to the Azure DevOps project.

Detailed Error Message

The error message observed on the VMSS instances provides valuable insight into the problem. The error typically manifests as a provisioning failure with a specific code and message. Here’s a breakdown of the error:

{
 "code": "ComponentStatus/Inputs validation/failed/53",
 "level": "Error",
 "displayStatus": "Provisioning failed",
 "message": "Could not verify that the deployment group 'vmss-v5-dev-cus' exists in the project 'My Project' in the specified organization 'https://dev.azure.com/MyOrganization'. Status: 404 Error: Please make sure that you enter the correct organization name and verify that the project exists in the organization.. "
}

This error message indicates that the extension is unable to verify the existence of the deployment group within the specified project. The key part of the message, "Could not verify that the deployment group 'vmss-v5-dev-cus' exists in the project 'My Project'", highlights the issue. The 404 status code further suggests that the project or deployment group cannot be found, likely due to the space in the project name.

Root Cause Analysis

The most probable cause of this issue is that the TeamServicesAgentLinux extension does not properly handle spaces in the project name when constructing the URLs or API calls to Azure DevOps. The space character in the project name, such as "My Project", needs to be correctly encoded (e.g., "%20") in URLs. If the extension fails to encode the space, the request to Azure DevOps will result in a 404 error because the project name cannot be resolved.

Additionally, the error message suggests a broader problem with input validation. The extension should ideally handle such scenarios gracefully, either by automatically encoding the spaces or by providing a more informative error message to the user. This lack of proper handling leads to a frustrating experience for users, as they may not immediately recognize the space in the project name as the culprit.

Attempts to Resolve the Issue

Users have attempted various workarounds to address this issue, including:

Using %20 in the project name: Some users have tried encoding the space character in the project name by using "%20" in the configuration. However, this approach has not proven successful, indicating that the issue might be more deeply rooted within the extension's code.
Verifying PAT Permissions: Ensuring that the Personal Access Token (PAT) used for the extension has full access permissions is a standard troubleshooting step. However, in this case, even with full access PATs, the issue persists, ruling out permission problems as the primary cause.

These unsuccessful attempts underscore the need for a fix within the TeamServicesAgentLinux extension itself.

Impact and Scope

The bug has a significant impact on users who rely on VMSS for agent pool scaling in Azure DevOps projects with spaces in their names. The inability to connect agents to the pool disrupts CI/CD pipelines, leading to delays in software delivery and increased operational overhead. The scope of the issue is limited to projects with spaces in their names, but it affects all users who utilize the TeamServicesAgentLinux extension in such projects.

Affected Environments

This issue primarily affects users in the following environment:

VMSS Pool: The problem is specific to VMSS agent pools, as the extension is used to provision agents on virtual machine scale sets.

Affected Azure DevOps Server Type

The issue is observed in the following Azure DevOps Server type:

dev.azure.com (formerly visualstudio.com): This indicates that the problem is present in the cloud-hosted version of Azure DevOps.

Potential Solutions and Workarounds

While a permanent solution requires a fix in the TeamServicesAgentLinux extension, there are a few potential workarounds that users can consider:

1. Renaming the Azure DevOps Project

Renaming the Azure DevOps project to remove the space is the most direct workaround. While it may require some coordination and adjustments to existing pipelines and configurations, it eliminates the root cause of the problem. This approach ensures that the extension can correctly resolve the project URL and connect the agents. However, this is a significant undertaking that requires careful planning to avoid disrupting existing workflows.

To rename the project, follow these steps:

Navigate to the Project settings in your Azure DevOps organization.
Under the Overview section, you will find the option to Rename project.
Enter the new name without spaces and confirm the change.

After renaming, ensure that all references to the project in your pipelines, scripts, and other configurations are updated accordingly. This includes:

Pipeline triggers and YAML definitions
Service connections
Any scripts or tools that use the project name

2. Creating a New Project Without Spaces

Creating a new Azure DevOps project without spaces and migrating the necessary components is another viable workaround. This approach allows you to start with a clean slate and avoid the space-related issues. However, it also involves significant effort in migrating pipelines, repositories, and other project assets.

The steps involved in this workaround are:

Create a new project in Azure DevOps with a name that does not contain spaces.
Migrate your repositories to the new project. This can be done by cloning the existing repository and pushing it to the new project.
Export and import your build and release pipelines to the new project. Azure DevOps provides options to export pipeline definitions as YAML or JSON files, which can then be imported into the new project.
Reconfigure any service connections, agent pools, and other project-level settings in the new project.
Update any external tools or scripts that interact with your Azure DevOps project to point to the new project.

This approach, while effective, requires careful planning and execution to minimize disruption to your development workflows.

3. Using a Proxy Service

Implementing a proxy service that can rewrite the URLs before they reach the TeamServicesAgentLinux extension is a more advanced workaround. This approach involves setting up a proxy server that intercepts the requests from the extension, encodes the spaces in the project name, and then forwards the modified request to Azure DevOps. This workaround requires technical expertise in setting up and configuring proxy servers and may introduce additional complexity to the infrastructure.

The general steps for this workaround are:

Set up a proxy server (e.g., Nginx, Apache) in front of the VMSS instances.
Configure the proxy server to intercept requests from the TeamServicesAgentLinux extension.
Implement URL rewriting rules in the proxy server to encode spaces in the project name (e.g., replace " " with "%20").
Configure the VMSS instances to use the proxy server for outbound traffic to Azure DevOps.

This workaround is more complex and requires ongoing maintenance of the proxy server. It is suitable for organizations that have the expertise and infrastructure to manage a proxy service.

Conclusion and Recommendations

The inability to connect VMSS to Agent Pools in Azure DevOps projects with spaces in their names is a significant issue that disrupts CI/CD pipelines. The TeamServicesAgentLinux extension's failure to handle spaces in the project name correctly leads to provisioning errors and empty Agent Pools. While renaming the project or creating a new project without spaces are viable workarounds, they involve significant effort and coordination.

It is crucial for Microsoft to address this bug in the TeamServicesAgentLinux extension to ensure seamless integration of VMSS with Azure DevOps projects, regardless of the project name. In the meantime, users should carefully consider their options and choose the workaround that best fits their needs and technical capabilities.

Recommendations

Microsoft should prioritize fixing the bug in the TeamServicesAgentLinux extension to properly handle spaces in Azure DevOps project names.
Users should consider renaming their projects to remove spaces as a long-term solution, if feasible.
Creating new projects without spaces is another viable workaround, but it requires careful migration of existing assets.
Implementing a proxy service is a more complex workaround that should be considered only if other options are not feasible.

By addressing this issue, Microsoft can significantly improve the user experience and ensure the smooth operation of CI/CD pipelines in Azure DevOps environments.