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

Terraformを使って AWS にインストールする方法

2 weeks ago2 min read
Server v2.x
On This Page

Terraform を使って CircleCI Server v2.x をインストールする手順は以下のとおりです。

Terraform の変数を定義する

  1. Setup リポジトリをクローンします。 すでにクローンしている場合は、クローンが最新であり、メインブランチにいることを確認するために、下記を実行します。

    git checkout main && git pull

  2. ローカルマシンの enterprise-setup リポジトリの一番上のディレクトリに移動します。

  3. terraform init を実行して、作業ディレクトリを初期化します。

  4. make init を実行し、terraform.tfvars ファイルを初期化します (既に terraform.tfvars が存在する場合、同じディレクトリにバックアップされます)。

  5. エディターで terraform.tfvars を開き、1. に適切な AWS 値を入力します。

  6. 1.0 Builder を使用する場合は、 2. で circle_secret_passphrase を指定し、 …​ を英数字に置き換えますが、1.0 Builder を使用しない場合はそのままにしておきます。1.0 Builder は、3. のデフォルト設定で無効になっています。

  7. Nomad クライアントのインスタンスタイプを指定します。 デフォルトでは、Nomad クライアント用の terraform.tfvars ファイルの値は m5.2xlarge (vCPU 8 基、RAM 32 GB)です。 各 Nomad クライアントが同時に実行できる CircleCI ジョブの数を増やすには、terraform.tfvars ファイルの 2. で nomad_client_instance_type の値を大きくします。 詳細については、AWSの Amazon EC2 Instance Types ガイドを参照し、CircleCIドキュメントの システム要件 をお読みください。

  8. 下記の 3. では、以下が可能です。

    1. プロジェクトで必要な場合は、カウントを 1 に変更して 1.0 Builder の使用を選択する。

    2. プロキシの詳細を入力し、AWS リージョン内に複数のインストールがある場合は、プレフィックスを入力する。Services および Nomad クライアントのインスタンスは、AWS コンソールではこのプレフィックスで表示されます。

tfvars の例
#####################################
# 1. 必要なクラウド設定
#####################################

aws_access_key = "..."
aws_secret_key = "..."
aws_region = "eu-central-1"
aws_vpc_id = "..."
aws_subnet_id = "..."
aws_ssh_key_name = "..."

#####################################
# 2. 必要な CircleCI の設定
#####################################

circle_secret_passphrase = "..."
services_instance_type = "m4.2xlarge"
builder_instance_type = "r3.4xlarge"
nomad_client_instance_type = "m4.2xlarge"

#####################################
# 3. オプションのクラウド設定
#####################################

# 下記を `1` またはそれ以上に設定し、CircleCI 1.0 Builder を有効にします。
desired_builders_count = "0"

# ネットワーク設定で必要な場合は、プロキシアドレスを指定します。
http_proxy = ""
https_proxy = ""
no_proxy = ""

# 同一の AWS リージョン内に複数のサーバーをインストールしている場合、下記変数を使用します。
prefix = "..."

上記の terraform.tfvars ファイル例を編集します。 下記の表では、デフォルト設定と、クラスタを更にカスタマイズする際に使用できるオプションの変数を紹介します。 変数とデフォルトの全リストは、enterprise-setup ディレクトリのルートにある variables.tf ファイルにあります。

変数のオプション

変数説明デフォルト値

services_instance_type

一元管理されたサービスボックスのインスタンスタイプです。 m4 インスタンスを推奨します。

m4.2xlarge

builder_instance_type

1.0 Builder マシンのインスタンスタイプです。 r3 インスタンスを推奨します。

r3.2xlarge

max_builders_count

1.0 Builder の最大数です。

2

nomad_client_instance_type

Nomad クライアント (2.0 Builder) のインスタンスタイプです。 XYZ インスタンスを推奨します。

m4.xlarge

max_clients_count

Nomad クライアントの最大数です。

2

prefix

リソース名のプレフィックスです。

circleci

enable_nomad

CircleCI Server v2.x 用の Nomad クラスタをプロビジョニングします。

1

enable_route

Services ボックスの Route53 ルートの作成を有効にします。

0

enable_govcloud

AWS GovCloud へのデプロイを許可します。

false

services_user_data_enabled

サービスボックスへの自動インストールを無効にするには、0 に設定します。

1

force_destroy_s3_bucket

インストールのシャットダウン時に S3 バケットを強制的に破棄する機能を追加/削除します。

false

services_disable_api_termination

