Cluster configuration#

tpaexec configure コマンドは、プロビジョニング/展開/テストサイクルの後続のステージで必要なYAMLクラスター構成ファイルを生成します。

クイックスタート#

tpaexec configure ~/clusters/speedy --architecture M1 \
        --postgresql 14 \
        --failover-manager repmgr

このコマンドは、 ~/clusters/speedy という名前のディレクトリを作成し、 M1という名前のアーキテクチャのレイアウトに従うconfig.yml という名前の構成ファイルを生成します。シングルプライマリ、Nレプリカ。新しいディレクトリにgitリポジトリを作成し、生成されたconfig.yml を含む初期コミットを作成します。

また、コマンドは、構成を変更するためのさまざまなオプション選択したアーキテクチャまたはプラットフォームに固有の一部を受け入れますが、デフォルトは賢明で、すぐに使用できるように設計されています。生成されたconfig.ymlを読み、ニーズに合わせて構成を微調整することをお勧めします。 (これが Instance configuration の概要です。)

config.ymlを完全に手動で書くことも可能ですが、生成されたファイルを編集するほうが簡単です。

構成オプション#

最初の引数は、クラスターディレクトリ、たとえば、speedy または~/clusters/speedy である必要があります。クラスターの名前は、どちらの場合もspeedyになります。すべてのクラスターを共通のディレクトリたとえば、上記の例では~/clusters に保持することをお勧めします。

アーキテクチャ、たとえば M1 、 BDR-Always-ON 、または PGD-X を選択するには、次の引数が--architecture <name> である必要があります。アーキテクチャの完全なリストについては、tpaexec info architectures を実行してください。

次に、インストールする Postgresのフレーバーとバージョンを指定する必要があります。

上記の引数は常に必須です。上記の例のように、ここで説明するオプションの残りの部分は安全に省略できます。デフォルトでは使用可能な結果が得られます。

共通オプションのリストについては、 tpaexec help configure-options を実行します。

アーキテクチャ固有のオプション#

選択したアーキテクチャにより、他のどのオプションが受け入れられるかが決まります。通常、各アーキテクチャは、いくつかの一意のオプションと以下で説明する汎用オプションを受け入れます。

たとえば、M1では --location-names l1 l2 を使用して、2つの名前付けの場所にノードを含むクラスターを作成できます。アーキテクチャが受け入れるオプションのリストについては、アーキテクチャのドキュメントを参照してください。または、場合によっては必要となります。

プラットフォームオプション#

次に、 --platform <name> を使用してプラットフォーム、たとえば awscliを使用してボリューム属性を変更するまたは bare(-metal servers) を選択できます。

アーキテクチャは特定のプラットフォームをサポートする場合と、サポートしない場合があります。そうしない場合、クラスターの構成に失敗します。

プラットフォームの選択は、特定のオプションの解釈に影響を与えます。たとえば、awsを選択した場合、--region <region> および--instance-type <type> への引数は有効な AWS region name である必要があります

と EC2 instance type

それぞれ。詳細については、プラットフォームのドキュメントを参照してください。

プラットフォームを明示的に選択しない場合、現在デフォルトはawsです。

注 TPAは、さまざまなプラットフォーム上のインスタンスを使用したクラスターの作成を完全にサポートしていますが、 tpaexec configure は現在このような構成を生成できません。 config.ymlを編集して、複数のプラットフォームを指定する必要があります。

所有者#

--owner <name> を指定して、クラスターを何らかのプラットフォーム固有の手段AWSタグなどで関連付けるには、クラスターに責任を負う人の名前を関連付けます。これは、クラウドプラットフォームにとって特に重要です。デフォルトでは、所有者はtpaexec provision を実行しているユーザーのログイン名に設定されます。

あなたのイニシャル、または「名、姓」、またはあなたを一意に識別するその他のものを使用できます。

リージョン#

--region <region> を指定してリージョンを選択します。

