Cluster configuration#

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

クイックスタート#

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

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

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

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

構成オプション#

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

アーキテクチャ、たとえば: M1 または BDR-Always-ON を選択するには、次の引数が--architecture <name>

である必要があります。アーキテクチャの完全なリストについては、tpaexec info architectures を実行してください。

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

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

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

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

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

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

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

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

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

プラットフォームの選択は、特定のオプションの解釈に影響を与えます。たとえば、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を編集して、複数のリージョンを指定する必要があります。

ネットワーク構成#

デフォルトでは、各クラスターは、選択したアーキテクチャに応じて、 CIDR範囲10.33.0.0/16 からランダムに選択された多数の/28 サブネットで構成されます。

--network 192.168.0.0/16 を指定して、別のネットワークからサブネットを割り当てます。

注 AWSクラスターでは、これはVPC CIDRに対応します。詳細については、: awscliを使用してボリューム属性を変更するドキュメントを参照してください。

--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 を使用して、ホスト名をまったくソートしません。この場合、ホスト名ファイルで見つかった順序で割り当てられます。これは、ホスト名ファイルが明示的に指定された場合のデフォルトです。

--cluster-prefixed-hostnames を使用して、各ホスト名がクラスターの名前で始まるようにします。これは、同じホストで複数のDockerクラスターを実行している場合、ホスト名の衝突を回避するのに役立ちます。

ホスト名には、文字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リポジトリを使用する方法のより詳細な説明が利用できます: TPAをインストールする場所

--2Q-repositories source/name/maturity … または--edb-repositories repository … を指定して、2ndQuadrantパブリックリポジトリに加えて、各インスタンスにインストールする2ndQuadrantまたはEDBリポジトリの完全なリストを指定します。

EDBリポジトリが指定されている場合、2ndQuadrantのEDBリポジトリは無視されます。

このオプションは注意して使用してください。 TPAは、組み合わせが適切であることを確認せずに名前付けリポジトリを構成します。

これらのオプションを使用するには、 tpaexecを実行する前にexport TPA_2Q_SUBSCRIPTION_TOKEN=xxx またはexport EDB_SUBSCRIPTION_TOKEN=xxx を行う必要があります。 2ndQuadrantトークンは、2ndQuadrantポータルの左側メニューの[会社情報]、[会社]の下から取得できます。 EDBトークンは、enterprisedb.com/reposから取得できます。

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

--enable-local-repo を使用して、パッケージをターゲットインスタンスにシップするローカルパッケージリポジトリを作成します。

ネットワークアクセスが制限されている環境では、代わりに--use-local-repo-only を使用してローカルリポジトリを作成し、ターゲットインスタンスで他のすべてのパッケージリポジトリを無効にして、パッケージがローカルリポジトリからのみインストールされるようにできます。

ローカルリポジトリのサポートに関するページに詳細が記載されています。

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

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

TPAは、 PostgreSQL、 EDB Postgres Extended、およびEDB Postgres Advanced Server ServerEPASバージョン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 は、非RedwoodモードでEPAS 15をインストールします

EPASをインストールする場合、--redwood または--no-redwood モードで動作するかどうか、つまりOracle互換性機能を有効にするか無効にするかを指定する必要があります。

EDB Postgres ExtendedまたはPostgres Advanced Serverのインストールには、有効な EDB repository subscription が必要です。

パッケージバージョン#

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

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

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リポジトリからビルドおよびインストールされます。 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ファイルを比較して、すべてのオーバーライドの効果を理解することをお勧めします。

Ansible Tower#

--use-ansible-tower および--tower-git-repository オプションを使用して、Ansible Towerでの展開に適応したクラスターを作成します。詳細は、 Ansible Tower を参照してください。

ビーコンエージェント#

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

例#

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

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

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

$ 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

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

または、 the cluster as a whole の構成をカスタマイズする方法または: individual instance の構成方法の詳細を参照してください。

Cluster configuration

目次