############## チュートリアル ############## 本チュートリアルについて ================================= 本チュートリアルでは、お客さまにCNAPサービスを利用したコンテナアプリケーションのデプロイ方法をご理解いただくことを目的としています。 CNAPサービスをはじめてご利用いただく際、CNAPの使い方を習得いただくため、まず最初にチュートリアルを実施いただくことを推奨しています。 本チュートリアルは以下の内容を含んでいます。 * Deploy Keyをお客さまのGithubリポジトリに登録する * アプリケーションのマニフェストをGithubリポジトリに保存し、アプリケーションとクラウドリソースをデプロイする * アプリケーションのデプロイ後、DNSレコードが自動登録されていることを確認する * TLSの設定方法について、マネージドTLS証明書と、セルフマネージド証明書を利用する2つの方式を実施する * アプリケーションのマニフェストを登録するGitリポジトリを追加登録する * Kubernetesクラスタに任意のNamespaceを追加作成する * Grafanaダッシュボードを利用する * 本チュートリアルで作成したリソースを削除する 本チュートリアルでは、インターネットからアクセスできるWebサービスを作成します。このサービスはWebアプリケーションとマネージドRDBから構成されます。 .. drawio-figure:: /_static/drawio/CNAP_tutorial_architecture.drawio :page-index: 0 :alt: チュートリアルのアプリケーションアーキテクチャ 対象読者と前提知識 ================== 本チュートリアルの想定する対象読者は以下のとおりです。 * これからCNAPを使う方 * CNAPサービス上で稼働するアプリケーションの設計・開発・運用に関わる方 本チュートリアルを進めるにあたり、必要となる前提知識は以下のとおりです。 * Gitの基本的な仕組みを理解し、Gitコマンドを利用した経験がある * Kubernetesの基本概念を理解し、kubectlコマンドを利用した経験がある * クラウドコンソールを操作し、リソースを作成・確認することができる * ネットワークに関する基本的な用語（TLS、DNSなど）がわかる CNAPでは、本来記述すべきKubernetesやマネージドクラウドサービスのコードを大幅に縮小した、ローコードによりマニフェストを記述可能です。 ただしローコードとはいえ、コードでインフラを記述しデプロイする作業は必要となるため、YAMLの基本的な書き方についての知識があると内容がより理解し易いです。 あらかじめご用意いただくもの ========================================== このチュートリアルを進めるにあたり、以下の情報、およびリソースがお手元にあることをご確認ください。 * CNAPでご提供したKubernetesクラスタ * お客さまリポジトリ用Deploy Key お客さまリポジトリ用Deploy Keyは、あらかじめ弊社から提供している英数字と記号から構成される文字列です。サンプルは以下の通りです。 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAMIX+oD5Imr1huwc7qerYcZsTZXNF3Soa4wp05m8sSF msp12345678 Deploykey CodeCommit などをご使用の場合には、ssh-rsa で始まる長い文字列になります。 また、以下のCLIツールが利用可能であることをご確認ください。詳細については、各CLIツールの開発元のドキュメントをご確認ください。 * git * kubectl 参考： `Azureにおけるkubectl設定方法 `_ `Google Cloudにおけるkubectl設定方法 `_ `AWSにおけるkubectl設定方法 `_ 事前準備：Deploy Keyの登録 ====================================== CNAPでは、お客さまのアプリケーションの一貫性と信頼性を保つため、GitOpsを採用しています。 お客さまにアプリケーションのマニフェストを作成いただき、Gitリポジトリにpushしていただくと、CNAPのシステムが自動で変更を検知し、各種リソースとアプリケーションをデプロイします。 このため、まず、GitリポジトリとCNAPを連携させるため、お客さまのGitリポジトリにDeploy Keyの登録を行う必要があります。 以下では、Github、AWS CodeCommitでの設定方法について説明します。 それ以外のGitリポジトリをご利用の場合には、サポートにご相談ください。 Github ------ GithubリポジトリにDeploy Keyを登録します。 (1) リポジトリ上部メニューの **settings** をクリックしてください .. image:: /_static/images/github-settings.png (2) 左メニューの **Deploy keys** をクリックし、右上の **Add deploy key** をクリックしてください .. image:: /_static/images/github-add-deploykey.png (3) 任意の **タイトル** を設定し、 **Key** 欄にDeploy Keyを入力してください。弊社から提供した文字列の一部ではなく、先頭から末尾まで全て入力してください。 :doc:`コンテナイメージの自動更新 <../managed/basic-deployment.html#deployment-image-update-automation>` の機能を利用する場合は **Allow write access** チェックボックスのチェックが必要です。 .. image:: /_static/images/github-input-deploykey.png (4) 緑色の **Add key** ボタンをクリックしてください .. image:: /_static/images/github-push-addkey.png 以上でDeploy Keyがお客さまのリポジトリに登録されました。 AWS CodeCommit -------------- CNAPからAWS CodeCommitリポジトリに接続するためにDeploy Keyを登録します。 (1) CodeCommit アクセスに使用するIAMユーザーを作成します。 IAMサービスの「ユーザー」メニューで、IAMユーザーを作成します。 (2) 作成したIAM ユーザーに、 ``AWSCodeCommitPowerUser`` ポリシーをアタッチします。 作成したIAMユーザーを開き、 「アクセス権限タブ」で「アクセス権限の追加」ボタンを押します。 既存のポリシーから ``AWSCodeCommitPowerUser`` を選択します。 .. image:: /_static/images/codecommit-policy.png (3) 作成したIAMユーザーにSSHパブリックキーを設定します。 作成したIAMユーザーを開き、「認証情報」タブで「AWS CodeCommit の SSH キー」の項目の「SSHパブリックキーをアップロード」ボタンを押します。 ウィンドウが開いたらDeploy Keyを貼り付けて「SSHパブリックキーをアップロード」ボタンを押します。 (4) SSH キー IDを取得します。 「認証情報」タブで「AWS CodeCommit の SSH キー」の項目の「SSH キー ID」を取得します。 取得した「SSH キー ID」を、法人テクニカルサポートWebにおいて、CNAP申し込み時のケースでご連絡ください。 .. image:: /_static/images/codecommit-ssh-key-id.png クラウドコンソールへのアクセス ===================================== クラウドコンソールへのアクセスに特別な操作が必要なものについて説明します。 AWS --- CNAP申し込み時に作成したIAMユーザで AWS Management Console にサインインしてクラウドリソースを参照・操作するためには、 ``cnap_customer`` ロールにロール切り替えを行う必要があります。 ロール切り替えは下記の手順で行います。 IAMユーザで AWS Management Console にサインインし、右上のナビゲーションバーのユーザー名を選択します。 （通常は username@account_ID_number_or_alias のように表示されます。） [アカウント ID] が表示されているので、コピーしておきます。 [ロールの切り替え] を選択します。このオプションを選択するのが初めての場合、詳細な情報がページに表示されます。情報を読んだ後、[ロールの切り替え] を選択します。 [ロールの切り替え] ページで、[アカウント] にコピーしておいたアカウント IDを入力し、[ロール]に ``cnap_customer`` を入力しロール切り替えを行います。 .. _DeploymentTut: アプリケーションの構築 =========================== これから、サンプルのアプリケーションを構築していきます。 本チュートリアルで作成するアプリケーションは、`kanboard `_ というwebアプリケーションと、kanboardのデータを保存するマネージドRDBサービスから構成されています。 CNAPでは、ユーザーが kubernetes およびクラウドサービスにインフラ環境を構築するためのパッケージを提供します。 サンプルアプリケーションでは、webアプリケーション部分を ``basic-deployment`` パッケージ、マネージRDBサービスを ``RDB`` パッケージでデプロイします。 CNAPで各種パッケージをデプロイするためには、 ``Application`` カスタムリソースのマニフェストでデプロイしたいパッケージやそのバージョン、設定を定義します。 .. drawio-figure:: /_static/drawio/CNAP_tutorial_architecture.drawio :page-index: 1 :alt: チュートリアルで作成するアプリケーションとCNAPパッケージ アプリケーションの構築は、GitOpsに基づいて実施します。 GitOpsではアプリケーションの信頼性と一貫性を保つため、Gitリポジトリを信頼できる唯一の情報源として扱います。 アプリケーションとインフラの望ましい状態を宣言的に記述したマニフェストを保存し、記述された通りにアプリケーションとインフラを維持します。 CNAPでは、Gitリポジトリにお客さまのアプリケーションのマニフェストを登録いただくことで、CNAPのシステムが自動的にマニフェストに基づきクラウドリソースとアプリケーションをデプロイします。 RDBサービスの構築 ----------------------- (1) マネージドRDBサービスのマニフェストを作成します。 まずは ``RDB`` パッケージを使用してマネージドRDBサービスを構成するマニフェストを作成します。マネージドRDBサービスをデプロイするクラウドベンダーに合わせてマニフェストをコピーし、お客さまのローカルgitリポジトリに保存してください。 YAML形式であるマニフェストはインデントに意味を持つため、各行正しい位置になるようご注意ください。 保存した後、各マニフェストで使用するパッケージのバージョンを編集します。spec.chart.version: と記載されている箇所を編集し、最新バージョンを入力してください。各パッケージの最新バージョンは、:doc:`/usermanual/4-reference_for_user` より、使用されるパッケージのリファレンスのChange Logを確認してください。 パッチを自動的に適用させる場合には、バージョンの末尾の番号（パッチバージョン）は x と設定してください。 パッケージの最新バージョンが 1.0.3 の場合、パッチバージョンを自動適用させるためには「1.0.x」と設定します。 パッケージのパッチバージョンアップでは、お客さまの操作に影響が無い範囲でのバグ修正や小規模な改善が行われるため、自動適用することを推奨します。 入力例: パッケージ「RDB」のバージョン 1.0.x を指定する場合 .. code-block:: yaml # ~~~省略~~~ spec: chart: name: rdb version: 1.0.x # ~~~省略~~~ **Azure** .. literalinclude:: /usermanual/example/1.5.1_Azure/example_pgsql.yaml :language: yaml **Google Cloud** .. literalinclude:: /usermanual/example/1.5.2_GC/example_mysql.yaml :language: yaml **AWS** .. literalinclude:: /usermanual/example/1.5.3_AWS/example_mysql.yaml :language: yaml (:doc:`参考:HELM ユーザー用パッケージ RDB <../managed/rdb>`) このマニフェストでは、お客さまのアプリケーションで使用するRDBサーバの構成について記述しています。CNAPはこのマニフェストに従い、お客さまの契約されたクラウドサービスのマネージドRDBサービスを利用して、RDBサーバを構築します。 Azure環境にマニフェストをデプロイする場合は、 ``.spec.settings.instance.name`` の ```` を、お客さまがCNAP開通時に弊社のヒアリングシートに記載したMSP契約番号に置き換えてください。この項目はDBのホスト名に使われるので全Azureアカウントで一意である必要があります。 またsqlserverでは、 ``.spec.settings.instance.owner.azure.resourceGroup.name`` を、お客さまのデプロイ先となるリソースグループ名に置き換えてください。 AWS環境にマニフェストをデプロイする場合は、 ``.spec.settings.network.aws.subnets`` の ```` および ```` を、お客さまがRDBインスタンスをデプロイするサブネットのIDに置き換えてください。 また ``.spec.settings.network.aws.securityGroups`` の ```` を、お客さまがデプロイするRDBインスタンスに設定するセキュリティグループのIDに置き換えてください。 (2) お客さまがご利用のクラウドサービスが提供するシークレットストアサービスに、DBの認証情報を登録します。 Azureの場合は初期開通時に作成されている ``cnap-`` のキーコンテナに、 ``.spec.settings.users[0].secret.key`` に指定した値をキー名として、任意のDBアクセス用パスワードを保存してください。 Google Cloudの場合はSecretManagerに ``kanboard`` という名前のシークレットを作成し、任意のDBアクセス用パスワードを保存してください。 AWSの場合はSecretManagerのシークレットのタイプからその他のシークレットのタイプを選択してDBの認証情報を登録します。 ``.spec.settings.users[0].secret.key`` に指定した値がSecrets Managerのシークレット名、 ``.spec.settings.users[0].secret.property`` に指定した値がシークレット内のキー名に対応します。 前述のマニフェストの場合は、 ``rdb-admin`` シークレットの ``password`` というキーに対応する値として任意のDBアクセス用パスワードを保存してください。 .. note:: 一般的に、データベースサーバに接続する際はパスワードなどの機密情報を使用する必要があります。CNAPでは、お客さまの機密情報を各クラウドサービスが提供するシークレットストアサービスに保管します。 シークレットストアサービスからパスワードなどの機密情報を取得し、Podに渡す流れは以下の通りです。 .. drawio-figure:: /_static/drawio/CNAP_tutorial_architecture.drawio :page-index: 2 :alt: ESOのアーキテクチャ Secret Storeリソースによりシークレットストアサービスへ認証が行われ、取得した資格情報をExternal Secretが利用してパスワードを取得・Secretリソースに格納します。 SecretリソースをPodにマウントすることでPodからRDBにアクセス可能になります。 なお、External SecretリソースはRDBパッケージもしくはbasic-deploymentパッケージから作成され、Secret StoreはVaultパッケージから作成されます。 CNAPではデフォルトのSecret Store（name: default）が作成されており、本チュートリアルではデフォルトのSecret Storeを利用するためVaultパッケージは利用せずにパスワードを取得します。 シークレットストアサービスのアクセス制限をしたいといった理由でデフォルトのSecret Storeを利用したくない場合は、Vaultパッケージを使って別途Secret Storeを作成してください。 (3) アプリケーションのマニフェストをコミットし、リモートのGitリポジトリにpushしてください。 .. code-block:: console git add . && git commit -m "add rdb manifest" git push (4) マニフェストからリソースが正常に作成されたことを確認します。 ``Application`` カスタムリソースが適用されたことを確認します。以下のコマンドを入力し、 ``mysql-application`` もしくは ``postgres-application`` という名前のリソースが存在し、READYのステータスがTrueになっていることを確認してください。 .. code-block:: console kubectl get helmrelease -n staging READYのステータスがFalseとなっている場合デプロイに失敗しているため、インデントが間違ってないか、chartのversionが正しいかなど、YAMLの記載内容を確認してください。 デプロイに成功したらマネージドRDBが作成されたことを確認します。ご利用のクラウドベンダーのポータル画面にログインし、マネージドRDBのインスタンスが存在することを確認してください。 AWSの場合は、作成したマネージドRDBのエンドポイントを控えてください。 Azureの場合、RDBはNamespaceと同名のリソースグループ（サンプルでは ``staging``）に作成されます。 別のリソースグループにクラウドリソースを構築したい場合には、RDBマニフェストに ``.spec.settings.instance.owner.azure.resourceGroup.name`` の設定を追加し対象のリソースグループ名を指定します。 また、事前に、 :ref:`Azure リソースグループの追加` を参考に ``UserConfig`` を使用してリソースグループを作成しておく必要があります。 Webアプリケーションの構築 ------------------------------- (1) 次に、basic-deploymentパッケージを使用してWebアプリケーションを構成するマニフェストを作成します。アプリケーションをデプロイするクラウドベンダーに合わせて下記のマニフェストをコピーし、お客さまのローカルのgitリポジトリに保存してください。 **Azure** .. literalinclude:: /usermanual/example/1.5.4_Azure/example_basic_deployment.yaml :language: yaml **Google Cloud** .. literalinclude:: /usermanual/example/1.5.5_GC/example_basic_deployment.yaml :language: yaml **AWS** .. literalinclude:: /usermanual/example/1.5.6_AWS/example_basic_deployment.yaml :language: yaml (:doc:`参考:HELM ユーザー用パッケージ basic-deployment <../managed/basic-deployment>`) このマニフェストでは、 kanboardのdeploymentリソースと、アプリケーションにアクセスするためのDNSレコードが作成されます。 ``.spec.settings.network.domain`` の ```` は、お客さまがCNAP開通時に弊社のヒアリングシートに記載したゾーン名に置き換えてください。例として、example.comをヒアリングシートに記載された場合、初期開通時にあらかじめ ``example.com`` というゾーンがマネージドDNSサービスに登録されています。その中に ``kanboard.example.com`` というAレコードが作成されます。 Azureの場合は ``.spec.settings.env`` 内の ```` を、お客さまがCNAP開通時に弊社のヒアリングシートに記載したMSP契約番号に置き換えてください。 AWSの場合は ``.spec.settings.env`` 内の ```` を、先ほど控えておいたマネージドRDBのエンドポイントに置き換えてください。 また、AzureおよびGoogle Cloudの場合には ``.spec.settings.env[3].valueFrom.secretKeyRef.name`` は ``rdb-user---`` となるので確認してください。 (2) アプリケーションのマニフェストをコミットし、リモートのGitリポジトリにpushしてください。 .. code-block:: console git add . && git commit -m "add application manifest" git push (3) マニフェストからリソースが正常に作成されたことを確認します。 ``Application`` カスタムリソースが適用されたことを確認します。以下のコマンドを入力し、 ``kanboard`` という名前のリソースがあることを確認してください。 .. code-block:: console kubectl get application -n staging アプリケーションの ``Deployment`` リソースが作成されたことを確認します。以下のコマンドを入力し、 ``kanboard-application-basic-deployment`` という名前のリソースが存在し、READYが1/1になっていることを確認してください。 .. code-block:: console kubectl get deployment -n staging マネージドDNSのレコードが作成されたことを確認します。ご利用のクラウドベンダーのポータル画面にログインし、マネージドDNSゾーンとレコードが存在することを確認してください。 (4) 作成されたアプリケーションにブラウザからアクセスし、アプリケーションが利用可能であることを確認します。 ``.spec.settings.network.domain`` で指定したURLにブラウザでアクセスしてください。以下のような画面が表示されれば、アプリケーションのデプロイは成功しています。 .. image:: /_static/images/sample-kanboard.png 補足 kanboardのdeploymentリソースをAzureのMySQLと接続する場合 --------------------------------------------------------------- Azureにおいて ``Application`` カスタムリソース の名前を ``mysql`` と設定した場合には追加の設定が必要です。 AzureのMySQLサーバへ接続する場合、Azureの提供する証明書を用いて接続を暗号化する必要があります。 証明書をインストールし、データベースへの接続時にその証明書を使用するように設定することで、kanboardアプリケーションを立ち上げることが可能です。 ``postgres`` の場合と異なる設定は ``.spec.settings.env[5]`` ``.spec.settings.sharedMounts`` ``.spec.settings.initContainers`` です。 .. literalinclude:: /usermanual/example/1.5.4_Azure/example_basic_deployment_mysql.yaml :language: yaml 補足 カスタムImageの格納先としてContainer Registryを作成する方法 -------------------------------------------------------------------------- カスタムImageを使用する場合、Imageをコンテナレジストリに保管する必要があります。 CNAPでは、Container Registryの作成をサポートしています。 以下はご利用のクラウドベンダーごとの作成例です。 CNAP クラスタからリポジトリへのアクセスは初期状態で許可されているため、アクセス許可設定は不要です。 作成例の acl はコンテナレジストリにユーザがアクセスできるようにするための設定です。 Azure (ACR) ~~~~~~~~~~~~ .. literalinclude:: /usermanual/example/1.5.7_Azure/example_container_registry.yaml :language: yaml Google (Artifact Registry) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: /usermanual/example/1.5.8_Google/example_container_registry.yaml :language: yaml AWS (ECR) ~~~~~~~~~~ .. literalinclude:: /usermanual/example/1.5.9_AWS/example_container_registry.yaml :language: yaml 補足 Applicationカスタムリソースのタイムアウト値の設定について -------------------------------------------------------------- ``Application`` カスタムリソースでは ``.spec.settings.timeout`` にタイムアウトの値を設定することが可能です。 設定する場合は ``10m`` や ``1h`` のように数値と単位を組み合わせた形式で指定してください。 ``Application`` カスタムリソースによって作成されるリソース群は 作成時間がタイムアウト値に設定した値を超えるとエラーとなり作成が中断される場合があります。 そのため、アプリケーションマニフェストなど作成に時間がかからないリソースはタイムアウト値を短めに、RDBマニフェストなど作成に時間がかかるリソースはタイムアウト値を長めに設定することを推奨します。 .. _TlsTut: セルフマネージドTLS証明書の設定方法 ================================================ .. drawio-figure:: /_static/drawio/CNAP_tutorial_architecture.drawio :page-index: 3 :alt: セルフマネージドTLS証明書利用時のアーキテクチャ CNAPでは、https通信に利用するTLS証明書については、以下の２つの方式に対応しています。 * マネージドTLS証明書を利用する方式 * Let's Encrypt で発行した DV 証明書をCNAPが自動的に設定します。 * 証明書の更新は自動で行われます。 * セルフマネージドTLS証明書を利用する方式 * 外部の認証機関が発行した証明書を設定します。 * 証明書の自動更新は行われないため、期限が切れる前に証明書を更新する必要があります。 セルフマネージドTLS証明書を利用する方式では、お客さまにてクラウドベンダーの暗号化キーマネージメントサービスへの登録・更新を実施していただく必要があるため、以下にて設定手順を説明します。 登録方法 -------- ご利用のクラウドベンダーごとに以下の手順で登録作業を行います。 Azure ~~~~~ Azure ポータルからキーコンテナに証明書を格納する場合、改行が崩れて証明書を正しい形式で登録することができません。 そのため CLI 経由で証明書を登録します。 (1) 秘密鍵ファイルの登録 以下のコマンドを実行します。 .. code-block:: console az keyvault secret set --vault-name "cnap-[顧客 Id]" --name "[cluster名]-ingress-key-1" --file "<秘密鍵ファイルのパス> " (2) 証明書ファイルの登録 以下のコマンドを実行します。 .. code-block:: console az keyvault secret set --vault-name "cnap-[顧客 Id]" --name "[cluster名]-ingress-crt-1" --file "<証明書ファイルのパス>" ※ [顧客 Id] とは、 MSP契約番号を小文字にした 「msp1234567」のような文字列になります。MSP契約番号は、MSP開通通知書に記載されてます。 Google Cloud ~~~~~~~~~~~~ クラウドコンソールでの登録 """""""""""""""""""""""""" (1) 秘密鍵ファイルの登録 Portal の ``Secret Manager`` メニューにて ``シークレットを作成`` を選択します。 ``名前`` に ``[cluster名]-ingress-key-1`` を設定し、 ``シークレットの値`` にて 秘密鍵ファイルをアップロードし、 ``シークレットを作成`` をクリックします。 (2) 証明書ファイルの登録 Portal の ``Secret Manager`` メニューにて ``シークレットを作成`` を選択します。 ``名前`` に ``[cluster名]-ingress-crt-1`` を設定し、 ``シークレットの値`` にて 証明書ファイルをアップロードし、 ``シークレットを作成`` をクリックします。 gcloud cli での登録 """"""""""""""""""" (1) 秘密鍵ファイルの登録 以下のコマンドを実行します。 .. code-block:: console gcloud secrets create "[cluster名]-ingress-key-1" --data-file "<秘密鍵ファイルのパス> " (2) 証明書ファイルの登録 以下のコマンドを実行します。 .. code-block:: console gcloud secrets create "[cluster名]-ingress-crt-1" --data-file "<証明書ファイルのパス> " AWS ~~~ マネージドコンソールでの登録 """""""""""""""""""""""""""" * `AWS Secrets Manager に TLS 証明書を保存する`_ aws cli での登録 """""""""""""""" (1) 秘密鍵ファイルの登録 以下のコマンドを実行します。 .. code-block:: console aws secretsmanager create-secret --name [cluster名]-ingress-key-1 --secret-string file://<秘密鍵ファイルのパス> (2) 証明書ファイルの登録 以下のコマンドを実行します。 .. code-block:: console aws secretsmanager create-secret --name [cluster名]-ingress-crt-1 --secret-string file://<証明書ファイルのパス> 更新方法 -------- ご利用のクラウドベンダーごとに以下の手順で更新作業を行います。 Azure ~~~~~ (1) 秘密鍵ファイルの更新 以下のコマンドを実行します。 .. code-block:: console az keyvault secret set --vault-name "cnap-[顧客 Id]" --name "[cluster名]-ingress-key-1" --file "<秘密鍵ファイルのパス> " (2) 証明書ファイルの更新 以下のコマンドを実行します。 .. code-block:: console az keyvault secret set --vault-name "cnap-[顧客 Id]" --name "[cluster名]-ingress-crt-1" --file "<証明書ファイルのパス>" ※ [顧客 Id] とは、 MSP契約番号を小文字にした 「msp1234567」のような文字列になります。MSP契約番号は、MSP開通通知書に記載されてます。 Google Cloud ~~~~~~~~~~~~ (1) 秘密鍵ファイルの更新 Portal の ``Secret Manager`` メニューにて ``[cluster名]-ingress-key-1`` を選択します。 ``新しいバージョン`` を選択し、秘密鍵ファイルをアップロードし、 ``新しいバージョンを追加`` をクリックします。 (2) 証明書ファイルの更新 Portal の ``Secret Manager`` メニューにて ``[cluster名]-ingress-crt-1`` を選択します。 ``新しいバージョン`` を選択し、証明書ファイルをアップロードし、 ``新しいバージョンを追加`` をクリックします。 AWS ~~~ (1) 秘密鍵ファイルの更新 以下のコマンドを実行します。 .. code-block:: console aws secretsmanager put-secret-value --secret-id [cluster名]-ingress-key-1 --secret-binary file://<秘密鍵ファイルのパス> (2) 証明書ファイルの更新 以下のコマンドを実行します。 .. code-block:: console aws secretsmanager put-secret-value --secret-id [cluster名]-ingress-crt-1 --secret-binary file://<証明書ファイルのパス> Gitリポジトリ・Namespace・Azure リソースグループの追加方法 ========================================================== :doc:`/usermanual/5-userconfig` 用マニフェスト ``UserConfig`` の使用方法。 .. _UcGitRepoTut: Gitリポジトリの追加 ------------------------ CNAPでは、アプリケーションのマニフェストを登録するGitリポジトリをお客さま自身で追加することが可能です。 本節末尾の :ref:`マニフェスト例` を参考に ``UserConfig`` カスタムリソースが記載されたマニフェストを作成するか、 すでにCNAPに反映済の ``UserConfig`` カスタムリソースが記載されたマニフェストが存在している場合は当該マニフェストにGitリポジトリの設定を追記してください。 Gitリポジトリの情報は ``UserConfig`` カスタムリソースの ``.spec.repositories`` に記載してください。 作成もしくは設定を追記したマニフェストをCNAPと連携済みのGitリポジトリに登録することで追加のGitリポジトリへCNAPがアクセスするためのDeoploy Key（公開鍵）が発行されます。 なお、作成されたDeploy KeyはKubernetesクラスタ上で以下のコマンドを実行することで取得することができます。 .. code-block:: console kubectl get secret -n flux-system -userconfig--user-repo -o=jsonpath='{.data.identity\.pub}'| base64 --decode 例として、本章末尾の例のようにマニフェストを設定した場合、コマンドは以下となります。 .. code-block:: console sample-repo1 用の Deoploy key を取得する kubectl get secret -n flux-system uc-userconfig-sample1-user-repo -o=jsonpath='{.data.identity\.pub}'| base64 --decode sample-repo2 用の Deoploy key を取得する kubectl get secret -n flux-system uc-userconfig-sample2-user-repo -o=jsonpath='{.data.identity\.pub}'| base64 --decode Windows などbase64コマンドが使えない環境の場合は、以下のようなコマンドでDeploy Keyを取得してください。 .. code-block:: console kubectl get secret -n flux-system -userconfig--user-repo -o=jsonpath='{.data.identity\.pub}' > encoded.txt certutil -decode encoded.txt decoded.txt # decoded.txt に Deploy Key が出力されます 取得したDeploy Keyをお客さまのGitリポジトリに登録することでCNAPとの連携が完了します。 .. _UcNamespaceTut: Namespaceの追加 ------------------------ また、CNAPでは、提供したKubernetesクラスタに任意のNamespaceをお客さま自身で追加することが可能です。 本節末尾の :ref:`マニフェスト例` を参考に ``UserConfig`` カスタムリソースが記載されたマニフェストを作成するか、 すでにCNAPに反映済の ``UserConfig`` カスタムリソースが記載されたマニフェストが存在している場合は当該マニフェストにNamespaceの設定を追記してください。 Namespaceの情報は ``UserConfig`` カスタムリソースの ``.spec.namespaces`` に記載してください。 作成もしくは設定を追記したマニフェストをすでにCNAPと連携済みのGitリポジトリに登録することでKubernetesクラスタ上に追加のNamespaceが作成されます。 Azureでご利用の場合、CNAPは、KubernetesクラスタのNamespaceに対応した同名のリソースグループを作成します。 Namespaceを削除しても、作成されたリソースグループは削除されません（お客さまのクラウドリソースを保護するためです）。 その他、設定可能な値についてはユーザ設定の章をご参照ください。 .. _AddAzureResourceGroup: Azure リソースグループの追加 -------------------------------- CNAPでは、Azure サブスクリプション にKubernetes Namespace に対応した同名のリソースグループを自動的に作成します。 これ以外に任意のリソースグループをお客さま自身で追加することができます。以下では追加方法を示します。 本節末尾の :ref:`マニフェスト例` を参考に ``UserConfig`` カスタムリソースが記載されたマニフェストを作成してください。 Azure リソースグループの情報は ``UserConfig`` カスタムリソースの ``.spec.azure.resourceGroups`` に記載してください。 作成もしくは設定を追記したマニフェストをすでにCNAPと連携済みのGitリポジトリに登録することでリソースグループが作成されます。 その他、設定可能な値についてはユーザ設定の章をご参照ください。 作成したリソースグループにRDBなどのクラウドリソースを作成するには、RDBパッケージなどにおいてリソースグループを指定してください。 指定しない場合には、Application をインストールしたNamespace と同名のリソースグループに作成されます。 .. note:: マニフェストからAzure リソースグループの情報を削除しても、Azureサブスクリプションからリソースグループは削除されません（お客さまのクラウドリソースを保護するためです）。 また、CNAP以外で作成されたリソースグループを扱いたい場合、上記と同様に ``UserConfig`` カスタムリソースでリソースグループを定義してください。 .. _exampleuserconfig: .. literalinclude:: /usermanual/example/userconfig/example_userconfig.yaml :language: yaml .. note:: 1つのKubernetesクラスタにつき1つの ``UserConfig`` カスタムリソースが有効になります。2つ目以降の ``UserConfig`` カスタムリソースの内容はKubernetesクラスタに反映されません。ご注意ください。 .. _GrafanaTut: Grafanaの利用方法 ================= CNAPでは、Grafanaを用いたリソースの使用状況を確認できるダッシュボード機能及びアラート機能を提供しており、クラスタおよびお客さまのコンテナアプリケーションのリソース使用状況を把握することが可能です。 AWS、Azureを利用している場合、Grafanaはクラウドベンダが提供するマネージドサービスで構築されます。 Google Cloudを利用している場合、Grafanaがクラスタ内に構築されます。 ユーザーチュートリアルでは、Grafanaへのアクセス方法と、ダッシュボード・アラートのサンプルについて説明します。 なお、ダッシュボードやアラートの作成方法・機能については、Grafanaの公式ドキュメント `Grafana documentation `_ 等を 各データソースごとのクエリの構成方法については、 Prometheusの公式ドキュメント `QUERYING PROMETHEUS `_ ならびに 各クラウドベンダの監視機能のドキュメントを参照ください。 また、 Grafana ではのバージョンアップにより画面構成が変わることが考えられます。 以下の説明のメニュー名など実際のUIと異なることもありますので、その場合は公式ドキュメントを確認してください。 Grafanaへのアクセス方法 ----------------------- ご利用のGrafanaがクラスタ内に構築されているか、クラウドベンダが提供するマネージドサービスで構築されているかによって、アクセス方法が異なります。 AWS ~~~ AWSを利用している場合、Grafanaは ``Amazon Grafana`` で構築されます。 マネジメントコンソールにアクセスし、 ``Amazon Grafana`` から、作成されているGrafana WorkspaceのURLへアクセスしてください。 ログイン画面が表示されますので、 事前にヒアリングシートの ``Grafana用 IAM Identity Center アカウント`` にて 作成を依頼したユーザーと構築時に連携されたパスワードを利用してログインしてください。 .. warning:: 2023年1月現在、Amazon Grafanaのバグにより、 ``Grafana用 IAM Identity Center アカウント`` を一度削除すると、ユーザーを再作成してもログイン不可となります。 削除したユーザーを再作成したい場合には、管理者権限のある他のユーザーでログインし、Grafanaの管理画面上から該当ユーザーを削除するワークアラウンドを実施してください。 Azure ~~~~~ Azureを利用している場合、Grafanaは ``Azure Managed Grafana`` で構築されます。 CNAP-customerグループに所属しているアカウントを利用して、Azure portalにアクセスし、 リソースグループ ``managed-grafana-rg`` 内に作成されているGrafanaのURLへアクセスしてください。ログインは自動的に実施されます。 Google Cloud ~~~~~~~~~~~~ Google Cloudを利用している場合、Grafanaはクラスタ内に構築されます。 ``monitoring-grafana.<お客さまがCNAP開通時に弊社のヒアリングシートに記載したゾーン名>`` で指定したURLにブラウザでアクセスしてください。 初回ログイン時は、以下のお客様用 admin ユーザーでログインします。 * Username: ``customer_admin`` * Password: ``grafana-default-password`` 初回ログイン後に customer_admin ユーザのパスワードを変更します。 また、customer_admin でログインし、 customer_admin 以外の個別のユーザーを作成し 二回目以降のログインで、作成したユーザーを利用してログインします。 Grafanaダッシュボード --------------------------------- Grafanaではダッシュボード作成して、各種メトリクス・ログを可視化することができます。 本チュートリアルでは、ダッシュボードの新規作成とサンプルダッシュボードのインポートについて説明します。 新規ダッシュボードの作成 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Grafana ではユーザーが自分自身でダッシュボードを作成・カスタマイズして作ることができます。 CNAPでは、以下にてダッシュボードの作成方法についてサンプルを用意しています。 * :doc:`Prometheus を Datasource に設定して、HTTP 5XXエラー率を表示するダッシュボードの作成方法サンプル <./example/grafana-manual/create-dashboard-prometheus-http-metrics>` なお、ダッシュボードの詳細な作成方法、クエリの作成方法等については、Grafana の公式ドキュメントを参照してください。 サンプルダッシュボードのインポート ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Grafana ではユーザーが自分自身で既に用意されているダッシュボードをインポートして利用することができます。 CNAPでは、以下のサンプルダッシュボードを用意しています。 * :doc:`アプリケーションのCPU/メモリ等基本的なメトリクスの表示用のサンプルダッシュボード <./example/grafana-dashboard/sample-dashboard>` * :doc:`アプリケーションのデプロイ状況表示用のサンプルダッシュボード <./example/grafana-dashboard/application-status>` * :doc:`コンテナのログ表示用のサンプルダッシュボード(Google Cloud Logging連携) <./example/grafana-dashboard/google-cloud-logging-container-log>` * :doc:`コンテナのログ表示用のサンプルダッシュボード(Azure Monitor連携) <./example/grafana-dashboard/azure-monitor-container-log>` * :doc:`コンテナのログ表示用のサンプルダッシュボード(Amazon CloudWatch Logs連携) <./example/grafana-dashboard/amazon-cloudwatch-logs-container-log>` * :doc:`クラスタ料金案分サンプルダッシュボード <./example/grafana-dashboard/opencost>` また、CNAPで用意しているサンプルダッシュボードの他に、Grafanaが公式で提供しているサンプルダッシュボードもインポートして利用が可能です。 `Grafanaのダッシュボードページ `_ へアクセスしてダッシュボードを選択し、 ``Download JSON`` からjsonファイルを取得してください。 インポート方法は上記記載のCNAPで提供しているjsonファイルのインポート方法と同様です。 データソースの設定 ~~~~~~~~~~~~~~~~~~~~~~~~~ Grafana ではユーザーが自分自身でダッシュボードのデータ取得元となるデータソースを設定できます。 CNAP では各ベンダごとに以下のデータソースが予め設定済みです。 * Azure * Managed Prometheus、Azure Monitor * Google Cloud * Managed Prometheus、Google Cloud Monitoring、Google Cloud Logging * AWS * Managed Prometheus、Amazon CloudWatch なお、データソースの設定に関しては、データソースごとに認証などの仕組みが異なりますので、 予め設定されているデータソースを新規に設定する場合は、Grafana の公式ドキュメントを参照してください。 Grafanaアラート ------------------------- Grafanaではメトリクス・ログに基づいてアラートを作成したり、アラートを通知したりすることができます。 本チュートリアルでは、アラートの作成、通知先の作成、アラートと通知先の紐づけの方法について説明します。 アラートの設定 ~~~~~~~~~~~~~~~~~~~~~~~~~ Grafanaでは、ユーザーが自分自身でアラートを作成することができます。 CNAPでは、以下にてアラートの設定方法についてサンプルを用意しています。 * :doc:`Prometheus を Datasource に設定して、HTTP 5XXエラー率による監視を行うアラートの作成方法サンプル <./example/grafana-manual/create-alert-prometheus-http-metrics>` なお、アラートの詳細な条件の作成方法等については、Grafana の公式ドキュメントを参照してください。 通知先(コンタクトポイント)の設定 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Grafanaでは、ユーザーが自分自身でコンタクトポイントという、アラートの通知先の設定を行うことができます。 CNAPでは、以下にて通知先の設定方法についてサンプルを用意しています。 * :doc:`アラート通知先 Slack の設定方法サンプル <./example/grafana-manual/create-alert-contact-point-slack>` なお、その他の通知先の設定方法については、 CNAP の基盤側での設定変更が必要な場合がありますので、サポートにご相談ください。 アラートと通知先の紐づけ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Grafanaでは、ユーザーが自分自身でアラートと通知先の紐づけの設定を行うことができます。 作成したアラートと通知先は紐付けは、 ``Alerting`` メニューの ``Notification policies`` から行う事ができます。 ``Default policy`` の右端の ︙ から「Edit」を選択し、 ``Default contact point`` に設定した通知先を選択し、 ``Update default policy`` を選択して保存することで、 アラート発生時に設定した通知先へ通知を送付することができます。 また、アラートのタグ等に応じて複数の通知先を使い分けたいときには、 ``New nested policy`` を選択して設定します。 作成したリソースの削除 ====================== アプリケーションのマニフェストファイルを削除しコミット・pushすることで、作成したリソースを削除できます。または、ファイルの中のYAMLを全行コメントアウトした上でコミット・pushしても削除可能です。 なお、誤操作によるインスタンスの削除を防ぐため、RDBサービスでは ``keepOnDelete`` の値がデフォルトで **true** に設定されています。 true の状態でパッケージをアンインストールしてもデータベースインスタンスは残るため、実際に削除する際は、以下の通り ``keepOnDelete`` を **false** に更新し、一度コミット・pushした後で、削除を行ってください。 .. code-block:: yaml # ~~~省略~~~ spec: chart: name: rdb version: settings: keepOnDelete: false # ~~~省略~~~ .. _AWS Secrets Manager に TLS 証明書を保存する: https://docs.aws.amazon.com/ja_jp/emr/latest/ManagementGuide/emr-ranger-tls-certificates.html Tips: Chat GPTを利用したCNAPマニフェストの作成支援 ========================================================= CNAPでは、CNAP for Mobius をご利用のお客様に対し、CNAPのマニフェスト作成を支援するカスタムGPTsを公開しています。詳細は :doc:`こちら ` なお、Azure 生成AIパッケージをご利用のお客様におきましても、本カスタムGPTsを利用可能です。利用をご希望のお客様はお問い合わせください。