チュートリアル: Service Fabric クラスターへのデプロイ

[アーティクル]
06/08/2023

このチュートリアルでは、Jenkins 環境のいくつかのセットアップ方法と、ビルド後にアプリケーションを Service Fabric クラスターにデプロイするさまざまな方法について説明します。 Jenkins を正しく構成し、GitHub から変更をプルし、アプリケーションをビルドしてクラスターにデプロイするには、次の一般的な手順に従います。

必ず、前提条件をインストールしてください。
その後、次のいずれかのセクションの手順に従って Jenkins をセットアップします。
Jenkins を設定したら、「Jenkins ジョブの作成と構成」の手順に従って、アプリケーションに変更が加えられたときに Jenkins をトリガーするように GitHub をセットアップしたり、GitHub から変更をプルしてアプリケーションをビルドするビルドステップを使用して Jenkins ジョブパイプラインを構成したりします。
最後に、アプリケーションを Service Fabric クラスターにデプロイするように、Jenkins ジョブのビルド後のステップを構成します。アプリケーションをクラスターにデプロイするように Jenkins を構成する方法は 2 つあります。
- 開発およびテスト環境では、「クラスター管理エンドポイントを使用してデプロイを構成する」に従ってください。この方法は、デプロイの最も簡単なセットアップ方法です。
- 運用環境では、「Azure 資格情報を使用してデプロイを構成する」に従ってください。運用環境にはこの方法をお勧めします。Azure 資格情報を使えば、Jenkins ジョブによる Azure リソースへのアクセス権を制限できるためです。

前提条件

