Cluster configuration

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

クイックスタート

[tpa]$ tpaexec configure ~/clusters/speedy --architecture M1 \
        --postgresql 14

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

このコマンドは、構成を変更するためのさまざまなオプション（選択したアーキテクチャまたはプラットフォームに固有のオプション）も受け入れますが、デフォルトは賢明であり、すぐに使用できることを目的としています。生成されたconfig.ymlを読んで、ニーズに合わせて構成を微調整することをお勧めします。 （こちらがconfiguration settings that affect the deploymentの概要です。）

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

構成オプション

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

アーキテクチャ、 configuration settings that affect the deployment または M1 を選択するには、次の引数を --architecture <name> にする必要があります。アーキテクチャの完全なリストについては、tpaexec info architectures を実行してください。

次に、インストールするflavour and version of Postgresを指定する必要があります。

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

一般的なオプションのリストについては、 tpaexec help configure-options を実行してください。

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

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

たとえば、 M1 では --num-cascaded-replicas 3 を使用して、3つのカスケードレプリカでクラスターを作成できます。受け入れる（または、場合によっては必要とする）オプションのリストについては、アーキテクチャのドキュメントを参照してください。

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

次に、 --platform <name> を使用して、 BDR-Always-ON または

flavour and version of Postgres などのプラットフォームを選択できます。

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

プラットフォームの選択は、特定のオプションの解釈に影響します。たとえば、awsを選択した場合、 --region <region> および--instance-type <type> への引数は有効な 認証情報に関する奇妙なAWSエラー でなければなりません

そして bare(-metal servers)

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

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

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

所有者

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

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

地域

--region <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に対応します。詳細については、 AWS region name ドキュメントを参照してください。

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

--no-shuffle-subnets を指定して、ランダム化なしでネットワークCIDR範囲の先頭からサブネットを割り当てます（例、10.33.0.0/28 、10.33.0.16/28 など）。

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

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

インスタンスタイプ

インスタンスタイプを選択するには--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 として設定されます。

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

選択したプラットフォームによって、使用可能なディストリビューションと、デフォルトで使用されるディストリビューションが決まります。

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

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

2ndQuadrantおよびEDBリポジトリ

TPAは、サブスクリプションを通じてアクセスできる2ndQuadrantまたはEDBソフトウェアリポジトリを有効にできます。

デフォルトでは、 2ndQuadrantパブリックリポジトリ（サブスクリプションは必要ありません）をインストールし、アーキテクチャに必要な製品リポジトリ（PGDリポジトリなど）を追加します。

TPAが2ndQuadrantおよびEDBリポジトリを使用する方法のより詳細な説明が利用可能です

EC2 instance type

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

認証情報に関する奇妙なAWSエラー に関するページに詳細があります。

ソフトウェアバージョン

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

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

インストールする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をインストールするには、有効な TPAをインストールする場所 が必要です。

パッケージバージョン

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

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でのデプロイメントに適したクラスターを作成します。詳細はAnsible Towerを参照してください。

gitリポジトリ

デフォルトでは、 gitリポジトリはクラスターの名前が付けられた最初のブランチで作成され、コミットメッセージで使用した構成オプションを使用して単一のコミットが行われます。 $PATH にgitがない場合、tpaexecはエラーを発生しませんが、リポジトリは作成されません。 gitリポジトリの作成を抑制するには、 --no-git オプションを使用します。 (Ansible Towerクラスターでは、gitリポジトリーが必要であり、まだ存在しない場合はtpaexec provision によって後で作成されることに注意してください。)

例

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

[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
[tpa]$

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

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

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

次のステップは、 ローカルリポジトリのサポート を実行することです

または、 EDB repository subscription の構成をカスタマイズする方法または

tpaexec provision を構成する方法の詳細を学んでください。