CircleCI Server v3.x インストール ステップ 3

CircleCI サーバー v3.x ビルドサービスのインストールステップを開始する前に、 ステップ 1: 前提条件ステップ 2: コアサービスのインストールが実行済みであることを確認してください。

In the following steps replace any items or credentials displayed between < > with your details.

ステップ 3: ビルドサービスのインストール

出力プロセッサ

概要

出力プロセッサは、 Normad クライアントからの出力処理を行います。 システムの速度が低下している場合にスケーリングするための重要なサービスです。 要求に応じてサービスをスケールアップできるよう、出力プロセッサのレプリカセットを増やすことをお勧めします。

KOTS の管理者コンソールにアクセスします。 Get to the KOTS admin console by running the following, substituting your namespace: kubectl kots admin-console -n <YOUR_CIRCLECI_NAMESPACE>

設定で次の項目を入力します。

  1. [Output Processor Load Balancer (出力プロセッサ ロードバランサー)](必須): 次のコマンドにより、サービスの IP アドレスを取得します

    kubectl get service output-processor --namespace=<YOUR_CIRCLECI_NAMESPACE>
  2. [Save your configuration (設定を保存)]: Nomad クライアントの設定の完了後、設定のデプロイと確認を行います。

Nomad クライアント

概要

As mentioned in the Overview, Nomad is a workload orchestration tool that CircleCI uses to schedule (via Nomad Server) and run (via Nomad Clients) CircleCI jobs.

Nomad クライアントは Kubernetes クラスタの外部にインストールされ、コントロールプレーン( Nomad サーバー)はクラスタ内にインストールされます。 Nomad クライアントと Nomad コントロールプレーン間の通信は、 mTLS によって保護されます。 Nomad クライアントのインストールが完了すると、 mTLS 証明書、プライベートキー、および認証局が出力されます。

完了すると、 CircleCI Server の設定を更新して、 Nomad コントロールプレーンが Nomad クライアントと通信できるようになります。

Terraform によるクラスタの作成

CircleCI では、任意のクラウド プロバイダーに Nomad クライアントをインストールできるように Terraform モジュールをキュレーションしています。 You can browse the modules in our public repository including example Terraform config files (man.tf) for both AWS and GKEs for main.tf. main.tf を完了するには、クラスタとサーバーのインストールに関する情報が必要です。 以下でその情報を入手する方法を説明します。

AWS

