Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 2018.x Documentation

Documentation for Previous Versions

Icon

You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

It is assumed that the machine images are pre-configured to start TeamCity agent on boot (see details below). The exception is the usage of agent push.

Once a cloud profile is configured in TeamCity with one or several images, TeamCity does a test start for all the new images to learn about the agents configured on them.
Once the agents are connected, TeamCity stores their parameters to be able to correctly process the build configurations-to-agents compatibility correctly.

For each queued build, TeamCity first tries to start it on one of the regular, non-cloud agents. If there are no usual agents available, TeamCity finds a matching cloud image with a compatible agent and starts a new instance for the image. TeamCity ensures that the running instances limit configured in the cloud profile is not exceeded.

Once an agent is connected from a cloud instance started by TeamCity, it is automatically authorized (provided there are available agent licenses). After that, the agent is processed as a regular agent.
If running timeout is configured on the cloud profile and it is reached, the instance is terminated.
If an EBS-based instance id is specified in the images list, the instance is stopped instead. 

...

Please ensure that the server URL specified on the Global Settings page in the Administration area is correct since agents will use it to connect to the server.

If you need TeamCity to use a proxy to access EC2 services, please read on a current workaround in the dedicated issue.

...

To launch an instance with Iam the Iam Role (applicable to instances cloned from AMI-s only), the following additional permissions are required:

...

  • TeamCity agent should be correctly installed.
  • TeamCity agent should start on machine startup
  • buildAgent.properties can be left " as is". The "serverUrl", "name" and "authorizationToken" properties can be empty or set to any value, ; they are ignored when TeamCity starts the instance.

...

If you need the connection between the server and the agent machine to be secure, you will need to set up the agent machine to establish a secure tunnel (e.g., VPN) to the server on boot so that TeamCity agent receives data via the secure channel.

Recommended image (e.g., Amazon AMI) preparation steps:

  1. Choose one of the existing generic images.
  2. Start the image.
  3. Configure the running instance:
    • Install and configure a build agent:
      • Configure server name and agent name in conf/buildAgent.properties — this is optional, if optional if the image will be started by TeamCity, but it is useful to test the agent is configured correctly.
      • It usually makes sense to specify tempDir and workDir in conf/buildAgent.properties to use non-system drive (d: under Windows)
    • Install any additional software necessary for the builds on the machine.
    • Run the agent and check it is working OK and is compatible with all necessary build configurations, etc.
    • Configure system so that agent it is started on machine boot (and make sure TeamCity server is accessible on machine boot).
    • Anchor
      EC2ConfigDep
      EC2ConfigDep
      To ensure proper TeamCity agent communication with EC2 API (including access to additional drives) on Windows, add a dependency from the TeamCity Build Agent service on the AmazonSSMAgent or EC2Launch / EC2Config service (the service which makes sure the machine is fully initialized in regard to AWS infrastructure use). This can be done, for example, via the Registry or using sc config, e.g. sc config TCBuildAgent depend=EC2Config
      Alternatively, you can use the "Automatic (delayed start)" service starting mode.

  4. Test the setup by rebooting the machine and checking that the agent connects normally to the server.
  5. Prepare the Image for bundling:
    • Remove any temporary/history information in the system.
    • Stop the agent (under Windows stop the service but leave it in Automatic startup type)
    • Delete content logs and temp directories in agent home (optional)
    • Delete "<Agent Home>/conf/amazon-*" file (optional)
    • Change config/buildAgent.properties to remove properties: name, serverUrl, authorizationToken (optional). serverUrl can be removed for EC2 integration plugins. Other plugins might require that it is present and set to correct value.
  6. Make a new image from the running instance (or just stop it for Amazon EBS images).

...

To ensure proper TeamCity agent communication with EC2 API (including access to additional drives) on Windows, add a dependency from the TeamCity Build Agent service on the AmazonSSMAgent or EC2Launch / EC2Config service (the service which makes sure the machine is fully initialized in regard to AWS infrastructure use). This can be done, for example, via the Registry or using sc config, e.g., sc config TCBuildAgent depend=EC2Config
Alternatively, you can use the "Automatic (delayed start)" service starting mode.

...

Due to the bug in the network settings, instance meta-data is not available by default. That means TeamCity agent service cannot retrieve its properties and cloud integration doesn't work (agent does not connect to the server or is not automatically authorized).
To fix the issue please do the following:
1) Install the latest EC2Config
2) When EC2Config is installed make TCBuildAgent service dependent on both EC2Config and AmazonSSMAgent via the command: sc config TCBuildAgent depend=Ec2Config/AmazonSSMAgent

...

TeamCity agent auto-upgrades whenever distribution of agent plugins on the server changes (e.g., after TeamCity upgrade). If you want to cut agent startup time, you might want to re-bundle the agent AMI after agent plugins have been auto-updated.

...

TeamCity enables users to get instance launch information by marking the created instances with the "teamcity:TeamcityData" tag containing <server UUID>:-<cloud profile ID>:-<image reference>.

...

As mentioned above, TeamCity tags every instance it launches with "the teamcity:TeamcityData" tag that represents a server, cloud profile, and source (AMI or EBS-instance). So, in case when several TeamCity servers tries try to use the same EBS instance, the second one will see the following message "Instance is used by another TeamCity server. Unable to start/stop it". If you are sure that no other TeamCity servers are working with this instance, you can delete the "teamcity:TeamcityData" tag and the instance will become available for all TeamCity servers again.

...

Since Amazon doesn't provide a robust API method to retrieve all instance types, Amazon integration relies on the periodical update of AWS SDK to make new instance types available.

...