GitLab Duo with Amazon Qを設定する

プラン: Ultimate
アドオン: GitLab Duo with Amazon Q
提供形態: GitLab Self-Managed

GitLab Duo with Amazon Qは、他のGitLab Duoアドオンと組み合わせることはできません。

GitLab Duo with Amazon Qのサブスクリプションを取得するには、アカウントエグゼクティブにお問い合わせください。

トライアルをリクエストするには、このフォームに記入してください。

Self-Managedインスタンス上のGitLab Duo with Amazon Qを設定するには、次の手順を実行します。

GitLab Duo with Amazon Qをセットアップする

GitLab Duo with Amazon Qを設定するには、以下を行う必要があります:

前提要件

GitLab Self-Managedインスタンスが必要です:
- GitLab 17.11以降。
- Amazon Qは、リクエストされたアクションを実行する際に、GitLabインスタンスのREST APIを使用してデータを読み取りおよび書き込みを行い、HTTPS URLにアクセスできる必要があります（SSL証明書は自己署名でない必要があります）。
- インスタンスは、インスタンスが使用するように設定されているポートでTCP/TLSを使用して、次のIPアドレスから発信されるAmazon Qサービスからの受信ネットワークアクセスを許可する必要があります。これはデフォルトでポート443です。
  - 34.228.181.128
  - 44.219.176.187
  - 54.226.244.221
- GitLabと同期されたUltimateサブスクリプションと、GitLab Duo with Amazon Qアドオンが必要です。

Amazon Q Developerコンソールでプロファイルを作成する

Amazon Q Developerプロファイルを作成します。

Amazon Q Developerコンソールを開きます。
Amazon Q Developer in GitLab（GitLabのAmazon Q Developer）を選択します。
Get Started（開始）を選択します。
プロファイル名に、リージョンの一意のプロファイル名を入力します。たとえばQDevProfile-us-east-1などです。
オプション。Profile description - optional（プロファイルの説明（オプション））に、説明を入力します。
作成を選択します。

IAM Identity Providerを作成する

次に、IAM Identity Providerを作成します。

まず、GitLabからいくつかの値が必要です:

前提要件:

管理者である必要があります。

GitLabにサインインします。
左側のサイドバーの下部で、管理者を選択します。
設定 > 一般を選択します。
GitLab Duo with Amazon Qを展開します。
設定の表示を選択します。
手順1で、プロバイダーURLとオーディエンスをコピーします。これらは次の手順で必要になります。

次に、AWS Identity Providerを作成します:

AWS IAMコンソールにサインインします。
Access Management > Identity providersを選択します。
Add provider（プロバイダーの追加）を選択します。
プロバイダータイプで、OpenID Connectを選択します。
プロバイダーURLに、GitLabからの値を入力します。
オーディエンスに、GitLabからの値を入力します。
Add provider（プロバイダーの追加）を選択します。

IAMロールを作成する

次に、IAM Identity Providerを信頼し、Amazon QにアクセスできるIAMロールを作成する必要があります。

IAMロールを設定した後、ロールに関連付けられているAWSアカウントを変更することはできません。

AWS IAMコンソールで、Access Management > ロール > ロールを作成するを選択します。
Web identity（ウェブアイデンティティ）を選択します。
Web identity（ウェブアイデンティティ）で、以前に入力したプロバイダーURLを選択します。
オーディエンスで、以前に入力したオーディエンス値を選択します。
次へを選択します。
Add permissions（権限の追加）ページで、以下を実行します:
- 管理されたポリシーを使用するには、Permissions policies（許可ポリシー）で検索してGitLabDuoWithAmazonQPermissionsPolicyを選択します。
- インラインポリシーを作成するには、Permissions policies（許可ポリシー）をスキップして、次へを選択します。ポリシーは後で作成します。
次へを選択します。
たとえば、QDeveloperAccessのようにロールに名前を付けます。

信頼ポリシーが正しいことを確認してください。次のようになります:

{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Principal": {
             "Federated": "arn:aws:iam::<AWS_Account_ID>:oidc-provider/auth.token.gitlab.com/cc/oidc/<Instance_ID>"
         },
         "Condition": {
             "StringEquals": {
                 "auth.token.gitlab.com/cc/oidc/<Instance_ID>:aud": "gitlab-cc-<Instance_ID>"
             },

         }
      }
   ]
}

ロールを作成するを選択します。

インラインポリシーを作成する（オプション）

管理されたポリシーを使用するのではなく、インラインポリシーを作成するには、次の手順を実行します:

権限 > Add permissions（権限の追加） > Create inline policy（インラインポリシーの作成）を選択します。

