TeamCity サーバーとエージェントのアップグレード

TeamCity は、以前のバージョンからそれ以降のバージョンへのアップグレードをサポートしています。アップグレードノートに記載がない限り、すべての設定とデータは保持されます。

少なくともいくつかのバグ修正アップデートがリリースされた後、最新の TeamCity バージョンを実行するための定期的なアップグレードを計画することをお勧めします。このようにして、最新の修正とセキュリティパッチを適用した完全にサポートされたバージョンを実行します。

セキュリティパッチ

TeamCity は、サーバー、ビルドエージェント、VCS プロバイダー、その他の外部サービス (AWS S3 バケットやネクサス LFS リポジトリなど) 間の通信に大きく依存する Web アプリケーションです。そのため、非クローズド環境にデプロイされた場合、TeamCity は、採用しているサードパーティソリューションやライブラリから継承されたものも含め、一般的な脆弱性と露出 (CVE) を悪用する攻撃に対して脆弱です。

リスクを軽減するために、セキュリティ修正を含むアップデートを速やかにインストールすることを強くお勧めします。重大ではないセキュリティ脆弱性を排除する修正は、通常のバグ修正アップデートで対処されます。修正された問題のリストについては、リリースノートを参照し、セキュリティ速報を確認してください。

重大なセキュリティ上の脅威となる重大な脆弱性は、別途予定外のセキュリティパッチで修正されます。解決策が見つかると、これらのパッチは直ちにリリースされます。そのような更新が利用可能な場合、TeamCity はそれを自動的にダウンロードし、管理者にインストールを促します。

TeamCity がこれらのパッチを自動的にダウンロードしないようにするには、管理 | 更新ページの「利用可能なセキュリティパッチを自動的にダウンロードし、インストールの準備ができたら管理者に通知する」オプションのチェックを外します。ただし、この機能は新たなセキュリティの脅威に迅速に対応し、迅速な更新を保証するため、無効にしないことを強くお勧めします。

アップグレードの前に

TeamCity をアップグレードする前に:

メジャーアップグレードについては、新機能で取得するものを確認してください。
同じメジャーな YYYY.MM バージョンのバグ修正リリースの範囲内でアップグレードしていない限りライセンスキーを確認します。
新しい TeamCity バージョンをダウンロードします（リリースされたすべてのバージョンへのリンクを参照してください）。
アップグレードノートを注意深く見直してください。
テストサーバーでアップグレードを調査することを検討してください。
バンドルされていないプラグインをインストールしている場合は、プラグインページで新しいバージョンとの互換性を確認し、必要に応じてプラグインをアップグレード / アンインストールします。
TeamCity が、インストールディレクトリと TeamCity データディレクトリの両方に対する読み取りおよび書き込み権限を持つユーザーアカウントで実行されていることを確認してください。

サーバーをアップグレードするには

設定、データベース、補足データを含む現在の TeamCity データをバックアップします。アップグレードが失敗した場合に備えて、バックアップを以前のバージョンにロールバックする必要があります。
アップグレード手順を実行する :
- Windows インストーラを使用したアップグレード
- Linux での手動アップグレード

ライセンス

アップグレードする前に、ライセンスのメンテナンス期間がまだ経過していないことを確認してください (ライセンスキーを確認するには、管理 | ライセンスページを使用してください)。ライセンスは、メンテナンス期間内に有効なリリース日を持つ TeamCity のバージョンに対してのみ有効です。リリースリストで有効なリリース日を確認してください。
通常、すべてのマイナーアップデート (YYYY.MM.B TeamCity バージョンの B 部分の変更によって示されます) では、同じ有効リリース日 (メジャーリリースの日付) が使用されます。
すべてのライセンスが対象バージョンのリリース日をカバーしていない場合は、アップグレード前にライセンスを更新することを検討してください (アップグレード前でも、古いライセンスキーを更新したライセンスキーに置き換えることができます)。

新しいバージョンのみを評価する場合は、ダウンロードページから試用ライセンスを取得できます。TeamCity の各バージョンは 1 回のみ評価できることに注意してください。試用期間を延長するには、JetBrains セールス部門にお問い合わせください。

