6.6. サービスからバインディングデータの公開
アプリケーション開発者は、ワークロードをビルドして接続するバッキングサービスへのアクセスが必要です。ワークロードをバッキングサービスに接続するのは、サービスプロバイダーごと、シークレットにアクセスしてワークロードで消費するのに必要となる方法が異なるので、困難です。
サービスバインディング Operator を使用すると、アプリケーション開発者は、手作業でバインディング接続を設定する手順なしに、オペレーターが管理するバッキングサービスとワークロードを簡単にバインドできます。サービスバインディングオペレーターがバインディングデータを提供するには、オペレータープロバイダーまたはバッキングサービスを作成するユーザーが、サービスバインディングオペレーターによって自動的に検出されるようにバインディングデータを公開する必要があります。次に、サービスバインディング Operator は、バッキングサービスからバインディングデータを自動的に収集し、ワークロードと共有して、一貫性のある、予測可能なエクスペリエンスを提供します。
6.6.1. バインディングデータを公開する方法
本セクションでは、バインディングデータの公開に使用できる方法について説明します。
ワークロードの要件や環境、および提供されるサービスとの連携方法を理解しておくようにしてください。
バインディングデータは以下の状況下で公開されます。
バッキングサービスは、プロビジョニングされたサービスリソースとして利用できます。
接続するサービスはサービスバインディング仕様に準拠するものになります。必要なバインディングデータ値すべてを使用して
Secretリソースを作成し、バッキングサービスカスタムリソース (CR) で参照する必要があります。すべてのバインディングデータ値の検出は自動的に実行されます。バッキングサービスは、プロビジョニングされたサービスリソースとしては利用できません。
バッキングサービスからバインディングデータを公開する必要があります。ワークロード要件および環境に応じて、以下のいずれかの方法でバインディングデータを公開することができます。
- 直接のシークレット参照
- カスタムリソース定義 (CRD) または CR アノテーションを使用したバインディングデータの宣言
- 所有リソースによるバインディングデータの検出
6.6.1.1. プロビジョニングされたサービス
プロビジョニングされたサービスは、バッキングサービス CR の .status.binding.name フィールドに配置された Secret リソースへの参照のあるバッキングサービス CR を表します。
Operator プロバイダーまたは、バッキングサービスを作成するユーザーが、Secret リソースを作成し、バッキングサービス CR の status.binding.name セクションでその CR を参照して、この方法を使用してサービスバインディング仕様に準拠できます。この Secret リソースは、バッキングサービスに接続するためにワークロードに必要なすべてのバインディングデータ値を指定する必要があります。
以下の例は、バッキングサービスおよび CR から参照される Secret リソースを表す AccountService CR を示しています。
例: AccountService CR
apiVersion: example.com/v1alpha1
kind: AccountService
name: prod-account-service
spec:
# ...
status:
binding:
name: hippo-pguser-hippo
例: 参照された Secret リソース
apiVersion: v1 kind: Secret metadata: name: hippo-pguser-hippo data: password: "<password>" user: "<username>" # ...
サービスバインディングリソースを作成するとき、次のように ServiceBinding仕様で AccountService リソースの詳細を直接指定できます。
ServiceBinding リソースの例
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: account-service
spec:
# ...
services:
- group: "example.com"
version: v1alpha1
kind: AccountService
name: prod-account-service
application:
name: spring-petclinic
group: apps
version: v1
resource: deployments
例: 仕様 API での ServiceBinding リソース
apiVersion: servicebinding.io/v1beta1
kind: ServiceBinding
metadata:
name: account-service
spec:
# ...
service:
apiVersion: example.com/v1alpha1
kind: AccountService
name: prod-account-service
workload:
apiVersion: apps/v1
kind: Deployment
name: spring-petclinic
この方法では、ワークロードにプロジェクションされるバインディングデータとして、Secret リソースを参照する hippo-pguser-hippo に、すべてのキーを公開します。
6.6.1.2. 直接のシークレット参照
サービスバインディング定義で参照できる Secret リソースで、必要なバインディングデータ値すべてが利用できる場合にこの手法使用できます。この方法では、ServiceBinding リソースは Secret リソースを直接参照し、サービスに接続します。Secret リソースの全キーがバインディングデータとして公開されます。
例: binding.operators.coreos.com API での仕様
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: account-service
spec:
# ...
services:
- group: ""
version: v1
kind: Secret
name: hippo-pguser-hippo
例: servicebinding.io API に準拠した仕様
apiVersion: servicebinding.io/v1beta1
kind: ServiceBinding
metadata:
name: account-service
spec:
# ...
service:
apiVersion: v1
kind: Secret
name: hippo-pguser-hippo
6.6.1.3. CRD または CR アノテーションによるバインディングデータを宣言する
この方法を使用して、バッキングサービスのリソースにアノテーションを付け、バインディングデータを特定のアノテーションで公開できます。metadata セクションにアノテーションを追加すると、バッキングサービスの CR および CRD が変更されます。サービスバインディング Operator は CR および CRD に追加されるアノテーションを検出し、アノテーションに基づいて抽出された値を使用して Secret リソースを作成します。
以下の例は、metadata セクションに追加されるアノテーションと、リソースから参照される ConfigMap オブジェクトを示しています。
例:CR アノテーションで定義される Secret オブジェクトからのバインディングデータの公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
# ...
上記の例では、hippo-pguser-hippo に解決する {.metadata.name}-pguser-{.metadata.name} テンプレートにシークレット名の名前を配置します。テンプレートには複数の JSONPath 表現を含めることができます。
例: リソースからの参照された Secret オブジェクト
apiVersion: v1 kind: Secret metadata: name: hippo-pguser-hippo data: password: "<password>" user: "<username>"
例:CR アノテーションで定義される ConfigMap オブジェクトからのバインディングデータの公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-config,objectType=ConfigMap'
# ...
上記の例では、hippo-config に解決する {.metadata.name}-config テンプレートに設定マップの名前を配置します。テンプレートには複数の JSONPath 表現を含めることができます。
例: リソースからの参照された ConfigMap オブジェクト
apiVersion: v1 kind: ConfigMap metadata: name: hippo-config data: db_timeout: "10s" user: "hippo"
6.6.1.4. 所有リソースによるバインディングデータの検出
バッキングサービスが、バインディングデータの検出に使用できるルート、サービス、設定マップ、シークレットなど、1 つ以上の Kubernetes リソースを所有している場合は、このメソッドを使用できます。この方法では、Service Binding Operator は、バッキングサービス CR が所有するリソースからバインディングデータを検出します。
次の例では、detectBindingResourcesAPI オプションが ServiceBindingCR で true に設定されています。
例
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: spring-petclinic-detect-all
namespace: my-petclinic
spec:
detectBindingResources: true
services:
- group: postgres-operator.crunchydata.com
version: v1beta1
kind: PostgresCluster
name: hippo
application:
name: spring-petclinic
group: apps
version: v1
resource: deployments
直前の例では、PostgresCluster カスタムリソースはルート、サービス、設定マップ、またはシークレットなどの 1 つ以上の Kubernetes リソースを所有します。
サービスバインディング Operator は、所有リソースごとに公開されるバインディングデータを自動的に検出します。
6.6.2. データモデル
アノテーションで使用されるデータモデルは、特定の規則に従います。
サービスバインディングアノテーションは、以下の規則を使用する必要があります。
service.binding(/<NAME>)?:
"<VALUE>|(path=<JSONPATH_TEMPLATE>(,objectType=<OBJECT_TYPE>)?(,elementType=<ELEMENT_TYPE>)?(,sourceKey=<SOURCE_KEY>)?(,sourceValue=<SOURCE_VALUE>)?)"ここでは、以下のようになります。
|
|
バインディング値を公開する名前を指定します。 |
|
|
|
データモデルは、path、elementType、objectType、sourceKey、および sourceValue パラメーターの許可される値とセマンティックの詳細を提供します。
| パラメーター | 説明 | デフォルト値 |
|---|---|---|
|
| 中かっこ {} で囲まれた JSONPath 表現で設定される JSONPath テンプレート。 | 該当なし |
|
|
|
|
|
|
|
|
|
|
バインディングデータを収集する際にバインディングシークレットに追加される 注記:
| 該当なし |
|
|
マップのスライスのキーを指定します。 注記:
| 該当なし |
sourceKey および sourceValue パラメーターは、path パラメーターで指定された要素が ConfigMap または Secret リソースを参照する場合にのみ適用されます。
6.6.3. アノテーションマッピングをオプションに設定する
アノテーションにはオプションのフィールドを含めることができます。たとえば、サービスエンドポイントが認証を必要としない場合、資格情報へのパスが存在しない可能性があります。このような場合、アノテーションのターゲットパスにフィールドが存在しない可能性があります。その結果、Service Binding Operator はデフォルトでエラーを生成します。
サービスプロバイダーは、アノテーションマッピングが必要かどうかを示すために、サービスを有効にするときにアノテーションに optional フラグの値を設定できます。Service Binding Operator は、ターゲットパスが使用可能な場合にのみ、アノテーションマッピングを提供します。ターゲットパスが利用できない場合、Service Binding Operator はオプションのマッピングをスキップし、エラーを出力することなく既存のマッピングの展開を続行します。
手順
アノテーションのフィールドをオプションにするには、
optionalフラグ値をtrueに設定します。例
apiVersion: apps.example.org/v1beta1 kind: Database metadata: name: my-db namespace: my-petclinic annotations: service.binding/username: path={.spec.name},optional=true # ...
-
optionalフラグ値をfalseに設定し、Service Binding Operator がターゲットパスを見つけることができない場合、Operator はアノテーションマッピングに失敗します。 -
optionalのフラグに値が設定されていない場合、サービスバインディング Operator はデフォルトで値をfalseと見なし、アノテーションマッピングに失敗します。
6.6.4. RBAC 要件
サービスバインディング Operator を使用してバッキングサービスバインディングデータを公開するには、特定のロールベースアクセス制御 (RBAC) パーミッションが必要になります。ClusterRole リソースの rules フィールドに特定の動詞を指定し、バッキングサービスリソースの RBAC パーミッションを付与します。これらの rules を定義すると、サービスバインディング Operator はクラスター全体でバッキングサービスリソースのバインディングデータを読み取ることができます。ユーザーにバインディングデータの読み取りまたはアプリケーションリソースの変更のパーミッションがない場合、サービスバインディング Operator はこのようなユーザーがサービスをアプリケーションにバインドできないようにします。RBAC 要件を順守することで、ユーザーの不要なパーミッション昇格を回避し、承認されていないサービスまたはアプリケーションへのアクセスを防ぎます。
サービスバインディング Operator は、専用のサービスアカウントを使用して Kubernetes API に対してリクエストを実行します。デフォルトでは、このアカウントはサービスをワークロードにバインドするためのパーミッションを持ち、共に以下の標準の Kubernetes または OpenShift オブジェクトで表されます。
-
デプロイメント -
DaemonSets -
ReplicaSet -
StatefulSets -
DeploymentConfig
Operator サービスアカウントは集約されたクラスターロールにバインドされ、Operator プロバイダーまたはクラスター管理者はワークロードへのカスタムサービスリソースのバインドを有効にできます。ClusterRole 内の必要なパーミッションを付与するには、これに servicebinding.io/controller フラグでラベルを付け、フラグの値を true に設定します。以下の例は、サービスバインディング Operator が Crunchy PostgreSQL Operator のカスタムリソース (CR) を 取得、監視、および 一覧表示 するのを許可する方法を示しています。
例:Crunchy PostgreSQL Operator によってプロビジョニングされる PostgreSQL データベースインスタンスへのバインディングの有効化
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: postgrescluster-reader
labels:
servicebinding.io/controller: "true"
rules:
- apiGroups:
- postgres-operator.crunchydata.com
resources:
- postgresclusters
verbs:
- get
- watch
- list
...
このクラスターロールは、バッキングサービス Operator のインストール時にデプロイできます。
6.6.5. 公開可能なバインディングデータのカテゴリー
サービスバインディング Operator を使用すると、バッキングサービスリソースおよびカスタムリソース定義 (CRD) からバインディングデータ値を公開できます。
本セクションでは、さまざまな公開可能なバインディングデータのカテゴリーを使用する方法を例とともに紹介します。これらのサンプルは、実際の環境と要件に合わせて変更する必要があります。
6.6.5.1. リソースからの文字列の公開
以下の例は、PostgresCluster カスタムリソース (CR) の metadata.name フィールドから文字列を公開する方法を示しています。
例
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding/username: path={.metadata.name}
# ...
6.6.5.2. 定数値のバインディング項目としての公開
以下の例は、PostgresCluster カスタムリソース (CR) から定数値を公開する方法を示しています。
例: 定数値の公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
"service.binding/type": "postgresql" 1
- 1
postgresql値で公開されるバインディングタイプ。
6.6.5.3. リソースから参照される設定マップまたはシークレット全体を公開する
以下の例では、シークレット全体をアノテーションにより公開する方法を説明します。
例: アノテーションによるシークレット全体の公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-pguser-{.metadata.name},objectType=Secret'
例: バッキングサービスリソースから参照されるシークレット
apiVersion: v1 kind: Secret metadata: name: hippo-pguser-hippo data: password: "<password>" user: "<username>"
6.6.5.4. リソースから参照される設定マップまたはシークレットから特定のエントリーを公開する
以下の例では、アノテーションにより設定マップから特定のエントリーを公開する方法を説明します。
例: アノテーションを使用した設定マップからのエントリーの公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding: 'path={.metadata.name}-config,objectType=ConfigMap,sourceKey=user'
例: バッキングサービスリソースから参照される設定マップ
バインディングデータには、名前が db_timeout、値が 10s のキーが必要です。
apiVersion: v1 kind: ConfigMap metadata: name: hippo-config data: db_timeout: "10s" user: "hippo"
6.6.5.5. リソース定義値の公開
以下の例は、リソース定義の値をアノテーションを使用して公開する方法を説明します。
例: アノテーションによるリソース定義値の公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
service.binding/username: path={.metadata.name}
...
6.6.5.6. コレクションのエントリーを、各エントリーのキーと値で公開する
以下の例は、アノテーションを使用して各エントリーのキーと値を持つコレクションのエントリーを公開する方法を示しています。
例: アノテーションによるコレクションのエントリーの公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
"service.binding/uri": "path={.status.connections},elementType=sliceOfMaps,sourceKey=type,sourceValue=url"
spec:
# ...
status:
connections:
- type: primary
url: primary.example.com
- type: secondary
url: secondary.example.com
- type: '404'
url: black-hole.example.com
以下の例では、1 つ前のアノテーションでのコレクションエントリーが、バインドされたアプリケーションにどのようにプロジェクションされるかを紹介します。
例: データファイルのバインディング
/bindings/<binding-name>/uri_primary => primary.example.com /bindings/<binding-name>/uri_secondary => secondary.example.com /bindings/<binding-name>/uri_404 => black-hole.example.com
例: バッキングサービスリソースの設定
status:
connections:
- type: primary
url: primary.example.com
- type: secondary
url: secondary.example.com
- type: '404'
url: black-hole.example.com
上記の例では、primary、secondary などのキーを使用したすべての値をプロジェクションできるようにします。
6.6.5.7. コレクションのアイテムをアイテムごとに 1 つのキーで公開する
以下の例は、アノテーションを使用して項目ごとに 1 つのキーを持つコレクションの項目を公開する方法を示しています。
例: アノテーションによるコレクションの項目の公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
"service.binding/tags": "path={.spec.tags},elementType=sliceOfStrings"
spec:
tags:
- knowledge
- is
- power
以下の例では、1 つ前のアノテーションでのコレクションアイテムが、バインドされたアプリケーションにどのようにプロジェクションされるかを紹介します。
例: データファイルのバインディング
/bindings/<binding-name>/tags_0 => knowledge /bindings/<binding-name>/tags_1 => is /bindings/<binding-name>/tags_2 => power
例: バッキングサービスリソースの設定
spec: tags: - knowledge - is - power
6.6.5.8. エントリー値ごとに 1 つのキーを使用してコレクションエントリーの値を公開する
以下の例は、アノテーションを使用してエントリー値ごとに 1 つのキーを持つコレクションエントリーの値を公開する方法を示しています。
例: アノテーションを使用したコレクションエントリーの値の公開
apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
name: hippo
namespace: my-petclinic
annotations:
"service.binding/url": "path={.spec.connections},elementType=sliceOfStrings,sourceValue=url"
spec:
connections:
- type: primary
url: primary.example.com
- type: secondary
url: secondary.example.com
- type: '404'
url: black-hole.example.com
以下の例では、1 つ前のアノテーションでのコレクション値が、バインドされたアプリケーションにどのようにプロジェクションされるかを紹介します。
例: データファイルのバインディング
/bindings/<binding-name>/url_0 => primary.example.com /bindings/<binding-name>/url_1 => secondary.example.com /bindings/<binding-name>/url_2 => black-hole.example.com