JSONを選択し、エディターに以下を貼り付けます:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GitLabDuoUsagePermissions",
      "Effect": "Allow",
      "Action": [
        "q:SendEvent",
        "q:CreateAuthGrant",
        "q:UpdateAuthGrant",
        "q:GenerateCodeRecommendations",
        "q:SendMessage",
        "q:ListPlugins",
        "q:VerifyOAuthAppConnection"
      ],
      "Resource": "*"
    },
    {
      "Sid": "GitLabDuoManagementPermissions",
      "Effect": "Allow",
      "Action": [
        "q:CreateOAuthAppConnection",
        "q:DeleteOAuthAppConnection"
      ],
      "Resource": "*"
    },
    {
      "Sid": "GitLabDuoPluginPermissions",
      "Effect": "Allow",
      "Action": [
        "q:CreatePlugin",
        "q:DeletePlugin",
        "q:GetPlugin"
      ],
      "Resource": "arn:aws:qdeveloper:*:*:plugin/GitLabDuoWithAmazonQ/*"
    }
  ]
}

アクション > Optimize for readability（可読性のために最適化）を選択して、AWS形式を作成し、JSONを解析します。
次へを選択します。
ポリシーにgitlab-duo-amazon-q-policyという名前を付けて、ポリシーの作成を選択します。

ロールを編集する

次に、ロールを編集します:

作成したロールを見つけて選択します。
セッション時間を12時間に変更します。セッションが12時間以上に設定されていない場合、AssumeRoleWithWebIdentityはAIゲートウェイで失敗します。
1. Roles search（ロールの検索）フィールドに、IAMロールの名前を入力し、ロール名を選択します。
2. サマリーで、編集を選択して、セッション時間を編集します。
3. Maximum session duration（最大セッション時間）ドロップダウンリストを選択し、12 hours（12時間）を選択します。
4. 変更を保存を選択します。
ページに表示されているARNをコピーします。次のようになります:
```
arn:aws:iam::123456789:role/QDeveloperAccess
```

GitLabでARNを入力してAmazon Qを有効にする

次に、ARNをGitLabに入力し、どのグループとプロジェクトが機能にアクセスできるかを決定します。

前提要件:

GitLab管理者である必要があります。

GitLab Duo with Amazon Qの設定を完了するには、以下を実行します:

GitLabにサインインします。
左側のサイドバーの下部で、管理者を選択します。
設定 > 一般を選択します。
GitLab Duo with Amazon Qを展開します。
設定の表示を選択します。
IAMロールのARNで、ARNを貼り付けます。
どのグループとプロジェクトがGitLab Duo with Amazon Qを使用できるかを決定するには、オプションを選択します:
- インスタンスに対してオンにし、グループとプロジェクトでオフにできるようにするには、デフォルトで有効にするを選択します。
  - オプション。Amazon Qがマージリクエストでコードを自動的にレビューするように設定するには、マージリクエストにあるコードをAmazon Qで自動的にレビューするを選択します。
- インスタンスに対してオフに設定しても、グループやプロジェクトでオンにできるようにするには、デフォルトで無効にするを選択します。
- インスタンスに対してオフにし、グループやプロジェクトでオンにできないようにするには、常にオフを選択します。
変更を保存を選択します。

変更を保存すると、APIがAIゲートウェイに接続し、Amazon QでOAuthアプリケーションを作成します。

成功したことを確認するには、次のようにします:

Amazon CloudWatchコンソールのログで、204ステータスコードを確認します。詳しくは、Amazon CloudWatchとはをご覧ください。
GitLabで、Amazon Q settings have been savedという通知が表示されます。
GitLabの左側のサイドバーで、アプリケーションを選択します。Amazon Q OAuthアプリケーションが表示されます。

管理者が顧客管理キーを使用できるようにする

管理者の場合は、AWS Key Management Service（AWS KMS）のカスタマーマネージドキー（CMK）を使用して顧客データを暗号化できます。

KMSコンソールで設定されたロールにキーポリシーを作成するときに、CMKを使用する権限を付与するようにロールポリシーを更新します。

