ドキュメント
circleci.com
Start Building for Free

ステップ 3 - 実行環境

1 month ago5 min read
Server v4.x
サーバー管理者
このページの内容

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

1. Nomad クライアント

Nomad は、CircleCI が CircleCI ジョブのスケジュール設定 (Nomad サーバー経由) と実行 (Nomad クライアント経由) に使用するワークロードオーケストレーションツールです。

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

a. Terraform でクラスタを作成します

CircleCI では、任意のクラウドプロバイダーに Nomad クライアントをインストールできるように Terraform モジュールをキュレーションしています。 このモジュールについては、 パブリックリポジトリ を参照してください。AWS と GCP の両方の Terraform 設定ファイル例も含まれています。

AWS クラスタ

Terraform モジュールに必要な変数を入力するにはクラスタおよびサーバのインストール環境に関する情報が必要です。 変数の完全な例と完全なリストについては、 AWS Terraform の設定例 を参照してください。

  • Server_endpoint: ポート番号 4647 を付加した CircleCI アプリケーションのドメイン名です。

  • クラスタの サブネット ID (subnet)VPC ID (vpc_id)DNS サーバー (dns_server): 次のコマンドを実行して、クラスタの VPC ID (vpcId) とサブネット (subnetIds) を入手します。

    # Fetch VPC ID
    aws eks describe-cluster --name=<cluster-name> --query "cluster.resourcesVpcConfig.vpcId" --region=<region> -output text | xargs
    
    # Fetch Subnet IDs
    aws eks describe-cluster --name=<cluster-name> --query "cluster.resourcesVpcConfig.subnetIds" --region=<region> --output text | xargs

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

    # VPC Id
    vpc-02fdfff4ca
    
    # Subnet Ids
    subnet-08922063f12541f93 subnet-03b94b6fb1e5c2a1d subnet-0540dd7b2b2ddb57e subnet-01833e1fa70aa4488

    次に、見つけた 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=<vpc-id> --query "Vpcs[].CidrBlock" --region=<region> --output text | xargs

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

    192.168.0.0/16

適切な情報を入力したら、以下を実行することにより Normad クライアントをデプロイできます。

terraform init
terraform plan
terraform apply

Terraform は、Nomad クライアントのスピンアップが完了すると、CircleCI Server で Nomad コントロールプレーンを設定するために必要な証明書とキーを出力します。 それらを安全な場所にコピーします。 この適用プロセスの所要時間は、通常 1 分程度です。

GCP クラスタ

以下の情報が必要です。

  • CircleCI アプリケーションのドメイン名

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

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

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

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

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

変数の完全な例と完全なリストについては、 GCP Terraform の設定例 を参照してください。

適切な情報を入力したら、以下を実行することにより Normad クライアントをデプロイできます。

terraform init
terraform plan
terraform apply

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

b. Nomad Autoscaler を設定します

Nomad は、クライアントがクラウドプロバイダの自動スケーリングリソースによって管理されている場合、 Nomad クライアントを自動的にスケールアップまたはスケールダウンすることができます。 Nomad Autoscaler を使う場合、自動スケーリングリソースを管理し、その場所を指定する権限をユーティリティに与える必要があります。 CircleCI の Nomad Terraform モジュールは権限リソースをプロビジョニングすることも、手動で実行することもできます。

AWS Autoscaler IAM/ロール

IAM ユーザーまたは Nomad Autoscaler のロールとポリシーを作成します。 次の いずれか の方法で作成します。

  • 変数 nomad_auto_scaler = true を設定すると、 Nomad モジュール が IAM ユーザーを作成し、キーを出力します。 詳細については、リンクの例を参照してください。 既にクライアントを作成済みの場合は、変数を更新して terraform apply を実行します。 作成されたユーザーアクセスキーとシークレットキーは Terraform の出力で使用できます。

  • 下記の IAM ポリシー を使って Nomad Autoscaler IAM ユーザーを手動で作成します。 次に、このユーザー用のアクセスキーとシークレットキーを生成します。

  • Nomad Autoscaler 用の サービスアカウントのロール を作成し、 下記の IAM ポリシー を添付します。

