Quickstart
==========


.. raw:: html

   <!-- SPDX-License-Identifier: CC-BY-4.0 -->

このセクションでは、
`Kind <https://kind.sigs.k8s.io/>`_ または `Minikube <https://kubernetes.io/docs/setup/learning-environment/minikube/>`_ のいずれかを使用してローカルKubernetesクラスターにCloudNativePGを展開することにより、ローカルマシンでPostgreSQLクラスターをテストする方法を説明します。

..  Warning::
   このセクションに含まれる手順は、デモンストレーション、テスト、および練習のみを目的としているため、実稼働環境では使用しないでください。 　

他のKubernetesアプリケーションと同様に、CloudNativePGはYAMLで書かれた通常のマニフェストを使用して展開されます。

このページの手順に従うと、ローカルのKubernetesインストールでPostgreSQLクラスターを起動し、実験できるはずです。

..  Note::
   Kubernetesクラスターに接続するためには、マシンに`kubectl` がインストールされていることを確認してください。 `how to install `kubectl` <https://kubernetes.io/docs/tasks/tools/install-kubectl/>`_ のKubernetesドキュメントに従ってください。 　

パート1:ローカルKubernetesプレイグラウンドをセットアップする
------------------------------------------------------------

最初の部分は、MinikubeまたはKindのインストールに関するものです。時間をかけてシステムについて読み、どれを続行するかを決定してください。いずれかの設定を行ったら、パート2に進んでください。

:ref:`パート4 PrometheusとGrafanaを使用してクラスターを監視する <パート4 PrometheusとGrafanaを使用してクラスターを監視する>` では、ローカルテスト/評価のためにPrometheusとGrafanaを使用したモニタリングを設定する手順も提供します

Minikube
^^^^^^^^

Minikubeは、Kubernetesをローカルで簡単に実行できるツールです。
Minikubeは、Kubernetesを試してみるか、日常的に開発しようとしているユーザーのために、ラップトップの仮想マシンVM内でシングルノードKubernetesクラスターを実行します。通常、VirtualBoxと組み合わせて使用します。

詳細については、ローカルの個人環境の公式 `Kubernetes documentation on how toinstall Minikube <https://kubernetes.io/docs/tasks/tools/install-minikube>`_ で見つけることができます。インストールしたら、次のコマンドを実行してminikubeクラスターを作成します。

.. code:: sh

   minikube start

これにより、Kubernetesクラスターが作成され、使用する準備が整います。次のコマンドで動作することを確認します。

.. code:: sh

   kubectl get nodes

``minikube`` という名前のノードが1つ表示されます。

種類
^^^^

仮想マシンハイパーバイザーを使用したくない場合、
Kindは、Dockerコンテナ「ノード」を使用してローカルKubernetesクラスターを実行するためのツールです。Kindは、確かに「Kubernetes
IN Docker」の略です。

`Quickstart <https://kind.sigs.k8s.io/docs/user/quick-start>`_ の指示に従って、環境に\ ``kind``
をインストールし、次のKubernetesクラスターを作成します。

.. code:: sh

   kind create cluster --name pg

パート2 CloudNativePGのインストール
-----------------------------------

ラップトップでKubernetesインストールをアップして実行しているため、CloudNativePGのインストールに進むことができます。

:ref:`Installation and upgrades <Installation and upgrades>` セクションを参照して、PostgreSQLクラスターの展開を続行してください。

パート3 PostgreSQLクラスターを展開する
--------------------------------------

Kubernetesの他の展開と同様に、PostgreSQLクラスターを展開するには、目的の\ ``Cluster``
を定義する構成ファイルを適用する必要があります。

 
`cluster-example.yaml <https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/cluster-example.yaml>`_ サンプルファイルは、デフォルトのストレージクラスを使用して単純な\ ``Cluster``
を定義して、ディスク領域を割り当てます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-example
   spec:
     instances: 3

     storage:
       size: 1Gi

..  Note::
   使用可能なオプションの詳細については、 :ref:`API Reference <API Reference>` を参照してください。 　

3ノードPostgreSQLクラスターを作成するには、次のコマンドを実行する必要があります。

.. code:: sh

   kubectl apply -f cluster-example.yaml

``get pods`` コマンドでポッドが作成されていることを確認できます。

.. code:: sh

   kubectl get pods