kms:ViaService条件キーは、指定されたAWSサービスからのリクエストに対するKMSキーの使用を制限します。さらに、特定のサービスからのリクエストの場合にKMSキーの使用を許可しないために使用されます。条件キーを使用すると、CMKを使用してコンテンツを暗号化されたり、復号化したりできるユーザーを制限できます。

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "Sid0",
         "Effect": "Allow",
         "Principal": {
            "AWS": "arn:aws:iam::<awsAccountId>:role/<rolename>"
         },
         "Action": [
            "kms:Decrypt",
            "kms:DescribeKey",
            "kms:Encrypt",
            "kms:GenerateDataKey",
            "kms:GenerateDataKeyWithoutPlaintext",
            "kms:ReEncryptFrom",
            "kms:ReEncryptTo"
         ],
         "Resource": "*",
         "Condition": {
            "StringEquals": {
                "kms:ViaService": [
                    "q.<region>.amazonaws.com"
                ]
            }
        }
      }
   ]
}

詳しくは、AWS KMS開発者ガイドのkms:ViaServiceをご覧ください。

GitLab Duo with Amazon Qをオフにする

インスタンス、グループ、またはプロジェクトのGitLab Duo with Amazon Qをオフにすることができます。

インスタンスに対してオフにする

前提要件:

管理者である必要があります。

インスタンスのGitLab Duo with Amazon Qをオフにするには、次のようにします:

GitLabにサインインします。
左側のサイドバーの下部で、管理者を選択します。
設定 > 一般を選択します。
GitLab Duo with Amazon Qを展開します。
設定の表示を選択します。
常にオフを選択します。
変更を保存を選択します。

グループに対してオフにする

前提要件:

グループのオーナーロールが必要です。

グループのGitLab Duo with Amazon Qをオフにするには、次のようにします:

左側のサイドバーで、検索または移動先を選択して、グループを見つけます。
設定 > 一般を選択します。
Amazon Qを展開します。
次のオプションを選択します:
- グループに対してオフに設定しても、他のグループやプロジェクトでオンにできるようにするには、デフォルトで無効にするを選択します。
- グループに対してオフにし、他のグループやプロジェクトでオンにできないようにするには、常にオフを選択します。
変更を保存を選択します。

プロジェクトに対してオフにする

前提要件:

プロジェクトのオーナーロールを持っている必要があります。

プロジェクトのGitLab Duo with Amazon Qをオフにするには、次のようにします:

左側のサイドバーで、検索または移動先を選択して、グループを見つけます。
設定 > 一般を選択します。
可視性、プロジェクトの機能、権限を展開します。
Amazon Qで、トグルをオフにします。
変更を保存を選択します。

トラブルシューティング

GitLabをAmazon Qに接続する際に問題が発生した場合は、GitLabインストールがすべての前提条件を満たしていることを確認してください。

次の問題が発生する可能性もあります。

GitLabインスタンスUUIDの不一致

Amazon Qの接続を解除すると、GitLab instance UUID mismatchエラーが発生する可能性があります。通常、この問題は次の場合に発生します:

GitLabインスタンスがバックアップから復元されました。
GitLabインスタンスが新しいインフラストラクチャに移行されました。
GitLabインスタンスのUUIDが他の理由で変更されました。

不一致のUUIDが根本原因であることを確認するには、次の検証手順に進みます。

検証

GitLabがホストされているEC2インスタンスにサインインします。
Railsコンソールにアクセスします。
現在のUUIDを取得するGitlab::CurrentSettings.current_application_settings.uuid

JWTトークンを取得します:

token = CloudConnector::Tokens.get(unit_primitive: :agent_quick_actions, resource: :instance)
JWT.decode(token, false, nil)

手順3のsubフィールドと手順4のgitlab_instance_uuidの間にUUIDの不一致が存在する場合、問題は明らかです。

この問題を解決するには、次の手順を実行します。

すべてのアクティブなライセンスを削除します。
すべてのサブスクリプションアドオンの購入を削除します:
Railsコンソールを開き、以下を実行します:
```
GitlabSubscriptions::AddOnPurchase.all.destroy_all
```
インスタンスのUUIDリセットを実行します。Railsコンソールで、以下を実行します:
```
ApplicationSetting.update!(uuid: SecureRandom.uuid)
```
アクティブなライセンスを適用します。
1分ほど待ってから、ライセンスを同期します。このアクションにより、Cloud Connectorトークンが強制的に再生成されます。（この手順を実行しないと、ヘッダーの不一致が発生します。）
新しいUUIDでIdPとIAMロールを更新します。
次のステップを選択します:
- 新しいUUIDで既存のIdPとIAMロールを更新し、GitLab Duo with Amazon Qの使用を続行して、既存のセットアップを引き続き使用します。
- オフボード:
  1. GitLab Duo with Amazon Qからオフボードします。
  2. 必要に応じて、新しい接続を設定します。

完了すると、UUIDの不一致の問題が解決され、GitLab Duo with Amazon Qが新しい設定で正しく機能するはずです。