6.8. サービスバインディング Operator を使用したワークロードのバインド
アプリケーション開発者は、バインディングシークレットを使用して、ワークロードを 1 つまたは複数のバッキングサービスにバインドする必要があります。このシークレットは、ワークロードによって使用される情報を保存するために生成されます。
たとえば、接続するサービスがすでにバインディングデータを公開しているとします。この場合、ServiceBinding
カスタムリソース (CR) と共に、使用されるワークロードの必要になります。この ServiceBinding
CR を使用することで、ワークロードはバインドするサービスの詳細と共にバインディング要求を送信します。
ServiceBinding
CR の例
apiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: name: spring-petclinic-pgcluster namespace: my-petclinic spec: services: 1 - group: postgres-operator.crunchydata.com version: v1beta1 kind: PostgresCluster name: hippo application: 2 name: spring-petclinic group: apps version: v1 resource: deployments
上記の例で示されるように、ConfigMap
または Secret
自体を、バインディングデータのソースとして使用されるサービスリソースとして直接使用することもできます。
6.8.1. 命名ストラテジー
命名ストラテジーは、binding.operators.coreos.com
API グループでのみ利用できます。
命名ストラテジーは Go テンプレートを使用して、サービスバインディングリクエストでカスタムバインディング名を定義するのに役立ちます。命名ストラテジーは、ServiceBinding
カスタムリソース (CR) のマッピングを含むすべての属性に適用されます。
バッキングサービスは、バインディング名をファイルまたは環境変数としてワークロードに反映します。ワークロードが特定の形式で反映されるバインディング名を要求し、バッキングサービスから反映されるバインディング名がその形式で利用できない場合、命名ストラテジーを使用してバインディング名を変更できます。
定義済みの後処理関数
命名ストラテジーを使用する一方、ワークロードの要求や要件によっては、任意の組み合わせで以下の定義済みの後処理関数を使用して、文字列を変換できます。
-
upper
: 文字列を大文字に変換します。 -
lower
: 文字列を小文字に変換します。 -
title
: 特定の一部の語句を除いて、各語句の最初の文字が大文字になるように文字列を変換します。
事前に定義された命名ストラテジー
アノテーションで宣言されたバインディング名は、以下の事前に定義された命名ストラテジーに従って、ワークロードへの反映前に名前の変更に対して処理されます。
none
: これが適用されると、バインディング名は変更されません。例
テンプレートのコンパイル後、バインディング名は
{{ .name }}
の形式を取ります。host: hippo-pgbouncer port: 5432
upper
:namingStrategy
が定義されていない場合に適用されます。これが適用されると、バインディング名キーのすべての文字列を大文字に変換します。例
テンプレートのコンパイル後、バインディング名は
{{ .service.kind | upper}}_{{ .name | upper }}
の形式を取ります。DATABASE_HOST: hippo-pgbouncer DATABASE_PORT: 5432
ワークロードが別の形式を要求する場合は、カスタム命名ストラテジーを定義し、接頭辞とセパレーターを使用してバインディング名を変更できます (例:
PORT_DATABASE
)。
-
バインディング名がファイルとして反映される場合、デフォルトでは、事前定義された
none
命名ストラテジーが適用され、バインディング名は変更されません。 -
バインディング名が環境変数として反映され、
namingStrategy
が定義されていない場合には、デフォルトでは事前定義されたuppercase
命名ストラテジーが適用されます。 - カスタムバインディング名と事前定義済みの後処理関数の別の組み合わせを使用して、カスタム命名ストラテジーを定義することで、事前に定義された命名ストラテジーを上書きできます。
6.8.2. 高度なバインディングオプション
ServiceBinding
カスタムリソース (CR) を定義して、次の高度なバインディングオプションを使用できます。
-
バインディング名の変更: このオプションは、
binding.operators.coreos.com
API グループでのみ使用できます。 -
カスタムバインディングデータの作成: このオプションは、
binding.operators.coreos.com
API グループでのみ使用できます。 -
ラベルセレクターを使用したワークロードのバインド: このオプションは、
binding.operators.coreos.com
およびservicebinding.io
API グループの両方で使用できます。
6.8.2.1. ワークロードへの反映前のバインディング名の変更
ServiceBinding
CR の .spec.namingStrategy
属性で、バインディング名を変更するルールを指定できます。たとえば、PostgreSQL データベースに接続する Spring PetClinic サンプルアプリケーションについて考えてみましょう。この場合、PostgreSQL データベースサービスは、バインディングに使用するデータベースの host
および port
フィールドを公開します。Spring PetClinic サンプルアプリケーションは、バインディング名を使用してこの公開されたバインディングデータにアクセスできます。
例:ServiceBinding
CR の Spring PetClinic サンプルアプリケーション
# ... application: name: spring-petclinic group: apps version: v1 resource: deployments # ...
例:ServiceBinding
CR の PostgreSQL データベースサービス
# ... services: - group: postgres-operator.crunchydata.com version: v1beta1 kind: PostgresCluster name: hippo # ...
namingStrategy
が定義されておらず、バインディング名が環境変数として反映される場合、バッキングサービスの host: hippo-pgbouncer
値および反映される環境変数は以下の例のように表示されます。
例
DATABASE_HOST: hippo-pgbouncer
ここでは、以下のようになります。
|
|
| バインディング名を指定します。 |
POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV
命名ストラテジーを適用すると、サービスバインディングリクエストで準備したカスタムバインディング名の一覧が以下の例のように表示されます。
例
POSTGRESQL_DATABASE_HOST_ENV: hippo-pgbouncer POSTGRESQL_DATABASE_PORT_ENV: 5432
以下の項目は、POSTGRESQL_{{ .service.kind | upper }}_{{ .name | upper }}_ENV
命名ストラテジーで定義される表現について説明しています。
-
.name
: バッキングサービスが公開するバインディング名を参照します。上記の例では、バインディング名はHOST
およびPORT
です。 -
.service.kind
: バインディング名が命名ストラテジーで変更されるサービスリソースの種類を参照します。 -
upper
: Go テンプレート文字列をコンパイルする際に文字列を後処理するために使用する文字列関数。 -
POSTGRESQL
: カスタムバインディング名の接頭辞。 -
ENV
: カスタムバインディング名の接尾辞。
前述の例と同様に、namingStrategy
で文字列テンプレートを定義し、バインディング名のそれぞれのキーがサービスバインディングリクエストによってどのように準備されるかを定義できます。
6.8.2.2. カスタムバインディングデータの作成
アプリケーション開発者は、以下の状況でカスタムバインディングデータを作成できます。
- バッキングサービスがバインディングデータを公開しない。
- 公開される値が、ワークロードによって要求される形式では利用できません。
たとえば、バッキングサービス CR がホスト、ポート、およびデータベースユーザーをバインディングデータとして公開するが、ワークロードはバインディングデータを接続文字列として使用することを要求するケースを考えてみます。バッキングサービスを表す Kubernetes リソースの属性を使用して、カスタムバインディングデータを作成できます。
例
apiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: name: spring-petclinic-pgcluster namespace: my-petclinic spec: services: - group: postgres-operator.crunchydata.com version: v1beta1 kind: PostgresCluster name: hippo 1 id: postgresDB 2 - group: "" version: v1 kind: Secret name: hippo-pguser-hippo id: postgresSecret application: name: spring-petclinic group: apps version: v1 resource: deployments mappings: ## From the database service - name: JDBC_URL value: 'jdbc:postgresql://{{ .postgresDB.metadata.annotations.proxy }}:{{ .postgresDB.spec.port }}/{{ .postgresDB.metadata.name }}' ## From both the services! - name: CREDENTIALS value: '{{ .postgresDB.metadata.name }}{{ translationService.postgresSecret.data.password }}' ## Generate JSON - name: DB_JSON 3 value: {{ json .postgresDB.status }} 4
6.8.2.3. ラベルセレクターを使用したワークロードのバインド
ラベルセレクターを使用して、バインドするワークロードを指定できます。ラベルセレクターを使用してワークロードを取得するサービスバインディングを宣言すると、Service Binding Operator は、指定されたラベルセレクターに一致する新しいワークロードを定期的に見つけてバインドしようとします。
たとえば、クラスター管理者は、ServiceBinding
CR で適切な labelSelector
フィールドを設定することにより、environment: production
ラベルを持つ namespace 内のすべての Deployment
にサービスをバインドできます。これにより、Service Binding Operator はこれらの各ワークロードを 1 つの ServiceBinding
CR にバインドできます。
binding.operators.coreos.com/v1alpha1
API の ServiceBinding
CR の例
apiVersion: binding.operators.coreos.com/v1alpha1
kind: ServiceBinding
metadata:
name: multi-application-binding
namespace: service-binding-demo
spec:
application:
labelSelector: 1
matchLabels:
environment: production
group: apps
version: v1
resource: deployments
services:
group: ""
version: v1
kind: Secret
name: super-secret-data
- 1
- バインドされるワークロードを指定します。
servicebinding.io
API の ServiceBinding
CR の例
apiVersion: servicebindings.io/v1beta1
kind: ServiceBinding
metadata:
name: multi-application-binding
namespace: service-binding-demo
spec:
workload:
selector: 1
matchLabels:
environment: production
apiVersion: app/v1
kind: Deployment
service:
apiVersion: v1
kind: Secret
name: super-secret-data
- 1
- バインドされるワークロードを指定します。
次のフィールドのペアを定義すると、Service Binding Operator はバインディング操作を拒否し、エラーを生成します。
-
binding.operators.coreos.com/v1alpha1
API のname
フィールドとlabelSelector
フィールド。 -
servicebinding.io
API (Spec API) のname
フィールドとselector
フィールド。
再バインドの動作を理解する
バインドが成功した後、name
フィールドを使用してワークロードを識別する場合を考えてみましょう。そのワークロードを削除して再作成すると、ServiceBinding
リコンサイラーはワークロードを再バインドせず、Operator はバインディングデータをワークロードに投影できません。ただし、labelSelector
フィールドを使用してワークロードを識別する場合、ServiceBinding
リコンサイラーはワークロードを再バインドし、Operator はバインディングデータを反映します。
6.8.3. PodSpec に準拠していないセカンダリーワークロードのバインド
サービスバインディングの一般的なシナリオでは、バッキングサービス、ワークロード (デプロイメント)、およびサービスバインディング Operator を設定する必要があります。PodSpec に準拠しておらず、プライマリーワークロード (デプロイメント) とサービスバインディング Operator の間にあるセカンダリーワークロード (アプリケーション Operator の場合もあります) が関与するシナリオについて考えてみます。
このようなセカンダリーワークロードリソースの場合、コンテナーパスのロケーションは任意です。サービスバインディングの場合、CR のセカンダリーワークロードが PodSpec に準拠していない場合、コンテナーパスのロケーションを指定する必要があります。これにより、バインディングデータがServiceBinding
カスタムリソース (CR) のセカンダリーワークロードで指定されたコンテナーパスに反映されます (たとえば、Pod 内にバインディングデータを配置したくない場合)。
Service Binding Operator では、コンテナーまたはシークレットがワークロード内に存在する場所のパスを設定し、これらのパスをカスタムの場所にバインドできます。
6.8.3.1. コンテナーパスのカスタムロケーションの設定
Service Binding Operator がバインディングデータを環境変数として投影する場合、このカスタムの場所は binding.operators.coreos.com
API グループで使用できます。
PodSpec に準拠しておらず、spec.containers
パスに置かれているコンテナーを持つセカンダリーワークロード CR について考えてみます。
例: セカンダリーワークロード CR
apiVersion: "operator.sbo.com/v1" kind: SecondaryWorkload metadata: name: secondary-workload spec: containers: - name: hello-world image: quay.io/baijum/secondary-workload:latest ports: - containerPort: 8080
手順
ServiceBinding
CR で値を指定してspec.containers
パスを設定し、このパスをspec.application.bindingPath.containersPath
カスタムロケーションにバインドします。例:
ServiceBinding
CR とカスタムロケーションのspec.containers
パスapiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: name: spring-petclinic-pgcluster spec: services: - group: postgres-operator.crunchydata.com version: v1beta1 kind: PostgresCluster name: hippo id: postgresDB - group: "" version: v1 kind: Secret name: hippo-pguser-hippo id: postgresSecret application: 1 name: spring-petclinic group: apps version: v1 resource: deployments application: 2 name: secondary-workload group: operator.sbo.com version: v1 resource: secondaryworkloads bindingPath: containersPath: spec.containers 3
コンテナーパスのロケーションを指定した後に、サービスバインディング Operator はバインディングデータを生成します。これは、ServiceBinding
CR のセカンダリーワークロードで指定されるコンテナーパスで利用できます。
以下の例は、 envFrom
フィールドとsecretRef
フィールドを持つspec.containers
パスを示しています。
例:envFrom
および secretRef
フィールドのあるセカンダリーワークロード CR
apiVersion: "operator.sbo.com/v1" kind: SecondaryWorkload metadata: name: secondary-workload spec: containers: - env: 1 - name: ServiceBindingOperatorChangeTriggerEnvVar value: "31793" envFrom: - secretRef: name: secret-resource-name 2 image: quay.io/baijum/secondary-workload:latest name: hello-world ports: - containerPort: 8080 resources: {}
6.8.3.2. シークレットパスのカスタムロケーションの設定
Service Binding Operator がバインディングデータを環境変数として投影する場合、このカスタムの場所は binding.operators.coreos.com
API グループで使用できます。
PodSpec に準拠しておらず、spec.secret
パスに置かれているシークレットのみを持つセカンダリーワークロード CR を考えてみます。
例: セカンダリーワークロード CR
apiVersion: "operator.sbo.com/v1" kind: SecondaryWorkload metadata: name: secondary-workload spec: secret: ""
手順
ServiceBinding
CR で値を指定してspec.secret
パスを設定し、このパスをspec.application.bindingPath.secretPath
カスタムロケーションにバインドします。例:
ServiceBinding
CR とカスタムロケーションのspec.secret
パスapiVersion: binding.operators.coreos.com/v1alpha1 kind: ServiceBinding metadata: name: spring-petclinic-pgcluster spec: ... application: 1 name: secondary-workload group: operator.sbo.com version: v1 resource: secondaryworkloads bindingPath: secretPath: spec.secret 2 ...
シークレットパスのロケーションを指定した後に、サービスバインディング Operator はバインディングデータを生成します。これは、ServiceBinding
CR のセカンダリーワークロードで指定されるシークレットパスで利用できます。
以下の例は、binding-request
値による spec.secret
パスを示しています。
例:binding-request
値が設定されたセカンダリーワークロード CR
...
apiVersion: "operator.sbo.com/v1"
kind: SecondaryWorkload
metadata:
name: secondary-workload
spec:
secret: binding-request-72ddc0c540ab3a290e138726940591debf14c581 1
...
- 1
- Service Binding Operator が生成する
Secret
リソースの一意の名前。
6.8.3.3. ワークロードリソースマッピング
-
ワークロードリソースマッピングは、両方の API グループ (
binding.operators.coreos.com
およびservicebinding.io
) のServiceBinding
カスタムリソース (CR) のセカンダリーワークロードで使用できます。 -
servicebinding.io
API グループの下でのみ、ClusterWorkloadResourceMapping
リソースを定義する必要があります。ただし、ClusterWorkloadResourceMapping
リソースは、binding.operators.coreos.com
およびservicebinding.io
の両方の API グループでServiceBinding
リソースと対話します。
コンテナーパスの設定方法を使用してカスタムパスの場所を設定できない場合は、バインディングデータを投影する必要がある場所を正確に定義できます。servicebinding.io
API グループで ClusterWorkloadResourceMapping
リソースを定義して、特定のワークロードの種類のバインディングデータを投影する場所を指定します。
次の例は、CronJob.batch/v1
リソースのマッピングを定義する方法を示しています。
例: CronJob.batch/v1
リソースのマッピング
apiVersion: servicebinding.io/v1beta1 kind: ClusterWorkloadResourceMapping metadata: name: cronjobs.batch 1 spec: versions: - version: "v1" 2 annotations: .spec.jobTemplate.spec.template.metadata.annotations 3 containers: - path: .spec.jobTemplate.spec.template.spec.containers[*] 4 - path: .spec.jobTemplate.spec.template.spec.initContainers[*] name: .name 5 env: .env 6 volumeMounts: .volumeMounts 7 volumes: .spec.jobTemplate.spec.template.spec.volumes 8
- 1
ClusterWorkloadResourceMapping
リソースの名前。マップされたワークロードリソースのplural.group
として修飾する必要があります。- 2
- マップされているリソースのバージョン。指定されていないバージョンは、*ワイルドカードと一致させることができます。
- 3
- オプション: Pod 内の
.annotations
フィールドの識別子。固定 JSONPath で指定されます。デフォルト値は.spec.template.spec.annotations
です。 - 4
- JSONPath で指定された、Pod 内の
.containers
および.initContainers
フィールドの識別子。containers
フィールドの下にエントリーが定義されていない場合、Service Binding Operator のデフォルトは.spec.template.spec.containers[*]
および.spec.template.spec.initContainers[\*]
の 2 つのパスになり、他のすべてのフィールドはデフォルトとして次のように設定されます。ただし、エントリーを指定する場合は、.path
フィールドを定義する必要があります。 - 5
- オプション: コンテナー内の
.name
フィールドの識別子。固定 JSONPath で指定されます。デフォルト値は.name
です。 - 6
- オプション: コンテナー内の
.env
フィールドの識別子。固定 JSONPath で指定されます。デフォルト値は.env
です。 - 7
- オプション: コンテナー内の
.volumeMounts
フィールドの識別子。固定 JSONPath で指定されます。デフォルト値は.volumeMounts
です。 - 8
- オプション: Pod 内の
.volumes
フィールドの識別子。固定 JSONPath で指定されます。デフォルト値は.spec.template.spec.volumes
です。
このコンテキストでは、固定 JSONPath は、次の操作のみを受け入れる JSONPath 文法のサブセットです。
-
フィールド検索:
.spec.template
-
配列のインデックス:
.spec['template']
その他の操作は受け付けません。
-
フィールド検索:
-
これらのフィールドのほとんどはオプションです。指定されていない場合、Service Binding Operator は
PodSpec
リソースと互換性のあるデフォルトを想定します。 -
Service Binding Operator では、これらの各フィールドが Pod デプロイメントの対応するフィールドと構造的に同等である必要があります。たとえば、ワークロードリソースの
.env
フィールドの内容は、Pod リソースの.env
フィールドが受け入れるのと同じデータ構造を受け入れる必要があります。それができない場合、そのようなワークロードにバインディングデータを投影すると、Service Binding Operator で予期しない動作が発生する可能性があります。
binding.operators.coreos.com
API グループに固有の動作
ClusterWorkloadResourceMapping
リソースが binding.operators.coreos.com
API グループの下の ServiceBinding
リソースと対話する場合、次の動作が予想されます。
-
bindAsFiles: false
フラグ値を持つServiceBinding
リソースがこれらのマッピングのいずれかと一緒に作成される場合、環境変数は、対応するClusterWorkloadResourceMapping
リソースで指定された各path
フィールドの下の.envFrom
フィールドに投影されます。 クラスター管理者は、バインド目的で
ServiceBinding.bindings.coreos.com
リソースのClusterWorkloadResourceMapping
リソースと.spec.application.bindingPath.containersPath
フィールドの両方を指定できます。Service Binding Operator は、
ClusterWorkloadResourceMapping
リソースと.spec.application.bindingPath.containersPath
フィールドの両方で指定された場所にバインディングデータを投影しようとします。この動作は、path: $containersPath
属性を持つ対応するClusterWorkloadResourceMapping
リソースにコンテナーエントリーを追加することと同じです。他のすべての値はデフォルト値を取ります。
6.8.4. バッキングサービスからのワークロードのバインド解除
oc
ツールを使用して、バッキングサービスからワークロードのバインドを解除できます。
バッキングサービスからワークロードのバインドを解除するには、これにリンクされている
ServiceBinding
カスタムリソース (CR) を削除します。$ oc delete ServiceBinding <.metadata.name>
例
$ oc delete ServiceBinding spring-petclinic-pgcluster
ここでは、以下のようになります。
spring-petclinic-pgcluster
ServiceBinding
CR の名前を指定します。