CircleCI Server v3.x のバックアップと復元

概要

バックアップと復元は、CircleCI Server v3.1.0 以上で利用できます。

CircleCI Server の運用と管理を担当される方であれば、間違いなく、別のクラスタへの移行や重大なイベントからの復元が必要になった事態を想定し、バックアップを維持しシステムを復元する方法を考えていることでしょう。 このドキュメントでは、CircleCI Server インスタンスのデータと状態をバックアップして復元する方法に関する推奨事項を説明します。

CircleCI Server は、https://kots.io/[KOTS] を使用して管理します。KOTS では、バックアップと復元に Velero を使用します。 このアプローチのメリットは、アプリケーションのデータを復元するだけでなく、バックアップ時点の Kubernetes クラスタの状態とリソースも復元することです。 こうすれば、管理者コンソールの構成や、クラスタに加えたカスタマイズ内容も復元できます。

CircleCI サービスのバックアップと復元には、Velero が必須です。 クラスタが失われた場合、そのクラスタ内の Velero が正常に起動するまで、CircleCI を復元することはできません。 Velero が正常に起動すれば、CircleCI サービスを復元できます。

セットアップ

CircleCI Server のバックアップは、https://kots.io/[KOTS] を通じて非常に簡単に作成できます。 However, to enable backup support you will need to install and configure Velero on your cluster. 以下のセクションでは、クラスタへの Velero のインストール手順を説明します。

前提条件

  • お使いの環境に合った Velero CLI をダウンロードしてインストールします。

AWS を使う場合の前提条件

  • AWS CLI をインストール済みであること。

GCP を使う場合の前提条件

  • gcloudgsutil をインストール済みであること。 これらは両方とも Google Cloud SDK に含まれており、SDK をインストールすることでセットアップできます (こちらのドキュメントを参照してください)。

詳細については、Velero のhttps://velero.io/docs/v1.6/supported-providers/[サポート対象プロバイダーに関するページ]を参照してください。

以下で、AWS と GCP のそれぞれで CircleCI Server 3.x のバックアップを作成する手順について説明します。

S3 互換ストレージを使う場合の前提条件

  • お使いのストレージ プロバイダーに合った minio CLI をインストールし構成済みであること。

AWS での CircleCI Server 3.x のバックアップ

以下の手順では、プロバイダーが AWS であり、上記の前提条件を満たしていることを前提としています。

これらの手順は、https://github.com/vmware-tanzu/velero-plugin-for-aws#setup[こちら]の Velero ドキュメントを元にしています。

手順 1 - AWS S3 バケットの作成

BUCKET=<YOUR_BUCKET>
REGION=<YOUR_REGION>
aws s3api create-bucket \
    --bucket $BUCKET \
    --region $REGION \
    --create-bucket-configuration LocationConstraint=$REGION
us-east-1 では、https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html#API_CreateBucket_RequestBody[LocationConstraint] がサポートされていません。 us-east-1 リージョンを使用している場合、バケットの構成は省略してください。

手順 2 - Velero の権限の設定

  • IAM ユーザーを作成します。

aws iam create-user --user-name velero
  • 必要な権限を付与するポリシーをユーザー velero にアタッチします。

cat > velero-policy.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeVolumes",
                "ec2:DescribeSnapshots",
                "ec2:CreateTags",
                "ec2:CreateVolume",
                "ec2:CreateSnapshot",
                "ec2:DeleteSnapshot"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:PutObject",
                "s3:AbortMultipartUpload",
                "s3:ListMultipartUploadParts"
            ],
            "Resource": [
                "arn:aws:s3:::${BUCKET}/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::${BUCKET}"
            ]
        }
    ]
}
EOF
aws iam put-user-policy \
  --user-name velero \
  --policy-name velero \
  --policy-document file://velero-policy.json
  • ユーザー velero 用のアクセス キーを作成します。

aws iam create-access-key --user-name velero

このコマンドの結果は以下のようになります。

{
  "AccessKey": {
        "UserName": "velero",
        "Status": "Active",
        "CreateDate": "2017-07-31T22:24:41.576Z",
        "SecretAccessKey": <AWS_SECRET_ACCESS_KEY>,
        "AccessKeyId": <AWS_ACCESS_KEY_ID>
  }
}
  • 以下の内容を記載した、Velero 固有の認証情報ファイルをローカル ディレクトリに作成します (例: ./credentials-velero)。