TeamCity 4.x 以前からアップグレードする場合、TeamCity バージョン 5.0 以降のライセンスポリシーは、以前の TeamCity バージョンのライセンスポリシーとは異なります。公式サイトのライセンスポリシーページとライセンスとアップグレードセクションを確認してください。

TeamCity サーバーをアップグレードする

TeamCity は、以前のバージョンから現在のバージョンへのアップグレードをサポートします。
特に明記されていない限り、データを保持したままのダウングレードはメジャーバージョンの変更では不可能であり、バグ修正リリース内では可能です。

一般的なポリシーでは、バグ修正の更新（YYYY.MM.B TeamCity バージョンの B 部分の変更によって示される）はデータ形式を変更しないため、バグ修正バージョン内で自由にアップグレード / ダウングレードできます。ただし、次のメジャーバージョン（YYYY.N を変更）にアップグレードする場合、データ保存でダウングレードすることはできません。適切なバージョンのバックアップを復元する必要があります。リリース番号についての続きを読む。

アップグレード時には、アップグレードノートに記載がない限り、すべての TeamCity 構成設定およびその他のデータが保持されます。（Tomcat サーバー設定の変更のように）TeamCity のインストールをカスタマイズした場合は、アップグレード後にカスタマイズを繰り返す必要があります。

アップグレードの一般的な方法は、TeamCity サーバーホームで以前にインストールしたファイルをすべて削除し、新しいファイルを同じ場所に配置することです。TeamCity データディレクトリとデータベースをそのまま保持する（事前にバックアップを作成する）ことを確認してください。以前にカスタマイズした設定（たとえば、...\conf\server.xml、...\conf\web.xml ファイル）をバックアップおよび復元することも必要です。ログディレクトリ（...\logs）は、古いインストールファイルのままにしておくことができます。

サーバーに接続されたエージェントは自動的にアップグレードされます。

TeamCity データ構造のアップグレードに関する重要事項
TeamCity サーバーは、データベースとファイルシステム上の TeamCity データディレクトリにデータを保存します。TeamCity のバージョンによって、データベースとデータディレクトリのデータ構造が異なります。新しいバージョンの TeamCity を起動すると、Web UI のメンテナンスページでアップグレードとデータ変換を確認するまで、データは古い形式で保持されます。確認するまでは、古いデータをバックアップできますが、アップグレードが完了すると、データは新しい形式に変換されます。
データが変換されたら、異なるデータフォーマットを使用する以前の TeamCity バージョンへのダウングレードは不可能です !

データ形式のアップグレードには、いくつかの重要な問題があります。

データ構造のダウングレードはできません。新しい TeamCity バージョンでデータベースとデータディレクトリのデータ形式が変更されると、このデータを使用して古い TeamCity バージョンを実行することはできません。TeamCity をアップグレードする前に、必ずデータをバックアップしてください。
データベースとデータディレクトリの両方を同時にアップグレードする必要があります。新しいサーバーの最初の起動時に、正しい TeamCity データディレクトリが使用され、その <TeamCity Data Directory> \config\database.properties ファイルに正しいデータベースが構成されていることを確認してください。また、データディレクトリが完全であること (たとえば、すべてのビルドログとアーティファクトが配置されていること) も確認してください。データディレクトリのコンテンツは、古いサーバーバージョンのデータディレクトリからのコピーをサポートしていません。

誤って不整合なアップグレードを実行した場合は、回復手順を確認してください。

自動アップデート

自動的に更新するには、TeamCity サーバーが jetbrains.com、download.jetbrains.com、download-cdn.jetbrains.com に接続できる必要があります。

TeamCity の新しいバージョンが検出されると、サーバーはシステム管理者に対応する正常性項目を表示します。この項目はサーバーの管理 | 更新ページを指します。このページには、更新で利用可能なすべてのバージョンがリストされています。このページには、ライセンスの互換性、新しいバージョンの説明、手動更新手順を実行する代わりに自動更新を使用する場合の制御に関する注意事項が含まれています。

自動更新手順は以下のとおりです。

TeamCity サーバーが停止しています。
更新スクリプトが実行され、次のことが行われます。
1. <TeamCity Home Directory> /.old ディレクトリに現在のインストールのバックアップを作成します。
2. 停止したサーバーを新しいバージョンに更新します。
次に、更新されたサーバーが起動します。
更新の進行状況は <TeamCity Home Directory> /logs/teamcity-update.log ファイルに記録されます。