クラスタおよびサーバのインストールに関する情報を Terraform 設定ファイル (main.tf) のフィールドに入力します。 A full example as well as a full list of variables can be found here.

  • [Server_endpoint (サーバーエンドポイント)] : Nomad サーバーエンドポイント(Nomad サーバー外部ロードバランサー の外部 IP アドレス)が必要です。 この情報は以下のコマンドで入手します。

    kubectl get service nomad-server-external --namespace=<YOUR_CIRCLECI_NAMESPACE>
  • クラスタの Subnet ID (サブネット)VPC ID (VPC の ID)DNS server (DNS サーバー) : 以下のコマンドを実行して、クラスタの VPC ID (VPCのID)、CIDR ブロック (serviceIpv4Cidr)、およびサブネット (サブネットの ID)を入手します。

    aws eks describe-cluster --name=<YOUR_CLUSTER_NAME>

    すると、以下のようなコマンドが返されます。

    {...
    "resourcesVpcConfig": {
        "subnetIds": [
            "subnet-033a9fb4be69",
            "subnet-04e89f9eef89",
            "subnet-02907d9f35dd",
            "subnet-0fbc63006c5f",
            "subnet-0d683b6f6ba8",
            "subnet-079d0ca04301"
        ],
        "clusterSecurityGroupId": "sg-022c1b544e574",
        "vpcId": "vpc-02fdfff4c",
        "endpointPublicAccess": true,
        "endpointPrivateAccess": false
    ...
    "kubernetesNetworkConfig": {
                "serviceIpv4Cidr": "10.100.0.0/16"
            },
    ...
    }

    次に、見つけた VPCID を使用して次のコマンドを実行し、クラスタの CIDR ブロックを取得します。 AWS の場合、 DNS サーバーは CIDR ブロック (CidrBlock) の3番目の IP です。たとえば、 CIDR ブロックが `10.100.0.0/16 `の場合、 3 番目の IP は `10.100.0.2`になります。

    aws ec2 describe-vpcs --filters Name=vpc-id,Values=<YOUR_VPCID>

    すると、以下のようなコマンドが返されます。

    {...
    "CidrBlock": "192.168.0.0/16",
    "DhcpOptionsId": "dopt-9cff",
    "State": "available",
    "VpcId": "vpc-02fdfff4c"
    ...}

適切な情報を入力したら、 `main.tf `ファイルのディレクトリから次のコマンドを実行することにより、Normad クライアントをデプロイすることができます。

terraform init
terraform plan
terraform apply

Terraform は、 Nomad クライアントのスピンアップが完了すると、 CircleCI Server で Nomad コントロールプレーンを設定するために必要な証明書とキーを出力します。 この情報は、安全な場所にコピーしてください。 この適用プロセスには 通常 1 分しかかかりません。

GKE

CircleCI Server のデプロイ時に作成した Nomad コントロールプレーン(Nomad サーバー)の IP アドレスが必要になります。 以下のコマンドを発行することで IP アドレスを取得できます。

kubectl get service nomad-server-external --namespace=<YOUR_CIRCLECI_NAMESPACE>

以下の情報も必要です。

  • Nomad クライアントを実行する GPC プロジェクト

  • Nomad クライアントを実行する GPC ゾーン

  • Nomad クライアントを実行する GPC リージョン

  • Nomad クライアントを実行する GPC ネットワーク

  • Nomad クライアントを実行する GPC サブネットの ID

以下の例をローカル環境にコピーして、特定の設定に必要な情報を入力します。 適切な情報を入力したら、以下を実行して Normad クライアントをデプロイできます。

terraform init
terraform plan
terraform apply

Terraform は、 Nomad クライアントのスピンアップが完了すると、 CircleCI Server で Nomad コントロールプレーンを設定するために必要な証明書とキーを出力します。 この情報は、安全な場所にコピーしてください。

設定とデプロイ

Nomad クライアントの導入が完了したら、 CircleCI Server と Nomad コントロールプレーンを設定できます。 KOTS の管理者コンソールにアクセスします。 Get to the KOTS admin console by running the following, substituting your namespace: kubectl kots admin-console -n <YOUR_CIRCLECI_NAMESPACE>

設定で次の項目を入力します。

  • [Nomad Load Balancer (Normad ロードバランサー)](必須)

    kubectl get service nomad-server-external --namespace=<YOUR_CIRCLECI_NAMESPACE>
  • [Nomad Server Certificate (Nomad サーバーの証明書)](必須): `terraform apply`からの出力で提供されます。

  • [Nomad Server Private Key (Nomad サーバーのプライベートキー)](必須): `terraform apply`からの出力で提供されます。

  • [Nomad Server Certificate Authority (CA) (Nomad サーバーの証明書認証局)](必須): `terraform apply`からの出力で提供されます。

[Save config (設定の保存)] ボタンをクリックし、CircleCI Server を更新して再デプロイします。

Normad クライアントの確認

CircleCI Server のインストールをテストできる realitycheck というプロジェクトを作成しました。 CircleCI ではこのプロジェクトをフォローし、システムが期待どおりに動作しているかどうかを確認していきます。 引き続き次のステップを実行すると、 realitycheck のセクションが赤から緑に変わります。

realitycheck を実行するには、リポジトリのクローンを実行する必要があります。 Github の設定に応じて、以下のいずれかを実行します。

Github Cloud
git clone -b server-3.0 https://github.com/circleci/realitycheck.git
GitHub Enterprise
git clone -b server-3.0 https://github.com/circleci/realitycheck.git
git remote set-url origin <YOUR_GH_REPO_URL>
git push

レポジトリのクローンに成功したら、CircleCI Server 内からフォローすることができます。 以下の変数を設定する必要があります。 詳細はhttps://github.com/circleci/realitycheck/tree/server-3.0[リポジトリの README] を参照してください。

Table 1. 環境変数
名前

CIRCLE_HOSTNAME

<YOUR_CIRCLECI_INSTALLATION_URL>

CIRCLE_TOKEN

<YOUR_CIRCLECI_API_TOKEN>

Table 2. コンテキスト
名前 環境変数キー

環境変数値

org-global

CONTEXT_END_TO_END_TEST_VAR

空欄のまま

individual-local

MULTI_CONTEXT_END_TO_END_VAR

環境変数とコンテキストを設定したら、 realitycheck テストを再実行します。 機能とリソースジョブが正常に完了したことが表示されます。 テスト結果は次のようになります。

Screenshot showing the realitycheck project building in the CircleCI app

VM サービス

VM サービスは、VM とリモート Docker ジョブを設定します。 スケーリング ルールなど、VM サービスのさまざまなオプションを設定することができます。 VM サービスは、 EKS および GKE のインストールに固有のものです。これは、VMサービスがこれらのクラウドプロバイダーの機能に特に依存しているためです。

EKS

  1. セキュリティグループの作成に必要な情報を入手する

    以下のコマンドにより、VPC ID (vpcId)、CIDR ブロック (serviceIpv4Cidr)、クラスタ セキュリティーグループ ID (clusterSecurityGroupId)、 および Cluster ARN (arn) の値が返されます。これらの情報はこのセクションを通して必要です。

    aws eks describe-cluster --name=<your-cluster-name>
  2. セキュリティーグループを作成する

    以下のコマンドを実行して、VM サービス用のセキュリティーグループを作成します。

    aws ec2 create-security-group --vpc-id "<YOUR_VPCID>" --description "CircleCI VM Service security group" --group-name "circleci-vm-service-sg"

    これにより次の手順で使用するグループ ID が出力されます。

    {
        "GroupId": "sg-0cd93e7b30608b4fc"
    }
  3. セキュリティーグループ Nomad を適用する

    作成したセキュリティーグループと CIDR ブロック値を使ってセキュリティーグループを以下に適用します。

    aws ec2 authorize-security-group-ingress --group-id "<YOUR_GroupId>" --protocol tcp --port 22 --cidr "<YOUR_serviceIpv4Cidr>"
    aws ec2 authorize-security-group-ingress --group-id "<YOUR_GroupId>" --protocol tcp --port 2376 --cidr "<YOUR_serviceIpv4Cidr>"
    CircleCI Server とは異なるサブネットに Nomad クライアントを作成した場合は、サブネット CIDR ごとに上記の 2 つのコマンドを再実行する必要があります。
  4. セキュリティーグループに SSH接続を適用する

    次のコマンドを実行してセキュリティグループルールを適用し、ユーザーがジョブに SSH 接続できるようにします。

    aws ec2 authorize-security-group-ingress --group-id "<YOUR_GroupId>" --protocol tcp --port 54782
  5. ユーザーを作成する

    プログラムでのアクセス権を持つ新規ユーザーを作成します。

    aws iam create-user --user-name circleci-server-vm-service
  6. ポリシーを作成する

    以下の内容の policy.json ファイルを作成します。 クラスタのセキュリティーグループ ID (clusterSecurityGroupId) とCluster ARN (arn)を以下に入力します。

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Action": "ec2:RunInstances",
          "Effect": "Allow",
          "Resource": [
            "arn:aws:ec2:*::image/*",
            "arn:aws:ec2:*::snapshot/*",
            "arn:aws:ec2:*:*:key-pair/*",
            "arn:aws:ec2:*:*:launch-template/*",
            "arn:aws:ec2:*:*:network-interface/*",
            "arn:aws:ec2:*:*:placement-group/*",
            "arn:aws:ec2:*:*:volume/*",
            "arn:aws:ec2:*:*:subnet/*",
            "arn:aws:ec2:*:*:security-group/<YOUR_clusterSecurityGroupID>"
          ]
        },
        {
          "Action": "ec2:RunInstances",
          "Effect": "Allow",
          "Resource": "arn:aws:ec2:*:*:instance/*",
          "Condition": {
            "StringEquals": {
              "aws:RequestTag/ManagedBy": "circleci-vm-service"
            }
          }
        },
        {
          "Action": [
            "ec2:CreateVolume"
          ],
          "Effect": "Allow",
          "Resource": [
            "arn:aws:ec2:*:*:volume/*"
          ],
          "Condition": {
            "StringEquals": {
              "aws:RequestTag/ManagedBy": "circleci-vm-service"
            }
          }
        },
        {
          "Action": [
            "ec2:Describe*"
          ],
          "Effect": "Allow",
          "Resource": "*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "ec2:CreateTags"
          ],
          "Resource": "arn:aws:ec2:*:*:*/*",
          "Condition": {
            "StringEquals": {
              "ec2:CreateAction" : "CreateVolume"
            }
          }
        },
        {
          "Effect": "Allow",
          "Action": [
            "ec2:CreateTags"
          ],
          "Resource": "arn:aws:ec2:*:*:*/*",
          "Condition": {
            "StringEquals": {
              "ec2:CreateAction" : "RunInstances"
            }
          }
        },
        {
          "Action": [
            "ec2:CreateTags",
            "ec2:StartInstances",
            "ec2:StopInstances",
            "ec2:TerminateInstances",
            "ec2:AttachVolume",
            "ec2:DetachVolume",
            "ec2:DeleteVolume"
          ],
          "Effect": "Allow",
          "Resource": "arn:aws:ec2:*:*:*/*",
          "Condition": {
            "StringEquals": {
              "ec2:ResourceTag/ManagedBy": "circleci-vm-service"
            }
          }
        },
        {
          "Action": [
            "ec2:RunInstances",
            "ec2:StartInstances",
            "ec2:StopInstances",
            "ec2:TerminateInstances"
          ],
          "Effect": "Allow",
          "Resource": "arn:aws:ec2:*:*:subnet/*",
          "Condition": {
            "StringEquals": {
              "ec2:Vpc": "<YOUR_arn>"
            }
          }
        }
      ]
    }
  7. ポリシーをユーザーにアタッチする

    policy.json ファイルを作成したら、IAM ポリティーと作成したユーザーにアタッチします。

    aws iam put-user-policy --user-name circleci-vm-service --policy-name circleci-vm-service --policy-document file://policy.json
  8. ユーザー用のアクセスキーとシークレットを作成する

    作成していない場合は、circleci-vm-service ユーザー用のアクセスキーとシークレットが必要です。 以下のコマンドを実行して作成することができます。

    aws iam create-access-key --user-name circleci-vm-service
  9. サーバーの設定

    VM サービスをKOTS 管理者コンソールから設定します。 VM サービスを正しく動作させるために、次のフィールドに入力する必要があります。

    • [AWS Region (AWS リージョン)](必須): アプリケーションのリージョン

    • [Subnet (サブネット)] (必須): VM のデプロイ先になるサブネット (パブリックまたはプライベート) を選択します。 一意のサブネットを作成していない場合は、クラスタのサブネットを使用できます。 なお、すべてのサブネットが同じアベイラビリティーゾーンにある必要があります。

    • [Security Group ID (セキュリティ グループ ID)] (必須): VM にアタッチするセキュリティ グループ。 先ほど作成した ID です。

    • [AWS IAM Access Key ID (AWS IAM アクセスキー ID)] (必須): EC2 アクセス用の AWS アクセスキー ID

    • [AWS IAM Secret Key (AWS IAM シークレットキー)](必須): EC2 アクセス用の IAM シークレットキー

    • [AWS Windows AMI ID] (オプション): Windows ビルダーが必要な場合、その AMI ID をここに指定できます。