[default]
aws_access_key_id=<AWS_ACCESS_KEY_ID>
aws_secret_access_key=<AWS_SECRET_ACCESS_KEY>

ここで、AWS_ACCESS_KEY_ID プレースホルダーと AWS_SECRET_ACCESS_KEY プレースホルダーには、前の手順の create-access-key リクエストで返された値を指定します。

手順 3 - Velero のインストールと起動

  • 以下の velero install コマンドを実行します。 これにより、velero という名前空間が作成され、Velero を実行するのに必要なリソースがすべてインストールされます。 Make sure that you pass the correct file name containing the AWS credentials that you have created in Step 2.

KOTS のバックアップを使用するには、https://restic.net/[restic] が必要です。 Velero のインストール時に、以下に示すように --use-restic フラグを設定してください。
velero install \
    --provider aws \
    --plugins velero/velero-plugin-for-aws:v1.2.0 \
    --bucket $BUCKET \
    --backup-location-config region=$REGION \
    --snapshot-location-config region=$REGION \
    --secret-file ./credentials-velero \
    --use-restic \
    --wait
  • Velero がクラスタにインストールされたら、新しい velero 名前空間を確認します。 以下のように、Velero デプロイと restic デーモンセットがあれば成功です。

$ kubectl get pods --namespace velero
NAME                      READY   STATUS    RESTARTS   AGE
restic-5vlww              1/1     Running   0          2m
restic-94ptv              1/1     Running   0          2m
restic-ch6m9              1/1     Running   0          2m
restic-mknws              1/1     Running   0          2m
velero-68788b675c-dm2s7   1/1     Running   0          2m

restic はデーモンセットなので、Kubernetes クラスタ内のノード 1 つにつき 1 つの Pod が存在します。

GCP での CircleCI Server 3.x のバックアップ

以下の手順は、Google Cloud Platform を対象としており、前提条件を満たしていることを前提としています。

これらの手順は、https://github.com/vmware-tanzu/velero-plugin-for-gcp#setup[こちら]の Velero GCP プラグインのドキュメントを元にしています。

手順 1 - GCP バケットの作成

タイプミスの可能性を減らすために、一部のパラメーターをシェル変数として設定しています。 すべての手順を 1 つのセッションで完了できず、再開する場合は、必要に応じて変数を再設定するようにしてください。 たとえば、以下の手順では、バケット名に対応する変数を定義しています。 Replace the <YOUR_BUCKET> placeholder with the name of the bucket you want to create for your backups.

BUCKET=<YOUR_BUCKET>

gsutil mb gs://$BUCKET/

Step 2 - Setup permissions for Velero

CircleCI Server を GKE クラスタ内で実行している場合、RBAC オブジェクトを作成する必要があるため、使用する IAM ユーザーをクラスタの管理者に設定してください。 詳細については、https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control#iam-rolebinding-bootstrap[GKE のドキュメント]を参照してください。

  1. 最初に、プロジェクト ID に対応するシェル変数を設定します。 それにはまず、次のコマンドを実行して現在の構成を調査し、gcloud CLI が正しいプロジェクトを参照していることを確認します。

    gcloud config list
  2. プロジェクトが適切に参照されていれば、以下のように変数を設定します。

    PROJECT_ID=$(gcloud config get-value project)
  3. 以下のコマンドを実行して、サービス アカウントを作成します。

    gcloud iam service-accounts create velero \
        --display-name "Velero service account"
    Velero がインストールされたクラスタを複数実行している場合は、サービス アカウントに対して、ここで示している velero ではなく具体的な名前を付けることをお勧めします。
  4. 以下のコマンドを実行して、サービス アカウントが正常に作成されたことを確認します。

    gcloud iam service-accounts list
  5. 次に、サービス アカウントの電子メール アドレスを変数に格納します。

    SERVICE_ACCOUNT_EMAIL=$(gcloud iam service-accounts list \
      --filter="displayName:Velero service account" \
      --format 'value(email)')

    サービス アカウントに付けた表示名に合わせて、必要に応じてコマンドを変更してください。

  6. 必要な権限をサービス アカウントに付与します。

    ROLE_PERMISSIONS=(
        compute.disks.get
        compute.disks.create
        compute.disks.createSnapshot
        compute.snapshots.get
        compute.snapshots.create
        compute.snapshots.useReadOnly
        compute.snapshots.delete
        compute.zones.get
    )
    
    gcloud iam roles create velero.server \
        --project $PROJECT_ID \
        --title "Velero Server" \
        --permissions "$(IFS=","; echo "${ROLE_PERMISSIONS[*]}")"
    
    gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:$SERVICE_ACCOUNT_EMAIL \
        --role projects/$PROJECT_ID/roles/velero.server
    
    gsutil iam ch serviceAccount:$SERVICE_ACCOUNT_EMAIL:objectAdmin gs://${BUCKET}

