制限事項・FAQ

制限事項

Qmonus Value Streamにおける制限事項は、以下のとおりです。

• ユーザに割り当てられる権限は、閲覧者権限（閲覧のみ可） と管理者権限（全操作が可能）の2種類がありますが、各機能に対して詳細な権限設定ができません。そのため、管理者権限を設定する範囲にはご注意ください。権限の詳細は 機能・権限のページを参照してください。

  • 例: 閲覧者権限を割り当てられている人に対して、PromotionやApproval Requestへの承認の実行権限だけを付与する等

• 監査ログ（いつ、誰がAssemblyLineを動かした等）は取得できません。そのため、管理者権限を設定する範囲にはご注意ください。

• 2回目以降のAssemblyLineによるDeploy Task実行時に、以下のようなエラーが表示されますが、システム側の都合によるもので、なんら動作に影響はありません。

  • error: stack '[Project名]-[Application名]-[Deployment名]-xxxx' already exists

• 現在、GUIにおけるPipeline/Taskの登録機能は、コンパイルにかかる時間が15秒以内の場合のみ対応しております。

  • それ以上かかる場合に関しては、CLIにて登録作業(手順)を実施してください。

• 現在、Application RepositoryとCloud Native Adapterの設定状況により、特定のコンパイル処理が失敗します。下記の失敗する設定状況に該当する場合、Cloud Native AdapterをCLIツール qvsctl でダウンロードし、自身のリポジトリにCommitした上でご利用ください。(参考：qvsctl adapter get)

  • 失敗する処理
    • GUIのCompile and Apply Pipeline/Taskページにおけるパイプラインのコンパイル (qvsctl pipeline compile相当)
    • AssemblyLineのInfrastructure adapterのコンパイル Task (qvsctl manifest compile相当)
  • 失敗する設定状況
    • ApplicationとApplicationが使用するCloud Native Adapterで別のリポジトリサービスを利用している場合
      • e.g. GitLabにホスティングしているApplicationのQVS ConfigにGithub上でホスティングされているAdapterを指定している
    • ApplicationとApplicationが使用するCloud Native AdapterでリポジトリURLの記述スタイルが異なる場合
      • e.g. Application RepositoryはHTTPS形式でURLを登録しているが、ApplicationのQVS ConfigにはSSH形式のURLが記載されている
    • Application RepositoryのVisibilityはPublicであるが、Applicationが使用するCloud Native AdapterはPrivateリポジトリ上にホスティングされている場合

• AssemblyLineの実行ログは、一つのTaskにつき最大で1万行まで表示できます。1万行よりも多くのログを取得したい場合は、Report Logsボタンを押下してログをダウンロードしてください。Report Logsによるダウンロードの場合は、一つのTaskにつき最大で5万行まで取得できます。

  • 5万行よりも多くのログを取得したい場合は、qvsctlを用いてログを見る方法をお試しください:

    qvsctl pipeline -p <Project Name> logs <Pod Name> [-c <Step Name>|--all-containers]

  • AssemblyLineの実行ログ画面におけるPod Name および Step Nameの確認の仕方

• AssemblyLineの実行ログの表示やReport Logsによるログのダウンロードに時間がかかる場合、以下のエラーが出ることがあります。

  • AssemblyLineの実行ログの表示の場合：Failed to fetch logs.
  • Report Logsによるログのダウンロードの場合：Request failed with status code 500
  • 上記のエラーが出た場合、qvsctlを用いてログを見る方法をお試しください:

    qvsctl pipeline -p <Project Name> logs <Pod Name> [-c <Step Name>|--all-containers]

FAQ

よくある質問とその回答は、以下のとおりです。

Q1：masterまたはmainブランチではなく、別のリリース用ブランチ等のコード変更を起点として、AssemblyLineを実行できますか。

A1：任意のブランチを指定してWebhookの設定を登録をすることで、該当するブランチのコード変更を起点としてAssemblyLineを実行できます。ただし、常にリリース可能な状態を保つために、master・main等のベースブランチに対してAssemblyLineを実行して試験し続けることを推奨します。

Q2：すでに利用しているKubernetesのManifestをQmonus Value Streamで活用できますか。

