ステップ 3 - 実行環境
このページの内容
- 1. Nomad クライアント
- a. Terraform でクラスタを作成します
- AWS クラスタ
- GCP クラスタ
- b. Nomad Autoscaler を設定します
- AWS Autoscaler IAM/ロール
- Nomad Autoscaler の IAM ポリシー
- GCP オートスケーラーのサービスアカウント
- 2. Nomad サーバー
- a. Nomad ゴシップ暗号化キー
- b. Nomad mTLS
- c. Nomad Autoscaler
- AWS
- GCP
- d. Helm のアップグレード
- 3. Normad クライアントの確認
- Github Cloud
- GitHub Enterprise
- 3. VM サービス
- AWS
- セキュリティーグループを作成します
- 認証を設定します
- GCP
- VM サービスの検証
- 4. ランナー
- 概要
- 次のステップ
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 - 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 Block (
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の Role for Service Accountsを作成し、 IAM policy belowを添付することができます:
アクセスキーとシークレットキーを使用する場合、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 バイトの長さである必要があります。 値を紛失した場合、復元できません。 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.1.8 -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 を参照してください。
名前 | 値 |
---|---|
CIRCLE_HOSTNAME | <YOUR_CIRCLECI_INSTALLATION_URL> |
CIRCLE_TOKEN | <YOUR_CIRCLECI_API_TOKEN> |
CIRCLE_CLOUD_PROVIDER | < |
名前 | 環境変数キー | 環境変数値 |
---|---|---|
org-global | CONTEXT_END_TO_END_TEST_VAR | 空欄のまま |
individual-local | MULTI_CONTEXT_END_TO_END_VAR | 空欄のまま |
環境変数とコンテキストを設定したら、 realitycheck テストを再実行します。 機能とリソースジョブが正常に完了したことが表示されます。 テスト結果は次のようになります。
3. VM サービス
VM サービスにより、Linux VM、Windows、Arm の各実行環境で実行されるジョブや リモート Docker を使用するように設定されたジョブの仮想マシンを設定できます。 スケーリングルールなど、さまざまなオプションの設定が可能です。 VM サービスは、 AWS および GCP インストール環境に固有のものです。これは、VMサービスがこれらのクラウドプロバイダーの特定の機能に依存しているためです。
サーバーのインストールプロセスが完了したら、VM サービスの詳細設定が行えます。これには、開発者が Windows 実行環境にアクセスできるように Windows イメージをビルドおよび指定したり、代替の Linux マシンイメージを指定したり、スピンアップ状態を常に維持するための事前割り当てインスタンスの数の指定などが含まれます。 詳細については、 VM サービスを使った仮想マシンの管理 を参照してください。 |
AWS
セキュリティーグループを作成します
-
セキュリティグループの作成に必要な情報を入手します。
次のコマンドにより、このセクションで必要な 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
-
セキュリティーグループを作成します。
以下のコマンドを実行して、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>" }
-
セキュリティーグループ 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>"
-
セキュリティーグループに 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:
…
-
ファイアウォール ルールを作成します。
External VMs need the networking rules described in Hardening your Cluster
-
ユーザーを作成します。
VM サービス専用の一意のサービスアカウントを作成することをお勧めします。 コンピューティングインスタンス管理者 (ベータ版) ロールは、VM サービスを運用するための広範な権限を持っています。 アクセス許可をより詳細に設定する場合は、コンピューティングインスタンス管理者 (ベータ版) ロール ドキュメント を参照として使用できます。
gcloud iam service-accounts create circleci-server-vm --display-name "circleci-server-vm service account"
CircleCI Server を共有 VCP にデプロイする場合は、 VM ジョブを実行するプロジェクトにこのユーザーを作成します。 -
サービスアカウントのメールアドレスを取得します。
gcloud iam service-accounts list --filter="displayName:circleci-server-vm service account" --format 'value(email)'
-
ロールをサービスアカウントに適用します。
コンピューティングインスタンス管理者 (ベータ版) ロールをサービスアカウントに適用します。
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
-
サービスアカウントで Workload Identity を有効化、または JSON キーファイルを取得します
Workload Identity を使用しているかどうかにより、以下のいずれかのオプションを選択してください。
-
CircleC server を設定する
サービスアカウントキーを使って VM サービスのアクセス許可を設定する場合、2 つのオプションがあります。
VM サービスの検証
values.yaml
ファイルへの変更を適用します。
namespace=<your-namespace>
helm upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $namespace --version 4.1.8 -f <path-to-values.yaml>
CircleCI Server の設定とデプロイが完了したら、VM サービスが適切に動作しているか確認する必要がありあます。 CircleCI Server 内で、realitycheck プロジェクトを再実行できます。 VM サービスジョブは完了しているはずです。 この時点で、すべてのテストが合格しているはずです。
4. ランナー
概要
CircleCI のランナーには、追加のサーバー設定は不要です。 CircleCI Server はランナーと連携する準備ができています。 ただし、ランナーを作成し、CircleCI Server のインストールを認識するようにランナーエージェントを設定する必要があります。 ランナーの設定についての詳細は、 ランナーに関するドキュメント をご覧ください。
ランナーには組織ごとに1つ名前空間が必要です。 CircleCI Server には複数の組織が存在する場合があります。 CircleCI Server 内に複数の組織が存在する場合、各組織につき1つランナーの名前空間を設定する必要があります。 |