このオプションは、クラウドプラットフォームの場合にのみ意味があります。 AWSのデフォルトはeu-west-1です。

注 TPAは、マルチプルのリージョンにまたがるクラスターの作成を完全にサポートしていますが、 tpaexec configure は現在このような構成を生成できません。 config.ymlを編集して、複数のリージョンを指定する必要があります。

ネットワーク構成#

注釈

これらのオプションは、TPAが既存のサーバーのネットワーク構成を変更しない「ベア」プラットフォームでは意味がありません。

--network 192.168.0.0/16 を指定して、別のネットワークからサブネットを割り当てます。 AWSクラスターでは、これはVPC CIDRに対応します。詳細については、 awscliを使用してボリューム属性を変更するドキュメントを参照してください。

--subnet-prefix 26 を指定して、別のサイズのサブネット、この場合は/28ではなく/26のサブネットを割り当てます。

注釈

"docker"プラットフォームが選択されている場合、TPAはアーキテクチャに関係なく、常にクラスター全体を単一のサブネットに配置します。このサブネットは、ここで説明するロジックに従って生成されますが、 subnet-prefix が指定されない場合、TPAは`config.yaml` のインスタンス数に対応するのに十分な大きさのサブネットサイズを自動的に選択します。

--exclude-subnets-from <directory> を指定して、既存のクラスターconfig.ymlファイルで既に使用されているサブネットを除外します。この引数は、ディレクトリごとに複数回指定できます。

インスタンスタイプ#

--instance-type <type> を指定してインスタンスタイプを選択します。

このオプションは、クラウドプラットフォームの場合にのみ意味があります。 AWSのデフォルトはt3.microです。

ディスク領域#

--root-volume-size 64 を指定して、ルートボリュームのサイズをGB単位で設定します。プラットフォームによっては、ルートボリュームに必要な最小サイズが存在する場合があります。

--postgres-volume-size <size> および--barman-volume-size <size> オプションは、 PostgresとBarmanの個別のボリュームをサポートするアーキテクチャとプラットフォームで、 PostgresおよびBarmanボリュームのサイズを設定するために使用できます。

これらのオプションは、TPAがボリュームサイズを制御できない「ベア」プラットフォームでは意味がありません。

ホスト名#

デフォルトでは、tpaexec configure は、数十の名前の事前承認リストから必要な数のホスト名をランダムに選択します。ほとんどのクラスターではこれで十分です。

--hostnames-from <filename> を指定して、1行に1つの名前を含むファイルからホスト名を選択します。ファイルには、クラスター内のインスタンスと同じ数以上の有効なホスト名が含まれている必要があります。各行には、名前の後にオプションのIPアドレスを含めることができます。存在する場合、このアドレスはconfig.yml の対応するインスタンスのip_address として設定されます。 2つのIPアドレスが存在する場合、1つ目はpublic_ip として設定され、2つ目はprivate_ip として設定されます。

注釈

ホスト名ファイルを介してか`config.yml` で直接IPアドレスを明示的に指定する場合、それらがクラスターネットワークのCIDR範囲内にあることを確認する必要があります。 DockerおよびAWSプラットフォームの場合、これは、IPアドレスを指定する場合にネットワーク構成必要があることを意味します。

クラスターネットワークCIDRレンジを指定しない場合、TPAは、指定されたIPアドレスを参照せずにランダムに1つを選択します。これにより、展開が失敗するか、予想したものとは異なるIPアドレスのクラスターが発生します。

--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 <name> を指定してディストリビューションを選択します。

選択したプラットフォームにより、どのディストリビューションが利用可能か、およびデフォルトで使用されるディストリビューションが決まります。

一般に、「Debian」、「RedHat」、「Ubuntu」、および「SLES」を使用して、適切なイメージを選択できる必要があります。

オプションで、--os-version <version number> を渡すことにより、ディストリビューションのバージョンを含めることができます。