A2：可能です。Manifestを配置するパスの指定などはあるものの、Qmonus Value Streamが提供するデプロイ用のモジュールタスクを用いることで、ご利用いただいているManifestをそのままQmonus Value Streamからデプロイできます。 一方で、Manifestによって設定されるリソースが既にデプロイ先の環境にて作成済の場合、リソースの競合が発生してデプロイに失敗します。このため、デプロイ先の環境に作成済のリソースを消してから、Qmonus Value Streamよりデプロイするようにしてください。 デプロイ済のリソースを消すことがどうしても難しい場合は、Qmonus Value Streamのサポートメンバへお問い合わせください。

Q3：Taskのコンテナ起動に失敗した結果、AssemblyLineRunがRunningのまま止まってしまいました。

A3：Taskのタイムアウト時間を経過するとTaskRunのStatusがFailedになり、それと連動してAssemblyLineRunもFailedになりますので、タイムアウトになるまでお待ち下さい。Taskのタイムアウト時間は、1時間に設定されています。 なお、「Taskのイメージプル失敗」「Secretのマウント失敗」の2つはTaskのコンテナ起動に失敗する頻出ケースですので、イメージ名やsecretの定義を事前に確認することをお薦めします。

Q4：Approval Requestがタイムアウトしてしまいました。

A4：タイムアウトしてしまった場合は、AssemblyLineRunをRetryした上で、再度発行されるApproval Requestに対して承認行為を実施してください。

Q5：過去に実行したAssemblyLineRunのRetryができません。

A5：AssemblyLineRunのRetry機能は、初回実行から30日間に限り実行可能です。30日を経過したAssemblyLineRunは、実行結果の確認のみが可能です。

Q6：AssemblyLineRun/PipelineRun/TaskRunのイベントログが閲覧できません。

A6：AssemblyLineRun/PipelineRun/TaskRunのイベントログは、イベント発行時から1時間に限り確認可能です。

Q7：AssemblyLineRunのGraceful Cancelを実行したのに、PipelineRunが止まりません。

A7：AssemblyLineRunのGraceful Cancelは、走行中のPipelineRunを止めることはできません。次に控えているAssemblyLine Stageで定義されたPipelineRunを実行しないようにすることだけが可能です。

Q8：AssemblyLineRunがFatalErrorとなり、Retryを実行できなくなりました。

A8：AssemblyLineから実行されるTaskにおいて、Task Resultの定義があるにもかかわらずTask内でResultに値を設定することをしていない場合、AssemblyLineRunはFatalError（実行継続が不能な状態）になります。FatalErrorの場合、Pipeline/Taskのマニフェストの不備によりRetryできませんので、Pipeline/Taskのマニフェストを修正した上で新しくAssemblyLineを実行してください。

Q9：TaskやPipelineのManifestを修正してAssemblyLineをRetryしましたが、変更内容が反映されていません。

A9：AssemblyLineRunは、初回実行時のTaskやPipelineのManifestを保持しており、Retryの際も初回実行時と同じManifestを使用します。このため、TaskやPipelineのManifestを修正した場合は、新しくAssemblyLineを実行してください。

Q10：AssemblyLineのRetry時に再開する箇所を指定できますか。

A10：失敗したTaskの先頭からの再実行のみをサポートしています。失敗したPipelineの先頭や、その次のAssemblyLine StageのPipelineの先頭から、など、失敗したTask以外の箇所から再実行できません。

Q11：AssemblyLineが失敗した場合に、ロールバックは可能ですか。

A11：AssemblyLineのロールバック機能は提供しておりません。ロールバックを行うためには、一般的なデータベースのロールバックだけでなく、Kubernetes Manifest上のconfigMap等の設定ファイル・機密情報の設定値・その他の外部副作用の全てをロールバック可能にする作り込みが必要であり、ステートマシンが複雑化して定形パイプラインで対応することが困難になります。このことから、宣言的にリリースの状態を管理し、前回のリビジョンを指定して再度Deployを行うことで、ロールバックを行うことなく以前の状態を復元することを推奨しています。

Q12：全てのパイプラインを宣言的に定義し、常に再実行可能なように作成するのが難しいのですが、何かベストプラクティスはありますか？