API の終了から サービスインスタンスを保護します。 インストールのシャットダウン時に サービスボックスを自動的に終了させたい場合は、false に設定してください。

true

インスタンスのプロビジョニング

  1. 変更内容を tfvars ファイルに保存し、以下を実行します。

    terraform plan

  2. インスタンスのプロビジョニングを行うために、以下を実行します。

    terraform apply

    その際、先に進むかどうかを yes と入力して確認するように求められます。

  3. Terraform の出力の最後に IP アドレスが提供されます。 この IP アドレスにアクセスして、インストール作業を進めてください。

CircleCI へのアクセス

  1. ブラウザ上に、SSL/TLS の情報ボックスが表示される場合があります。 これは、次の画面でブラウザが管理コンソールへの接続が安全でないことを通知する場合があることを知らせるためのものですが、安全ですのでご安心ください。 [Continue to Setup] をクリックして、インストール先の IP に進みます。

    SSL Security
    Figure 1. SSL セキュリティ

  2. ホストネームを入力します。 ここではドメイン名または サービスマシンのインスタンスのパブリック IP を指定します。 この時、SSL公開キーと証明書があればアップロードすることも可能です。 これらを入力せずに進む場合は、[Use Self-Signed Cert ] をクリックします。 このオプションを選択すると、管理コンソールにアクセスするたびにセキュリティに関する警告が表示されます。

    Hostname
    Figure 2. ホスト名

  3. ライセンスをアップロードします。

  4. 管理コンソールのセキュリティを保護する方法を設定します。 選択肢は以下の 3 つです。

    1. 匿名の管理者によるコンソールへのアクセスを許可。ポート 8800 上の誰でもアクセスが可能です（非推奨）。

    2. 管理者コンソールに安全にアクセスできるようパスワードを設定 (推奨)。

    3. 既存のディレクトリベースの認証システム (LDPAなど) を使用。

      Secure the Management Console
      Figure 3. 管理者パスワード

  5. CircleCI に対して一連の事前チェックが行われます。完了したら、下にスクロールして [Continue] をクリックします。

    Preflight Checks
    Figure 4. 事前チェック

インストールの設定

