Configure Deployment Group agents

Last Update: 4/7/2017

Deployment Groups are logical groups of deployment target machines with agents installed on each of them. They also specify the security context and runtime targets for the agents. When authoring a Team Services Release definition, you can specify the deployments targets for a phase using the deployment group.

Deployment group agents are pull based agents and are different from the currently available build and deployment automation agents. You can install the Deployment Group agent on each of your target servers directly, and then drive rolling deployments to those servers. Unlike the agents which are installed on a set of proxy servers in an agent pool and drive deployments to remote target servers.

You can use the Deployment Group agent as cross-platform agent and its pull-based execution model to easily drive deployments on many servers no matter which domain they are on, without having to worry about the myriad of pre-requisites. In addition to scalability, Deployment Group also provide traceability of releases all the way down to agents.

Create a Deployment Group

  1. Open your Team Services or TFS team project in your web browser.
  2. Open the Deployment Groups tab of the Build & Release hub and choose + Deployment Group to create a new group
  3. Provide a name for the Deployment in the Details tab
  4. In the Security tab, add users and give them appropriate permissions to administer, manage, view and use the groups.

Get a Deployment Group agent

To build your code or deploy your software you need at least one agent, and as you add more code and people, you'll eventually need more.

Configure Windows Agent

Requirements

Windows System Pre-requisites

Configure your account

Create a PAT token with "all scopes" by following the steps outlined here.

Download and create the agent

  1. Open your Team Services or TFS team project in your web browser.
  2. Open the Deployment Groups tab of the Build & Release hub and choose an existing Deployment Group, or choose + Deployment Group to create a new one.
  3. In the Machines hub under the selected Deployment Group, choose + Machine.
  4. Choose Windows.
  5. Choose the Download button to download the agent.
  6. Run the commands under Create the agent.

Configure the agent

  1. Run: PS C:\agent> .\config.cmd --machinegroup
  2. Respond to the prompts by providing the following
    • Server URL
    • PAT token
    • Project Name
    • Deployment Group Name
    • Agent Name
  3. You're asked if you want to run the agent as a service.

Run interactively

After you've configured the agent, we recommend that you first try it in interactive mode to make sure it works. Also, in some cases you might need to run the agent interactively for production use. For example, if you need to run an elevated process or run UI tests.

If you configured the agent to run interactively, to run it: PS C:\agent> .\run.cmd

Run as a service

After you've verified that the agent is working, for production use, we recommend that you run the agent as a service. The main advantage is that the agent stays more reliably in a running state. For example, it starts automatically when you restart the machine and after some kinds of failures.

After you configure the agent to run as a service (see above), it starts automatically. You can view and control the agent running status from the Services snap-in. Run services.msc and look for "VSTS Agent (name of your agent)".

If you need to change the logon account, don't do it from the services snap-in. Instead, see the information below to re-configure the agent.

Replace an agent

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, then make sure you remove the agent (see below) that you're replacing. Otherwise after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent: .\config remove

After you've removed the agent, you can configure it again.

Help on other options

To learn about other options: .\config --help

The help provides information on authentication alternatives and unattended configuration.

Run the agent behind a web proxy

In the agent root directory, create .proxy file with your proxy server url.

echo http://name-of-your-proxy-server:8888 | Out-File .proxy

If your proxy doesn't require authentication, then you're ready to configure and run the agent as explained above.

Note: For backwards compatibility, if the proxy is not specified as described above, the agent also checks for a proxy URL from the VSTS_HTTP_PROXY environment variable.

Proxy authentication

If your proxy requires authentication, the simplest way to handle it is to grant permissions to the user under which the agent runs. Otherwise, you can provide credentials through environment variables.

Provide credentials through environment variables

When you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs.

  • Set the following environment variables:

batch set VSTS_HTTP_PROXY_USERNAME=proxyuser set VSTS_HTTP_PROXY_PASSWORD=proxypassword

Now you're ready to configure and run the agent as explained above.

Limitations