A12：宣言的にリリースの状態を管理するためには、AssemblyLineを再実行可能にする必要があり、PipelineのFinally機能 を使って、再実行可能な状態に遷移させるためのTaskを実行できます。ただし、このFinally機能はアルファ提供の機能であり、AssemblyLineの動作が不安定になる恐れがありますので、導入を検討されたい場合はQmonus Value Streamのサポートメンバへお問い合わせください。 また、PipelineのFinallyが実行された場合、AssemblyLineのRetryは実行しないでください。Retryを行うと前回失敗したTaskから再実行されますが、Retryの開始点以前の既に完了しているTaskのリリース状態がFinally処理により変わってしまっているため、Retryの開始点以降の処理が正しく実行されることが保証されなくなります。

Q13：推奨のブラウザ・OSがあれば、教えてください

A13：推奨のブラウザは、Google Chrome・Mozilla Firefox になります。また、推奨のOSは、Mac OS・Microsoft Windows (Windows Subsystem for Linux)になります。qvsctlなどのバイナリをご利用の場合、Windows(WSL)の方はLinuxのバイナリをご利用ください。

Q14：Taskが利用できるvCPUおよびメモリ量に制限がありますか？

A14：Project毎に同時に利用できるvCPUとメモリのリソース量に上限を設けています。Resource Quotaの機能で実現されており、上限値はCPU：7.5vCPU、メモリ：30GBです。 実行されるTask内のStepのlimitsの合計値が、プロジェクトのリソース量上限を超える場合、Taskの実行に必要なリソース量が解放されるまで、Taskの実行が待たされます。実行可能になると、そのまま継続してTaskが実行されます。また、上限に抵触した場合、TaskRunのEventにてexceeded quota と記録されます。

Q15：Task内のStepへのlimitsの設定は必須ですか？

A15：Resource Quotaの機能上、全てのTask内のStepには、limitsを設定する必要があります。ただし、Limit Rangeの機能でデフォルトのlimitsの値を設定してるため、全てにおいて明示的に指定する必要はありません。デフォルト値は、Task内のStep毎にCPU：0.25vCPU、メモリ：250MBです。 ユーザのユースケースによって必要なvCPUやメモリ量には違いがありますので、必要に応じてCloud Native Adapterにて、Task内のStepのlimitsを変更してください。

Q16：Task内のStepへのrequestsの設定は必須ですか？

A16：Resource Quotaの機能上、全てのTask内のStepには、requestsを設定する必要があります。Limit Rangeの機能でデフォルトのrequestsの値をlimitsと同じ値にて設定していますが、これはTektonの仕様により多くの場合自動的に小さい値に変更されます。よって多くのCPUやメモリ割り当てが必要な場合には、必要に応じてTask内のStepに明示的に指定してください。

Q17：Task内のStepへのlimits.cpuを指定したところ実行時間が長くなりました。

A17：limits.cpuが設定されると実行時間が長くなる場合があります。これはリソース制限の仕様によりCPUに待ち時間が発生する場合があるためです。TaskのStepに明示的に limits.cpuを明示的に指定しても、設定済みのLimit Rangeにより暗黙的にlimits.cpuを指定された場合においても同様に発生する場合があります。また、limits.cpuの量を適切に増やすことでこの問題を緩和できる場合があります。

Q18：Webhookがうまく動きません。

A18：各リポジトリプロバイダのWebhookの実行結果を確認してください。GitHubであればWebhook設定画面のRecent Deliveriesから確認できます。よくあるエラーとして、以下のようなステータスコードとエラーメッセージが表示されることがあります。

• ステータスコード：400、エラーメッセージ：{"detail":[{"loc":["body"],"msg":"value is not a valid dict","type":"type_error.dict"}]}
  • Content-Typeを確認し、application/jsonを選択してください。
• ステータスコード：403、エラーメッセージ：{"detail":"Request verification failed."}
  • Webhookの設定のページを参照してSecretを設定してください。

Q19：AssemblyLineの実行ログに「error: stack names may only contain alphanumeric, hyphens, underscores, or periods」というエラーメッセージが表示されます。

A19：AssemblyLineによるデプロイ時に、以下のようなエラーが発生して失敗する場合があります。

error: stack names may only contain alphanumeric, hyphens, underscores, or periods

このエラーメッセージは以下の場合に表示されます。必要に応じて、環境を修正してください。

• Project名、Application名、Deployment名、${deployStateName}に英数字、ハイフン、アンダースコア、ピリオド以外の文字列が含まれている場合。
• [Project名]-[Application名]-[Deployment名]-${deployStateName}が100文字を超過している場合。