次に、Velero でこのサービス アカウントを使用できるようにする必要があります。

オプション 1: JSON キー ファイル

サービス アカウントとしてアクションを実行できるように Velero を認証するには、JSON 認証情報ファイルを Velero に渡します。 それにはまず、以下のコマンドを実行してキーを作成します。

gcloud iam service-accounts keys create credentials-velero \
    --iam-account $SERVICE_ACCOUNT_EMAIL

これを実行すると、credentials-velero という名前のファイルがローカル作業ディレクトリに作成されます。

オプション 2: Workload Identity

クラスタで既に Workload Identity を使用している場合は、先ほど作成した GCP サービス アカウントを Velero の Kubernetes サービス アカウントにバインドします。 この場合、GCP サービス アカウントには、上記で指定済みの権限に加え、iam.serviceAccounts.signBlob ロールも必要です。

手順 3 - Velero のインストールと起動

  • サービス アカウントの認証方法に応じて、以下の velero install コマンドのいずれかを実行します。 これにより、velero という名前空間が作成され、Velero を実行するのに必要なリソースがすべてインストールされます。

KOTS のバックアップを使用するには、https://restic.net/[restic] が必要です。 Velero のインストール時に、--use-restic フラグを設定してください。

JSON キー ファイルを使用する場合

velero install \
    --provider gcp \
    --plugins velero/velero-plugin-for-gcp:v1.2.0 \
    --bucket $BUCKET \
    --secret-file ./credentials-velero \
    --use-restic \
    --wait

Workload Identity を使用する場合

velero install \
    --provider gcp \
    --plugins velero/velero-plugin-for-gcp:v1.2.0 \
    --bucket $BUCKET \
    --no-secret \
    --sa-annotations iam.gke.io/gcp-service-account=$SERVICE_ACCOUNT_EMAIL \
    --backup-location-config serviceAccount=$SERVICE_ACCOUNT_EMAIL \
    --use-restic \
    --wait

システムをカスタマイズする他のオプションについては、https://github.com/vmware-tanzu/velero-plugin-for-gcp#install-and-start-velero[Velero のドキュメント]を参照してください。

  • Velero がクラスタにインストールされたら、新しい velero 名前空間を確認します。 以下のように、Velero デプロイと restic デーモンセットがあれば成功です 。

$ kubectl get pods --namespace velero
NAME                      READY   STATUS    RESTARTS   AGE
restic-5vlww              1/1     Running   0          2m
restic-94ptv              1/1     Running   0          2m
restic-ch6m9              1/1     Running   0          2m
restic-mknws              1/1     Running   0          2m
velero-68788b675c-dm2s7   1/1     Running   0          2m

restic はデーモンセットなので、Kubernetes クラスタ内のノード 1 つにつき 1 つの Pod が存在します。

S3 互換ストレージでの CircleCI Server 3.x のバックアップ

以下の手順では、S3 互換オブジェクト ストレージ (AWS S3 に限らない) をバックアップに使用していることが前提です。 また、前提条件を満たしていることも前提としています。

これらの手順は、https://velero.io/docs/v1.6/contributions/minio/[こちら]の Velero ドキュメントを元にしています。

手順 1 - mc クライアントの構成

最初に、ストレージ プロバイダーに接続できるよう mc を構成します。

# エイリアスは任意の名前でよいが、以降のコマンドで同じ値を使用すること
export ALIAS=my-provider
mc alias set $ALIAS <YOUR_MINIO_ENDPOINT> <YOUR_MINIO_ACCESS_KEY_ID> <YOUR_MINIO_SECRET_ACCESS_KEY>

