Appendix C - Common object stores for backups
=============================================



.. raw:: html

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

..  Warning::
   CloudNativePG 1.26の時点で、** Barman Cloudプラグイン**を優先して、**ネイティブBarman Cloudサポートは非推奨です**。現時点ではネイティブ統合は機能し続けていますが、適切なテストの後、プラグインベースのインターフェイスへの段階的な移行を開始することを強くお勧めします。 Barman Cloud Pluginドキュメントでは、 
`how to use common object stores <https://cloudnative-pg.io/plugin-barman-cloud/docs/object_stores/>`_ について説明しています。

:ref:`Appendix B - Backup on object stores <Appendix B - Backup on object stores>` ファイルは、 Barman
Cloudインフラストラクチャでサポートされている任意のサービスに保存できます。つまり

- :ref:`AWS S3 <AWS S3>` 

- :ref:`Azure Blob Storage <Azure Blob Storage>` 

- :ref:`Google Cloud Storage <Google Cloud Storage>` 

サポートされているサービスの互換性のある実装を使用することもできます。

必要なセットアップは、選択したストレージプロバイダーによって異なり、以降のセクションで説明します。

AWS S3
------

`AWS Simple Storage Service (S3) <https://aws.amazon.com/s3/>`_ は、Amazonが提供する非常に人気のオブジェクトストレージサービスです。

CloudNativePGバックアップに関する限り、2つの方法でバックアップをS3バケットに保存する権限を定義できます。

- CloudNativePGがEKSで実行されている場合。
  `IRSA authentication method <https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html>`_ を使用することができます

- または、 ``ACCESS_KEY_ID`` および\ ``ACCESS_SECRET_KEY``
  資格情報を使用できます

AWSアクセスキー
^^^^^^^^^^^^^^^

環境に関する次の情報が必要です。

- ``ACCESS_KEY_ID``
  S3にファイルをアップロードするために使用されるアクセスキーのID

- ``ACCESS_SECRET_KEY`` 上記のアクセスキーのシークレット部分

- ``ACCESS_SESSION_TOKEN`` オプションのセッショントークン、必要な場合

使用されるアクセスキーには、バケットにファイルをアップロードする権限が必要です。そのため、資格情報を使用してKubernetesシークレットを作成する必要があります。これは、次のコマンドで行うことができます。

.. code:: sh

   kubectl create secret generic aws-creds \
     --from-literal=ACCESS_KEY_ID=<access key here> \
     --from-literal=ACCESS_SECRET_KEY=<secret key here>

   ##  --from-literal=ACCESS_SESSION_TOKEN=<session token here> # if required

資格情報はKubernetes内に保存され、インストールで保存時の暗号化が構成されている場合、暗号化されます。

そのシークレットが作成されたら、次の例のようにクラスターを構成できます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "<destination path here>"
         s3Credentials:
           accessKeyId:
             name: aws-creds
             key: ACCESS_KEY_ID
           secretAccessKey:
             name: aws-creds
             key: ACCESS_SECRET_KEY

宛先パスには、インスタンスがWALファイルをアップロードできるフォルダーを指す任意のURLを指定できます。
``s3://BUCKET_NAME/path/to/folder`` .

サービスアカウントIRSAのIAMロール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

IRSAを使用するには、Postgresクラスターの\ ``ServiceAccount``
で\ ``annotation`` を設定する必要があります。

``serviceAccountTemplate``
スタンザを使用してそれらを注入するようにCloudNativePGを構成できます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
   [...]
   spec:
     serviceAccountTemplate:
       metadata:
         annotations:
           eks.amazonaws.com/role-arn: arn:[...]
           [...]

S3ライフサイクルポリシー
^^^^^^^^^^^^^^^^^^^^^^^^

Barman CloudはS3にオブジェクトを書き込み、 Barman
Cloudリテンションポリシーによって削除されるまで更新しません。
S3ライフサイクルポリシーで推奨されるアプローチは、オブジェクトの現在のバージョンをBarman保持ポリシーより数日長く有効期限があり、オブジェクトのバージョニングを有効にし、数日後に非最新バージョンの有効期限を有効にすることです。このようなポリシーは、誤った削除から保護し、CloudNativePGワークロードへの権限を制限できるように、オブジェクトを完全に削除する権限を付与せずにS3からオブジェクトを削除できます。