ここで、${deployStateName}はDeploy Taskで使用される内部パラメータで、Qmonus Value StreamのInput Parametersで確認してユーザ側で変更できますが、内部管理で使用しているものであるため、デフォルト値から修正しないことを推奨します。

Q20：AssemblyLineの実行ログに「the Kubernetes API server reported that "${namespace}/${name}" failed to fully initialize or become live: '${name}' timed out waiting to be Ready」というエラーメッセージが表示されます。

A20：AssemblyLine実行時にDeployタスクが失敗し、以下のログが出力された場合、対象のKubernetesリソースの更新が正しく処理できていない可能性があります。

error: 2 errors occurred:
  * the Kubernetes API server reported that "${namespace}/${name}" failed to fully initialize or become live: '${name}' timed out waiting to be Ready
  * Attempted to roll forward to new ReplicaSet, but minimum number of Pods did not become live

この時、以下の2点について確認ください。

1. エラー表示された ${namespace}/${name} がDeploymentリソースであること
2. 対象のDeploymentリソースがREADY状態となっていること

• デプロイ先のクラスタに対し、kubectl -n ${namespace} get deploymentコマンドを実行することで確認できます。
• ここで、対象のDeploymentリソースについて、DESIRED数 = CURRENT数 = READY数となっている場合、READY状態です。それ以外の場合は、本件に該当しません。

上記、1, 2の両方に該当する場合、利用するOfficial Cloud Native Adapterのバージョンに応じて以下の手順を実行ください。

v0.9.1 以前の場合

1. 以下のコマンドにより対象のDeploymentリソースからlast-applied-configuration annotationを削除する。

kubectl -n ${namespace} patch deployment ${name} --type=json -p='[{"op": "remove", "path": "/metadata/annotations/kubectl.kubernetes.io~1last-applied-configuration"}]'

• 作業によるコンテナ／サービスへの影響はありません。
• ここで、${namespace}は対象のKubernetes Namespace、${name}は対象のKubernetes Deploymentリソースの名前を指定ください。

2. Qmonus Value Streamコンソールから、失敗したAssemblyLineをRetryする。

v0.10.0 以降の場合

1. Qmonus Value Streamコンソールから、失敗したAssemblyLineをRetryする。

Q21：AssemblyLineの実行ログに「fatal: detected dubious ownership in repository at '<リポジトリのパス>'」というエラーメッセージが表示されます。

A21：AssemblyLine実行時に git コマンドを実行するタスクで以下のようなログが出力されて失敗する場合があります。

fatal: detected dubious ownership in repository at '/workspace/qvs-workshop-app'
To add an exception for this directory, call:

 git config --global --add safe.directory /workspace/qvs-workshop-app

上記はコマンド実行ユーザとリポジトリパスのOwnerが一致しないことで発生しているエラーです。

暫定対処

ご利用のTekton TaskでOwnerのチェックを実施しないgitのversionを指定ください。具体的には、docker:git imageを利用している方は、docker:20.10.14-git を指定することで本問題を回避できます。 この修正によるセキュリティリスクはありません。

以下、TaskのYAMLを直接修正する際のサンプルを示します。手元のYAMLファイルを修正した場合、 qvsctl pipeline apply コマンドでQmonus Value Streamに適用ください。

 steps:
   - name: git-pull
-    image: docker:git
+    image: docker:20.10.14-git
     args:
       - clone
       - https://$(GIT_TOKEN)@$(params.gitRepositoryManagerFQDN)/$(params.gitOrganization)/$(params.gitRepository).git
@@ -13,7 +13,7 @@
             key: token
             name: github-secrets
   - name: git-checkout
-    image: docker:git
+    image: docker:20.10.14-git
     args:
       - checkout
       - $(params.gitRevision)

本格対処

本問題は、Tekton Task中の workingDir の利用方法（すなわちTaskの実装方法）に起因しており、Qmonus Value Streamが提供している Official Cloud Native Adapter を利用する限りは問題が起きません。

本格対処として、Official Cloud Native Adapterへの移行を検討ください。または、Official Cloud Native Adapterを参考に、CI/CD Adapterの実装・修正を検討ください。 移行・実装方法については、別途ご案内いたします。

Q22：AssemblyLineの実行ログに 「Original Error: autorest/azure: Service returned an error. Status=400 Code="InvalidSubscriptionId" Message="The provided subscription identifier '${SubscriptionId}' is malformed or invalid."」というメッセージが表示されます。