This procedure enables the agent infrastructure to operate behind a web proxy. Your build definition and scripts must still handle proxy configuration for each task and tool you run in your build. For example:

  • If you use Git, you must configure a proxy for it.
  • If you are using a task that makes a REST API call, you must configure the proxy for that task.

Configure OS X Agent

Requirements

System pre-requisites

Configure your account

Create a PAT token with "all scopes" by following the steps outlined here.

Download and create the agent

  1. Open your Team Services or TFS team project in your web browser.
  2. Open the Deployment Groups tab of the Build & Release hub and choose an existing Deployment Group, or choose + Deployment Group to create a new one.
  3. In the Machines hub under the selected Deployment Group, choose + Machine.
  4. Choose Windows.
  5. Choose the Download button to download the agent.
  6. Run the commands under Create the agent.

Configure the agent

  1. Run: ~/myagent$ ./config.sh --machinegroup
  2. Respond to the prompts by providing the following
    • Server URL
    • PAT token
    • Project Name
    • Deployment Group Name
    • Agent Name
  3. You're asked if you want to run the agent as a service.

Run interactively

After you've configured the agent, we recommend that you first try it in interactive mode to make sure it works. Also, in some cases you might need to run the agent interactively for production use. For example, if you need to run an elevated process.

To run the agent interactively:

  1. If you have been running the agent as a service, uninstall the service.
  2. Run: ~/myagent$ ./run.sh

Run as a launchd service

After you've verified that the agent is working, for production use, we recommend that you run the agent as a service. The main advantage is that the agent stays more reliably in a running state. For example, it starts automatically when your account is logged in to the machine and after some kinds of failures.

We provide the ./svc.sh script for you to run and manage your agent as a launchd LaunchAgent service. The service has access to the UI to run your UI tests.

Note: If you prefer other approaches, you can use whatever kind of service mechanism you prefer. See Service files.

Tokens

In the section below, these tokens are replaced:

  • {agent-name}
  • {tfs-name}

For example, you have configured an agent (see above) with the name our-osx-agent. In the following examples, {tfs-name} will be either:

  • Team Services: the name of your account. For example if you connect to fabrikam.visualstudio.com , then the service name would be vsts.agent.fabrikam.our-osx-agent

  • TFS: the name of your on-premises TFS AT server. For example if you connect to our-server:8080/tfs, then the service name would be vsts.agent.our-server.our-osx-agent

Commands

Change to the agent directory

For example, if you installed in the myagent subfolder of your home directory: cd ~/myagent$

Install

Command: ./svc.sh install

This command creates a launchd plist that points to ./runsvc.sh. This script sets up the environment (more details below) and starts the agent's host.

Start

Command: ./svc.sh start

Output:
starting vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

The left number is the pid if the service is running. If second number is not zero, then a problem occurred.

Status

Command: ./svc.sh status

Output:
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

The left number is the pid if the service is running. If second number is not zero, then a problem occurred.

Stop

Command: ./svc.sh stop

Output:
stopping vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Stopped

Uninstall

You should stop before you uninstall.

Command: ./svc.sh uninstall

Automatic log on and lock

The service runs when the user logs in. If you want the agent service start when the machine restarts, you can configure the machine it to automatically log on and lock on startup. See Auto Logon and Lock.

Update environment variables

When you start the service, it takes a snapshot of your PATH other useful environment variables such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software):

  • ./env.sh
  • ./svc.sh stop
  • ./svc.sh start

Run instructions before the service starts

You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts.

  1. Edit runsvc.sh.
  2. Replace the following line with your instructions:

# insert anything to setup env when running as a service

Service Files

When you install the service, some service files are put in place.

.plist service file

A .plist service file is created:
~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

For example:
~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist
sudo ./svc.sh install generates this file from this template: ./bin/vsts.agent.plist.template

.service file

./svc.sh start finds the service by reading the .service file, which contains the path to the plist service file described above.

Alternative service mechanisms

We provide the ./svc.sh script as a convenient way for you to run and manage your agent as a launchd LaunchAgent service. But you can use whatever kind of service mechanism you prefer.

