Cluster configuration ===================== ``tpaexec configure`` コマンドは、プロビジョニング/展開/テストサイクルの後続のステージで必要なYAMLクラスター構成ファイルを生成します。 クイックスタート ---------------- .. code:: bash [tpa]$ tpaexec configure ~/clusters/speedy --architecture M1 \ --postgresql 14 \ --failover-manager repmgr このコマンドは、 ``~/clusters/speedy`` という名前のディレクトリを作成し、 M1という名前のアーキテクチャのレイアウトに従う\ ``config.yml`` という名前の構成ファイルを生成します。シングルプライマリ、Nレプリカ。新しいディレクトリにgitリポジトリを作成し、生成された\ ``config.yml`` を含む初期コミットを作成します。 また、コマンドは、構成を変更するためのさまざまなオプション選択したアーキテクチャまたはプラットフォームに固有の一部を受け入れますが、デフォルトは賢明で、すぐに使用できるように設計されています。生成されたconfig.ymlを読み、ニーズに合わせて構成を微調整することをお勧めします。 (これが :ref:`Instance configuration ` の概要です。) config.ymlを完全に手動で書くことも可能ですが、生成されたファイルを編集するほうが簡単です。 構成オプション -------------- 最初の引数は、クラスターディレクトリ、たとえば、\ ``speedy`` または\ ``~/clusters/speedy`` である必要があります。クラスターの名前は、どちらの場合もspeedyになります。すべてのクラスターを共通のディレクトリたとえば、上記の例では\ ``~/clusters`` に保持することをお勧めします。 アーキテクチャ、たとえば :ref:`M1 ` 、 :ref:`BDR-Always-ON ` 、または :ref:`PGD-X ` を選択するには、次の引数が\ ``--architecture `` である必要があります。アーキテクチャの完全なリストについては、\ ``tpaexec info architectures`` を実行してください。 次に、インストールする :ref:`Postgresのフレーバーとバージョン ` を指定する必要があります。 上記の引数は常に必須です。上記の例のように、ここで説明するオプションの残りの部分は安全に省略できます。デフォルトでは使用可能な結果が得られます。 共通オプションのリストについては、 ``tpaexec help configure-options`` を実行します。 アーキテクチャ固有のオプション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 選択したアーキテクチャにより、他のどのオプションが受け入れられるかが決まります。通常、各アーキテクチャは、いくつかの一意のオプションと以下で説明する汎用オプションを受け入れます。 たとえば、M1では ``--location-names l1 l2`` を使用して、2つの名前付けの場所にノードを含むクラスターを作成できます。アーキテクチャが受け入れるオプションのリストについては、アーキテクチャのドキュメントを参照してください。または、場合によっては必要となります。 プラットフォームオプション ^^^^^^^^^^^^^^^^^^^^^^^^^^ 次に、 ``--platform `` を使用してプラットフォーム、たとえば :ref:`awscliを使用してボリューム属性を変更する ` または :ref:`bare(-metal servers) ` を選択できます。 アーキテクチャは特定のプラットフォームをサポートする場合と、サポートしない場合があります。そうしない場合、クラスターの構成に失敗します。 プラットフォームの選択は、特定のオプションの解釈に影響を与えます。たとえば、awsを選択した場合、\ ``--region `` および\ ``--instance-type `` への引数は有効な `AWS region name `_ である必要があります と `EC2 instance type `_ それぞれ。詳細については、プラットフォームのドキュメントを参照してください。 プラットフォームを明示的に選択しない場合、現在デフォルトはawsです。 **注** TPAは、さまざまなプラットフォーム上のインスタンスを使用したクラスターの作成を完全にサポートしていますが、 ``tpaexec configure`` は現在このような構成を生成できません。 config.ymlを編集して、複数のプラットフォームを指定する必要があります。 所有者 ^^^^^^ ``--owner `` を指定して、クラスターを何らかのプラットフォーム固有の手段AWSタグなどで関連付けるには、クラスターに責任を負う人の名前を関連付けます。これは、クラウドプラットフォームにとって特に重要です。デフォルトでは、所有者は\ ``tpaexec provision`` を実行しているユーザーのログイン名に設定されます。 あなたのイニシャル、または「名、姓」、またはあなたを一意に識別するその他のものを使用できます。 リージョン ^^^^^^^^^^ ``--region `` を指定してリージョンを選択します。 このオプションは、クラウドプラットフォームの場合にのみ意味があります。 AWSのデフォルトはeu-west-1です。 **注** TPAは、マルチプルのリージョンにまたがるクラスターの作成を完全にサポートしていますが、 ``tpaexec configure`` は現在このような構成を生成できません。 config.ymlを編集して、複数のリージョンを指定する必要があります。 ネットワーク構成 ^^^^^^^^^^^^^^^^ !!!注 これらのオプションは、TPAが既存のサーバーのネットワーク構成を変更しない「ベア」プラットフォームでは意味がありません。 .. :: デフォルトでは、各クラスターは、選択したアーキテクチャに応じて、 CIDR範囲`10.33.0.0/16` からランダムに選択された多数の`/28` サブネットで構成されます。 ``--network 192.168.0.0/16`` を指定して、別のネットワークからサブネットを割り当てます。 AWSクラスターでは、これはVPC CIDRに対応します。詳細については、 :ref:`awscliを使用してボリューム属性を変更する ` ドキュメントを参照してください。 ``--subnet-prefix 26`` を指定して、別のサイズのサブネット、この場合は/28ではなく/26のサブネットを割り当てます。 !!!注 「docker」プラットフォームが選択されている場合、TPAはアーキテクチャに関係なく、常にクラスター全体を単一のサブネットに配置します。このサブネットは、ここで説明するロジックに従って生成されますが、 ``subnet-prefix`` が指定されない場合、TPAは\ ``config.yaml`` のインスタンス数を収容するのに十分な大きさのサブネットサイズを自動的に選択します。 .. :: `--no-shuffle-subnets` を指定して、ランダム化なしで、ネットワークCIDR範囲の先頭からサブネットを割り当てます。例、`10.33.0.0/28` 、次に`10.33.0.16/28` など。 ``--exclude-subnets-from `` を指定して、既存のクラスターconfig.ymlファイルで既に使用されているサブネットを除外します。この引数は、ディレクトリごとに複数回指定できます。 インスタンスタイプ ^^^^^^^^^^^^^^^^^^ ``--instance-type `` を指定してインスタンスタイプを選択します。 このオプションは、クラウドプラットフォームの場合にのみ意味があります。 AWSのデフォルトはt3.microです。 ディスク領域 ^^^^^^^^^^^^ ``--root-volume-size 64`` を指定して、ルートボリュームのサイズをGB単位で設定します。プラットフォームによっては、ルートボリュームに必要な最小サイズが存在する場合があります。 ``--postgres-volume-size `` および\ ``--barman-volume-size `` オプションは、 PostgresとBarmanの個別のボリュームをサポートするアーキテクチャとプラットフォームで、 PostgresおよびBarmanボリュームのサイズを設定するために使用できます。 これらのオプションは、TPAがボリュームサイズを制御できない「ベア」プラットフォームでは意味がありません。 ホスト名 ^^^^^^^^ デフォルトでは、\ ``tpaexec configure`` は、数十の名前の事前承認リストから必要な数のホスト名をランダムに選択します。ほとんどのクラスターではこれで十分です。 ``--hostnames-from `` を指定して、1行に1つの名前を含むファイルからホスト名を選択します。ファイルには、クラスター内のインスタンスと同じ数以上の有効なホスト名が含まれている必要があります。各行には、名前の後にオプションのIPアドレスを含めることができます。存在する場合、このアドレスは\ ``config.yml`` の対応するインスタンスの\ ``ip_address`` として設定されます。 2つのIPアドレスが存在する場合、1つ目は\ ``public_ip`` として設定され、2つ目は\ ``private_ip`` として設定されます。 ``--hostnames-pattern '…pattern…'`` を使用して、選択をegrepパターンに一致する行に制限します。 ``--hostnames-sorted-by="--dictionary-order"`` を使用して、 ``--random-sort`` デフォルト以外のsort(1)オプションを選択します。 ``--hostnames-unsorted`` を使用して、ホスト名をまったくソートしません。この場合、ホスト名ファイルで見つかった順序で割り当てられます。これは、ホスト名ファイルが明示的に指定された場合のデフォルトです。 ``--cluster-prefixed-hostnames`` を使用して、各ホスト名がクラスターの名前で始まるようにします。これは、同じホストで複数のDockerクラスターを実行している場合、ホスト名の衝突を回避するのに役立ちます。 ホスト名には、文字a〜z、数字0〜9、および’-’のみを含めることができます。選択したプラットフォームによっては、FQDNである場合があります。ホスト名は小文字である必要があります。大文字は内部で小文字に変換され、config.ymlたとえば\ ``upstream: hostname`` でのこれらのホスト名への参照は小文字バージョンを使用する必要があります。 ソフトウェアの選択 ------------------ ディストリビューション ^^^^^^^^^^^^^^^^^^^^^^ ``--distribution `` を指定してディストリビューションを選択します。 選択したプラットフォームにより、どのディストリビューションが利用可能か、およびデフォルトで使用されるディストリビューションが決まります。 一般に、「Debian」、「RedHat」、「Ubuntu」、および「SLES」を使用して、適切なイメージを選択できる必要があります。 このオプションは、TPAがどのディストリビューションをインストールするかを制御できない「ベア」プラットフォームでは意味がありません。 EDBリポジトリ ^^^^^^^^^^^^^ TPAは、サブスクリプションを介してアクセスしているEDBソフトウェアリポジトリを有効にできます。デフォルトでは、TPAはアーキテクチャが必要とする製品リポジトリをインストールします。 TPAがEDBリポジトリを使用する方法の詳細な説明は、 :ref:`Configuring EDB Repos 2.0 repositories ` および各アーキテクチャのページで利用できます。 ``--edb-repositories repository …`` を指定して、各インスタンスにインストールするEDBリポジトリの完全なリストを指定します。 このオプションは注意して使用してください。 TPAは、組み合わせが適切であることを確認せずに名前付けリポジトリを構成します。 このオプションを使用するには、TPAを実行する前に\ ``export EDB_SUBSCRIPTION_TOKEN=xxx`` を行う必要があります。 EDBトークンは、enterprisedb.com/reposから取得できます。 ローカルリポジトリのサポート ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--enable-local-repo`` を使用して、パッケージをターゲットインスタンスにシップするローカルパッケージリポジトリを作成します。 ネットワークアクセスが制限されている環境では、代わりに\ ``--use-local-repo-only`` を使用してローカルリポジトリを作成し、ターゲットインスタンスで他のすべてのパッケージリポジトリを無効にして、パッケージがローカルリポジトリからのみインストールされるようにできます。 :ref:`Creating and using a local repository ` に関するページに詳細が記載されています。 ソフトウェアバージョン ^^^^^^^^^^^^^^^^^^^^^^ Postgresのフレーバーとバージョン ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TPAは、 PostgreSQL、 EDB Postgres Extended、およびEDB Postgres Advanced Serverバージョン11〜17をサポートしています。 インストールするPostgresのフレーバーまたはディストリビューションとメジャーバージョンの両方を指定する必要があります。たとえば、 - ``--postgresql 14`` はPostgreSQL 14をインストールします - ``--edb-postgres-extended 15`` はEDB Postgres Extended 15をインストールします - ``--edb-postgres-advanced 15 --redwood`` は、EPAS 15を「Redwood」モードでインストールします - ``--edb-postgres-advanced 15 --no-redwood`` は、非RedwoodモードでEPAS 15をインストールします EPASをインストールする場合、\ ``--redwood`` または\ ``--no-redwood`` モードで動作するかどうか、つまりOracle互換性機能を有効にするか無効にするかを指定する必要があります。 EDB Postgres ExtendedまたはPostgres Advanced Serverのインストールには、有効な :ref:`Configuring EDB Repos 2.0 repositories ` が必要です。 パッケージバージョン ^^^^^^^^^^^^^^^^^^^^ デフォルトでは、常にすべてのパッケージの最新バージョンをインストールします。これは通常、望ましい動作ですが、一部のテストシナリオでは、次のオプションのいずれかを使用して特定のパッケージバージョンを選択する必要がある場合があります。 1. ``--postgres-package-version 10.4-2.pgdg90+1`` 2. ``--repmgr-package-version 4.0.5-1.pgdg90+1`` 3. ``--barman-package-version 2.4-1.pgdg90+1`` 4. ``--pglogical-package-version '2.2.0*'`` 5. ``--bdr-package-version '3.0.2*'`` 6. ``--pgbouncer-package-version '1.8*'`` 7. ``--beacon-agent-package-version 1.56.2-1`` 8. ``--etcd-package-version 9.8.0-1.el8`` 9. ``--patroni-package-version 4.0.0-1PGDG.rhel8`` 10. ``--pem-server-package-version 9.7.0-1.el9`` 11. ``--pem-agent-package-version 9.7.0-1.el9`` 12. ``--pg-backup-api-package-version 2.0.0-1.el8`` 13. ``--pgd-proxy-package-version 5.0.0-1`` 14. ``--pgdcli-package-version 5.6.1`` aptまたはyumが受け入れるバージョン指定子を使用できます。 バージョンが一致しない場合は、 ``*`` ワイルドカードを追加してみてください。これは、パッケージバージョンに\ ``2:...`` のようなエポック修飾子がある場合に必要になることがよくあります。 ``--extra-packages p1 p2 …`` または\ ``--extra-postgres-packages p1 p2 …`` を指定して、追加パッケージをインストールすることもできます。前者はシステムパッケージとともにインストールするパッケージをリストし、後者はpostgresパッケージとともに後でインストールするパッケージをリストします。前者のリストでPostgresに依存するパッケージを記載すると、Postgresがまだインストールされていないため、インストールは失敗します。引数は変更せずにインストールのためにパッケージマネージャーに渡されます。 ``--extra-optional-packages p1 p2 …`` オプションは\ ``--extra-packages`` と同様に動作しますが、名前付けたパッケージをインストールできない場合、これはエラーではありません。 ワイルドカードの使用に関する既知の問題 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``config.yml`` に永続的に追加する場合、\ ``*_package_version`` でワイルドカードを使用すると、RHEL 8以降のノードまたはRocky Linuxなどのdnfを使用する派生OSで\ ``tpaexec deploy`` の実行中に、インストールされたソフトウェアの予期しない更新が発生する可能性があることに注意してください。既にパッケージがインストールされている既存のクラスターでdeployが実行されている場合、ansibleは完全なパッケージバージョンと一致しない場合があります。たとえば、 ``bdr_package_version`` の値が\ ``3.6*`` に設定されている場合、 ansibleはこれをPGDのインストールされたバージョンと照合できず、パッケージがインストールされていないと仮定し、次のパッケージの利用可能な最新バージョンをインストールしようとします。構成済みのリポジトリ内の同じ名前、例3.7. 私たちはこの制限をansible dnfモジュールのバグとして認識しており、TPAの将来のリリースでこれに対処したいと考えています。 ソースからのビルドとインストール ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--install-from-source postgres`` を指定すると、Postgresはパッケージからインストールされるのではなく、gitリポジトリからビルドおよびインストールされます。デフォルトでは、これは適切な\ ``REL_nnn_STABLE`` ブランチをビルドします。 ``--install-from-source postgres bdr5`` を使用してソースから両方のコンポーネントをビルドおよびインストールするか、\ ``--install-from-source bdr5`` を使用してPostgresのパッケージを使用できますが、ソースからPGD v5をビルドおよびインストールします。デフォルトでは、これはPGDの\ ``main`` ブランチをビルドします。 別のブランチをビルドするには、対応する引数に\ ``:branchname`` を追加します。例、\ ``--install-from-source 2ndqpostgres:dev/xxx`` 、または\ ``pglogical:bug/nnnn`` 。 代わりにソースインストールに置き換えることを選択したパッケージに依存するパッケージをインストールできない場合があります。たとえば、 PGD v3パッケージはpglogical v3パッケージに依存しているため、ソースリポジトリからpglogicalをインストールし、パッケージからPGDをインストールすることはできません。同様に、ソースからPostgresをインストールし、パッケージからpglogicalをインストールすることはできません。 オーバーライド -------------- オプションで\ ``--overrides-from a.yml …`` を指定して、生成されたconfig.ymlにマージする設定を含む1つ以上のYAMLファイルをロードできます。 ここで指定されたファイルは、最初にJinja2テンプレートとして展開され、結果はYAMLデータ構造としてロードされ、config.ymlアーキテクチャとプラットフォームのデフォルトとコマンドラインからの引数で構成される引数に再帰的にマージされます。このプロセスは、指定された追加オーバーライドファイルごとに繰り返されます。これは、1つのファイルで定義された設定が後続のファイルに可視されることを意味します。 たとえば、オーバーライドファイルには次のものが含まれる場合があります。 :: cluster_tags: some_tag: "{{ lookup(env, SOME_ENV_VAR) }}" cluster_vars: synchronous_commit: remote_write postgres_conf_settings: effective_cache_size: 4GB これらの設定は、config.ymlにある\ ``cluster_tags`` および\ ``cluster_vars`` を強化します。設定は再帰的にマージされるため、 ``cluster_tags`` には、デフォルトのOwnerタグと\ ``some_tag`` の両方が含まれることになります。同様に、\ ``effective_cache_size`` 設定はその変数をオーバーライドし、他の\ ``postgres_conf_settings`` 存在する場合は影響を受けません。つまり、config.ymlで特定のサブキーを設定またはオーバーライドすることはできますが、 ``cluster_tags`` またはその他のハッシュを完全に空にしたり置き換えたりすることはできません。 マージはハッシュ構造にのみ適用されるため、このメカニズムを使用してconfig.yml内の\ ``instances`` のリストを変更することはできません。環境によくある設定で\ ``cluster_vars`` および\ ``instance_defaults`` を強化するのが最も役立ちます。 とはいえ、このメカニズムはいかなる制限も強制するものではないため、十分な注意を払ってください。オーバーライドを含む場合とない場合の2つの構成を生成し、2つのconfig.ymlファイルを比較して、すべてのオーバーライドの効果を理解することをお勧めします。 Ansible Tower ------------- ``--use-ansible-tower`` および\ ``--tower-git-repository`` オプションを使用して、Ansible Towerでの展開に適応したクラスターを作成します。詳細については、 :ref:`TPA and Ansible Tower/Ansible Automation Platform ` を参照してください。 ビーコンエージェント -------------------- ``--enable-beacon-agent`` および\ ``--beacon-agent-project-id`` オプションを使用してビーコンエージェントをインストールします。これにより、 EDB Postgres AIコンソールでクラスターを表示できます。詳細は、 :ref:`Configuring the agent ` を参照してください。 Gitリポジトリ ------------- デフォルトでは、クラスターにちなんで名前付けられた初期ブランチでgitリポジトリが作成され、コミットメッセージで使用したconfigureオプションを使用して単一のコミットが作成されます。 ``$PATH`` にgitがない場合、tpaexecはエラーを発生させませんが、リポジトリは作成されません。 gitリポジトリの作成を抑制するには、 ``--no-git`` オプションを使用します。 Ansible Towerクラスターでは、gitリポジトリが必要で、\ ``tpaexec provision`` によってまだ存在しない場合は後で作成されることに注意してください。 ボールトパスワードのキーリングバックエンド ------------------------------------------ TPAは、クラスター固有のansible vaultパスワードを生成します。このパスワードは、クラスター用に生成された他の機密変数、postgresユーザーパスワード、barmanユーザーパスワードなどを暗号化するために使用されます。 キーリングバックエンド ``system`` は、 gnome-keyringやsecret-toolを含むPythonキーリングモジュールでサポートされているバックエンドのリストから、システムで最適なキーリングバックエンドを活用します。 デフォルトでは、新しいクラスターの\ ``system`` キーリングを使用してボールトパスワードを保存します。 ``provision`` の **前** 、config.ymlファイルの\ ``keyring_backend: system`` を削除すると、以前のデフォルトに戻してボールトのパスワードをプレーンテキストファイルに保存します。 ``keyring_backend: system`` を使用すると、ボールトパスワードの一意のストレージ名を保存するために使用されるconfig.ymlに\ ``vault_name`` エントリーも生成されます。 TPAはデフォルトでUUIDを生成しますが、命名スキーム要件はありません。 注 同じ\ ``cluster_name`` を使用する複数のクラスターで\ ``keyring_backend: system`` と同じベースのconfig.ymlファイルを使用する場合、構成ファイルを別の場所にコピーすることにより、値ペア ``vault_name`` 、\ ``cluster_name`` がクラスターコピーごとに一意であることを確認します。 注 ``keyring_backend: system`` を使用し、既にプロビジョニングされたクラスターフォルダーを別のtpaホストに移動する場合、新しいマシンのシステムキーリングに関連するボールトパスワードをエクスポートしていることを確認してください。 vaultパスワードは\ ``tpaexec show-vault `` を介して表示できます。 セキュリティ基準へのコンプライアンス ------------------------------------ ``--compliance stig`` または\ ``--compliance cis`` オプションを使用して、STIGまたはCIS標準に準拠するのに適した構成でクラスターを生成します。詳細は、 :ref:`セキュリティ基準へのコンプライアンス <セキュリティ基準へのコンプライアンス>` を参照してください。これらのオプションは、クラスターが関連する標準を満たすことを保証するものではないことに注意してください。これらは、TPAによって制御可能な標準のこれらの側面に準拠するように設計された構成をTPAに生成するだけです。 例 -- 次のコマンドを実行するとどうなるか見てみましょう。 .. code:: bash [tpa]$ tpaexec configure ~/clusters/speedy --architecture M1 \ --distribution Debian \ --platform aws --region us-east-1 --network 10.33.0.0/16 \ --instance-type t2.medium --root-volume-size 32 \ --postgres-volume-size 64 --barman-volume-size 128 \ --postgresql 14 \ --failover-manager repmgr [tpa]$ 出力はないため、エラーはありません。クラスターディレクトリが作成され、データが設定されました。 .. code:: bash $ ls -lh ~/clusters/speedy/ total 8.0K drwxrwxr-x 2 haroon haroon 4.0K Aug 17 02:33 commands - rw-rw-r-- 1 haroon haroon 1.5K Aug 17 02:33 config.yml lrwxrwxrwx 1 haroon haroon 53 Aug 17 02:33 deploy.yml -> /home/haroon/tpa/architectures/M1/deploy.yml クラスター構成はconfig.ymlにあり、その近傍は直接対話する必要のないアーキテクチャ固有のサポートファイルへのリンクです。構成は次のとおりです。 .. code:: yaml - -- architecture: M1 cluster_name: speedy cluster_tags: {} keyring_backend: system vault_name: cfae3da3-ec00-46cd-ab05-e153f1c788db cluster_rules: - cidr_ip: 0.0.0.0/0 from_port: 22 proto: tcp to_port: 22 - cidr_ip: 10.33.120.80/28 from_port: 0 proto: tcp to_port: 65535 ec2_ami: Name: debian-11-amd64-20240104-1616 Owner: 136693071363 ec2_instance_reachability: public ec2_vpc: us-east-1: Name: Test cidr: 10.33.0.0/16 cluster_vars: edb_repositories: [] failover_manager: repmgr postgres_flavour: postgresql postgres_version: 14 preferred_python_version: python3 locations: - Name: main az: us-east-1a region: us-east-1 subnet: 10.33.120.80/28 instance_defaults: default_volumes: - device_name: root encrypted: true volume_size: 32 volume_type: gp2 - device_name: /dev/sdf encrypted: true vars: volume_for: postgres_data volume_size: 64 volume_type: gp2 platform: aws type: t2.medium vars: ansible_user: admin instances: - Name: uproar backup: kinsman location: main node: 1 role: - primary - Name: unravel location: main node: 2 role: - replica upstream: uproar - Name: kinsman location: main node: 3 role: - barman - log-server - witness upstream: uproar volumes: - device_name: /dev/sdf encrypted: true vars: volume_for: barman_data volume_size: 128 volume_type: gp2 次のステップは、 :ref:`tpaexec provision ` を実行することです または、 :ref:`クラスター構成 <クラスター構成>` の構成をカスタマイズする方法または :ref:`Instance configuration ` の構成方法の詳細を参照してください。