管理コンソールの設定ページ (your-circleci-hostname.com:8800) が表示されます。

  1. Hostname: ホスト名フィールドは、インストールプロセスで事前に入力されているはずですが、そのステップをスキップした場合は、Servies マシンのインスタンスのドメインまたはパブリック IP を入力してください。 [Test Hostname Resolution] をクリックすると、正確に入力されているか確認できます。

  2. Services : Services のセクションは、サービスを外部化する場合のみ使用します。 外部化は Premium サービス契約のお客様のみご利用いただけます。 詳細については、 support@circleci.com までお問い合わせください。

    Hostname and Services Settings
    Figure 5. 外部サービス

  3. Execution Engines : レガシープロジェクトで 1.0 Builder が必要な場合のみ選択してください。ほとんどの場合、このチェックは外しておきます。

  4. Builders Configuration: 2.0 のセクションでクラスタを選択します。 シングルボックス オプションは、専用のインスタンスではなく サービスマシン上でジョブを実行するため、システムの試用や小規模なチームにのみ適しています。

    Execution Engine
    Figure 6. 1.0 / 2.0 Builder

  5. GitHub Integration: CircleCI を GitHub.com または GitHub Enterprise の新しい OAuth アプリケーションとして、ページに記載されている手順で登録します。

    1. GitHub から Client ID と Secret をコピーして、該当するフィールドにペーストし、[Test Authentication] をクリックします。

    2. GitHub.com をご利用の場合は、ステップ 6 に進みます。 Github Enterprise をご利用の場合は、いくつかの追加手順を行い、API トークンを提供していただき、お客様の組織を確認する必要があります。 トークンを提供するには、GitHub Enterprise のダッシュボードから以下を実行してください。

      1. Personal Settings (右上) に行き、 Developer Settings Personal Access Tokens に移動します。

      2. [generate new token] をクリックします。 誤って削除されないように、トークンには適切な名前を付けてください。 チェックボックスには何もチェックを入れないでください。ここでは、デフォルトのパブリックな読み取りレベルのアクセスが必要なだけで、追加のアクセス権限は必要ありません。 このトークンは一人のユーザーが所有するのではなく、組織全体で共有することをお勧めします。

      3. 新しいトークンをコピーして、GitHub Enterprise Default API Token フィールドに貼り付けます。

        Github Integration
        Figure 7. Github Enterprise Token を入力します。

  6. LDAP: インストールに LDAP 認証を使用する場合は、LDAP のセクションに必要な情報を入力してください。 LDAP 設定の詳細については、 LDAP 認証ガイドをご覧ください。

  7. Privacy: インストールには SSL 証明書と SSL キーの使用をお勧めします。 インストールの際にこのステップを行わなかった場合は、この Privacy のセクションでこれらの情報を提出することができます。

    Privacy settings
    Figure 8. プライバシーの設定

  8. Storage : ストレージには S3 の使用を推奨しており、入力が必要なフィールドはあらかじめ入力されています。 ここでは、本ドキュメントの planning で述べた IAM ユーザーを使用します。

    Storage options
    Figure 9. ストレージのオプション

  9. Enhanced AWS Integration: 1.0 Builder を使用している場合は、ここに入力します。

  10. Email: Email セクションは、ビルドアップデートメールの送信に独自のメールサーバーを設定する場合に入力します。 デフォルトのメールサーバーを使用する場合は、入力しません。

  11. VM Provider : リモート Docker または machine Executor (Linux/Windows) 機能を使用する場合は VM サービスを設定してください。 本ドキュメントの planning で述べたように、認証には IAM インスタンスプロファイルを使用することをお勧めします。 完了すると、リモートDocker でジョブを実行するか、 machine Executor を使用するように、インスタンスが自動的にプロビジョニングされます。 Windows の machine Executorを使用するには、 イメージをビルドする必要があります。 VM サービスの詳細と、リモート Docker および machine Executor ジョブのカスタム AMI の作成については、 VM サービスガイドをお読みください。

    インスタンスを事前に割り当てて常に起動しておくことで、リモート Docker や machine Executor ジョブが開始するまでの時間を短縮することが可能です。 事前割り当てが設定されている場合、cron ジョブが 1日に1回、事前割り当てされたインスタンスを回し、不良/デッド状態になることを防ぎます。

  12. AWS Cloudwatch Metrics や Datadog Metrics は、お客様のインストールに合わせて設定することが可能です。 該当するセクションでどちらかのメトリクスを設定します。 詳しくは、 監視に関するガイドをお読みください。

    AWS Cloudwatch and Datadog metrics
    Figure 10. メトリクス

  13. Custom Metrics で、Cloudwatch メトリクスや Datadog メトリクスの代わりに、Telegraf から受け取るメトリクスをカスタマイズすることも可能です。 詳しくは、 カスタムメトリクスガイドをお読みください。

  14. Distributed Tracing はサポートバンドルで使用されており、CircleCI サポートチームから変更要請がない限り、設定はデフォルトのままにしておく必要があります。

  15. Artifacts はジョブ終了後もデータを保持し、ビルドプロセスの出力を長期的に保存するために使用される場合があります。 CircleCI Server v2.x では、承認されたタイプのアーティファクトのみがデフォルトで利用可能です。 これは、ユーザーが悪意のあるコンテンツをアップロードおよび実行してしまう事態を防ぐための措置です。 Artifactsの設定で、この保護を上書きすることができます。 詳細については、 ビルドアーティファクトを参照してください。

  16. 使用許諾契約に同意し、設定を保存した後、ポップアップから [Restart Now (今すぐ再起動)]を選択します。 その後、CircleCI を起動し、管理コンソールのダッシュボードを表示するようにリダイレクトされます。 必要な Docker コンテナすべてをダウンロードするまで、数分かかります。

インストールの検証

  1. アプリケーションが起動したら、ブラウザで [Open] を選択して CircleCI を起動し、CircleCI にサインアップ/ログインして、2.0 ビルドの実行を開始します。 この時点では最初にサインインしたお客様が管理者になります。 入門ガイドを参照し、プロジェクトを追加します。

    CircleCI server dashboard
    Figure 11. ダッシュボードから CircleCI を起動する

  2. ビルドコンテナが起動してイメージがダウンロードされると、すぐに最初のビルドを開始します。 約 15 分が経過し、[Refresh] ボタンをクリックしても更新が行われない場合は、 CircleCI サポートにお問い合わせください。

  3. 次に、 realitycheck レポジトリを使用して、基本的な CircleCI 機能を確認します。

  4. 最初のビルドの実行に失敗する場合は、まず トラブルシューティングガイドで一般的なトラブルシューティングのトピックを参照してください。CircleCI Server 内の Builder の状態を確認する方法については、 Nomad クラスタの操作ガイドを参照してください。

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

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

サポートが必要ですか

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

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

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.