アクセスキーとシークレットキーを使用する場合、2 つの設定オプションが あります。

Nomad Autoscaler の IAM ポリシー
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "autoscaling:CreateOrUpdateTags",
                "autoscaling:UpdateAutoScalingGroup",
                "autoscaling:TerminateInstanceInAutoScalingGroup"
            ],
            "Resource": "<<Your Autoscaling Group ARN>>"
        },
        {
            "Sid": "VisualEditor1",
            "Effect": "Allow",
            "Action": [
                "autoscaling:DescribeScalingActivities",
                "autoscaling:DescribeAutoScalingGroups"
            ],
            "Resource": "*"
        }
    ]
}

GCP オートスケーラーのサービスアカウント

Nomad Autoscaler のサービスアカウントを作成します。 次の いずれか の方法で作成します。

2. Nomad サーバー

Nomad クライアントを正常にデプロイし、権限リソースを取得したので、Nomad サーバーを設定できるようになりました。

a. Nomad ゴシップ暗号化キー

Nomad では通信を暗号化するためのキーが必要です。 このキーは 32 バイトの長さである必要があります。 値を紛失した場合、CircleCI が復元することはできません。 Kubernetes シークレットの管理方法には、2 つのオプションがあります。

b. Nomad mTLS

`CACertificate` 、 `certificate` 、 `privateKey` は Terraform モジュールの出力でご確認ください。  base64 エンコードされています。
nomad:
  server:
    ...
    rpc:
      mTLS:
        enabled: true
        certificate: "<base64-encoded-certificate>"
        privateKey: "<base64-encoded-private-key>"
        CACertificate: "<base64-encoded-ca-certificate>"

c. Nomad Autoscaler

Nomad Autoscaler を有効にした場合は、 nomad の下に以下のセクションも含めます。

AWS

これらの値は Nomad Autoscaler の設定 で作成済みです。

nomad:
  ...
  auto_scaler:
    enabled: true
    scaling:
      max: <max-node-limit>
      min: <min-node-limit>

    aws:
      enabled: true
      region: "<region>"
      autoScalingGroup: "<asg-name>"

      accessKey: "<access-key>"
      secretKey: "<secret-key>"
      # or
      irsaRole: "<role-arn>"

GCP

これらの値は Nomad Autoscaler の設定 で作成済みです。

nomad:
  ...
  auto_scaler:
    enabled: true
    scaling:
      max: <max-node-limit>
      min: <min-node-limit>

    gcp:
      enabled: true
      project_id: "<project-id>"
      mig_name: "<instance-group-name>"

      region: "<region>"
      # or
      zone: "<zone>"

      workloadIdentity: "<service-account-email>"
      # or
      service_account: "<service-account-json>"

d. Helm のアップグレード

values.yaml ファイルへの変更を適用します。

namespace=<your-namespace>
helm upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.0.0 -f <path-to-values.yaml>

3. Normad クライアントの確認

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

realitycheck を実行する前に、次のコマンドを実行して Nomad サーバーが Nomad クライアントと通信できるか確認して下さい。

kubectl -n <namespace> exec -it $(kubectl -n <namespace> get pods -l app=nomad-server -o name | tail -1) -- nomad node status

出力は以下のようになります。

ID        DC       Name              Class        Drain  Eligibility  Status
132ed55b  default  ip-192-168-44-29  linux-64bit  false  eligible     ready

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

Github Cloud

git clone https://github.com/circleci/realitycheck.git

GitHub Enterprise

git clone https://github.com/circleci/realitycheck.git
git remote set-url origin <YOUR_GH_REPO_URL>
git push

レポジトリのクローンに成功したら、CircleCI Server 内からフォローすることができます。 以下の変数を設定する必要があります。 詳細は、 リポジトリ 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

3. VM サービス

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

AWS

