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

ステップ 1 - 前提条件

1 week ago4 min read
Server v4.x
サーバー管理者

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

1. 必要なソフトウェアをインストールします

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

ツールバージョン用途備考

Terraform

0.15.4 以上

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

kubectl

1.19 以上

Kubernetes CLI

Helm

3.9.2 以上

Kubernetes パッケージ管理

Helm Diff

3.5.0 以上

values.yaml の変更と更新の支援

オプションですが、リリース間のトラブルシューティングを支援します。

Velero CLI

最新バージョン

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

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

AWS で必要なソフトウェア

GCP で必要なソフトウェア

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

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

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

2. 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 のバージョン

4.0.0

1.22 - 1.23

Kubernetes クラスタの作成はご自身で行う必要があります。 その際は、

  • クラスタ内の Pod を一覧表示、作成、編集、削除するための権限が必要です。 権限を確認するには次のコマンドを実行します。

    kubectl auth can-i <list|create|edit|delete> pods
  • クラスタの VPC 設定やディスクサイズに関する要件はありません。 ただし、既存の VPC ではなく、新しい VPC を設定することをお勧めします。

EKS

Amazon EKS クラスタの作成に関する詳細は、 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 クラスタ の作成に関する詳細は、 GKE ドキュメント をご覧ください。

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

    あらかじめ project id と Compute Engine の zoneregion を設定しておくと、それ以降のコマンドの実行が容易になります。

    gcloud config set project <PROJECT_ID>
    gcloud config set compute/zone <ZONE>
    gcloud config set compute/region <REGION>
  2. クラスタの作成

    gcloud container clusters create circleci-server \
      --num-nodes 3 \
      --machine-type n1-standard-4 \
      --workload-pool=<PROJECT_ID>.svc.id.goog

    手動で kube コンテキストを更新する必要がある場合は、以下を実行します。

    gcloud container clusters get-credentials circleci-server
  3. kubectl 用に GKE 認証プラグイン をインストールします。

    gcloud components install gke-gcloud-auth-plugin
  4. クラスタを確認します。

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

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

    gcloud iam service-accounts keys create <KEY_FILE> \
      --iam-account <SERVICE_ACCOUNT_ID>@<PROJECT_ID>.iam.gserviceaccount.com

    ==== GKE で Workload Identity の有効化 (オプション)

GKE クラスタを既にお持ちで Workload Identity をクラスタとノードプールで有効化する必要がある場合は、下記の手順を実施します。

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

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

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

      gcloud container node-pools update "<NODEPOOL_NAME>" \
        --cluster="<CLUSTER_NAME>" \
        --workload-metadata="GKE_METADATA"

既存の全てのノードプールに対して、手順 3 を実行する必要があります。 Kubernetes サービスアカウントの Workload Identity を有効にする手順については、以下のリンクを参照してください。

3. 新しい GitHub OAuth アプリを作成します

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

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

    Screenshot showing setting up a new OAuth app
    Figure 1. 新しい 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 2. クライアント ID とシークレット

GitHub Enterprise

GitHub Enterprise を使用する場合は、パーソナルアクセストークンと GitHub Enterprise インスタンスのドメイン名も必要です。

User Settings > Developer Settings > Personal access tokens に移動し、defaultToken を作成します。 このトークンにはスコープは必要ありません。 この値は CircleCI Server の設定の際に必要になります。

4. Static IPs

It is recommended to provision a static IP address to assign to the load balancer created by the cluster. While this is not necessary, it does eliminate the need to update DNS records if the service-created load balancer is reprovisioned.

GCP - Reserve a static external IP address

To reserve a new static IP address in GCP, run the following gcloud command in your desired environment. More information is available on the Google Cloud docs.

gcloud compute addresses create circleci-server --global --ip-version IPV4

Make note of the returned IPv4 address for use later in the values.yaml file.

AWS - Reserve an elastic IP address

To reserve an elastic IP address in AWS, run the following AWS CLI commands in your desired environment.

This command needs to be run to generate an address for every subnet the load balancer deploys into - default 3.

# Run x times per x subnets (default 3)
aws ec2 allocate-address

# {
#    "PublicIp": "10.0.0.1,
#    "AllocationId": "eipalloc-12345",
#    "PublicIpv4Pool": "amazon",
#    "NetworkBorderGroup": "us-east-1",
#    "Domain": "vpc"
#}

Make note of each of the returned AllocationId values from the CLI for use in the values.yaml file.

5. フロントエンド TLS 証明書

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

下記のいずれかの方法で証明書を作成したら、このインストールの後半で必要になった際に以下のコマンドによりその証明書を取得できます。

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