クライアントが適切に構成されたかどうかは、mc ls my-provider を実行して確認できます。出力に、指定したプロバイダーのバケットが列挙されて表示されます。

手順 2 - バケットの作成

バックアップ用のバケットを作成します。 Velero では、他のコンテンツが含まれた既存のバケットを使用できないので、新しいバケットを使用する必要があります。

mc mb ${ALIAS}/<YOUR_BUCKET>

手順 3 - ユーザーとポリシーの作成

次に、Velero がバケットにアクセスするためのユーザーとポリシーを作成します。

In the following snippet <YOUR_MINIO_ACCESS_KEY_ID> and <YOUR_MINIO_SECRET_ACCESS_KEY> refer to the credentials used by Velero to access MinIO.
# ユーザーを作成
mc admin user add $ALIAS <YOUR_MINIO_ACCESS_KEY_ID> <YOUR_MINIO_SECRET_ACCESS_KEY>

# ポリシーを作成
cat > velero-policy.json << EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:*"
      ],
      "Resource": [
        "arn:aws:s3:::<YOUR_BUCKET>",
        "arn:aws:s3:::<YOUR_BUCKET>/*"
      ]
    }
  ]
}
EOF

mc admin policy add $ALIAS velero-policy velero-policy.json

# ユーザーをポリシーにバインド
mc admin policy set $ALIAS velero-policy user=<YOUR_VELERO_ACCESS_KEY_ID>

最後に、新しいユーザーの認証情報を以下の形式で記述したファイルを作成します (この例では ./credentials-velero)。

[default]
aws_access_key_id=<YOUR_VELERO_ACCESS_KEY_ID>
aws_secret_access_key=<YOUR_VELERO_SECRET_ACCESS_KEY>

手順 4 - Velero のインストールと起動

以下の velero install コマンドを実行します。 これにより、velero という名前空間が作成され、Velero を実行するのに必要なリソースがすべてインストールされます。

KOTS のバックアップを使用するには、https://restic.net/[restic] が必要です。 Velero のインストール時に、以下に示すように --use-restic フラグを設定してください。
velero install --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.2.0 \
  --bucket <YOUR_BUCKET> \
  --secret-file ./credentials-velero \
  --use-volume-snapshots=false \
  --use-restic \
  --backup-location-config region=minio,s3ForcePathStyle="true",s3Url=<YOUR_ENDPOINT> \
  --wait

Velero がクラスタにインストールされたら、新しい velero 名前空間を確認します。 以下のように、Velero デプロイと restic デーモンセットがあれば成功です。

$ kubectl get pods --namespace velero
NAME                      READY   STATUS    RESTARTS   AGE
restic-5vlww              1/1     Running   0          2m
restic-94ptv              1/1     Running   0          2m
restic-ch6m9              1/1     Running   0          2m
restic-mknws              1/1     Running   0          2m
velero-68788b675c-dm2s7   1/1     Running   0          2m

restic はデーモンセットなので、Kubernetes クラスタ内のノード 1 つにつき 1 つの Pod が存在します。

バックアップの作成

クラスタへの Velero のインストールが完了すると、管理コンソールのナビゲーション バーに [Snapshots (スナップショット)] オプションが表示されるようになります。

Kots Navbar

このオプションが表示されれば、バックアップの作成を始める準備は完了です。 このオプションが表示されない場合は、トラブルシューティングに関するセクションを参照してください。

オプション 1 - KOTS CLI を使用したバックアップ作成

バックアップを作成するには、以下のコマンドを実行します。

kubectl kots backup --namespace <your namespace>

オプション 2 - KOTS 管理者コンソールを使用したバックアップ作成

ナビゲーション バーの [Snapshots (スナップショット)] を選択します。 デフォルトでは [Full Snapshots (フル スナップショット)] が選択されています。これが推奨オプションです。

Kots Navbar

[Start a snapshot (スナップショットの開始)] ボタンを選択します。

Kots Create Snapshot

バックアップの復元

オプション 1 - スナップショットからのバックアップ復元

S3 互換ストレージに保存済みのバックアップから復元するには、Kubernetes クラスタに Velero がインストールされており、バックアップの格納されているストレージ バケットに Velero がアクセスできる必要があります。 EKS を使用する場合に CircleCI Server を復元するには、CircleCI Server のインスタンスが事前にインストールされている必要があります。 GKE や他のプラットフォームを使用する場合は、クラスタに Velero さえインストールされていれば機能します。