セキュリティーグループを作成します

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

    次のコマンドにより、このセクションで必要な VPC ID (vpcId) と CIDR Block (serviceIpv4Cidr) が返されます。

    # Fetch VPC Id
    aws eks describe-cluster --name=<cluster-name> --query "cluster.resourcesVpcConfig.vpcId" --region=<region> --output text | xargs
    
    # Fetch CIDR Block
    aws eks describe-cluster --name=<cluster-name> --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --region=<region> --output text | xargs
  2. セキュリティーグループを作成します。

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

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

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

    {
        "GroupId": "<VM_SECURITY_GROUP_ID>"
    }
  3. セキュリティーグループ Nomad を適用します。

    作成したセキュリティーグループと CIDR ブロック値を使ってセキュリティーグループを適用します。 これにより VM サービスは作成された EC2 インスタンスとポート 22 で通信できるようになります。

    aws ec2 authorize-security-group-ingress --group-id "<VM_SECURITY_GROUP_ID>" --protocol tcp --port 22 --cidr "<SERVICE_IPV4_CIDR>"

    Nomad クライアントが使用する各 サブネット のサブネット cidr ブロックを見つけ、次のコマンドを使って 2 つのルールを追加します。

    # find CIDR block
    aws ec2 describe-subnets --subnet-ids=<nomad-subnet-id> --query "Subnets[*].[SubnetId, CidrBlock]" --region=<region> | xargs
    # add a security group allowing docker access from nomad clients, to VM instances
    aws ec2 authorize-security-group-ingress --group-id "<VM_SECURITY_GROUP_ID>" --protocol tcp --port 2376 --cidr "<SUBNET_IPV4_CIDR>"
    # add a security group allowing SSH access from nomad clients, to VM instances
    aws ec2 authorize-security-group-ingress --group-id "<VM_SECURITY_GROUP_ID>" --protocol tcp --port 22 --cidr "<SUBNET_IPV4_CIDR>"
  4. セキュリティーグループに SSH接続を適用します (マシン用のパブリック IP を使用している場合)。

    VM サービスインスタンスでパブリック IP を使用している場合は、次のコマンドを実行してユーザーがジョブに SSH 接続できるようセキュリティグループのルールを適用します。

    aws ec2 authorize-security-group-ingress --group-id "<VM_SECURITY_GROUP_ID>" --protocol tcp --port 54782 --cidr "0.0.0.0/0"

認証を設定します

クラウドプロバイダー で CircleCI を認証するには、サービスアカウントの IAM ロール (IRSA) または IAM アクセスキーを使用する 2 つの方法があります。 IRSA の使用を推奨します。

GCP

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

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"
    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. サービスアカウントで Workload Identity を有効にします。

    この手順は、GKE で Workload Identity を使用している場合のみ実行する必要があります。 Workload Identity を有効化する手順は、 ステップ 1: 前提条件 を参照してください。

    gcloud iam service-accounts add-iam-policy-binding <YOUR_SERVICE_ACCOUNT_EMAIL> \
        --role roles/iam.workloadIdentityUser \
        --member "serviceAccount:<GCP_PROJECT_ID>.svc.id.goog[circleci-server/vm-service]"
  6. オプションで、JSON キーファイルを取得します。

    GKE で Workload Identity を使用している場合、この手順は不要です。

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

    gcloud iam service-accounts keys create circleci-server-vm-keyfile --iam-account <YOUR_SERVICE_ACCOUNT_EMAIL>
  7. サーバーを設定します。

    サービスアカウントキーを使って VM サービスのアクセス許可を設定する場合、2 つのオプションがあります。

VM サービスの検証

values.yaml ファイルへの変更を適用します。

namespace=<your-namespace>
helm upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.0.0 -f <path-to-values.yaml>

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

4. ランナー

概要

CircleCI のランナーには、追加のサーバー設定は不要です。 CircleCI Server はランナーと連携する準備ができています。 ただし、ランナーを作成し、CircleCI Server のインストールを認識するようにランナーエージェントを設定する必要があります。 ランナーの設定についての詳細は、 ランナーに関するドキュメント をご覧ください。


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

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

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。