その他のS3互換オブジェクトストレージプロバイダー
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**MinIO** や **Linode Object Storage**
のようなS3互換オブジェクトストレージを使用している場合、デフォルトのS3のものを使用する代わりにエンドポイントを指定できます。

この例では、リージョン\ ``us-east1`` の **Linode** の\ ``bucket``
を使用します。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "s3://bucket/"
         endpointURL: "https://us-east1.linodeobjects.com"
         s3Credentials:
           [...]

**Digital Ocean Spaces**
を使用している場合、Pathスタイルの構文を使用する必要があります。この例では、リージョン\ ``SFO3``
の **Digital Ocean Spaces** の\ ``bucket`` を使用します。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "s3://[your-bucket-name]/[your-backup-folder]/"
         endpointURL: "https://sfo3.digitaloceanspaces.com"
         s3Credentials:
           [...]

プライベートCAでのオブジェクトストレージの使用
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

HTTPS経由でMinIOを使用する場合など、プライベートCAで署名された証明書を使用するオブジェクトストレージプロバイダーを構成するとします。その場合、CAバンドルを含むシークレットを参照する\ ``barmanObjectStore``
内にオプション\ ``endpointCA`` を設定して、
Barmanが証明書を正しく検証できるようにする必要があります。
:ref:`Certificates <Certificates>` ドキュメントの証明書ファイルを使用してシークレットを作成する手順については、
:ref:`Certificates <Certificates>` ドキュメントで見つけることができます。シークレットを作成したら、次の例のように\ ``endpointCA``
を設定できます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     [...]
     backup:
       barmanObjectStore:
         endpointURL: <myEndpointURL>
         endpointCA:
           name: my-ca-secret
           key: ca.crt

..  Note::
   ConfigMapsとSecretsをインスタンスによって**自動的に**リロードしたい場合は、キー`cnpg.io/reload` のラベルをSecrets/ConfigMapsに追加できます。それ以外の場合は、 `kubectl cnpg reload` サブコマンドを使用してインスタンスをリロードする必要があります。 　

Azure Blob Storage
------------------

`Azure Blob Storage <https://azure.microsoft.com/en-us/services/storage/blobs/>`_ は、Microsoftが提供するオブジェクトストレージサービスです。

CloudNativePG管理対象データベースのバックアップとリカバリーのためにストレージアカウントにアクセスするには、次の資格情報のいずれかの組み合わせが必要です。

- 
`Connection String <https://docs.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string#configure-a-connection-string-for-an-azure-storage-account>`_ 

- ストレージアカウント名と 
`Storage account access key <https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage>`_ 

- ストレージアカウント名と 
`Storage account SAS Token <https://docs.microsoft.com/en-us/azure/storage/blobs/sas-service-create>`_ 

- ストレージアカウント名と `Azure AD Workload Identity <https://azure.github.io/azure-workload-identity/docs/introduction.html>`_ 

適切に構成されました。

**Azure AD Workload Identity**
を使用すると、資格情報をKubernetesシークレットに保存せず、次のように\ ``inheritFromAzureAD``
を追加するクラスター構成にすることができます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "<destination path here>"
         azureCredentials:
           inheritFromAzureAD: true

一方、 **ストレージアカウントアクセスキー** または
**ストレージアカウントSASトークン**
の両方を使用する場合、資格情報をKubernetes
Secret内に保存し、必要な場合にのみデータエントリを追加する必要があります。次のコマンドはそれを実行します。

.. code:: sh

   kubectl create secret generic azure-creds \
     --from-literal=AZURE_STORAGE_ACCOUNT=<storage account name> \
     --from-literal=AZURE_STORAGE_KEY=<storage account key> \
     --from-literal=AZURE_STORAGE_SAS_TOKEN=<SAS token> \
     --from-literal=AZURE_STORAGE_CONNECTION_STRING=<connection string>