A22：AssemblyLine実行時にAzureを利用するタスクが失敗し、以下のログが出力された場合AzureのサブスクリプションIDが正しくない可能性があります。

Original Error: populating Resource Provider cache: listing Resource Providers: loading the initial page: providers.ProvidersClient#List: Failure responding to request: StatusCode=400 -- Original Error: autorest/azure: Service returned an error. Status=400 Code="InvalidSubscriptionId" Message="The provided subscription identifier '${SubscriptionId}' is malformed or invalid."

この時、EnvironmentのProvisioning TargetでSubscription IDを確認してください。

• 利用するAzureのサブスクリプションIDが設定されていること
• サブスクリプションIDにスペースなど、余分な文字が含まれていないこと

Q23：Repository登録時に「Invalid git_clone_url ${Git Clone URL} with protocol https」「Invalid git_clone_url ${Git Clone URL} with protocol ssh」というメッセージが表示されます。

A23：リポジトリパスが正しくない可能性があります。Git Clone URLについて以下のことを確認してください。

• 末尾が .git になっていること
• 末尾に / (スラッシュ) など、余分な文字が入っていないこと

Q24：Repository登録時に「Failed to Validate GitToken」というメッセージが表示されます。

A24：Git Tokenが正しくない可能性があります。Git Tokenについて以下のことを確認してください。

• 有効期限が切れていないこと
• 改行など、余分な文字が入っていないこと

Git Token が不正、未入力でも再度CREATEボタンをクリックすることでRepository登録は可能です。

Q25：All ResourcesまたはApplication登録画面において、Deployment登録時に「Failed to validate kubeconfig.」というメッセージが表示されます。

A25: Kubeconfigが正しくない可能性があります。kubeconfigについて以下のことを確認してください。

• 利用するクラスタのkubeconfigを指定していること
• 末尾に改行など、余分な文字が入っていないこと

kubeconfig が不正の場合でも再度CREATEボタンをクリックすることでDeployment登録は可能です。

Q26：All ResourcesまたはApplication登録画面において、Deploymentの登録時に「Application ${Application Name} Already Exists」というメッセージが表示されます。

A26：すでに同じ名前のApplicationが登録されています。Project内には同名のApplicationを作成できません。Application作成画面に戻りApplicationの名前を変更してください。

Q27：Applicationが削除できません。

A27：Applicationを削除するには削除対象のApplication配下のDeploymentを先に削除しておく必要があります。Deploymentを削除してから再度Application削除を実施してください。

Q28：All ResourcesのAssemblyLine登録、またはApply and Compile Pipeline/TaskでのPipeline、Taskのコンパイル時に「the specified revision ${Git Revision} does not exist in the ${Repository Path} repository. please correct the git revision」というメッセージが表示されます。

A28：リポジトリに該当の Git Revisionが存在しない可能性があります。Git RevisionにはRepositoryのブランチ名、またはコミットハッシュを指定してください。

Q29：All ResourcesでのAssemblyLine登録時、またはApply and Compile Pipeline/TaskでのPipeline、Taskのコンパイル時に「Failed to load QVS Config. Please check the qvsconfig path ${Path to QVS Config} for ${Application Name}.」というメッセージが表示されます。

A29：リポジトリにコミットしたQVS Configのパスが正しくない可能性があります。Path to QVS Configについて以下のことを確認してください。

• 該当のリポジトリにQVS Configファイルがコミットされていること
• Path to QVS Config とリポジトリのQVS Configの名前が同じであること

Q30：All ResourcesでのAssemblyLine登録時に「validation failed: Invalid resource name: length must be no more than 63 characters: metadata.name」というメッセージが表示されます。

A30：AssemblyLineの登録前にPipeline、Taskのコンパイルを行っています。その際 [Application名]-[Pipeline名] [Application名]-[Task名] が63文字を超過するとエラーとなります。Pipeline名、Task名は固定値で変更できないためApplication名を短いものに変更してください。

Q31：AssemblyLine画面でPipeline Stagesのカードを選択すると「Deployment not found.」というメッセージが表示されます。

A31：該当のDeploymentが登録されていない、もしくは削除されています。Application画面からDeploymentを登録してください。

Q32：Qmonus Value Streamにログインしてもサインイン画面に戻ってしまいます。

A32：ブラウザでサードパーティCookieが許可されていない可能性があります。ブラウザの設定を確認してください。