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:`configuration settings that affect the deployment ` の概要はこちら 。） config.ymlを完全に手で書くことは可能ですが、生成されたファイルを編集する方がはるかに簡単です。 構成オプション -------------- 最初の引数は、クラスターディレクトリ、例、 ``speedy`` または\ ``~/clusters/speedy`` である必要があります（クラスターにはどちらの場合もspeedyという名前が付けられます）。すべてのクラスターを共通のディレクトリ（上記の例の\ ``~/clusters`` など）に保持することをお勧めします。 アーキテクチャ、 :ref:`M1 ` または :ref:`BDR-Always-ON ` を選択するには、次の引数を ``--architecture `` にする必要があります。アーキテクチャの完全なリストについては、\ ``tpaexec info architectures`` を実行してください。 次に、インストールする :ref:`flavour and version of Postgres <#postgres-flavour-and-version>` を指定する必要があります。 上記の引数は常に必須です。ここで説明する残りのオプションは、上記の例のように、安全に省略できます。デフォルトは使用可能な結果につながります。 一般的なオプションのリストについては、 ``tpaexec help configure-options`` を実行してください。 アーキテクチャ固有のオプション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 選択したアーキテクチャによって、他のどのオプションが受け入れられるかが決まります。通常、各アーキテクチャは、以下に説明する汎用オプションだけでなく、いくつかの一意のオプションを受け入れます。 たとえば、 M1 では ``--num-cascaded-replicas 3`` を使用して、3つのカスケードレプリカでクラスターを作成できます。受け入れる（または、場合によっては必要とする）オプションのリストについては、アーキテクチャのドキュメントを参照してください。 プラットフォームオプション ^^^^^^^^^^^^^^^^^^^^^^^^^^ 次に、 ``--platform `` を使用して、 :ref:`認証情報に関する奇妙なAWSエラー <認証情報に関する奇妙なAWSエラー>` または :ref:`bare(-metal servers) ` などのプラットフォームを選択できます。 アーキテクチャは、特定のプラットフォームをサポートする場合とサポートしない場合があります。そうでない場合、クラスターの構成に失敗します。 プラットフォームの選択は、特定のオプションの解釈に影響します。たとえば、awsを選択した場合、 ``--region `` および\ ``--instance-type `` への引数は有効な `AWS region name `_ でなければなりません そして `EC2 instance type `_ それぞれ。詳細については、プラットフォームのドキュメントを参照してください。 プラットフォームを明示的に選択しない場合、デフォルトは現在awsです。 **注：** TPAは、異なるプラットフォーム上のインスタンスを持つクラスターの作成を完全にサポートしていますが、 ``tpaexec configure`` は現在そのような構成を生成できません。 config.ymlを編集して、複数のプラットフォームを指定する必要があります。 所有者 ^^^^^^ ``--owner `` を指定して、クラスターを（AWSタグなどのプラットフォーム固有の手段によって）責任者の名前に関連付けます。これは、クラウドプラットフォームにとって特に重要です。デフォルトでは、所有者は\ ``tpaexec provision`` を実行しているユーザーのログイン名に設定されます。 （あなたのイニシャル、「Firstname Lastname」、またはあなたを一意に識別する他のものを使用できます。） 地域 ^^^^ ``--region `` を指定してリージョンを選択します。 このオプションは、クラウドプラットフォームでのみ意味があります。 AWSのデフォルトはeu-west-1です。 **注：** TPAは、複数のリージョンにまたがるクラスターの作成を完全にサポートしていますが、 ``tpaexec configure`` は現在そのような構成を生成できません。複数のリージョンを指定するには、 config.ymlを編集する必要があります。 ネットワーク構成 ^^^^^^^^^^^^^^^^ デフォルトでは、各クラスターは、選択したアーキテクチャに応じて、 CIDR範囲\ ``10.33.0.0/16`` からランダムに選択された多数の\ ``/28`` サブネットで構成されます。 ``--network 192.168.0.0/16`` を指定して、別のネットワークからサブネットを割り当てます。 **注：** AWSクラスターでは、これは VPC CIDRに対応します。詳細については、 :ref:`認証情報に関する奇妙なAWSエラー <認証情報に関する奇妙なAWSエラー>` ドキュメントを参照してください。 ``--subnet-prefix 26`` を指定して、異なるサイズのサブネット、この場合は/28ではなく/26を割り当てます。 ``--no-shuffle-subnets`` を指定して、ランダム化なしでネットワークCIDR範囲の先頭からサブネットを割り当てます（例、\ ``10.33.0.0/28`` 、\ ``10.33.0.16/28`` など）。 ``--exclude-subnets-from `` を指定して、既存のクラスター config.ymlファイルで既に使用されているサブネットを除外します。この引数は、ディレクトリごとに複数回指定できます。 **注：** これらのオプションは、TPAが既存のサーバーのネットワーク構成を変更しない「ベア」プラットフォームでは意味がありません。 インスタンスタイプ ^^^^^^^^^^^^^^^^^^ インスタンスタイプを選択するには\ ``--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`` として設定されます。 ``--hostnames-pattern '…pattern…'`` を使用して、選択をegrepパターンに一致する行に制限します。 ``--hostnames-sorted-by="--dictionary-order"`` を使用して、 ``--random-sort`` （デフォルト）以外のsort（1）オプションを選択します。 ``--hostnames-unsorted`` を使用して、ホスト名をまったくソートしないようにします。この場合、それらはhostnamesファイルで見つかった順序で割り当てられます。これは、hostnamesファイルが明示的に指定された場合のデフォルトです。 ホスト名に使用できるのは、文字（a〜z）、数字（0〜9）、および「-」のみです。選択したプラットフォームによっては、FQDNの場合があります。ホスト名は小文字にする必要があります。大文字は内部で小文字に変換され、 config.yml（たとえば、 ``upstream: hostname`` ）でこれらのホスト名への参照は小文字バージョンを使用する必要があります。 ソフトウェアの選択 ------------------ 配布 ^^^^ ``--distribution `` を指定してディストリビューションを選択します。 選択したプラットフォームによって、使用可能なディストリビューションと、デフォルトで使用されるディストリビューションが決まります。 一般に、「Debian」、「RedHat」、「Ubuntu」、および「SLES」を使用して、適切なイメージを選択できるはずです。 このオプションは、TPAがインストールするディストリビューションを制御できない「ベア」プラットフォームでは意味がありません。 2ndQuadrantおよびEDBリポジトリ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TPAは、サブスクリプションを通じてアクセスできる2ndQuadrantまたはEDBソフトウェアリポジトリを有効にできます。 デフォルトでは、 2ndQuadrantパブリックリポジトリ（サブスクリプションは必要ありません）をインストールし、アーキテクチャに必要な製品リポジトリ（PGDリポジトリなど）を追加します。 TPAが2ndQuadrantおよびEDBリポジトリを使用する方法のより詳細な説明が利用可能です :ref:`TPAをインストールする場所 ` ``--2Q-repositories source/name/maturity …`` または\ ``--edb-repositories repository …`` を指定して、 2ndQuadrantパブリックリポジトリに加えて、各インスタンスにインストールする2ndQuadrantまたはEDBリポジトリの完全なリストを指定します。 EDBリポジトリが指定されている場合、 2ndQuadrantリポジトリは無視されます。 このオプションは注意して使用してください。 TPAは、組み合わせが適切であることを確認せずに、名前付きリポジトリを構成します。 これらのオプションを使用するには、tpaexecを実行する前に\ ``export TPA_2Q_SUBSCRIPTION_TOKEN=xxx`` または\ ``export EDB_SUBSCRIPTION_TOKEN=xxx`` を行う必要があります。 2ndQuadrantポータルの左側メニュー「Company info」→「Company」から2ndQuadrantトークンを取得できます。 enterprisedb.com/reposからEDBトークンを取得できます。 ローカルリポジトリのサポート ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--enable-local-repo`` を使用して、パッケージをターゲットインスタンスに配布するローカルパッケージリポジトリを作成します。 ネットワークアクセスが制限されている環境では、代わりに ``--use-local-repo-only`` を使用してローカルリポジトリを作成し、ターゲットインスタンス上の他のすべてのパッケージリポジトリを無効にして、パッケージがローカルリポジトリからのみインストールされるようにすることができます。 :ref:`ローカルリポジトリのサポート <ローカルリポジトリのサポート>` に関するページに詳細があります。 ソフトウェアバージョン ^^^^^^^^^^^^^^^^^^^^^^ Postgresのフレーバーとバージョン ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TPAは、PostgreSQL、 EDB Postgres Extended、およびEDB Postgres Advanced Server （EPAS）バージョン11〜16をサポートしています。 インストールする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`` はEPAS 15を非Redwoodモードでインストールします EPASをインストールする場合は、 ``--redwood`` または\ ``--no-redwood`` モードで動作するかどうか、つまり、Oracle互換性機能を有効または無効にするかどうかを指定する必要があります。 EDB Postgres ExtendedまたはPostgres Advanced Serverをインストールするには、有効な :ref:`EDB repository subscription ` が必要です。 パッケージバージョン ^^^^^^^^^^^^^^^^^^^^ デフォルトでは、常にすべてのパッケージの最新バージョンをインストールします。これは通常、望ましい動作ですが、一部のテストシナリオでは、次のオプションのいずれかを使用して特定のパッケージバージョンを選択する必要がある場合があります。 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*'`` 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``\ でワイルドカードを使用すると、RHEL8以降（またはRockyLinuxなどのdnfを使用する派生OS）を使用するノードで\ ``tpaexecdeploy``\ 中にインストールされたソフトウェアが予期せず更新される可能性があることに注意してください。パッケージが既にインストールされている既存のクラスターでdeployが実行されると、ansibleは完全なパッケージバージョンと一致しない場合があります。たとえば、\ ``bdr_package_version``\ の値が\ ``3.6*`` に設定されていた場合、ansibleはこれをインストールされているPGDバージョンと照合できません。パッケージがインストールされていないと想定し、次のパッケージで利用可能な最新バージョンをインストールしようとします。構成されたリポジトリ内の同じ名前、例3.7。 この制限はansible dnfモジュールのバグとして認識しており、TPAの将来のリリースでこれに対処したいと考えています。 ソースからのビルドとインストール ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``--install-from-source postgres`` を指定すると、Postgresはパッケージからインストールされるのではなく、gitリポジトリからビルドされてインストールされます。 ``postgres`` の代わりに\ ``2ndqpostgres`` を使用して、2ndQPostgresをビルドおよびインストールします。デフォルトでは、これにより適切な\ ``REL_nnn_STABLE`` ブランチがビルドされます。 ``--install-from-source 2ndqpostgres pglogical3 bdr3`` を使用して3つすべてのコンポーネントをソースからビルドしてインストールするか、 ``--install-from-source pglogical3 bdr3`` を使用して2ndQPostgresのパッケージを使用できますが、ソースからpglogical v3およびPGD v3をビルドしてインストールします。デフォルトでは、これによりpglogicalおよびPGDの\ ``master`` ブランチがビルドされます。 別のブランチをビルドするには、対応する引数に\ ``: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ファイルを比較して、すべてのオーバーライドの効果を理解することをお勧めします。 アンシブルタワー ---------------- ``--use-ansible-tower`` および ``--tower-git-repository`` オプションを使用して、Ansible Towerでのデプロイメントに適したクラスターを作成します。詳細は :ref:`TPA and Ansible Tower/Ansible Automation Controller ` を参照。 gitリポジトリ ------------- デフォルトでは、 gitリポジトリはクラスターの名前が付けられた最初のブランチで作成され、コミットメッセージで使用した構成オプションを使用して単一のコミットが行われます。 ``$PATH`` にgitがない場合、tpaexecはエラーを発生しませんが、リポジトリは作成されません。 gitリポジトリの作成を抑制するには、 ``--no-git`` オプションを使用します。 (Ansible Towerクラスターでは、gitリポジトリーが必要であり、まだ存在しない場合は\ ``tpaexec provision`` によって後で作成されることに注意してください。) 例 -- 次のコマンドを実行するとどうなるかを見てみましょう。 .. code:: bash [tpa]$ tpaexec configure ~/clusters/speedy --architecture M1 \ --num-cascaded-replicas 2 --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 ~/clusters/speedy total 8 drwxr-xr-x 2 ams ams 4096 Aug 4 16:23 commands - rw-r--r-- 1 ams ams 1374 Aug 4 16:23 config.yml lrwxrwxrwx 1 ams ams 51 Aug 4 16:23 deploy.yml -> /home/ams/work/2ndq/TPA/architectures/M1/deploy.yml クラスター構成はconfig.ymlにあり、その近隣は直接対話する必要のないアーキテクチャ固有のサポートファイルへのリンクです。構成は次のとおりです。 .. code:: yaml - -- architecture: M1 cluster_name: speedy cluster_tags: {} cluster_rules: - cidr_ip: 0.0.0.0/0 from_port: 22 proto: tcp to_port: 22 - cidr_ip: 10.33.76.176/28 from_port: 0 proto: tcp to_port: 65535 - cidr_ip: 10.33.148.240/28 from_port: 0 proto: tcp to_port: 65535 ec2_ami: Name: debian-10-amd64-20210721-710 Owner: 136693071363 ec2_instance_reachability: public ec2_vpc: us-east-1: Name: Test cidr: 10.33.0.0/16 cluster_vars: enable_pg_backup_api: false failover_manager: repmgr postgres_flavour: postgresql postgres_version: 14 preferred_python_version: python3 use_volatile_subscriptions: false locations: - Name: main az: us-east-1a region: us-east-1 subnet: 10.33.76.176/28 - Name: dr az: us-east-1b region: us-east-1 subnet: 10.33.148.240/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: upsets backup: kayak location: main node: 1 role: - primary - Name: zebra location: main node: 2 role: - replica upstream: upsets - Name: kayak location: main node: 3 role: - barman - log-server - monitoring-server - witness upstream: upsets volumes: - device_name: /dev/sdf encrypted: true vars: volume_for: barman_data volume_size: 128 volume_type: gp2 - Name: queen location: dr node: 4 role: - replica upstream: zebra - Name: knock location: dr node: 5 role: - replica upstream: zebra 次のステップは、 :ref:`tpaexec provision ` を実行することです または、 :ref:`the cluster as a whole ` の構成をカスタマイズする方法または :ref:`individual instance ` を構成する方法の詳細を学んでください。