AWS Route53

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

    python3 -m pip 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 プラグインをインストールする必要があります。 プラグインのインストールには以下のコマンドを実行します。

    python3 -m pip install certbot-dns-google
  2. certbot の実行に使用するサービスアカウントは、ドメインの検証で Let’s Encrypt が使用する必要なレコードをプロビジョニングするために、Cloud DNS にアクセスできる必要があります。

    1. cerbot 用のカスタムロールを作成します

      gcloud iam roles create certbot --project=<PROJECT_ID> \
          --title="<TITLE>" --description="<DESCRIPTION>" \
          --permissions="dns.changes.create,dns.changes.get,dns.changes.list,dns.managedZones.get,dns.managedZones.list,dns.resourceRecordSets.create,dns.resourceRecordSets.delete,dns.resourceRecordSets.list,dns.resourceRecordSets.update" \
          --stage=ALPHA
    2. 新しいロールを先程作成したサービスアカウントにバインドします

      gcloud projects add-iam-policy-binding <PROJECT_ID> \
          --member="serviceAccount:<SERVICE_ACCOUNT_ID>@<PROJECT_ID>.iam.gserviceaccount.com" \
          --role="<ROLE_NAME>"
  3. 最後に、以下のコマンでインストール証明書をプロビジョニングします。

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

AWS Certificate Manager

ご自身の TLS 証明書をプロビジョニングする代わりに、AWS 環境で CircleCI Server を設定する場合は、Certificate Manager を使用して AWS が TLS 証明書をプロビジョニングするように設定できます。

aws acm request-certificate \
  --domain-name <CIRCLECI_SERVER_DOMAIN> \
  --subject-alternative-names app.<CIRCLECI_SERVER_DOMAIN> \
  --validation-method DNS \
  --idempotency-token circle

このコマンドを実行したら、Certificate Manager AWS コンソールに移動して、ウィザードに従って Route53 で必要な DNS 検証レコードをプロビジョニングします。 この証明書が発行されたら、ARN をメモします。

アップストリーム TLS の終了

アプリケーションの外側で CircleCI Server の TLS を終了する必要がある場合があります。 これは、ACM を使用したり、Helm のデプロイ中に証明書チェーンを提供する代わりの方法です。 たとえば、プロキシがドメイン名に TLS の終了を提供している CircleCI Server の前で実行されているとします。 この場合、CircleCI アプリケーションはロードバランサーやプロキシのバックエンドとして動作します。

CircleCI Server は、トラフィックのルーティング方法に応じて設定する必要がある複数のポートをリッスンします。 下記のポート番号リストを参照して下さい。

  • フロントエンド / API Gateway/ [TCP 80, 443]

  • VM サービス [TCP 3000]

  • Nomad サーバー[TCP 4647]

  • 出力プロセッサ [gRPC 8585]

要件に応じて、フロントエンド/ API ゲートウェイの TLS のみを終了するか、すべてのポートでリッスンするサービスの TLS を提供するかを選択できます。

6. 暗号化/署名キー

CircleCI で生成されるアーティファクトの暗号化と署名には、このセクションで生成したキーセットを使用します。 CircleCI Server の設定にはこれらが必要な場合があります。

a. アーティファクト署名キー

アーティファクト署名キーを生成するには、下記のコマンドを実行します。

docker run circleci/server-keysets:latest generate signing -a stdout

b. 暗号化署名キー

暗号化署名キーを生成するには、下記のコマンドを実行します。

docker run circleci/server-keysets:latest generate encryption -a stdout

7. オブジェクトストレージとアクセス許可

CircleCI Server v4.x では、ビルドしたアーティファクト、テスト結果、その他の状態のオブジェクトストレージをホストします。 以下のストレージオプションがサポートされています。

S3 互換のオブジェクトストレージであればどれでも動作すると考えられますが、テスト済みかつサポート対象のストレージは AWS S3 と MinIO です。 Azure Blob Strage などの S3 API をサポートしていないオブジェクトストレージプロバイダーを利用する場合は、MinIO Gateway の利用をお勧めします。

S3 または GCS のバケットとアクセス方法を作成するには、次の手順に従います。

S3 ストレージ

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

aws s3api create-bucket \
    --bucket <YOUR_BUCKET_NAME> \
    --region <YOUR_REGION> \
    --create-bucket-configuration LocationConstraint=<YOUR_REGION>

b. 認証を設定します

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

Google Cloud Storage

a. GCP バケットを作成します。

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

gsutil mb gs://circleci-server-bucket

b. 認証を設定します

ワークロードとポッドの認証で推奨される方法は、 Workload Identity を使った方法です。 ただし、静的な認証情報 (json キーファイル) を使用することも可能です。

  1. サービスアカウントを作成します。

    gcloud iam service-accounts create circleci-storage --description="Service account for CircleCI object storage" --display-name="circleci-storage"
  2. objectAdmin ロールをサービスアカウントにバインドします。

    gcloud projects add-iam-policy-binding <PROJECT_ID> \
        --member="serviceAccount:circleci-storage@<PROJECT_ID>.iam.gserviceaccount.com" \
        --role="roles/storage.objectAdmin" \
        --condition='expression=resource.name.startsWith("projects/_/buckets/circleci-server-bucket"),title=restrict_bucket'
  3. Workload Identity を有効にする、または静的な認証情報を使用します。


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

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

サポートが必要ですか

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

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