You can use the template described above as to facilitate generating other kinds of service files. For example, you modify the template to generate a service that runs as a launch daemon if you don't need UI tests and don't want to configure automatic log on and lock. See Mac Developer Library: Creating Launch Daemons and Agents.

Replace an agent

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, make sure you remove the agent (see below) that you're replacing. Otherwise after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent:

  1. Stop and uninstall the service as explained above.
  2. ./config.sh remove
  3. Enter your credentials.

After you've removed the agent, you can configure it again.

Help on other options

To learn about other options:

./config.sh --help

The help provides information on authentication alternatives and unattended configuration.

Run the agent behind a web proxy

In the agent root directory, create .proxy file with your proxy server url.

echo http://name-of-your-web-proxy:8888 > .proxy

If your proxy doesn't require authentication, then you're ready to configure and run the agent as explained above.

Note: For backwards compatibility, if the proxy is not specified as described above, the agent also checks for a proxy URL from the VSTS_HTTP_PROXY environment variable.

Proxy authentication

If your proxy requires authentication, the simplest way to handle it is to grant permissions to the user under which the agent runs. Otherwise, you can provide credentials through environment variables.

Provide credentials through environment variables

When you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs.

If you are running the agent interactively:

  • Set the following environment variables:

bash export VSTS_HTTP_PROXY_USERNAME=proxyuser export VSTS_HTTP_PROXY_PASSWORD=proxypassword

Now you're ready to configure and run the agent as explained above.

If you are running your agent as a service:

  1. Add the following section to .env file under the agent root directory:

    • VSTS_HTTP_PROXY_USERNAME=proxyuser
    • VSTS_HTTP_PROXY_PASSWORD=proxypassword
  2. Update the environment variables

Limitations

This procedure enables the agent infrastructure to operate behind a web proxy. Your build definition and scripts must still handle proxy configuration for each task and tool you run in your build. For example:

  • If you use Git, you must configure a proxy for it.
  • If you are using a task that makes a REST API call, you must configure the proxy for that task.

Q & A

Where can I learn more about how the launchd service works?

Configure Linux Agent

Requirements

Configure your account

Create a PAT token with "all scopes" by following the steps outlined here.

Download and create the agent

  1. Open your Team Services or TFS team project in your web browser.
  2. Open the Deployment Groups tab of the Build & Release hub and choose an existing Deployment Group, or choose + Deployment Group to create a new one.
  3. In the Machines hub under the selected Deployment Group, choose + Machine.
  4. Choose Windows.
  5. Choose the Download button to download the agent.
  6. Run the commands under Create the agent.

Configure the agent

  1. Run: ~/myagent$ ./config.sh --machinegroup
  2. Respond to the prompts by providing the following
    • Server URL
    • PAT token
    • Project Name
    • Deployment Group Name
    • Agent Name
  3. You're asked if you want to run the agent as a service.

Run interactively

After you've configured the agent, we recommend that you first try it in interactive mode to make sure it works. Also, in some cases you might need to run the agent interactively for production use. For example, if you need to run an elevated process.

To run the agent interactively:

  1. If you have been running the agent as a service, uninstall the service.
  2. Run: ~/myagent$ ./run.sh

Run as a launchd service

systemd service

After you've verified that the agent is working, for production use, we recommend that you run the agent as a service. The main advantage is that the agent stays more reliably in a running state. For example, it starts automatically when you restart the machine and after some kinds of failures.

If your build agent is running on these operating systems, you can run the agent as a systemd service:

  • Ubuntu 16 LTS or newer
  • Red Hat 7.1 or newer

We provide the ./svc.sh script for you to run and manage your agent as a systemd service.

Note: If you have a different distribution, or if you prefer other approaches, you can use whatever kind of service mechanism you prefer. See Service files.

Commands

Change to the agent directory

For example, if you installed in the myagent subfolder of your home directory: cd ~/myagent$

Install

Command: sudo ./svc.sh install

