CircleCI Server v3.x インストール ステップ 1
ステップ 1: 前提条件
CircleCI Server v.x のインストールには 4 つのステップがあります。 各ステップの最後に、そのステップが成功していることを確認してから次のステップに進みます。 お客様の要件によっては、ステップ 3 と 4 で、更に複数の手順がある場合があります。 このインストールガイドは、 CircleCI Server v3.x の概要 を先に読んでいることを前提としています。

以下のセクションでは、 < > の中に表示される認証情報の項目にご自身の情報を入力してください。 |
必要なソフトウェアのインストール
まず、以下のソフトウェアをダンロードし、インストールします。
ツール | バージョン | 用途 | メモ |
---|---|---|---|
0.15.4 以上 | インフラストラクチャの管理 | ||
1.19 以上 | Kubernetes CLI | ||
3.9.2 以上 | Kubernetes パッケージ管理 | ||
1.65.0 * | Replicated Kubernetes アプリケーション管理。 KOTS は、 | tar.gz ( | |
最新バージョン | バックアップおよびリストア機能 | 詳細については、Velero の サポート対象プロバイダー に関するページを参照してください。 |
-
Kubernetes クラスタでサポートされている KOTS バージョンにご注意ください。 KOTS バージョンの互換性
AWS に必要なソフトウェア
GCP に必要なソフトウェア
-
gcloud
とgsutil
。 Google Cloud SDK をインストールすると、これらのツールがインストールおよびセットアップされます。 詳細については、 Google Cloud SDK のドキュメント を参照してください。
S3 互換ストレージに必要なソフトウェア
-
ご自身のストレージプロバイダーの MinIO CLI をインストールおよび設定してください。
Kubernetes クラスタの作成
CircleCI Server は既存の Kubernetes クラスタにインストールされます。 このアプリケーションは大量のリソースを使用します。 お客様の用途に応じて、Kubernetes クラスタが以下の要件を満たしている必要があります。
1 日の CircleCI アクティブ ユーザー数 | 最小ノード数 | 合計 CPU | 合計 RAM | NIC 速度 |
---|---|---|---|---|
500 名未満 | 3 | 12 コア | 32 GB | 1 Gbps |
500 名以上 | 3 | 48 コア | 240 GB | 10 Gbps |
サポートされているKubernetes のバージョン
CircleCI のバージョン | Kubernetes のバージョン |
---|---|
3.0.0 - 3.2.1 | < 1.21 |
3.2.2 - 3.3.0 | 1.16 - 1.21 |
3.4.0 - 3.4.1 | 1.16 - 1.23 |
Kubernetes クラスタの作成はご自身で行う必要があります。 その際は以下をご留意ください。
-
クラスタの外部アクセスが許可されており、Docker コンテナのプルやライセンスの確認が可能である必要があります。 外部アクセスを制限したい場合は、 アクセスが必要なポート一覧 を参照してください。
-
クラスタ内の Pod を一覧表示、作成、編集、削除するための権限が必要です。 権限を確認するには以下を実行します。
kubectl auth can-i <list|create|edit|delete> pods
-
クラスタの VPC 設定やディスク サイズに関する要件はありません。 ただし、既存の VPC ではなく、新しい VPC を設定することをお勧めします。
EKS
Amazon EKS クラスタ の作成に関する詳細は、 こちら をご覧ください。 クラスタの作成には eksctl
の使用を推奨しています。 このツールにより、VPC の作成と適切なセキュリティグループの選択が自動で行われます。
-
eksctl
をインストールします。 -
以下を実行してクラスタを作成します (
eksctl
and EKS を使った CloudFormation には 20 分以上かかる場合があります。)eksctl create cluster --name=circleci-server --nodes 4 --node-type m5.xlarge
-
クラスタの作成が完了したら、以下のコマンドで
kubectl
のアクセスを設定します。eksctl utils write-kubeconfig --cluster circleci-server
次のエラーが表示される場合があります。: AWS STS Access - cannot get role ARN for current session: InvalidClientTokenID これはお客様のAWS認証情報が無効、またはお客様の IAM ユーザーに EKS クラスタを作成する権限がないことを意味します。 eksctl を使用するには適切な IAM 権限が必要です。 IAM 権限 に関しては AWS のドキュメントをご覧ください。 |
GKE
GKE クラスタ の作成に関する詳細は、 こちら をご覧ください。
Autopilot クラスターは使用しないでください。 CircleCI Server には、GKE Autopilot ではサポートされていない機能が必要です。 |
-
GCP CLI を インストール し、お使いの GCP アカウント用に 設定 します。 これには Google Project の作成も含まれます。お客様のプロジェクト内にクラスタを作成する際に必要となります。
プロジェクトを作成する際は、必ず API アクセスを有効にしてください。 API アクセスを有効にしないと、次に実行するクラスタ作成コマンドが失敗します。 -
以下のコマンドを実行して、クラスタを作成します。
gcloud container clusters create circleci-server --project <YOUR_GOOGLE_CLOUD_PROJECT_ID> --region europe-west1 --num-nodes 3 --machine-type n1-standard-4
-
gcloud 認証情報 で
kubectl
を設定します。gcloud container clusters get-credentials circleci-server --region europe-west1
-
クラスタを確認します。
kubectl cluster-info
-
このクラスタのサービスアカウントを作成します。
gcloud iam service-accounts create <YOUR_SERVICE_ACCOUNT_ID> --description="<YOUR_SERVICE_ACCOUNT_DESCRIPTION>" --display-name="<YOUR_SERVICE_ACCOUNT_DISPLAY_NAME>"
-
サービスアカウントの認証情報を取得します。
gcloud iam service-accounts keys create <PATH_TO_STORE_CREDENTIALS> --iam-account <SERVICE_ACCOUNT_ID>@<YOUR_GOOGLE_CLOUD_PROJECT_ID>.iam.gserviceaccount.com
===== GKE で Workload Identity を有効化する (オプション)
GKE の Workload Identity により、GKE クラスタのワークロード/ポッドが、静的サービスアカウントの認証情報を使わずに、IAM サービスアカウントに代わって Google Cloud サービスにアクセスすることができます。 Workload Identity を使用するには、GKE クラスタで有効化します。
-
既存のクラスタで Workload Identity を有効にします。
gcloud container clusters update "<CLUSTER_NAME>" \ --region="<REGION>" \ --workload-pool="<PROJECT_ID>.svc.id.goog"
-
既存の GKE クラスタの ノードプールを取得します。
gcloud container node-pools list --cluster "<CLUSTER_NAME>" --region "<REGION>"
-
既存のノードプールを更新します。
gcloud container node-pools update "<NODEPOOL_NAME>" \ --cluster="<CLUSTER_NAME>" \ --workload-metadata="GKE_METADATA" \ --region="<REGION>"
既存の全てのノードプールに対して、手順 3 を実行する必要があります。 Kubernetes サービスアカウントの Workload Identity を有効にする手順については、 Nomad Autoscaler 、 VM 、 オブジェクトストレージ に従ってください。
新しい GitHub OAuth アプリの作成
GitHub Enterprise と CircleCI Server が同一のドメインにない場合、GHE からイメージやアイコンの CircleCI Web アプリへのロードに失敗します。 |
CircleCI Server 用に GitHub OAuth アプリを登録し設定することで、 GitHub OAuth を使ったサーバーインストールの認証を制御し、ビルドステータス情報を使用して GitHub プロジェクトやレポジトリを更新することができるようになります。
-
ブラウザから、your GitHub instance > Settings > Developer Settings > OAuth Apps に移動し、New OAuth App ボタンをクリックします。
Figure 2. 新しい GitHub OAuth アプリ -
ご自身のインストールプランに合わせて以下の項目を入力します。
-
Homepage URL : CircleCI Serverをインストールする URL
-
Authorization callback URL : 認証コールバック URL は、インストールする URL に
/auth/github
を追加します。
-
-
完了すると、クライアントID が表示されます。 Generate a new Client Secret を選択し、新しい OAuth アプリ用のクライアントシークレットを生成します。 CircleCI Server の設定にはこれらの値が必要です。
Figure 3. クライアント ID とシークレット
GitHub Enterprise を使用する場合は、パーソナルアクセストークンと GitHub Enterprise インスタンスのドメイン名も必要です。 |
フロントエンド TLS 証明書
デフォルトでは、すぐに CircleCI Sever の使用を始められるように、自己署名証明書が自動的に作成されます。 本番環境では、信頼できる認証局の証明書を指定する必要があります。 例えば、 Let’s Encrypt 認証局は certbot ツールを使用して証明書を無料で発行できます。 ここでは、Google Cloud DNS と AWS Route53 の使用について説明します。
AWS Route53
-
DNS に AWS Route53 を使用している場合、certbot-route53 プラグインをインストールする必要があります。 プラグインのインストールには以下のコマンドを実行します。
pip3 install certbot-dns-route53
-
次に、以下の例を実行して、ローカルで
/etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>
にプライベートキーと証明書 (中間証明書を含む) を作成します。certbot certonly --dns-route53 -d "<CIRCLECI_SERVER_DOMAIN>" -d "app.<CIRCLECI_SERVER_DOMAIN>"
使用する証明書には、サブジェクトとしてドメインと app.* サブドメインの両方が設定されていなければなりません。 たとえば、CircleCI Server が server.example.com でホストされている場合、証明書には app.server.example.com と server.example.com が含まれている必要があります。 |
Google Cloud DNS
-
DNS を Google Cloud でホストしている場合、certbot-dns-google プラグインをインストールする必要があります。 プラグインのインストールには以下のコマンドを実行します。
pip3 install certbot-dns-google
-
以下のコマンでインストール証明書をプロビジョニングします。
certbot certonly --dns-google --dns-google-credentials <PATH_TO_CREDENTIALS> -d "<CIRCLECI_SERVER_DOMAIN>" -d "app.<CIRCLECI_SERVER_DOMAIN>"
使用する証明書には、サブジェクトとしてドメインと app.* サブドメインの両方が設定されていなければなりません。 たとえば、CircleCI Server が server.example.com でホストされている場合、証明書には app.server.example.com と server.example.com が含まれている必要があります。 |
後にこれらの証明書が必要になりますが、以下のコマンドで取得することができます。
ls -l /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>
cat /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>/fullchain.pem
cat /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN>/privkey.pem
暗号化/署名キー
CircleCI で生成されるアーティファクトの暗号化と署名には、以下のキーセットを使用します。 CircleCI Server の設定にはこれらの値が必要です。
これらの値をセキュアな状態で保存します。 紛失すると、ジョブの履歴やアーティファクトの復元ができなくなります。 |
アーティファクト署名キー
アーティファクト署名キーを生成するには、下記のコマンドを実行します。
docker run circleci/server-keysets:latest generate signing -a stdout
暗号化署名キー
暗号化署名キーを生成するには、下記のコマンドを実行します。
docker run circleci/server-keysets:latest generate encryption -a stdout
オブジェクトストレージとアクセス許可
CircleCI Server 3.x では、オブジェクト ストレージにビルド アーティファクト、テスト結果、その他の状態をホストします。 CircleCI では以下をサポートしています。
S3 互換のオブジェクトストレージであればどれでも動作すると考えられますが、テスト済みかつサポート対象のストレージは AWS S3 と MinIO です。
ニーズに最適なストレージを選んでください。 [Storage Bucket Name (ストレージ バケット名)] は必須です。 AWS と GCP のどちらを使用しているかに応じて、以下のフィールドも入力してください。 続行する前に、指定したバケット名が選択したオブジェクトストレージプロバイダに存在することを確認してください。
プロキシ経由でインストールする場合は、オブジェクトストレージも同じプロキシ経由にする必要があります。 そうしないと、各プロジェクト毎にジョブレベルでプロキシの詳細を記載しななければならなくなります。.circleci/config.yml により、アーティファクト、テスト結果、キャッシュの保存およびリストア、ワークスペースの実行が可能になります。 詳細については、 プロキシの設定 ガイドを参照してください。 |
S3 ストレージ バケットの作成
CircleCI Server の設定には以下の詳細が必要です。
-
Storage Bucket Name: CircleCI Server に使用するバケット名
-
Access Key ID: S3 バケットへのアクセス用のアクセスキー ID
-
Secret Key: S3 バケットへのアクセス用のシークレットキー
-
AWS S3 Region: プロバイダーが AWS の場合、バケットの AWS リージョンを指定します。 設定により、AWS リージョンまたは S3 エンドポイントのどちらかになります。
-
S3 Endpoint : ストレージプロバイダーが Amazon S3 でない場合、S3 ストレージプロバイダーの API エンドポイントを指定します。
S3 バケットの作成手順
-
AWS S3 バケットを作成します。
aws s3api create-bucket \ --bucket <YOUR_BUCKET_NAME> \ --region <YOUR_REGION> \ --create-bucket-configuration LocationConstraint=<YOUR_REGION>
us-east-1
は LocationConstraint をサポートしていません。us-east-1
リージョンを使用している場合、バケットの設定は省略してください。 -
circleci-server 用の IAM ユーザーを作成します。
aws iam create-user --user-name circleci-server
-
ポリシードキュメント、policy.json を作成します。
サービスアカウント(IRSA) の認証に IAM ロールを使用する場合は、以下を使用します
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutAnalyticsConfiguration", "s3:GetObjectVersionTagging", "s3:CreateBucket", "s3:GetObjectAcl", "s3:GetBucketObjectLockConfiguration", "s3:DeleteBucketWebsite", "s3:PutLifecycleConfiguration", "s3:GetObjectVersionAcl", "s3:PutObjectTagging", "s3:DeleteObject", "s3:DeleteObjectTagging", "s3:GetBucketPolicyStatus", "s3:GetObjectRetention", "s3:GetBucketWebsite", "s3:GetJobTagging", "s3:DeleteObjectVersionTagging", "s3:PutObjectLegalHold", "s3:GetObjectLegalHold", "s3:GetBucketNotification", "s3:PutBucketCORS", "s3:GetReplicationConfiguration", "s3:ListMultipartUploadParts", "s3:PutObject", "s3:GetObject", "s3:PutBucketNotification", "s3:DescribeJob", "s3:PutBucketLogging", "s3:GetAnalyticsConfiguration", "s3:PutBucketObjectLockConfiguration", "s3:GetObjectVersionForReplication", "s3:GetLifecycleConfiguration", "s3:GetInventoryConfiguration", "s3:GetBucketTagging", "s3:PutAccelerateConfiguration", "s3:DeleteObjectVersion", "s3:GetBucketLogging", "s3:ListBucketVersions", "s3:ReplicateTags", "s3:RestoreObject", "s3:ListBucket", "s3:GetAccelerateConfiguration", "s3:GetBucketPolicy", "s3:PutEncryptionConfiguration", "s3:GetEncryptionConfiguration", "s3:GetObjectVersionTorrent", "s3:AbortMultipartUpload", "s3:PutBucketTagging", "s3:GetBucketRequestPayment", "s3:GetAccessPointPolicyStatus", "s3:GetObjectTagging", "s3:GetMetricsConfiguration", "s3:PutBucketVersioning", "s3:GetBucketPublicAccessBlock", "s3:ListBucketMultipartUploads", "s3:PutMetricsConfiguration", "s3:PutObjectVersionTagging", "s3:GetBucketVersioning", "s3:GetBucketAcl", "s3:PutInventoryConfiguration", "s3:GetObjectTorrent", "s3:PutBucketWebsite", "s3:PutBucketRequestPayment", "s3:PutObjectRetention", "s3:GetBucketCORS", "s3:GetBucketLocation", "s3:GetAccessPointPolicy", "s3:GetObjectVersion", "s3:GetAccessPoint", "s3:GetAccountPublicAccessBlock", "s3:ListAllMyBuckets", "s3:ListAccessPoints", "s3:ListJobs" ], "Resource": [ "arn:aws:s3:::<YOUR_BUCKET_NAME>", "arn:aws:s3:::<YOUR_BUCKET_NAME>/*" ] }, { "Effect": "Allow", "Action": [ "iam:GetRole", "sts:AssumeRole" ], "Resource": "<YOUR_OBJECT_STORAGE_ROLE>" } ] }
認証に IAM キーを使用する場合は、以下を使用します。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:PutAnalyticsConfiguration", "s3:GetObjectVersionTagging", "s3:CreateBucket", "s3:GetObjectAcl", "s3:GetBucketObjectLockConfiguration", "s3:DeleteBucketWebsite", "s3:PutLifecycleConfiguration", "s3:GetObjectVersionAcl", "s3:PutObjectTagging", "s3:DeleteObject", "s3:DeleteObjectTagging", "s3:GetBucketPolicyStatus", "s3:GetObjectRetention", "s3:GetBucketWebsite", "s3:GetJobTagging", "s3:DeleteObjectVersionTagging", "s3:PutObjectLegalHold", "s3:GetObjectLegalHold", "s3:GetBucketNotification", "s3:PutBucketCORS", "s3:GetReplicationConfiguration", "s3:ListMultipartUploadParts", "s3:PutObject", "s3:GetObject", "s3:PutBucketNotification", "s3:DescribeJob", "s3:PutBucketLogging", "s3:GetAnalyticsConfiguration", "s3:PutBucketObjectLockConfiguration", "s3:GetObjectVersionForReplication", "s3:GetLifecycleConfiguration", "s3:GetInventoryConfiguration", "s3:GetBucketTagging", "s3:PutAccelerateConfiguration", "s3:DeleteObjectVersion", "s3:GetBucketLogging", "s3:ListBucketVersions", "s3:ReplicateTags", "s3:RestoreObject", "s3:ListBucket", "s3:GetAccelerateConfiguration", "s3:GetBucketPolicy", "s3:PutEncryptionConfiguration", "s3:GetEncryptionConfiguration", "s3:GetObjectVersionTorrent", "s3:AbortMultipartUpload", "s3:PutBucketTagging", "s3:GetBucketRequestPayment", "s3:GetAccessPointPolicyStatus", "s3:GetObjectTagging", "s3:GetMetricsConfiguration", "s3:PutBucketVersioning", "s3:GetBucketPublicAccessBlock", "s3:ListBucketMultipartUploads", "s3:PutMetricsConfiguration", "s3:PutObjectVersionTagging", "s3:GetBucketVersioning", "s3:GetBucketAcl", "s3:PutInventoryConfiguration", "s3:GetObjectTorrent", "s3:PutBucketWebsite", "s3:PutBucketRequestPayment", "s3:PutObjectRetention", "s3:GetBucketCORS", "s3:GetBucketLocation", "s3:GetAccessPointPolicy", "s3:GetObjectVersion", "s3:GetAccessPoint", "s3:GetAccountPublicAccessBlock", "s3:ListAllMyBuckets", "s3:ListAccessPoints", "s3:ListJobs" ], "Resource": [ "arn:aws:s3:::<YOUR_BUCKET_NAME>", "arn:aws:s3:::<YOUR_BUCKET_NAME>/*" ] } ] }
-
ポリシーをユーザーにアタッチします。
aws iam put-user-policy \ --user-name circleci-server \ --policy-name circleci-server \ --policy-document file://policy.json
-
ユーザーの circleci-server 用のアクセスキーを作成します。
このアクセスキーは後でサーバーインストールの設定をする際に必要になります。 aws iam create-access-key --user-name circleci-server
このコマンドの結果は以下のようになります。
{ "AccessKey": { "UserName": "circleci-server", "Status": "Active", "CreateDate": "2017-07-31T22:24:41.576Z", "SecretAccessKey": <AWS_SECRET_ACCESS_KEY>, "AccessKeyId": <AWS_ACCESS_KEY_ID> } }
Google Cloud ストレージバケットの作成
CircleCI Server の設定には以下の詳細が必要です。
-
Storage Bucket Name: CircleCI Server に使用するバケットです。
-
以下のいずれかを選択します。
-
Service Account JSON: バケットへのアクセスに使用する JSON 形式のサービスアカウントキーです。
-
Service Account Email: Google Workload Identity を使用する場合、サービスアカウントのメール ID を指定します。
-
専用のサービスアカウントをお勧めします。 アカウントをストレージオブジェクト管理者ロールに追加して、上記で指定したバケットにしかアクセスできないように制限する条件をリソース名に適用します。 たとえば、Google の IAM コンソールの条件エディターに以下を入力します。
startsWith を使用し、バケット名に projects/_/buckets/ というプレフィックスを付けます。 |
resource.name.startsWith("projects/_/buckets/<YOUR_BUCKET_NAME>")
-
GCP バケットを作成します。
CircleCI Server を GKE クラスタ内で実行している場合、RBAC (ロールベースのアクセス制御)オブジェクトを作成する必要があるため、使用する IAM ユーザーをクラスタの管理者に設定してください。 詳細については、 GKE のドキュメント を参照してください。
gsutil mb gs://circleci-server-bucket
-
サービスアカウントを作成します。
gcloud iam service-accounts create circleci-server --display-name "circleci-server service account"
次の手順でこのサービスアカウント用のメールアドレスが必要になります。 次のコマンドを実行して検索します。
gcloud iam service-accounts list \ --filter="displayName:circleci-server account" \ --format 'value(email)'
-
サービスアカウントにアクセス許可を付与します。
gcloud iam roles create circleci_server \ --project <PROJECT_ID> \ --title "CircleCI Server"
gcloud projects add-iam-policy-binding <PROJECT_ID> \ --member serviceAccount:<SERVICE_ACCOUNT_EMAIL> \ --role projects/<PROJECT_ID>/roles/circleci_server
gsutil iam ch serviceAccount:<SERVICE_ACCOUNT_EMAIL>:objectAdmin gs://circleci-server-bucket
-
JSON キーファイル
Workload Identity を使用している場合は、この手順を実行する必要はありません。
以下のコマンドを実行すると、
circleci-server-vm-keyfile
という名前のファイルがローカル作業ディレクトリに作成されます。 このファイルはサーバーインストールを設定する際に必要になります。gcloud iam service-accounts keys create circleci-server-keyfile \ --iam-account <SERVICE_ACCOUNT_EMAIL>
-
Workload Identity を有効にします。
この手順は、GKE で Workload Identity を使用している場合のみ実行する必要があります。 Workload Identity を有効化する手順は、 こちらを参照してください。
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/object-storage]"
gcloud projects add-iam-policy-binding <GCP_PROJECT_ID> \ --member serviceAccount:<YOUR_SERVICE_ACCOUNT_EMAIL> \ --role roles/iam.serviceAccountTokenCreator \ --condition=None
静的 JSON 認証情報から Workload Identity に切り替える場合は、GCP および CircleCI KOTS 管理者コンソールからキーを削除する必要があります。 |
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.