自動アップデートが失敗した場合は、次の手順を実行して TeamCity をアップデート前の状態に復元します。

TeamCity サーバーが稼働している場合は停止します。
<TeamCity Home Directory> /.old ディレクトリに存在する各フォルダーについて、 <TeamCity Home Directory> 内の対応するフォルダーを削除します。一部のファイルは TC_home/.old ディレクトリにバックアップされていないため、「bin」フォルダーは削除しないでください。
<TeamCity Home Directory> /.old フォルダーからすべてをコピーし、<TeamCity Home Directory> に貼り付けて、重複するファイルをすべて置き換えます。
TeamCity サーバーを起動します。

自動更新のその他の制限:

TeamCityService.exe や teamcity-server.bat などの一部のファイルは、自動更新の範囲に含まれていません。
サーバーコンテキストが変更されたインストールなど、一部のカスタマイズは自動更新ではサポートされていません。
Windows アンインストーラーはアップグレード中に更新されないため、いくつかの更新後も、古い TeamCity バージョンが Windows リストに表示されます。アンインストール中に、すべての TeamCity インストールファイルが削除されるとは限りません。

手動更新

Windows インストーラを使用する

バックアップを作成します。更新された TeamCity スタートの TeamCity メンテナンスモードページで、「基本」プロファイルを使用してバックアップを作成できます。
TeamCity サーバーを実行するために使用されたユーザー名に注意してください。新しいバージョンのインストール中に必要になります。
カスタマイズした Windows サービス設定がある場合は、保存して後でカスタマイズを繰り返します。
64 ビット Java を使用してサービスを実行している場合 (たとえば、サーバーの管理 | 診断またはスレッドダンプの「Java VM 情報」で「64」を確認する)、 <TeamCity Home Directory> \jre ディレクトリのバックアップを検討してください。
（これらはアップグレードによって上書きされないため、オプションです）バンドルされている Tomcat サーバー（ポート、HTTPS プロトコルなど）または JRE（存在する場合）のカスタマイズをバックアップします。
ローカルエージェントがインストールされているかどうかを確認し（ローカルエージェントをインストールすることはお勧めしません）、後でインストーラーでこのオプションを選択できるようにします。
新しいインストーラーを実行し、TeamCity がインストールされているのと同じ場所をポイントします（インストールに使用された場所は自動的に記憶されます）。以前のインストールのアンインストールを確認します。TeamCity アンインストーラーは適切なアンインストールを保証しますが、アンインストールの完了後に TeamCity サーバーのインストールディレクトリにカスタマイズされていないファイルが含まれていないことを確認することをお勧めします。存在する場合は、インストールを続行する前にバックアップ / 削除してください。
プロンプトが表示されたら、以前のインストールで使用した <TeamCity Data Directory> を指定します。
（これらはアップグレードによって上書きされないため、オプションです）外部データベースドライバーがインストールされていることを確認してください（これは、外部データベースを使用する場合にのみ適用されます）。
必要な Windows サービスと Tomcat 構成のカスタマイズを確認し、復元します。TeamCity バージョン 7.1 以前からアップグレードする場合は、サーバーのメモリ設定を環境変数に転送するようにしてください。
サーバーを実行するために 64 ビット Java を使用していた場合は、以前にバックアップした <TeamCity Home Directory> \jre ディレクトリを復元するか、64 ビット Java のインストール手順を繰り返します。
conf\teamcity-server-log4j.xml ファイルでカスタマイズされた Log4j 構成を使用し、それを保持したい場合（代わりにログプリセットを使用することをお勧めします）、インストーラーによって既存のコピーから作成された conf\teamcity-server-log4j.xml.backup を、デフォルト名で保存されたデフォルトファイルと比較してマージします。conf\teamcity-*-log4j.xml.dist ファイルを対応する conf\teamcity-*-log4j.xml ファイルと比較し、.xml ファイルにすべての .dist ファイルのデフォルトが含まれていることを確認します。変更されたログ構成が本当に必要になるまで、.dist ファイルを対応する .xml ファイルにコピーすることをお勧めします。
TeamCity サーバー（およびインストーラと一緒にインストールされている場合はエージェント）を起動します。
TeamCity メンテナンスモードページを確認して問題が発生していないことを確認し、対応するボタンをクリックしてアップグレードを確認します。それ以降、すべてのデータが新しい形式に変換されます。

