Labels and Annotations

Kubernetesのリソースはフラット構造で編成され、階層情報やそれらの間の関係はありません。ただし、このようなリソースとオブジェクトは、 ラベル と アノテーション を介してリンクし、関係にすることができます。

注釈

詳細については、 annotations および labels に関するKubernetesドキュメントを参照してください。

簡単に言うと

  • アノテーションは、外部ツールとの統合を促進することを目的に、追加の非識別情報をリソースに割り当てるために使用されます。

  • ラベルは、オブジェクトをグループ化し、Kubernetesネイティブセレクター機能を介して照会するために使用されます。

CloudNativePG展開で使用する1つ以上のラベルまたはアノテーションを選択できます。次に、クラスターのメタデータでこれらのラベルまたはアノテーションを定義すると、それによって作成されたすべてのリソースポッドを含むすべてに継承されるようにオペレーターを構成する必要があります。

注釈

ラベルとアノテーションの継承は、ポッドテンプレートなどの代替アプローチの代わりにCloudNativePGによって採用された技術です。

事前定義されたラベル

CloudNativePGは、次の事前定義されたラベルを管理します。

cnpg.io/backupDate

ISO 8601形式YYYYMMDD のバックアップの日付。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupName

バックアップ識別子。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupMonth

バックアップが取られた年/月。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupTimeline

バックアップが作成されたときのインスタンスのタイムライン。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupYear

バックアップが取られた年。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/cluster

クラスターの名前。

cnpg.io/immediateBackup

バックアップがimmediate がtrue に設定されているScheduledBackup オブジェクトから作成された最初のバックアップである場合、 Backup リソースに適用されます。

cnpg.io/instanceName

PostgreSQLインスタンスの名前古い非推奨のpostgresql ラベルを置き換えます。

cnpg.io/jobRole

ジョブのロールつまり import 、initdb 、join , …

cnpg.io/majorVersion

バックアップのデータディレクトリの整数PostgreSQLメジャーバージョンたとえば 17 。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/onlineBackup

バックアップがオンラインであるかホットか、Postgresがダウンしているときに取得されたコールドかどうか。このラベルは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/podRole

プーラー展開専用のポッドとデータベースインスタンスに使用されるポッドを区別します。

cnpg.io/poolerName

PgBouncerプーラーの名前。

cnpg.io/pvcRole

PG_DATA やPG_WAL などのPVCの目的。

cnpg.io/reload

ConfigMap およびSecret リソースで使用できます。 true に設定されている場合、リソースの変更はオペレーターによって自動的にリロードされます。

cnpg.io/userType

Secret 、superuser Postgresスーパーユーザーアクセスまたはapp CloudNativePG用語でアプリケーションレベルのユーザーのいずれかに関連付けられているPostgreSQLユーザーのタイプを指定し、CloudNativePGによって作成されたデフォルトユーザー通常はpostgres およびapp に制限されます。

role - 非推奨

ポッドで実行されているインスタンスがprimary またはreplica かどうか。このラベルは非推奨です。代わりにcnpg.io/instanceRole を使用する必要があります。

cnpg.io/scheduled-backup

使用可能な場合、特定のBackup オブジェクトを作成したScheduledBackup リソースの名前。

cnpg.io/instanceRole

ポッドで実行されているインスタンスがprimary またはreplica かどうか。

app.kubernetes.io/managed-by

マネージャーの名前。常にcloudnative-pg になります。すべてのCloudNativePG管理対象リソースで利用できます。

app.kubernetes.io/name

アプリケーションの名前。常にpostgresql になります。ポッド、ジョブ、展開、サービス、持続的ボリュームクレーム、ボリュームスナップショット、podDisruptionBudgets、podMonitorsで使用できます。

app.kubernetes.io/component

コンポーネントの名前 database 、pooler 、… 。ポッド、ジョブ、展開、サービス、持続的ボリュームクレーム、ボリュームスナップショット、podDisruptionBudgets、podMonitorsで使用できます。

app.kubernetes.io/instance

所有するCluster リソースの名前。ポッド、ジョブ、展開、サービス、volumeSnapshot、podDisruptionBudget、podMonitorで使用できます。

app.kubernetes.io/version

PostgreSQLのメジャーバージョン。ポッド、ジョブ、サービス、volumeSnapshot、podDisruptionBudget、podMonitorで使用できます。

事前定義されたアノテーション

CloudNativePGは、次の事前定義されたアノテーションを管理します。