This command creates a service file that points to ./runsvc.sh. This script sets up the environment (more details below) and starts the agents host.

Start

sudo ./svc.sh start

Status

sudo ./svc.sh status

Stop

sudo ./svc.sh stop

Uninstall

You should stop before you uninstall.

sudo ./svc.sh uninstall

Update environment variables

When you start the service, it takes a snapshot of your PATH other useful environment variables such as PATH, LANG, JAVA_HOME, ANT_HOME, and MYSQL_PATH. If you need to update the variables (for example, after installing some new software):

  1. ./env.sh
  2. $ sudo ./svc.sh stop
  3. $ sudo ./svc.sh start

Run instructions before the service starts

You can also run your own instructions and commands to run when the service starts. For example, you could set up the environment or call scripts.

  1. Edit runsvc.sh.
  2. Replace the following line with your instructions:

# insert anything to setup env when running as a service

Service files

When you install the service, some service files are put in place.

systemd service file

A systemd service file is created:
/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

For example, you have configured an agent (see above) with the name our-linux-agent. The service file will be either:

  • Team Services: the name of your account. For example, if you connect to fabrikam.visualstudio.com, the service name would be /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service

  • TFS: the name of your on-premises TFS AT server. For example, if you connect to our-server:8080/tfs, the service name would be /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service

sudo ./svc.sh install generates this file from this template:
./bin/vsts.agent.service.template

.service file

sudo ./svc.sh start finds the service by reading the .service file, which contains the name of systemd service file described above.

Alternative service mechanisms

We provide the ./svc.sh script as a convenient way for you to run and manage your agent as a systemd service. But you can use whatever kind of service mechanism you prefer (for example: initd or upstart).

You can use the template described above as to facilitate generating other kinds of service files.

Replace an agent

When you configure an agent using the same name as an agent that already exists, you're asked if you want to replace the existing agent. If you answer Y, make sure you remove the agent (see below) that you're replacing. Otherwise after a few minutes of conflicts, one of the agents will shut down.

Remove and re-configure an agent

To remove the agent:

  1. Stop and uninstall the service as explained above.
  2. Run 3. ./config.sh remove
  3. Enter your credentials.

After you've removed the agent, you can configure it again.

Help on other options

To learn about other options:

./config.sh --help

The help provides information on authentication alternatives and unattended configuration.

Run the agent behind a web proxy

In the agent root directory, create .proxy file with your proxy server url:

echo http://name-of-your-web-proxy:8888 > .proxy

If your proxy doesn't require authentication, then you're ready to configure and run the agent as explained above.

Note: For backwards compatibility, if the proxy is not specified as described above, the agent also checks for a proxy URL from the VSTS_HTTP_PROXY environment variable.

Proxy authentication

If your proxy requires authentication, the simplest way to handle it is to grant permissions to the user under which the agent runs. Otherwise, you can provide credentials through environment variables.

Provide credentials through environment variables

When you provide credentials through environment variables, the agent keeps the credentials secret by masking them in job and diagnostic logs.

If you are running the agent interactively:

  • Set the following environment variables:

bash export VSTS_HTTP_PROXY_USERNAME=proxyuser export VSTS_HTTP_PROXY_PASSWORD=proxypassword

Now you're ready to configure and run the agent as explained above.

If you are running your agent as a service:

  1. Add the following section to .env file under the agent root directory:
    • VSTS_HTTP_PROXY_USERNAME=proxyuser
    • VSTS_HTTP_PROXY_PASSWORD=proxypassword
  2. Update the environment variables.

Limitations

This procedure enables the agent infrastructure to operate behind a web proxy. Your build definition and scripts must still handle proxy configuration for each task and tool you run in your build. For example:

  • If you use Git, you must configure a proxy for it.
  • If you are using a task that makes a REST API call, you must configure the proxy for that task.

Q & A

How do I deploy an agent on Azure?

Why is sudo needed to run the service commands?

./svc.sh uses systemctl, which requires sudo.
Source code: systemd.svc.sh.template on GitHub