Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

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

2 days ago3 min read
Server v3.x
サーバー管理者
このページの内容

ステップ 1: 前提条件

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

Flow chart showing the installation flow for server 3.x with phase 1 highlighted
Figure 1. インストール 手順(フローチャートのステップ 1)

必要なソフトウェアのインストール

まず、以下のソフトウェアをダンロードし、インストールします。

ツールバージョン用途メモ

Terraform

0.15.4 以上

インフラストラクチャの管理

kubectl

1.19 以上

Kubernetes CLI

Helm

3.9.2 以上

Kubernetes パッケージ管理

KOTS: Mac または Linux

1.65.0 *

Replicated Kubernetes アプリケーション管理。 KOTS は、kubectl プラグイン です。

tar.gz (tar zxvf kots_linux_amd64.tar.gz) から kots を抽出したら、 sudo mv kots /usr/local/bin/kubectl-kots を実行し、インストールします。 Mac ユーザーはセキュリティ例外を付与する必要があります。

Velero CLI

最新バージョン

バックアップおよびリストア機能

詳細については、Velero の サポート対象プロバイダー に関するページを参照してください。

AWS に必要なソフトウェア

GCP に必要なソフトウェア

  • gcloudgsutil。 Google Cloud SDK をインストールすると、これらのツールがインストールおよびセットアップされます。 詳細については、 Google Cloud SDK のドキュメント を参照してください。

S3 互換ストレージに必要なソフトウェア

  • ご自身のストレージプロバイダーの MinIO CLI をインストールおよび設定してください。

Kubernetes クラスタの作成

CircleCI Server は既存の Kubernetes クラスタにインストールされます。 このアプリケーションは大量のリソースを使用します。 お客様の用途に応じて、Kubernetes クラスタが以下の要件を満たしている必要があります。

1 日の CircleCI アクティブ ユーザー数最小ノード数合計 CPU合計 RAMNIC 速度

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 の作成と適切なセキュリティグループの選択が自動で行われます。

  1. AWS CLI を インストール し、お使いの AWS アカウント用に 設定 します。

  2. eksctl をインストールします。

  3. 以下を実行してクラスタを作成します (eksctl and EKS を使った CloudFormation には 20 分以上かかる場合があります。)

    eksctl create cluster --name=circleci-server --nodes 4 --node-type m5.xlarge
  4. クラスタの作成が完了したら、以下のコマンドで kubectl のアクセスを設定します。

    eksctl utils write-kubeconfig --cluster circleci-server

GKE

GKE クラスタ の作成に関する詳細は、 こちら をご覧ください。

  1. GCP CLI を インストール し、お使いの GCP アカウント用に 設定 します。 これには Google Project の作成も含まれます。お客様のプロジェクト内にクラスタを作成する際に必要となります。

  2. 以下のコマンドを実行して、クラスタを作成します。

    gcloud container clusters create circleci-server --project <YOUR_GOOGLE_CLOUD_PROJECT_ID> --region europe-west1 --num-nodes 3 --machine-type n1-standard-4
  3. gcloud 認証情報 で kubectl を設定します。

    gcloud container clusters get-credentials circleci-server --region europe-west1
  4. クラスタを確認します。

    kubectl cluster-info
  5. このクラスタのサービスアカウントを作成します。

    gcloud iam service-accounts create <YOUR_SERVICE_ACCOUNT_ID> --description="<YOUR_SERVICE_ACCOUNT_DESCRIPTION>"  --display-name="<YOUR_SERVICE_ACCOUNT_DISPLAY_NAME>"
  6. サービスアカウントの認証情報を取得します。

    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 クラスタで有効化します。

  1. 既存のクラスタで Workload Identity を有効にします。

      gcloud container clusters update "<CLUSTER_NAME>" \
        --region="<REGION>" \
        --workload-pool="<PROJECT_ID>.svc.id.goog"
  2. 既存の GKE クラスタの ノードプールを取得します。

      gcloud container node-pools list --cluster "<CLUSTER_NAME>" --region "<REGION>"
  3. 既存のノードプールを更新します。

      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 アプリの作成

