PTC との展開固有の外部接続情報の共有
captureExternalConnections ユーティリティを使用して、展開固有の外部接続情報を PTC と共有できます。これにより、複数の Windchill+ 展開を外部システムの別個の URL に接続できます。展開固有のすべての外部 URL とシークレットをランタイムで使用でき、開発、テスト、本番など、Windchill+ の展開ごとに専用に設定できます。
このユーティリティは Windchill+ インストールの一部です。これは、Linux システム上の既存の Windchill+ インストールからコピーでき、Windchill+ とは関係なくほかの Linux システムで使用できます。Windows システムでは、このユーティリティは MSYS2 や Cygwin などの Linux アプリケーションセットとともに機能します。PTC Cloud Portal で Windchill テンプレートの新しいインスタンスをリクエストすると、そのインスタンスにはデフォルトで MSYS2 が含まれます。
Windchill+ のほかのユーティリティと同様に、captureExternalConnections は JSON ファイルで提供されているシークレットとファイルシステムからの証明書を使用するシェルスクリプトです。詳細については、後述の「このユーティリティを実行する手順」のセクションを参照してください。このユーティリティは、PTC 提供の公開キーを使用して情報を暗号化し、展開固有の (開発または生産) Azure コンテナに YAML パッケージをアップロードします。
Windchill+ 本番展開を複製して開発環境またはテスト環境を作成すると、本番環境で指定されている外部エンドポイント URL が開発環境またはテスト環境で使用可能になり、データが破損することがあります。このような環境間接続を防止するため、展開固有の外部接続情報を PTC と共有することが重要です。
この外部接続情報は、CustomIntegrationHelper API を使用して作成された Windchill+ カスタマイズによって、指定されたエンドポイントと通信するために使用されます。Windchill+ 展開ごとに別個の接続情報をサブミットする場合、異なる Windchill+ 展開に同じカスタマイズコードを使用できます。Code and Configuration (CCD) ユーティリティを使用してカスタマイズをサブミットできます。CustomIntegrationHelper で使用可能な API の詳細については、該当する Windchill Javadoc を参照してください。
CCD ユーティリティを使用してサブミットされた同じカスタマイズコードは、異なる Windchill+ 展開で使用できますが、captureExternalConnections ユーティリティを使用して共有される外部接続情報 (json パラメータ) は、各 Windchill+ 展開に固有です。
このユーティリティを実行するには、次の情報があることを確認します。
• captureExternalConnections ユーティリティへのアクセス。
• PTC から電子メールを介して提供された BLOB_SAS_URL。
• PTC から電子メールを介して提供されたシークレットを暗号化するための公開キー。
• client-keycertchain - クライアントキーチェーンは、エンドポイントがクライアント証明書を必要とする場合にのみ必要です。
• server-certchain - サーバー証明書チェーンは、エンドポイントが非公開エンドポイントである場合にのみ必要です。
 |
Windchill+ 展開がリクエストされると、接続情報を暗号化するための Public Key とともに、暗号化された接続情報を含む BLOB への Blob SAS URL が、電子メールの添付資料として PTC から送信されます。Blob SAS URL を含むほかの電子メールを受信することもありますが、captureExternalConnections ユーティリティでは、公開キーとともに受信した Blob SAS URL を入力する必要があります。
|
 |