これにより、デフォルトの名前空間でポッドが検索されます。
Kubernetesインストールの他のワークロードからクラスターを分離するには、クラスターを展開する新しい名前空間をいつでも作成できます。または、ラベルを使用できます。オペレーターは、特定のクラスターに関連するすべてのオブジェクトに\ ``cnpg.io/cluster``
ラベルを適用します。例

.. code:: sh

   kubectl get pods -l cnpg.io/cluster=<CLUSTER>

..  Note::
   ラベルとして`cnpg.io/cluster` を使用していることに注意してください。過去に`postgresql` を見たり使用したりしたことがあるかもしれません。このラベルは非推奨であり、将来的に削除される予定です。 `cnpg.io/cluster` を使用してください。 　

デフォルトでは、オペレーターは、オペレーターがリリースされたときにPostgreSQLの最新メジャーバージョンの利用可能な最新のマイナーバージョンをインストールします。
``Cluster`` 定義の\ ``spec`` セクションで\ ``imageName``
キーを設定することにより、これをオーバーライドできます。例、PostgreSQL
13.6をインストールするには

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
      # [...]
   spec:
      # [...]
      imageName: ghcr.io/cloudnative-pg/postgresql:13.6
      #[...]

..  Note::
   不変のインフラストラクチャパラダイムでは、常にコンテナイメージの特定のバージョンをポイントする必要があります。クラスター内の更新ポリシーとバージョンの一貫性の点で予期せぬシナリオが発生する可能性があるため、実稼働環境では`latest` や`13` のようなタグを使用しないでください。厳密な決定論的で反復可能な展開の場合、 `<image>:<tag>@sha256:<digestValue>` 形式を介してイメージ名にダイジェストを追加できます。 　

..  Note::
   オペレーターにバンドルされたクラスター構成の例がいくつかあります。 :ref:`例 <例>` を参照してください。 　

パート4 PrometheusとGrafanaを使用してクラスターを監視する
---------------------------------------------------------

..  Note::
   PrometheusとGrafanaのインストールは、このプロジェクトの範囲を超えています。このセクションの手順は、実験と説明のみを目的として提供されています。 　

このセクションでは、可観測性を実現するためにPrometheusとGrafanaを展開する方法、CloudNativePGクラスターを監視するためのGrafanaダッシュボードを作成する方法、およびアラート条件を定義するPrometheusルールセットを示します。

`Kube-Prometheus stack <https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack>`_ を活用します

Helmチャート。
`Prometheus Community <https://github.com/prometheus-community>`_ によって維持されます。追加のドキュメントと背景については、プロジェクトのWebサイトを参照してください。

Kube-Prometheus-stack Helmチャートは、 `Prometheus Operator <https://prometheus-operator.dev>`_ 
`Alert Manager <https://prometheus.io/docs/alerting/latest/alertmanager/>`_ を含む `Prometheus Operator <https://prometheus-operator.dev>`_ 
、および `Grafana <https://grafana.com>`_ 展開をインストールします。

このHelmチャートの展開のための構成ファイルが含まれており、CloudNativePGクラスターのオブザーバビリティに役立つ初期設定を提供します。

インストール
^^^^^^^^^^^^

`Helm <https://helm.sh>`_ をまだインストールしていない場合は、
`instructions <https://helm.sh/docs/intro/quickstart/>`_ に従って、システムにインストールしてください。

``prometheus-community`` Helmチャートリポジトリを追加し、サンプル構成
 
`kube-stack-config.yaml <./https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml>`_  で *Kube Prometheusスタック*
をインストールする必要があります。

これは、次のコマンドで実行できます。

.. code:: sh

   helm repo add prometheus-community \
     https://prometheus-community.github.io/helm-charts

   helm upgrade --install \
     -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/kube-stack-config.yaml \
     prometheus-community \
     prometheus-community/kube-prometheus-stack

完了すると、Prometheus、Grafana、およびAlert
Managerが\ ``kube-stack-config.yaml`` ファイルで構成されます。

- Prometheusインストールから、 **any** ``PodMonitor``
  を監視するPrometheus Operatorが登場します
  :ref:`*monitoring* <Monitoring>` を参照してください。

- Alert ManagerとGrafanaは両方とも有効になっています。

..  Note::
   上記のhelmコマンドの詳細については、 `helm    install <https://helm.sh/docs/helm/helm_install/>`_ を参照してください。

ドキュメント。 　

いくつかのカスタムリソースが作成されたことがわかります。