CircleCI Server 用に GitHub OAuth アプリを登録し設定することで、 GitHub OAuth を使ったサーバーインストールの認証を制御し、ビルドステータス情報を使用して GitHub プロジェクトやレポジトリを更新することができるようになります。

  1. ブラウザから、your GitHub instance > Settings > Developer Settings > OAuth Apps に移動し、New OAuth App ボタンをクリックします。

    Screenshot showing setting up a new OAuth app
    Figure 2. 新しい GitHub OAuth アプリ
  2. ご自身のインストールプランに合わせて以下の項目を入力します。

    • Homepage URL : CircleCI Serverをインストールする URL

    • Authorization callback URL : 認証コールバック URL は、インストールする URL に /auth/github を追加します。

  3. 完了すると、クライアントID が表示されます。 Generate a new Client Secret を選択し、新しい OAuth アプリ用のクライアントシークレットを生成します。 CircleCI Server の設定にはこれらの値が必要です。

    Screenshot showing GitHub Client ID
    Figure 3. クライアント ID とシークレット

フロントエンド TLS 証明書

デフォルトでは、すぐに CircleCI Sever の使用を始められるように、自己署名証明書が自動的に作成されます。 本番環境では、信頼できる認証局の証明書を指定する必要があります。 例えば、 Let’s Encrypt 認証局は certbot ツールを使用して証明書を無料で発行できます。 ここでは、Google Cloud DNS と AWS Route53 の使用について説明します。

AWS Route53

  1. DNS に AWS Route53 を使用している場合、certbot-route53 プラグインをインストールする必要があります。 プラグインのインストールには以下のコマンドを実行します。

    pip3 install certbot-dns-route53
  2. 次に、以下の例を実行して、ローカルで /etc/letsencrypt/live/<CIRCLECI_SERVER_DOMAIN> にプライベートキーと証明書 (中間証明書を含む) を作成します。

    certbot certonly --dns-route53 -d "<CIRCLECI_SERVER_DOMAIN>" -d "app.<CIRCLECI_SERVER_DOMAIN>"

Google Cloud DNS

  1. DNS を Google Cloud でホストしている場合、certbot-dns-google プラグインをインストールする必要があります。 プラグインのインストールには以下のコマンドを実行します。

    pip3 install certbot-dns-google
  2. 以下のコマンでインストール証明書をプロビジョニングします。

    certbot certonly --dns-google --dns-google-credentials <PATH_TO_CREDENTIALS> -d "<CIRCLECI_SERVER_DOMAIN>" -d "app.<CIRCLECI_SERVER_DOMAIN>"

後にこれらの証明書が必要になりますが、以下のコマンドで取得することができます。

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 です。 Azure Blob Strage などの S3 API をサポートしていないオブジェクトストレージプロバイダーを利用する場合は、MinIO Gateway の利用をお勧めします。

ニーズに最適なストレージを選んでください。 [Storage Bucket Name (ストレージ バケット名)] は必須です。 AWS と GCP のどちらを使用しているかに応じて、以下のフィールドも入力してください。 続行する前に、指定したバケット名が選択したオブジェクトストレージプロバイダに存在することを確認してください。

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 バケットの作成手順

  1. AWS S3 バケットを作成します。

    aws s3api create-bucket \
        --bucket <YOUR_BUCKET_NAME> \
        --region <YOUR_REGION> \
        --create-bucket-configuration LocationConstraint=<YOUR_REGION>
  2. circleci-server 用の IAM ユーザーを作成します。

    aws iam create-user --user-name circleci-server
  3. ポリシードキュメント、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>/*"
          ]
        }
      ]
    }
  4. ポリシーをユーザーにアタッチします。

    aws iam put-user-policy \
      --user-name circleci-server \
      --policy-name circleci-server \
      --policy-document file://policy.json
  5. ユーザーの 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 コンソールの条件エディターに以下を入力します。

resource.name.startsWith("projects/_/buckets/<YOUR_BUCKET_NAME>")
  1. GCP バケットを作成します。

    CircleCI Server を GKE クラスタ内で実行している場合、RBAC (ロールベースのアクセス制御)オブジェクトを作成する必要があるため、使用する IAM ユーザーをクラスタの管理者に設定してください。 詳細については、 GKE のドキュメント を参照してください。

    gsutil mb gs://circleci-server-bucket
  2. サービスアカウントを作成します。

    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)'
  3. サービスアカウントにアクセス許可を付与します。

    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
  4. JSON キーファイル

    Workload Identity を使用している場合は、この手順を実行する必要はありません。

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

    gcloud iam service-accounts keys create circleci-server-keyfile \
        --iam-account <SERVICE_ACCOUNT_EMAIL>
  5. 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

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

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

サポートが必要ですか

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

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