解決できないエラーが発生した場合は、古い TeamCity が動作していないこと、または起動時に起動しないことを確認し、マシンを再起動して、インストール手順を繰り返します。

.tar.gz ディストリビューションの使用

バックアップを作成します。
前回のインストール以降にカスタマイズされたファイルをバックアップする (おそらく <TOMCAT_HOME>/conf/server.xml)
古いインストールファイル（<TeamCity Home Directory> 全体）を削除します。事前にディレクトリをバックアップすることをお勧めします。
TeamCity が以前にインストールされていた場所に新しいアーカイブを解凍します。
Tomcat サーバー（独自のサーバーまたは .tar.gz TeamCity ディストリビューションにバンドルされているサーバー）を使用する場合は、work ディレクトリのコンテンツを削除することをお勧めします。これは、同じ Web サーバーにデプロイされている他の Web アプリケーションに影響を与える可能性があることに注意してください。
上記の手順 2 でバックアップしたカスタマイズ設定を復元します。カスタマイズした <TOMCAT_HOME>/conf/server.xml ファイルがある場合は、デフォルトファイルの適切なセクションに変更内容を適用します。
以前に構成された TeamCity サーバー始動プロパティ（存在する場合）がまだ実際のものであることを確認してください。
TeamCity サーバーを起動します。
TeamCity メンテナンスモードページを確認して問題が発生していないことを確認し、対応するボタンをクリックしてアップグレードを確認します。その後初めて、すべての設定データとデータベーススキーマは TeamCity コンバーターによって更新されます。

Docker イメージの使用

バックアップを作成します。
前回のインストール以降にカスタマイズされたファイルをバックアップする (おそらく <TOMCAT_HOME>/conf/server.xml)
独自の Docker イメージを構築した場合は、TeamCity サーバーの基本イメージの新しいバージョンに基づいて Docker イメージを再構築します(英語)。
docker run (英語) を呼び出して、ターゲットホスト上で新しいコンテナー ( 公式 TeamCity(英語) イメージまたは再構築したイメージのいずれか) を起動します。
TeamCity メンテナンスモードページを参照して問題が発生していないことを確認し、対応するボタンをクリックしてアップグレードを確認します。

マルチノード設定のアップグレード

マルチノード設定は、TeamCity サーバーによって実行されるタスクを複数の個別ノード間で分散し、システムの安定性とパフォーマンスを大幅に向上させます。この設定では、各ノードに個別のアップグレードが必要です。詳細については、このセクションを参照してください: アップグレード / ダウングレード。

IDE プラグイン

すべてのユーザーは、IDE プラグインを、使用中の TeamCity サーバーバージョンと互換性のある最新バージョン (少なくとも、ユーザープロファイルの TeamCity サーバーのツールセクションから入手できるバージョン) に定期的に更新することをお勧めします。
通常、IntelliJ IDEA、TeamCity プラグインと Visual Studio、TeamCity アドインのバージョンは、TeamCity サーバーのバージョンと同じである必要があります。プラグインのバージョンが一致しないユーザーは、一致しないバージョンで TeamCity サーバーにログインしようとすると、メッセージが表示されます。

サーバーのロールバック

自動または手動のサーバーアップグレードが失敗するというまれなシナリオでは、TeamCity を以前の状態に復元できます。詳細については、次の記事を参照してください。

ビルドエージェントのアップグレード

自動ビルドエージェントのアップグレード
ビルドエージェントを手動でアップグレードする
- ビルドエージェント Windows サービスラッパーのアップグレード

自動ビルドエージェントの更新

TeamCity サーバーを起動すると（およびサーバー上のエージェントディストリビューションまたはプラグインを更新すると）、サーバーに接続され、正しくインストールされている TeamCity エージェントは、サーバーに対応するバージョンに自動的に更新されます。これは、サーバーのアップグレードとダウングレードの両方で発生します。エージェントで実行中のビルドがある場合、ビルドは終了します。エージェントがサーバーを最新の状態にしない限り、エージェントで新しいビルドは開始されません。