.. code:: sh

   % kubectl get crds
   NAME                                        CREATED AT
   …
   alertmanagers.monitoring.coreos.com         <timestamp>
   …
   prometheuses.monitoring.coreos.com          <timestamp>
   prometheusrules.monitoring.coreos.com       <timestamp>
   …

および一連のサービス

.. code:: sh

   % kubectl get svc     
   NAME                                      TYPE        PORT(S)
   …                                         …           …
   prometheus-community-grafana              ClusterIP   80/TCP
   prometheus-community-kube-alertmanager    ClusterIP   9093/TCP
   prometheus-community-kube-operator        ClusterIP   443/TCP
   prometheus-community-kube-prometheus      ClusterIP   9090/TCP

Prometheusでの表示
^^^^^^^^^^^^^^^^^^

この時点で、モニタリングをアクティブ化して展開されたCloudNativePGクラスターは、Prometheusを介して監視できます。

たとえば、\ ``PodMonitor`` を有効にした単純なクラスターを展開できます。

.. code:: sh

   kubectl apply -f - <<EOF
   - --
   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: cluster-with-metrics
   spec:
     instances: 3

     storage:
       size: 1Gi
   - --
   apiVersion: monitoring.coreos.com/v1
   kind: PodMonitor
   metadata:
     name: cluster-with-metrics
   spec:
     selector:
       matchLabels:
         cnpg.io/cluster: cluster-with-metrics
     podMetricsEndpoints:
     - port: metrics
   EOF

Prometheusにアクセスするには、Prometheusサービスをポート転送します。

.. code:: sh

   kubectl port-forward svc/prometheus-community-kube-prometheus 9090

次に、次のPrometheusコンソールにローカルにアクセスします。 `http://localhost:9090/ <http://localhost:9090/>`_ 

CloudNativePGクラスターに関連する一連のメトリックを見つけます。詳細については、
:ref:`monitoring section <Monitoring>` を参照してください。

.. figure:: /images/prometheus-local.png
   :width: 70% 
   :alt: local prometheus

   local prometheus

CloudNativePGオペレーターをターゲットとするPodMonitorを作成することにより、CloudNativePGオペレーターをモニタすることもできます。
:ref:`monitoring page <Monitoring>` の関連セクションを参照してください。

``prometheusRule``
を作成することにより、いくつかのアラートを定義できます。

.. code:: sh

   kubectl apply -f \
     https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/docs/src/samples/monitoring/prometheusrule.yaml

デフォルトのアラートが表示されます。

.. code:: sh

   % kubectl get prometheusrules                      
   NAME                                                       AGE
   cnpg-default-alerts                                        3m27s

Prometheusコンソールで、 *Alerts*
メニューをクリックして、インストールしたばかりのアラートを表示できます。

Grafanaダッシュボード
^^^^^^^^^^^^^^^^^^^^^

これまでのインストールでは、Grafanaは事前定義されたダッシュボードなしで展開されます。

Grafanaを開くには、grafanaサービスをポート転送できます。

.. code:: sh

   kubectl port-forward svc/prometheus-community-grafana 3000:80

`http://localhost:3000/ <http://localhost:3000/>`_ でGrafanaにローカルにアクセスします

ユーザー名として資格情報が\ ``admin``
、パスワードとして\ ``prom-operator`` を提供します
``kube-stack-config.yaml`` で定義。

CloudNativePGは、専用の
`grafana-dashboards <https://github.com/cloudnative-pg/grafana-dashboards>`_ でGrafanaのデフォルトのダッシュボードを提供します。ファイル
`grafana-dashboard.json <https://github.com/cloudnative-pg/grafana-dashboards/blob/main/charts/cluster/grafana-dashboard.json>`_ をダウンロードできます。

GUIから手動でインポートしますメニューDashboards > New > Import
。作成したばかりの\ ``CloudNativePG``
ダッシュボードをクリックできるようになりました。

.. figure:: /images/grafana-local.png
   :width: 70% 
   :alt: local grafana

   local grafana

..  Warning::
   前のダッシュボードの一部のグラフは、`No data` を表示するいくつかのグラフを生成する`kubelet_volume_stats_available_bytes` や`kubelet_volume_stats_capacity_bytes` など、これが作成された時点でアルファ段階にあったメトリックを利用しています。 　

ローカル設定では、PrometheusとGrafanaは、モニタリング機能を有効にして展開されたCloudNativePGクラスターを自動的に検出および監視するように構成されていることに注意してください。