• 証明書 (PEM エンコード) が正しく、有効なソースから取得されていることを確認します。クライアント証明書が必要になるのは、外部接続で必要な場合のみです。サーバー証明書が必要になるのは、あまり知られていない証明機関から発行された証明書を外部接続が使用する場合のみです。この証明書は、既成の Java ランタイムによって信頼されません。
• 認証はさまざまな方法で実装できます。外部接続には、静的トークンを必要とするものと、別のエンティティが発行したトークンを必要とするものがあります。トークン発行者間でも、違いがある可能性があります。このユーティリティを使用して静的シークレット (テナント ID、クライアント ID、クライアントシークレット、トークン発行者 URL など) のみを取り込み、外部接続で想定される有効期間の短いトークンをフェッチする適切なプロセスを実装することをお勧めします。
|
このユーティリティを実行する手順
1. 次のコマンドを実行して、テンプレート JSON ファイルを生成します。
${WT_HOME}/prog_examples/IntegrationsExample/captureExternalConnections.sh -t <template-file-path>
<template-file-path> で、JSON ファイルへのパスを指定します。
2. テンプレートファイルに記載されている指示と制約に基づいて JSON ファイルを作成します。JSON ファイルには、展開固有のエンドポイントに関する接続情報が含まれている必要があります。詳細については、以下の「JSON ファイルで指定する情報」のセクションを参照してください。
3. 同じターミナルで、次のコマンドを実行してシークレットをローカルに取り込みます。
${WT_HOME}/prog_examples/IntegrationsExample/captureExternalConnections.sh -f <json-file-path>
<json-file-path> で、外部接続情報が含まれている JSON ファイルへのパスを指定します。
スクリプトの実行に成功すると、"Connection information submitted successfully." というメッセージが表示されます。
|
|
• 接続情報をローカルに取り込む場合でも、BLOB_SAS_URL と暗号化用公開キーの指定は必須です。
• 外部エンドポイントを取り込む場合、JSON ファイルでの apply_at パラメータの使用はオプションです。このパラメータをスキップした場合、PTC への接続情報のロールアウトは実行されません。ただし、提供された接続情報を使用するようにローカル Windchill 展開を設定できます。
|
テンプレート JSON ファイル
{
"blob_sas_url": "http://samplestorageaccount.blob.core.windows.net/connection-yaml-tests/connectionInfo.yaml",
"external_connections": {
"sample_connection.alpha": {
"baseurl": "https://acme.com"
},
"sample_connection.bravo": {
"baseurl": "https://bravo.com",
"secrets": {
"client_cert": "/path/to/client.keycertchain",
"secret.username": "alpha27",
"secret.age": "24"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<***>.txt"",
"apply_at": "2024-03-30T12:24"
}
"blob_sas_url": "http://samplestorageaccount.blob.core.windows.net/connection-yaml-tests/connectionInfo.yaml",
"external_connections": {
"sample_connection.alpha": {
"baseurl": "https://acme.com"
},
"sample_connection.bravo": {
"baseurl": "https://bravo.com",
"secrets": {
"client_cert": "/path/to/client.keycertchain",
"secret.username": "alpha27",
"secret.age": "24"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<***>.txt"",
"apply_at": "2024-03-30T12:24"
}
外部エンドポイント名 endpoint1 および endpoint2を含むカスタマイズコードをサブミットできます。captureExternalConnections ユーティリティを使用して異なる接続情報を指定することで、Windchill+ の開発展開と本番展開の両方で同じカスタマイズコードを使用できます。以下の展開固有の JSON ファイルを参照してください。
|
開発環境での Windchill+ 展開用パラメータファイル: devConnections.json
|
本番環境での Windchill+ 展開用パラメータファイル: prodConnections.json
|
|---|---|
|
{
"blob_sas_url": "...deployment specific URL as received from PTC...", "external_connections": { "endpoint1": { "baseurl": https://foo-dev.acme.com }, "endpoint2": { "baseurl": https://bar-dev.acme.com, "secrets": { "client_cert": "/path/to/client-dev.keycertchain", "secret.username": "user1", "secret.age": "5" } }, "url_fragments": { "get_user_name": "users/username", "get_user_age": "users/age" } }, "public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<dev***>.txt", "apply_at": "2024-03-30T12:24+5:30" } |
{
"blob_sas_url": "...deployment specific URL as received from PTC...", "external_connections": { "endpoint1": { "baseurl": https://foo-prod.acme.com }, "endpoint2": { "baseurl": https://bar-prod.acme.com, "secrets": { "client_cert": "/path/to/client-prod.keycertchain", "secret.username": "user2", "secret.age": "4" } }, "url_fragments": { "get_user_name": "users/username", "get_user_age": "users/age" } }, "public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<Prod***>.txt", "apply_at": "2024-03-30T17:56+5:30" } |
CustomIntegrationHelper による接続情報の使用とカスタマイズの例については、統合の例を参照してください。
JSON ファイルで指定する情報
|
パラメータ
|
必須またはオプション
|
説明
|
||
|---|---|---|---|---|
|
blob_sas_url
|
必須
|
PTC から電子メールを介して提供された Blob SAS URL を指定します。これは connectionInfo.yaml を指している必要があります。次に例を示します。
https://somestorageaccount.blob.core.windows.net/somecontainer/connectionInfo.yaml?sp=rw&st=2024-03-11T11:05:43Z&se=2024-03-12T19:05:43Z&spr=https&sv=2022-11-02&sr=b&sig=XHIXmZAL5b4wBxWg17AqS27Yvn8pa%2B8ZNPafxNoU0pE%3D
|
||
|
connection.name
|
必須
|
一意の接続名を指定します。必要に応じて 1 つ以上の接続を追加できます。
次に例を示します。
sample.connection.alpha
sample.connection.bravo
erp.dev
|
||
|
baseurl
|
必須
|
各接続のベース URL を指定します。ベース URL 名には次の文字のみを使用できます: a-z 0-9 ._
次に例を示します。
|
||
|
client_cert
|
オプション
|
クライアント証明書またはチェーンへのパスとパスワードレスキーを指定します。例: /path/to/client.keycertchain
|
||
|
secret.name
|
オプション
|
API トークン、資格証明などのその他のシークレットを指定します。シークレット名には次の文字のみを使用できます: a-z 0-9 ._
次に例を示します。
k>#=B3*jKX!Fa)e(;TsygY6P72Rd%:Ar
x-acme-header=AcmeMaterial
|
||
|
server_cert
|
オプション
|
サーバー SSL 証明書があまり知られていない認証機関によって発行されている場合、サーバー証明書またはチェーンへのパスを指定します。
例: /path/to/server.certchain
|
||
|
url_fragments
|
オプション
|
複数のエンドポイントが同じアイデンティティ、サーバー、またはクライアントシークレットを共有している場合、同じベース URL に関連付けられている URL フラグメントを指定できます。
フラグメント名には次の文字のみを使用できます: a-z 0-9 ._
例: /inventory/api
|
||
|
public_key_for_encrypting_custom_secrets
|
必須
|
暗号化用の公開キーへのパスを指定します。公開キーファイルは PTC から電子メールを介して提供されます。
例: /path/to/asymmetric_encryption_public_key_<***>.txt
|
||
|
apply_at
|
オプション
|
接続情報のロールアウトを開始する ISO 8601 タイムスタンプを指定します。タイムスタンプは現在の時刻より少なくとも 1 時間後でなければなりません。apply_at パラメータをスキップした場合、接続情報のロールアウトは実行されません。ただし、提供された接続情報を使用するようにローカル Windchill 展開を設定できます。
例: 2024-03-11T11:24+00:00
|
|
|
PTC に新しいシークレットをサブミットしてから、これらのシークレットが使用可能になるまでの間に、最短で 1 時間の遅延がある場合でも、新しいシークレット値のロールアウトを事前にスケジュールできます。ただし、新しいシークレット値のロールアウトスケジュールが開始されるまで、Windchill+ カスタマイズコードは引き続き古いシークレット値を使用します。この時間枠内に外部エンドポイントの統合を機能させる場合、それに応じて CCD でカスタマイズコードを修正する必要があります。または、新しいシークレット値をロールアウトするのと並行して、古いシークレット値を段階的に廃止することもできます。
|
|
|
接続の詳細をアップロードしたりコンフィギュレーションを変更したりする場合は、このセクションで説明する手順に従います。captureExternalConnections ユーティリティを再実行して接続情報 (JSON ファイル) を更新し、スケジュールされたオーケストレーションプロセスでコンフィギュレーション (必要な再起動を含む) を適用できるようにします。
|