Git がローカルにインストールされていることを確認してください。 Git のダウンロードページから、お使いのオペレーティングシステムに応じて適切な Git バージョンをインストールできます。 Git を使用するのが初めての場合、Git に関するドキュメントで詳細を確認してください。
この記事では、アプリケーションのビルドとデプロイのために GitHub にある Service Fabric Getting Started Sample (https://github.com/Azure-Samples/service-fabric-java-getting-started) を使用します。このリポジトリをフォークして従うことも、手順を一部変更して独自の GitHub プロジェクトを使用することもできます。

既存の Jenkins 環境への Service Fabric プラグインのインストール

Service Fabric プラグインを既存の Jenkins 環境に追加する場合は、次の手順を実行する必要があります。

Service Fabric CLI (sfctl)。 Jenkins で CLI コマンドを実行できるよう、CLI は、ユーザーレベルではなくシステムレベルでインストールしてください。
Java アプリケーションをデプロイするには、Gradle および Open JDK 8.0 の両方をインストールします。
.NET Core 2.0 アプリケーションをデプロイするには、.NET Core 2.0 SDK をインストールします。

環境に必要な前提条件をインストールした後は、Jenkins Marketplace で Azure Service Fabric プラグインを検索してインストールすることができます。

プラグインをインストールした後は、「Jenkins ジョブの作成と構成」に進んでください。

Service Fabric クラスター内での Jenkins のセットアップ

Jenkins は、Service Fabric クラスター内外でセットアップできます。次のセクションでは、Azure Storage アカウントを使用してコンテナーインスタンスの状態を保存する際にクラスター内部で Jenkins をセットアップする方法について説明します。

Service Fabric Linux クラスターに Docker をインストールしておきます。 Azure で実行する Service Fabric クラスターにあらかじめ Docker をインストールしておきます。クラスターをローカル (OneBox 開発環境) で実行している場合は、docker info コマンドを使って Docker がコンピューターにインストールされているかどうかを確認します。 Docker がインストールされていない場合、次のコマンドを使用してインストールします。
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Note

クラスターで 8081 ポートがカスタムエンドポイントとして指定されていることを確認します。ローカルクラスターを使用している場合は、ホストコンピューターでポート 8081 が開いていることと、公開 IP アドレスがあることを確認します。

次のコマンドを使用して、アプリケーションを複製します。

git clone https://github.com/suhuruli/jenkins-container-application.git
cd jenkins-container-application

ファイル共有内の Jenkins コンテナーの状態を維持します。
1. クラスターと同じリージョンに Azure Storage アカウント (例: sfjenkinsstorage1) を作成します。
2. そのストレージアカウントの下に、ファイル共有 (例: sfjenkins) を作成します。
3. そのファイル共有の [接続] をクリックして、[Linux からの接続] の下に表示される、以下のような値をメモします。
```
sudo mount -t cifs //sfjenkinsstorage1.file.core.windows.net/sfjenkins [mount point] -o vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777
```
Note

cifs 共有をマウントするには、クラスターノードに cifs ユーティリティパッケージがインストールされている必要があります。
setupentrypoint.sh スクリプトのプレースホルダーの値を、手順 2 の Azure Storage の内容に更新します。
```
vi JenkinsSF/JenkinsOnSF/Code/setupentrypoint.sh
```
- [REMOTE_FILE_SHARE_LOCATION] を、上記の手順 2 の接続の出力にある値 //sfjenkinsstorage1.file.core.windows.net/sfjenkins に置き換えます。
- [FILE_SHARE_CONNECT_OPTIONS_STRING] を上記の手順 2 の値 vers=3.0,username=<username>,password=<storage-key>,dir_mode=0777,file_mode=0777 に置き換えます。
セキュリティで保護されたクラスターのみ:

Jenkins からセキュリティで保護されたクラスター上のアプリケーションのデプロイを構成するには、Jenkins コンテナー内でクラスター証明書をアクセス可能にする必要があります。 ApplicationManifest.xml ファイルの ContainerHostPolicies タグの下にこの証明書参照を追加し、拇印の値をクラスター証明書の値に更新します。
```
<CertificateRef Name="MyCert" X509FindValue="[Thumbprint]"/>
```
さらに、ApplicationManifest.xml ファイルの ApplicationManifest (ルート) タグの下に次の行を追加し、拇印の値をクラスター証明書の拇印の値で更新します。
```
<Certificates>
  <SecretsCertificate X509FindType="FindByThumbprint" X509FindValue="[Thumbprint]" />
</Certificates> 
```
クラスターに接続し、コンテナーアプリケーションをインストールします。

セキュリティで保護されたクラスター
```
sfctl cluster select --endpoint https://PublicIPorFQDN:19080  --pem [Pem] --no-verify # cluster connect command
bash Scripts/install.sh
```
上記のコマンドは、PEM 形式で証明書を受け取ります。証明書が PFX 形式の場合は、次のコマンドを使用して変換できます。 PFX ファイルがパスワードで保護されていない場合は、passin パラメーターを -passin pass: に指定します。
```
openssl pkcs12 -in cert.pfx -out cert.pem -nodes -passin pass:<password>
```
セキュリティで保護されていないクラスター
```
sfctl cluster select --endpoint http://PublicIPorFQDN:19080 # cluster connect command
bash Scripts/install.sh
```
これでクラスターに Jenkins コンテナーがインストールされます。このコンテナーは Service Fabric Explorer を使用して監視できます。

Note

Jenkins イメージがクラスターにダウンロードされるまでに数分かかる場合があります。
ブラウザーで http://PublicIPorFQDN:8081 に移動します。サインインに必要な最初の管理者パスワードのパスが提供されます。
Jenkins コンテナーで実行されているノードは、Service Fabric Explorer で確認します。このノードに Secure Shell (SSH) でサインインします。
```
ssh user@PublicIPorFQDN -p [port]
```
docker ps -a を使用してコンテナーのインスタンス ID を取得します。
Secure Shell (SSH) でコンテナーにサインインして、Jenkins ポータルに表示されたパスを貼り付けます。たとえば、ポータルに表示されたパスが PATH_TO_INITIAL_ADMIN_PASSWORD の場合、次のコマンドを実行します。
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash   # This takes you inside Docker shell
```
```
cat PATH_TO_INITIAL_ADMIN_PASSWORD # This displays the password value
```
Jenkins の最初のページで、[Select plug-in to install]$インストールするプラグインの選択$ オプションを選択し、[None]$なし$ チェックボックスを選択して、[Install]$インストール$ をクリックします。
ユーザーを作成するか、管理者として続行します。

Jenkins をセットアップした後は、「Jenkins ジョブの作成と構成」に進んでください。

Service Fabric クラスター外での Jenkins のセットアップ

Jenkins は、Service Fabric クラスターの内部か外部でセットアップできます。次のセクションでは、クラスターの外部でセットアップする方法について説明します。

ターミナルから docker info を実行して、Docker がマシンにインストールされていることを確認します。その出力結果に、Docker サービスが実行中であるかどうかが表示されます。
Docker がインストールされていない場合は、次のコマンドを実行します。
```
sudo apt-get install wget
wget -qO- https://get.docker.io/ | sh
```
Service Fabric Jenkins コンテナーイメージを取得しますdocker pull rapatchi/jenkins:latest。このイメージには Service Fabric Jenkins プラグインがプレインストールされています。
コンテナーイメージを実行します。docker run -itd -p 8080:8080 rapatchi/jenkins:latest
コンテナーイメージインスタンスの ID を取得します。 docker ps –a コマンドを使用して、すべての Docker コンテナーの一覧を取得できます。
次の手順を使用して Jenkins ポータルにサインインします。
1. ホストから Jenkins シェルにサインインします。コンテナー ID の最初の 4 桁の数字を使用します。たとえば、コンテナー ID が 2d24a73b5964 の場合は、2d24 を使用します。
```
docker exec -it [first-four-digits-of-container-ID] /bin/bash
```
2. Jenkins シェルから、コンテナーインスタンスの管理者パスワードを取得します。
```
cat /var/jenkins_home/secrets/initialAdminPassword
```
3. Jenkins ダッシュボードにサインインするには、Web ブラウザーで次の URL を開きます: http://<HOST-IP>:8080。前の手順のパスワードを使用して、Jenkins のロックを解除します。
4. (省略可能) 初めてサインインした後は、独自のユーザーアカウントを作成して以降の手順で使用するか、管理者アカウントを使い続けることができます。ユーザーを作成した場合は、そのユーザーを使い続ける必要があります。
「Generating a new SSH key and adding it to the SSH agent (新しい SSH キーの生成と SSH エージェントへの追加)」で説明されている手順を使用して、Jenkins を利用できるように GitHub をセットアップします。
- GitHub によって提供されている手順を使用して、SSH キーを生成し、リポジトリをホストする GitHub アカウントにその SSH キーを追加します。
- (ホストではなく) Jenkins Docker シェルで、前のリンク先に記載されているコマンドを実行します。
- ホストから Jenkins シェルにサインインするには、次のコマンドを使用します。
```
docker exec -t -i [first-four-digits-of-container-ID] /bin/bash
```

Jenkins コンテナーイメージがホストされているクラスターまたはコンピューターに公開 IP アドレスがあることを確認します。この公開 IP を使用することで、Jenkins インスタンスは GitHub から通知を受け取ることができます。

Jenkins をセットアップした後は、次のセクション、「Jenkins ジョブの作成と構成」に進んでください。

Jenkins ジョブの作成と構成

このセクションの手順は、GitHub リポジトリ内の変更に対応し、変更内容を取り込んでビルドするように Jenkins ジョブを構成する方法を示しています。このセクションの最後には、開発/テスト環境または運用環境のどちらにデプロイするかに応じてアプリケーションをデプロイするようにジョブを構成する、最後の手順が指示されます。

Jenkins ダッシュボードで、[New Item]$新しい項目$ をクリックします。
項目の名前を入力します (例: MyJob)。 フリースタイルプロジェクトを選択し、 [OK] をクリックします。
ジョブを構成するページが開きます。 (Jenkins ダッシュボードから構成を始めるには、ジョブをクリックしてから、[構成] をクリックします)。
[全般] タブで [GitHub プロジェクト] のチェックボックスをオンにし、GitHub プロジェクトの URL を指定します。この URL では、Jenkins の継続的インテグレーション/継続的デプロイ (CI/CD) フローと統合する Service Fabric Java アプリケーションがホストされます (例: https://github.com/{your-github-account}/service-fabric-java-getting-started)。
[Source Code Management (ソースコードの管理)] タブで [Git] を選択します。 Jenkins CI/CD フローと統合する Service Fabric Java アプリケーションをホストするリポジトリの URL を指定します (例: https://github.com/{your-github-account}/service-fabric-java-getting-started)。ビルドする分岐を指定することもできます (例: /master)。
Jenkins と対話するように GitHub リポジトリを構成します。
1. GitHub リポジトリのページで [Settings (設定)]>[Integrations and Services (統合とサービス)] の順に移動します。
2. [Add Service]$サービスの追加$ を選択して「Jenkins」と入力し、[Jenkins-GitHub plug-in]$Jenkins-GitHub プラグイン$ を選択します。
3. Jenkins webhook の URL を入力します (既定では、http://<PublicIPorFQDN>:8081/github-webhook/ です)。 [Add service (サービスの追加)] または [Update service (サービスの更新)] をクリックします。
4. テストイベントが Jenkins インスタンスに送信されます。 GitHub で webhook の側に緑色のチェックマークが表示され、プロジェクトがビルドされます。
Jenkins の [Build Triggers (ビルドトリガー)] タブで、目的のビルドオプションを選択します。この例では、リポジトリへのプッシュが行われるたびにビルドがトリガーされるようにします。そのため、[GitHub hook trigger for GITScm polling (GITScm ポーリングの GitHub フックトリガー)] を選択します。 (以前、このオプションの名前は [Build when a change is pushed to GitHub (変更が GitHub にプッシュされたときにビルド)] でした)。
[ビルド] タブで、Java アプリケーションまたは .NET Core アプリケーションのどちらをビルドするかに応じて、次のいずれかを実行します。
- Java アプリケーションの場合:[ビルドステップの追加] ドロップダウンから [Gradle スクリプトの呼び出し] を選択します。 詳細設定をクリックします。詳細メニューで、[Root build script (ルートビルドスクリプト)] にアプリケーションのパスを指定します。ウィジェットは、指定されたパスから build.gradle を取得し、適切に動作します。 ActorCounter アプリケーションの場合、これは ${WORKSPACE}/reliable-services-actor-sample/Actors/ActorCounter です。
- .NET Core アプリケーションの場合:[ビルドステップの追加] ドロップダウンから [Execute Shell (シェルの実行)] を選択します。表示されるコマンドボックスで、ディレクトリを、build.sh ファイルが配置されているパスに最初に変更する必要があります。ディレクトリを変更したら、build.sh スクリプトを実行してアプリケーションをビルドできます。
```
cd /var/jenkins_home/workspace/[Job Name]/[Path to build.sh]  
./build.sh
```
  次のスクリーンショットは、Jenkins ジョブの名前が CounterServiceApplication の、カウンターサービスサンプルをビルドするときに使用されるコマンド例を示しています。
ビルド後のアクションでアプリを Service Fabric クラスターにデプロイするように Jenkins を構成するには、Jenkins コンテナー内のそのクラスターの証明書の位置が必要です。 Jenkins コンテナーをクラスター内またはクラスター外のどちらで実行するかに応じて、次のいずれかを選択し、クラスター証明書の位置を書き留めます。
- クラスター内で実行される Jenkins の場合: 証明書へのパスは、コンテナー内から Certificates_JenkinsOnSF_Code_MyCert_PEM 環境変数の値をエコーして確認できます。
```
echo $Certificates_JenkinsOnSF_Code_MyCert_PEM
```
- クラスター外で実行される Jenkins の場合: 次の手順に従って、クラスター証明書をコンテナーにコピーします。
  1. 証明書は、PEM 形式でなければなりません。 PEM ファイルがない場合は、証明書の PFX ファイルから作成できます。 PFX ファイルがパスワードで保護されていない場合は、ホストから次のコマンドを実行します。
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:
```
    PFX ファイルがパスワードで保護されている場合は、-passin パラメーターにパスワードを含めます。次に例を示します。
```
openssl pkcs12 -in clustercert.pfx -out clustercert.pem -nodes -passin pass:<password>
```
  2. Jenkins コンテナーのコンテナーの ID を取得するには、ホストから docker ps を実行します。
  3. 次の Docker コマンドを使用して、PEM ファイルをコンテナーにコピーします。
```
docker cp clustercert.pem [first-four-digits-of-container-ID]:/var/jenkins_home
```

あともう少しで終了です。 Jenkins ジョブは開いたままにください。残りのタスクは、アプリケーションを Service Fabric クラスターにデプロイするようにビルド後のステップを構成することだけです。

開発またはテスト環境にデプロイするには、「クラスター管理エンドポイントを使用してデプロイを構成する」の手順に従います。
運用環境にデプロイするには、「Azure 資格情報を使用してデプロイを構成する」の手順に従います。

クラスター管理エンドポイントを使用してデプロイを構成する

開発およびテスト環境では、クラスター管理エンドポイントを使用してアプリケーションをデプロイすることができます。クラスター管理エンドポイントでアプリケーションをデプロイするようにビルド後のアクションを構成するには、最小限のセットアップが必要です。運用環境にデプロイする場合は、「Azure 資格情報を使用してデプロイを構成する」に進んで、デプロイ時に使用する、Microsoft Entra サービスプリンシパルを構成します。

Jenkins ジョブで [Post-build Actions (ビルド後のアクション)] タブをクリックします。
[Post-Build Actions (ビルド後のアクション)] ボックスの一覧の [Deploy Service Fabric Project (Service Fabric プロジェクトのデプロイ)] を選択します。
Service Fabric Cluster Configuration (Service Fabric クラスター構成)] の下にある [Fill the Service Fabric Management Endpoint (Service Fabric 管理エンドポイントの設定)] ラジオボタンを選択します。
[Management Host (管理ホスト)] には、クラスターの接続エンドポイント (例: {your-cluster}.eastus.cloudapp.azure.com) を入力します。
[Client Key (クライアントキー)] と [Client Cert (クライアント証明書)] には、Jenkins コンテナー内 PEM ファイルの位置 (例: /var/jenkins_home/clustercert.pem) を入力します。 (「Jenkins ジョブの作成と構成」の最後の手順でコピーした証明書の位置です。)
[Application Configuration (アプリケーションの構成)] で、[アプリケーション名]、[アプリケーションの種類]、および [Path to Application Manifest (アプリケーションマニフェストへのパス)] (相対) の各フィールドを設定します。
[Verify Configuration]をクリックします。検証が正常に行われたら、[保存] をクリックします。これで Jenkins ジョブパイプラインが完全に構成されました。次のステップに進んで、デプロイをテストしてください。