このオプションは、TPAがどのディストリビューションをインストールするかを制御できない「ベア」プラットフォームでは意味がありません。

EDBリポジトリ#

TPAは、サブスクリプションを介してアクセスしているEDBソフトウェアリポジトリを有効にできます。デフォルトでは、TPAはアーキテクチャが必要とする製品リポジトリをインストールします。

TPAがEDBリポジトリを使用する方法の詳細な説明は、 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 を使用してローカルリポジトリを作成し、ターゲットインスタンスで他のすべてのパッケージリポジトリを無効にして、パッケージがローカルリポジトリからのみインストールされるようにできます。

Creating and using a local repository に関するページに詳細が記載されています。

ソフトウェアバージョン#

Postgresのフレーバーとバージョン#

TPAは、 PostgreSQL、 EDB Postgres Extended、およびEDB Postgres Advanced Serverバージョン13〜18をサポートしています。

インストールする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のインストールには、有効な Configuring EDB Repos 2.0 repositories が必要です。

パッケージバージョン#

デフォルトでは、常にすべてのパッケージの最新バージョンをインストールします。これは通常、望ましい動作ですが、一部のテストシナリオでは、次のオプションのいずれかを使用して特定のパッケージバージョンを選択する必要がある場合があります。

--postgres-package-version 10.4-2.pgdg90+1
--repmgr-package-version 4.0.5-1.pgdg90+1
--barman-package-version 2.4-1.pgdg90+1
--pglogical-package-version '2.2.0*'
--bdr-package-version '3.0.2*'
--pgbouncer-package-version '1.8*'
--beacon-agent-package-version 1.56.2-1
--etcd-package-version 9.8.0-1.el8
--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での展開に適応したクラスターを作成します。詳細は、 TPA and Ansible Tower/Ansible Automation Platform を参照してください。

PGAIエージェント#

--enable-beacon-agent および--beacon-agent-project-id オプションを使用して、PGAIエージェントbeacon-agent としてパッケージ化されます。これにより、 EDB Postgres AIコンソールでクラスターを表示できます。詳細は、 Configuring the PGAI 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 <cluster_dir> を介して表示できます。

セキュリティ基準へのコンプライアンス#

--compliance stig または--compliance cis オプションを使用して、STIGまたはCIS標準に準拠するのに適した構成でクラスターを生成します。詳細は、セキュリティ基準へのコンプライアンスを参照してください。これらのオプションは、クラスターが関連する標準を満たすことを保証するものではないことに注意してください。これらは、TPAによって制御可能な標準のこれらの側面に準拠するように設計された構成をTPAに生成するだけです。

例#

次のコマンドを実行するとどうなるか見てみましょう。

tpaexec configure ~/clusters/speedy --architecture M1 \
        --distribution Debian \
        --os-version 12 \
        --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

出力はないため、エラーはありません。クラスターディレクトリが作成され、データが設定されました。

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にあり、その近傍は直接対話する必要のないアーキテクチャ固有のサポートファイルへのリンクです。構成は次のとおりです。

- --
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

次のステップは、 tpaexec provision を実行することです

または、クラスター構成の構成をカスタマイズする方法または Instance configuration の構成方法の詳細を参照してください。

Cluster configuration

目次

Cluster configuration#

クイックスタート#

構成オプション#

アーキテクチャ固有のオプション#

プラットフォームオプション#

所有者#

リージョン#

ネットワーク構成#

インスタンスタイプ#

ディスク領域#

ホスト名#

ソフトウェアの選択#

ディストリビューション#

EDBリポジトリ#

ローカルリポジトリのサポート#

ソフトウェアバージョン#

Postgresのフレーバーとバージョン#

パッケージバージョン#

ワイルドカードの使用に関する既知の問題#

ソースからのビルドとインストール#

オーバーライド#

Ansible Tower#

PGAIエージェント#

Gitリポジトリ#

ボールトパスワードのキーリングバックエンド#

セキュリティ基準へのコンプライアンス#

例#