エージェントのアップグレードを開始する前に、エージェントの空きディスク容量（デフォルトでは 3 GB）がチェックされます。アップグレードに必要な値を変更するには、teamcity.agent.upgrade.ensure.free.space エージェントのプロパティを構成します。

エージェントの更新手順は次のとおりです。エージェント（agent.bat、agent.sh、エージェントサービス）は、現在のエージェントパッケージを TeamCity サーバーからダウンロードします。ダウンロードが完了し、エージェントがアイドル状態になると、アップグレードプロセスが開始されます（エージェントが停止され、エージェントファイルが更新され、エージェントが再起動されます）。このプロセスは、エージェントのハードウェアとネットワーク帯域幅によっては数分かかる場合があります。アップグレードプロセスを中断しないでくださいを実行すると、アップグレードが失敗する可能性があり、エージェントを手動で再インストールする必要があります。

TeamCity UI でエージェントが「エージェントが切断されます (アップグレードされます)」と表示されている場合は、エージェントコンソールを閉じたり、エージェントプロセスを再起動したりせずに、数分間待機してください。

エージェントのアップグレード中は、さまざまなコンソールウィンドウを開閉できます。エージェントのアップグレードが完了するまで、しばらくお待ちください。プロセスを中断しないでください。

手動ビルドエージェントの更新

接続されているエージェントはすべて、正しくインストールされている限り自動的にアップグレードされるため、手動でのアップグレードは必要ありません。

エージェントを手動でアップグレードする必要がある場合は、以下の手順に従ってください。

TeamCity エージェントは固有の情報を保持していないため、エージェントをアップグレードする最も簡単な方法は次のとおりです。

<Agent Home>/conf/buildAgent.properties ファイルをバックアップします。
既存のエージェントをアンインストール / 削除します。
新しいエージェントバージョンをインストールします。
以前に保存した buildAgent.properties ファイルを同じ場所に復元します。
エージェントを起動します。

アップグレード後の清潔なチェックアウトを排除するためなど、すべてのエージェントデータを保持する必要がある場合は、次のことができます。

エージェントを停止します。
conf を除く、エージェント .zip ディストリビューションに存在するエージェントインストール内のすべてのディレクトリを削除します。
「conf」ディレクトリをスキップして、.zip ディストリビューションをエージェントのインストールディレクトリに解凍します。
エージェントを起動します。

後者の場合、サービスを使用して Windows でエージェントを実行する場合は、以下で説明するように Windows サービスのアップグレードも必要になる場合があります。

ビルドエージェント Windows サービスラッパーのアップグレード

サービスラッパーの更新が必要な場合、新しいバージョンが <agent>/launcher.latest ディレクトリにダウンロードされますが、変更は自動的には適用されません。

サービスラッパーを手動でアップグレードするには、次の手順に従います。

<agent>/launcher.latest フォルダーが存在することを確認してください。
<agent>\bin\service.stop.bat を使ってサービスを停止します。
service.uninstall.bat を使ってサービスをアンインストールします。
<agent>/launcher/conf/wrapper.conf ファイルをバックアップします。
<agent>/launcher を削除します。
<agent>/launcher.latest を <agent>/launcher に名前変更します。
<agent>/launcher/conf/wrapper.conf ファイルを編集します。wrapper.java.command プロパティが java.exe ファイルを指していることを確認してください。レジストリを使用して java を検索するには、空白のままにします。java.exe を離れて、PATH で java.exe を検索します。スタンドアロンエージェントの場合、サービス値は ../jre/bin/java である必要があり、サーバーにエージェントをインストールする場合、値は ../../jre/bin/java である必要があります。wrapper.conf ファイルのバックアップバージョンを使用できます。
<agent>\bin\service.install.bat を使用してサービスをインストールしてください。
サービスが適切なユーザーアカウントで実行されていることを確認してください。SYSTEM を使用すると、MSBuild/Sln2005 構成を使用するビルドが失敗する可能性があることに注意してください。
<agent>\bin\service.start.bat を使ってサービスを開始します。