フィールドの設定が完了したら、*設定を保存*し、更新したアプリケーションをデプロイします。

GKE

以下のセクションを完了するにはクラスタに関する追加情報が必要です。 以下を実行します。

gcloud container clusters describe

このコマンドは、次のような情報を返します。この情報には、ネットワーク、リージョン、および次のセクションを完了するために必要なその他の詳細情報が含まれます。

addonsConfig:
  gcePersistentDiskCsiDriverConfig:
    enabled: true
  kubernetesDashboard:
    disabled: true
  networkPolicyConfig:
    disabled: true
clusterIpv4Cidr: 10.100.0.0/14
createTime: '2021-08-20T21:46:18+00:00'
currentMasterVersion: 1.20.8-gke.900
currentNodeCount: 3
currentNodeVersion: 1.20.8-gke.900
databaseEncryption:
  1. ファイアウォール ルールを作成する

    以下のコマンドを実行して、GKE の VM サービス用のファイヤーウォール ルールを作成します。

    gcloud compute firewall-rules create "circleci-vm-service-internal-nomad-fw" --network "<network>" --action allow --source-ranges "0.0.0.0/0" --rules "TCP:22,TCP:2376"
    自動モードを使用している場合は、https://cloud.google.com/vpc/docs/vpc#ip-ranges[こちらの表]を参照して、リージョンに基づき Nomad クライアントの CIDR を検索できます。
    gcloud compute firewall-rules create "circleci-vm-service-internal-k8s-fw" --network "<network>" --action allow --source-ranges "<clusterIpv4Cidr>" --rules "TCP:22,TCP:2376"
    gcloud compute firewall-rules create "circleci-vm-service-external-fw" --network "<network>" --action allow --rules "TCP:54782"
  2. ユーザーを作成する

    VM サービス専用の一意のサービス アカウントを作成することをお勧めします。 コンピューティング インスタンス管理者 (ベータ版) ロールは、VM サービスを運用するための広範な権限を持っています。 アクセス許可をより詳細に設定したい場合は、 コンピューティング インスタンス管理者 (ベータ版) ロールのドキュメントを参照してください。

    gcloud iam service-accounts create circleci-server-vm --display-name "circleci-server-vm service account"
  3. サービスアカウントのメールアドレスを取得する

    gcloud iam service-accounts list --filter="displayName:circleci-server-vm service account" --format 'value(email)'
  4. ロールをサービスアカウントに適用する

    コンピューティング インスタンス管理者 (ベータ版) ロールをサービスアカウントに適用します。

    gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> --member serviceAccount:<YOUR_SERVICE_ACCOUNT_EMAIL> --role roles/compute.instanceAdmin --condition=None

    さらに

    gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> --member serviceAccount:<YOUR_SERVICE_ACCOUNT_EMAIL> --role roles/iam.serviceAccountUser --condition=None
  5. JSON キーファイルを取得する

    以下を実行すると、circleci-server-vm-keyfile という名前のファイルがローカル作業ディレクトリに作成されます。 サーバーインストールを設定する際に必要になります。

    gcloud iam service-accounts keys create circleci-server-vm-keyfile --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
  6. サーバーの設定

    VM サービスをKOTS 管理者コンソールから設定します。

    • [VM Service Load Balancer (VM サービスロードバランサー ](必須): 以下のコマンドで確認できます。

      kubectl get service vm-service --namespace=<YOUR_CIRCLECI_NAMESPACE>
    • [GCP project ID (GCP プロジェクト ID)] (必須): クラスタが存在する GCP プロジェクトの名前

    • [GCP Zone (GCP ゾーン)](必須): us-east1-b などに仮想マシン インスタンスを作成する GCP ゾーン

    • [GCP VPC Network (GCP VPC ネットワーク)] (必須): VPC ネットワークの名前

    • [GCP VPC Subnet (GCP VPC サブネット)](オプション): VPC サブネットの名前 自動サブネット化を使用する場合は、このフィールドは空欄にします。

    • <strong>[GCP Service Account JSON Key File (GCP サービスアカウントの JSON キーファイル] (必須)</strong>:サービスアカウントの JSON ファイルの内容をコピー&ペーストします。

    • [GCP Windows Image (GCP Windows イメージ)](オプション): Windows ビルドに使用するイメージの名前。 Windows ビルドが不要な場合は、このフィールドを空欄にします。

[Save config (構成の保存)] ボタンをクリックし、CircleCI Server を更新して再デプロイします。

VM サービスに関するその他の設定

  • [Number of<VM type>VMs to keep prescaled (事前スケーリングする VM 数)]: デフォルトでは、このフィールドは 0 に設定されています。 この値の場合、該当するリソース タイプのインスタンスがオンデマンドで作成、プロビジョニングされます。 リソース タイプごとにインスタンスを最大 5 つまで事前割り当てできます。 インスタンスを事前に割り当てると、起動時間が短くなり、マシンと remote_docker のビルド速度が速くなります。

    ただし、事前割り当てされたインスタンスは常に実行されるため、コストが上がる可能性があります。 また、この設定値を減らす場合、変更が反映されるまで最大で 24 時間かかります。 これらのインスタンスは、必要に応じて手動で終了できます。

VM サービスの確認

CircleCI Server の設定とデプロイが完了したら、VM サービスが適切に動作しているか確認する必要がありあます。 CircleCI Server 内で、realitycheckプロジェクトを再実行できます。 緑色であれば VM サービスジョブは完了してます。 この時点で、すべてのテストが緑色で合格しているはずです。

ランナー

概要

CircleCI のランナーには、追加のサーバー設定は不要です。 CircleCI Server はランナーと連携する準備ができています。 ただし、ランナーを作成し、CircleCI Server のインストールを認識するようにランナーエージェントを設定する必要があります。 For complete instructions for setting up runner see the runner documentation.

ランナーには各組織につき1つ名前空間が必要です。 CircleCI Server には複数の組織を存在させることができます。 CircleCI Server 内に複数の組織が存在する場合、各組織につき1つランナーの名前空間を設定する必要があります。


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースで、GitHub で使用できます。 ご協力いただき、ありがとうございます。


クリエイティブ・コモンズ・ライセンス
CircleCICircleCI ドキュメントは、クリエイティブ・コモンズの表示--非営利-継承 4.0 国際ライセンス に基づいてライセンス供与されています。