Azure 資格情報を使用してデプロイを構成する

運用環境の場合は、アプリケーションをデプロイするように Azure 資格情報を構成することを強くお勧めします。このセクションでは、ビルド後のアクションでアプリケーションをデプロイするために使用するように、Microsoft Entra サービスプリンシパルを構成する方法を示します。ディレクトリのロールにサービスプリンシパルを割り当てて、Jenkins ジョブの権限を制限することができます。

開発およびテスト環境の場合は、アプリケーションをデプロイするように、Azure 資格情報またはクラスター管理エンドポイントのいずれかを構成することができます。クラスター管理エンドポイントの構成方法の詳細については、「クラスター管理エンドポイントを使用してデプロイを構成する」をご覧ください。

Microsoft Entra サービスプリンシパルを作成し、Azure サブスクリプションで権限を割り当てるには、「Microsoft Entra アプリケーションとサービスプリンシパルをポータルで作成する」の手順に従ってください。次の点に注意してください。
- トピックの手順を実行する際は、[アプリケーション ID]、[アプリケーションキー]、[ディレクトリ ID (テナント ID)]、および [サブスクリプション ID] の値を必ずコピーし、保存してください。それらは Jenkins で Azure 資格情報を構成するために必要です。
- ディレクトリに必要な権限がない場合は、管理者に依頼して、権限を付与するかサービスプリンシパルを作成してもらう必要があります。または、Jenkins のジョブ用に [Post-Build Actions (ビルド後のアクション)] でクラスターの管理エンドポイントを構成する必要があります。
- 「Microsoft Entra アプリケーションを作成する」のセクションでは、[サインオン URL] に適切な形式の URL を入力することができます。
- 「アプリケーションをロールに割り当てる」のセクションでは、アプリケーションにクラスターのリソースグループの閲覧者ロールを割り当てることができます。
Jenkins ジョブに戻って、[Post-build Actions (ビルド後のアクション)] タブをクリックします。
[Post-Build Actions (ビルド後のアクション)] ボックスの一覧の [Deploy Service Fabric Project (Service Fabric プロジェクトのデプロイ)] を選択します。
[Service Fabric Cluster Configuration]$Service Fabric クラスター構成$ の [Select the Service Fabric Cluster]$Service Fabric クラスターの選択$ をクリックします。 [Azure Credentials (Azure 資格情報)] の横の [追加] をクリックします。 [Jenkins] をクリックして、Jenkins 資格情報プロバイダーを選択します。
Jenkins 資格情報プロバイダーで、[種類] ドロップダウンから [Microsoft Azure サービスプリンシパル] を選択します。
手順 1 でサービスプリンシパルを設定するときに保存した値を使用して、次のフィールドを設定します。
- クライアント ID:アプリケーション ID
- クライアントシークレット:アプリケーションキー
- テナント ID: ディレクトリ ID
- サブスクリプション ID: サブスクリプション ID
Jenkins で資格情報を選択するために使用するわかりやすい ID と、簡単な [説明] を入力します。次に、[Verify Service Principal (サービスプリンシパルの検証)] をクリックします。検証が成功したら、[追加] をクリックします。
[Service Fabric Cluster Configuration (Service Fabric クラスター構成)] に戻って、[Azure Credentials (Azure 資格情報)]に新しい資格情報が選択されていることを確認します。
[リソースグループ] ドロップダウンで、アプリケーションをデプロイするクラスターのリソースグループを選択します。
[Service Fabric] ドロップダウンで、アプリケーションをデプロイするクラスターを選択します。
[Client Key (クライアントキー)] と [Client Cert (クライアント証明書)] には、Jenkins コンテナー内 PEM ファイルの位置を入力します。たとえば、「 /var/jenkins_home/clustercert.pem 」のように指定します。
[Application Configuration (アプリケーションの構成)] で、[アプリケーション名]、[アプリケーションの種類]、および [Path to Application Manifest (アプリケーションマニフェストへのパス)] (相対) の各フィールドを設定します。
[Verify Configuration]をクリックします。検証が正常に行われたら、[保存] をクリックします。これで Jenkins ジョブパイプラインが完全に構成されました。次のステップに進んで、デプロイをテストしてください。

Jenkins プラグインのトラブルシューティング

Jenkins プラグインでバグが発生した場合は、Jenkins JIRA で特定のコンポーネントについてイシューを登録してください。

試してみましょう

GitHub と Jenkins の構成が完了しました。リポジトリ (https://github.com/Azure-Samples/service-fabric-java-getting-started) のフォークの reliable-services-actor-sample/Actors/ActorCounter プロジェクトにサンプルの変更を加えてみましょう。リモートの master 分岐 (または動作するように構成したいずれかの分岐) に変更をプッシュすると、構成した Jenkins ジョブ MyJob がトリガーされます。 GitHub から変更内容がフェッチされてビルドが行われ、ビルド後のアクションで指定したクラスターにアプリケーションがデプロイされます。

次のステップ

Azure 上の Jenkins

次の方法で共有