新しいクラスタの場合または Velero の再インストールが必要な場合は、上記で生成したのと同じ認証情報を使用してインストールを行う必要があります。

オプション 2 - KOTS CLI を使用したバックアップ復元

KOTS CLI を使用してバックアップを復元するには、以下のコマンドを実行してバックアップのリストを取得します。

kubectl kots get backups

復元プロセスを開始するには、前述のコマンドで取得したバックアップ名を使用して、以下のコマンドを実行します。

kubectl kots restore --from-backup <backup-instance-id>

オプション 3 - KOTS 管理者コンソール UI を使用したバックアップ復元

バックアップ時と同様に、KOTS 管理者コンソールの [Snapshots (スナップショット)] に移動します。 今回は、復元アイコン付きのバックアップがすべて表示されます。 使用するバックアップを選択し、復元アイコンを選択します。

Kots Create Snapshot
復元すると、CircleCI サービス用に新しいロード バランサーが作成されます。 そのため、KOTS 管理者コンソールでの DNS レコードまたはホスト名の構成の更新が必要になります。 また、Nomad クライアントに指定する nomad server endpoint も更新することをお勧めします。
既存の Nomad クライアントを使用している場合、Nomad サーバー クラスタに接続する前にクライアントを再起動する必要があります。

CircleCI Server が復元され、運用可能な状態になるまで、約 10 ~ 15 分かかります。

オプション - KOTS 使用したバックアップのスケジュール設定

定期的なバックアップ スケジュールを設定するには、KOTS 管理者コンソールで [Snapshots (スナップショット)][Settings & Schedule (設定とスケジュール)] の順に選択します。

Snapshots Selected

ここでは、スケジュール設定をはじめ、スナップショットに関する設定を行えます。

Snapshot Settings

バックアップと復元のトラブルシューティング

[Snapshots (スナップショット)] オプションが KOTS 管理者コンソールに表示されない

KOTS 管理者コンソールに [Snapshots (スナップショット)] オプションが表示されない場合、以下を試してください。

  • 使用している KOTS バージョンがスナップショットをサポートしていることを確認します。 現時点では、v1.40.0 以上が推奨されます。

$ kubectl kots version
Replicated KOTS 1.40.0
  • Velero がデプロイされ、適切に動作していることを確認します。 Velero のログは、以下のコマンドで確認できます。

$ kubectl logs deployment/velero --namespace velero

問題がある場合は、Velero の再インストールが必要です。

  • お使いのライセンスでスナップショットを利用できることを確認します。 これを確認するには、CircleCI カスタマー サポート チームにお問い合わせください。

バックアップ プロセスまたは復元プロセスでエラーが発生した

バックアップまたは復元プロセスでエラーが発生した場合は、まず Velero ログを確認してください。 上記のコマンドの結果 4XX エラーが見つかった場合、ストレージ バケットへのアクセスの問題が原因の可能性があります。

  • バケットが存在していることと、想定するリージョンにあることを確認します。

  • Velero に指定した認証情報でバケットにアクセスできることを確認します。

  • 問題が解決しない場合は、新しいバケット情報を指定して Velero のインストール コマンドを再び実行する必要があります。

また、velero 名前空間にある Pod のステータスを確認します。

$ kubectl get pods --namespace velero
NAME                      READY   STATUS    RESTARTS   AGE
restic-5vlww              1/1     Pending   0          10m
restic-94ptv              1/1     Running   0          10m
restic-ch6m9              1/1     Pending   0          10m
restic-mknws              1/1     Running   0          10m
velero-68788b675c-dm2s7   1/1     Running   0          10m

上記の例では、restic Pod のいくつかが保留状態です。これは、利用可能な CPU リソースまたはメモリ リソースがノードに割り当てられるまで待機していることを意味します。 この場合、restic に合わせたノードのスケーリングが必要な可能性があります。



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

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


クリエイティブ・コモンズ・ライセンス
CircleCICircleCI ドキュメントは、クリエイティブ・コモンズの表示--非営利-継承 4.0 国際ライセンス に基づいてライセンス供与されています。