使用されるKubernetesクラスターでこの機能が有効になっている場合、資格情報は保存時に暗号化されます。

前述のシークレットを踏まえて、提供された資格情報をクラスター構成内に注入できます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "<destination path here>"
         azureCredentials:
           connectionString:
             name: azure-creds
             key: AZURE_CONNECTION_STRING
           storageAccount:
             name: azure-creds
             key: AZURE_STORAGE_ACCOUNT
           storageKey:
             name: azure-creds
             key: AZURE_STORAGE_KEY
           storageSasToken:
             name: azure-creds
             key: AZURE_STORAGE_SAS_TOKEN

Azure Blob Storageを使用する場合、\ ``destinationPath``
は次の構造を満たします。

.. code:: sh

   <http|https>://<account-name>.<service-name>.core.windows.net/<resource-path>

``<resource-path>`` は\ ``<container>/<blob>`` です。
**ストレージアカウント名** とも呼ばれる **アカウント名**
は、使用されるホスト名に含まれます。

その他のAzure Blob Storage互換プロバイダー
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Azure Blob Storage
APIの別の実装を使用している場合、\ ``destinationPath``
は次の構造になります。

.. code:: sh

   <http|https>://<local-machine-address>:<port>/<account-name>/<resource-path>

その場合、\ ``<account-name>`` はパスの最初のコンポーネントです。

これは、 Azureストレージエミュレータまたは
`Azurite <https://github.com/Azure/Azurite>`_ を介してAzureサポートをテストする場合に必要です。

Google Cloud Storage
--------------------

現在、CloudNativePGオペレーターは、
`Google Cloud Storage <https://cloud.google.com/storage/>`_ の2つの認証方法をサポートしています。

- 最初のものは、ポッドがGoogle Kubernetes
  Engineクラスター内で実行されていることを前提としています

- 2つ目は、環境変数\ ``GOOGLE_APPLICATION_CREDENTIALS`` を活用します

Google Kubernetes Engine内での実行
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Google Kubernetes Engine内で実行されている場合、資格情報を設定せずに
`Workload Identity <https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity>`_ 
に単に依存するようにバックアップを構成できます。特に、次のことを行う必要があります。

- ``.spec.backup.barmanObjectStore.googleCredentials.gkeEnvironment``
  を\ ``true`` に設定します

- ``serviceAccountTemplate``
  スタンザに\ ``iam.gke.io/gcp-service-account``
  アノテーションを設定する

次の例を参考として使用してください。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     [...]
     backup:
       barmanObjectStore:
         destinationPath: "gs://<destination path here>"
         googleCredentials:
           gkeEnvironment: true

     serviceAccountTemplate:
       metadata:
         annotations:
           iam.gke.io/gcp-service-account:  [...].iam.gserviceaccount.com
           [...]

認証を使用する
^^^^^^^^^^^^^^

`instruction from Google <https://cloud.google.com/docs/authentication/getting-started>`_ をフォローする

認証に必要な情報をすべて含むJSONファイルを取得します。

JSONファイルのコンテンツは、次のコマンドで作成できる\ ``Secret``
を使用して提供する必要があります。

.. code:: shell

   kubectl create secret generic backup-creds --from-file=gcsCredentials=gcs_credentials_file.json

これにより、次のようにyamlファイルで使用される\ ``backup-creds``
という名前で\ ``Secret`` が作成されます。

.. code:: yaml

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   [...]
   spec:
     backup:
       barmanObjectStore:
         destinationPath: "gs://<destination path here>"
         googleCredentials:
           applicationCredentials:
             name: backup-creds
             key: gcsCredentials

次に、オペレーターは資格情報を使用してGoogle Cloud
Storageに対して認証します。

..  Note::
   この認証方法は、Google Cloud Storageバケットにアクセスするために必要なすべての情報を含むJSONファイルをコンテナ内に作成します。つまり、誰かがポッドへのアクセスを取得すると、バケットへの書き込み権限もあります。