container.apparmor.security.beta.kubernetes.io/*

名前付けたコンテナに適用するAppArmorプロファイルの名前。 AppArmorを使用してポッドアクセスを制限する を参照

詳細については。

cnpg.io/backupEndTime

バックアップが終了した時刻。このアノテーションは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupEndWAL

バックアップ終了後のWAL。このアノテーションは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/backupStartTime

バックアップが開始された時刻。

cnpg.io/backupStartWAL

バックアップの開始時のWAL。このアノテーションは、VolumeSnapshot リソースでのみ使用できます。

cnpg.io/coredumpFilter

ビットマスクで表現されるPostgresプロセスのコアダンプを制御するフィルター。デフォルトでは、ダンプから共有メモリセグメントを除外するように0x31 に設定されます。 PostgreSQLコアダンプ を参照

詳細については、

cnpg.io/clusterManifest

このリソースPVCなどを所有するCluster のマニフェスト。このラベルは、古い非推奨のcnpg.io/hibernateClusterManifest ラベルを置き換えます。

cnpg.io/fencedInstances

JSON形式で表現される、フェンスする必要があるインスタンスのリスト。リストに* 要素が含まれる場合、クラスター全体がフェンスされます。

cnpg.io/forceLegacyBackup

テスト目的のみでCluster リソースに適用され、 --name オプションが使用できなかったバージョン3.4 2023年1月より前のbarman-cloud-backup の動作をシミュレートします。

cnpg.io/hash

リソースのハッシュ値。

cnpg.io/hibernation

Cluster リソースに適用されて、 declarative hibernation feature を制御します。使用できる値はon およびoff です。

cnpg.io/managedSecrets

オペレーターが管理するシークレットをプルし、各PostgresクラスターのServiceAccount リソースに自動的に設定します。

cnpg.io/nodeSerial

ポッドリソースで、Postgresクラスター内のインスタンスのシリアル番号を識別します。

cnpg.io/operatorVersion

オペレーターのバージョン。

cnpg.io/pgControldata

pg_controldata コマンドの出力。このアノテーションは、古い非推奨のcnpg.io/hibernatePgControlData アノテーションを置き換えます。

cnpg.io/podEnvHash

cnpg.io/podSpec アノテーションにもポッド環境が含まれるようになったため、非推奨。

cnpg.io/podPatch

アノテーションはCluster リソースに適用できます。

JSONパッチ形式のパッチに設定されている場合、パッチはインスタンスポッドに適用されます。

⚠️警告 この機能は、オペレーターの予想とKubernetesの動作間の不一致を導入する可能性があります。最後の手段としてのみ使用してください。

重要 このアノテーションを追加または変更しても、生成されたポッドのローリング展開はトリガーされません。後者は、kubectl cnpg restart を使用してユーザーが手動でトリガーできます。

cnpg.io/podSpec

オペレーターによって生成されたポッドのspec のスナップショット。このアノテーションは、古い非推奨のcnpg.io/podEnvHash アノテーションを置き換えます。

cnpg.io/poolerSpecHash

プーラーリソースのハッシュ。

cnpg.io/pvcStatus

PVCの現在のステータス initializing 、ready 、またはdetached 。

cnpg.io/reconcilePodSpec

アノテーションをCluster またはPooler に適用して、再起動を防止できます。

Cluster でdisabled に設定されている場合、オペレーターはPodSpecの変更によるインスタンスが再起動しないようにします。これには、次の変更が含まれます。

  • トポロジまたはアフィニティ - スケジューラー - ボリュームまたはコンテナ

Pooler でdisabled に設定されている場合、オペレーターはspec.instances への変更を除き、展開仕様の変更を制限します。

cnpg.io/reconciliationLoop

Cluster でdisabled に設定されている場合、オペレーターは調整ループの実行を防止します。

cnpg.io/reloadedAt

最新のクラスターreload 時間が含まれています。 reload は、プラグインを介してユーザーによってトリガーされます。

cnpg.io/skipEmptyWalArchiveCheck

Cluster リソースでenabled に設定されている場合、オペレーターは、データを書き込む前にWALアーカイブが空であることを確認するチェックを無効にします。自分の責任で使用してください。

cnpg.io/skipWalArchiving

Cluster リソースでenabled に設定されている場合、オペレーターはWALアーカイブを無効にします。これにより、archive_mode がoff に設定され、すべてのPostgreSQLインスタンスの再起動が必要です。自分の責任で使用してください。

cnpg.io/snapshotStartTime

スナップショットが開始された時刻。

cnpg.io/snapshotEndTime

スナップショットが使用する準備ができているとマークされた時間。

cnpg.io/validation

CloudNativePG管理のカスタムリソースでdisabled に設定されている場合、検証Webhookは制限なしですべての変更を許可します。

⚠️警告 検証を無効にすると、安全でないまたは破壊的な操作が許可される場合があります。この設定は、自己の責任で注意して使用してください。

cnpg.io/volumeSnapshotDeadline

Backup およびScheduledBackup リソースに適用され、ボリュームのスナップショットのバックアップが失敗したと見なす前に、オペレーターが回復可能なエラーを再試行する時間を制御できます。分単位、デフォルト10

kubectl.kubernetes.io/restartedAt

利用可能な場合、最後にPostgresクラスターの再起動が要求された時間。

alpha.cnpg.io/unrecoverable

PostgreSQLインスタンスを実行しているPod に適用される実験的なアノテーション。 Pod およびそれに関連するすべてのPVCを削除するようにオペレーターに指示します。インスタンスは、構成された参加戦略に従って再作成されます。このアノテーションは、現在のプライマリでも指定されたターゲットプライマリでもないインスタンスでのみ使用できます。

前提条件

デフォルトでは、クラスターのメタデータで定義されたラベルまたはアノテーションは、関連付けられたリソースに継承されません。ラベル/アノテーションの継承を有効にするには、 Operator configuration で提供されている手順に従ってください。

以下はその例の続きであり、次のことに制限します。

  • アノテーション categories

  • ラベル app 、environment 、およびworkload

注釈

注釈とラベルの両方に、コンテキストに最も適した名前を自由に選択してください。名前付けにワイルドカードを使用し、すべてのラベルに`mycompany/*` を使用したり、mycompany/ で始まるアノテーションを継承するように設定したりするなどの戦略を採用することもできます。

クラスターのメタデータの定義

クラスターを定義するときに、リソースがデプロイされる前に、次のようにメタデータを設定できます。

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
  annotations:
    categories: database
  labels:
    environment: production
    workload: database
    app: sso
spec:
     # ... <snip>

クラスターが展開されると、たとえば、ポッドにラベルが正しく設定されたことを確認できます。

kubectl get pods --show-labels

現在の制限

現在、CloudNativePGは、ラベルまたはアノテーションの削除を自動的に伝播しません。したがって、以前に基になるポッドに伝播されたクラスターからアノテーションまたはラベルが削除される場合、オペレーターは、関連するリソースでそれを削除しません。