一般的な側面

はじめに

Things Cloudマイクロサービスは、Things Cloudのホスティング、セキュリティ、API管理に完全統合されたサーバーサイドアプリケーションであり、オプションで高可用性、拡張性、マルチテナンシーを提供します。たとえば、自社のマイクロサービスを開発して、IoT関連のプロセスをバックオフィスソフトウェアに統合したり、独自の分析ロジックでIoTデータの一括分析を実行したり、デバイスからのメッセージ用のデコーダーを作成したり、その他多くのバックエンドユースケースに対応できます。

マイクロサービスは、完全な認証と認可を備えた標準REST APIを使用して、Things Cloudと通信します。ほとんどの場合、それらはマルチテナントです。つまり、各テナントを厳密に分離し、同時に複数のテナントへ接続できる必要があります。

マイクロサービスは、システム統合のため、Things CloudおよびThings Cloud基盤のアプリケーションで使用できる独自のエンドポイントを提供する場合があります。このようなマイクロサービスの一例としては、Jasper Control Centerの統合や、SMS通知をエンドユーザーに送信するためのSMS統合などがあります。

Things Cloudマイクロサービスには、以下の特性があります。

• デフォルトでRESTまたはWebsocket APIを提供します。
• インバウンドRESTおよびWebsocketエンドポイントは、Things Cloudコアの組み込みAPIゲートウェイ機能によって保護されています。
• 一つのマイクロサービスからThings Cloud REST APIへのリクエストは、（受信リクエストの）元のユーザーアカウントを使用するか、サービスユーザーを使用して実行できます。
• マルチテナントのサポート。

以下の管理機能がサポートされています。

• マイクロサービスは、個々のテナントおよびスーパーテナント（サブテナントを持つテナント）に登録できます。
• マルチテナントマイクロサービスは、他のテナントにサブスクライブできます。

技術的に言えば、マイクロサービスはThings CloudがホストするDockerコンテナであり、特定の規則に従います。通常は、/service/<microservice-name>の下にあるThings Cloud REST APIを使用してアクセスします。マイクロサービスは、ドキュメント化されたREST APIを使用してThings Cloudへアクセスするのが一般的です。

開発者は、Things Cloudのマイクロサービスの開発時にプログラミング言語に制限されることはありません。ただし、マイクロサービスはポート80で動作するHTTPサーバーとして機能する必要があり、Dockerイメージにカプセル化する必要があります。

マイクロサービスのホスティングはThings Cloudによって提供されます。このため、開発者はビジネスロジックに集中でき、スケーリング、セキュリティ、高可用性、モニタリングはThings Cloudに任せることができます。マイクロサービスは、Things Cloudが公開するAPIの上に構築可能です。これにより、Things Cloudマイクロサービスは新たな機能の提供や既存機能の拡張のための便利な手段となります。

Things Cloud上でマイクロサービスを開発・デプロイする詳細については、このセクション内の該当する章を参照してください。これらの章では、Things Cloudにおけるマイクロサービスの一般的なコンセプト、および各種プログラミング言語に関する具体的なガイダンスや例を提供しています。

コンテナ化とオーケストレーション

イメージとコンテナ

Dockerは、コンテナを使用してアプリケーションを開発、デプロイ、実行するためのプラットフォームです。イメージとは、アプリケーションを実行するために必要なすべてのもの（コード、ランタイム、ライブラリ、構成設定ファイル）を含む実行可能なパッケージです。コンテナは、イメージのイメージのランタイムインスタンスです（つまり、実行時にメモリ内に保存されるイメージの形です）。Dockerについての詳細はDockerドキュメントを参照してください。

Things Cloud マイクロサービスはDockerに基づいています。したがって、Things Cloudプラットフォームで実行するには、マイクロサービスをDockerイメージとしてパッケージ化する必要があります。マイクロサービスは、実行時にDockerコンテナ内で実行されます。Dockerコンテナは、マイクロサービスがThings Cloudで実行されている他のマイクロサービスに害を及ぼさないことを保証します。

コンテナのマイクロサービスのスレッド上限は10240です。

ポッド

Kubernetesは、コンテナ化されたアプリケーションのデプロイ、スケーリング、管理を自動化するためのコンテナオーケストレーションエンジンです。ポッドはKubernetesの基礎構成要素であり、クラスターで実行中のプロセスを表します。Podは、アプリケーションコンテナ、ストレージリソース、固有ネットワークIP、コンテナの実行方法を制御するオプションをカプセル化します。

Dockerは、Kubernetesポッドで使用される最も一般的なコンテナランタイムです。 さらに、KubernetesはDockerコンテナのオーケストレーションに使用され、自動スケーリングや負荷分散など、Dockerコンテナをホストするためのエンタープライズ級の機能を多数提供します。Kubernetesの詳細については、Kubernetesのドキュメントを参照してください。

Dockerが、例えば、ポッド同期エラーのような、いくつかの問題に直面したとき、アラームが作成され、コックピットアプリケーションのアラームに表示されます。よくある問題については、このセクションにあるトラブルシューティングを参照してください。

要件と相互作用

Things Cloudマイクロサービスに関する次の要件を満たす必要があります。

• マイクロサービスは、(linux/amd64) Dockerイメージとして実行されなければなりません。
• Dockerイメージは_image.tar_としてパッケージ化され、マニフェストファイル(cumulocity.json)を含める必要があります。
• マイクロサービスはステートレスでなければなりません。つまり、一時的な状態のみを含む。これは、ハードウェアの都合（サーバー障害）および操作の都合（アップグレード、移行）のために、マイクロサービスが（ランダムな）再起動を行う必要があるためです。
• すべての永続状態は、インベントリ、バイナリ、テナントオプション、およびその他のAPIを介してThings Cloudプラットフォームに保存する必要があります。永続ボリュームはサポートされていません。
• マイクロサービスはデータベースに直接アクセスできないため、Things Cloud APIを使用する必要があります。
• マイクロサービスは、1つのインバウンドREST APIを提供しなければなりません。追加の受信ポートはサポートされていません。
• マイクロサービスは複数の送信ポートを使用できます。
• リクエストのライフタイムには最大値でなければなりません。インフラストラクチャは、長時間実行されているリクエストを終了する場合があります。
• すべてのログ情報は、インフラストラクチャでキャプチャおよび保持するために標準出力へ送信する必要があります。

次の図に示すように、マイクロサービスはThings Cloudと外部、両方と相互作用します。

マイクロサービスのライフサイクルは、マイクロサービスのサブスクリプションAPIを使用して管理されます。これにより、マイクロサービスの登録とサブスクリプションが可能になります。 外部アクター（たとえば、Webユーザーインターフェイス、統合または他のマイクロサービス）は、RESTまたはWebsocketリクエストをエンドポイント/service/<microservice-name>/<path>に送信することにより、マイクロサービスを呼び出すことができます。マイクロサービスは、外部エンドポイントまたはThings Cloud REST APIにリクエストを発行できます。マイクロサービスは関連する開発者テナントにログとメトリックを保存できます。

マイクロサービスマニフェスト

アプリケーションマニフェストは、Things Cloud プラットフォームでのマイクロサービスインスタンスとアプリケーションのデプロイを管理するために必要な設定を提供します。Things Cloud プラットフォーム上にアップロードされたバイナリの cumulocity.json ファイル内に定義が提供されます。

こちらはマニフェストの例です。

{
    "apiVersion": "v2",
    "name": "my-microservice",
    "version": "1.0.0",
    "provider": {
        "name": "New Company Ltd.",
        "domain": "https://new-company.com",
        "support": "support@new-company.com"
    },
    "isolation": "MULTI_TENANT",
    "scale": "AUTO",
    "replicas": 2,
    "resources": {
        "cpu": "1",
        "memory": "1G"
    },
    "requestedResources":{
            "cpu": "100m",
            "memory": "128Mi"
    },
    "requiredRoles": [
        "ROLE_ALARM_READ"
    ],
    "livenessProbe": {
        "httpGet": {
            "path": "/health"
        },
        "initialDelaySeconds": 60,
        "periodSeconds": 10
    },
    "readinessProbe": {
        "httpGet": {
            "path": "/health",
            "port": 80

        },
        "initialDelaySeconds": 20,
        "periodSeconds": 10
    },
    "settingsCategory": "myms",
    "settings": [
        {
            "key": "tracker-id",
            "defaultValue": "1234"
        }
    ]
}

使用可能な設定の詳細については、以下を参照してください。

設定

バージョン

バージョンは、マイクロサービスのアップロード動作に影響を与えます。

• マイクロサービス用の新しいZIPファイルがアップロードされていているが、バージョンが以前のものと同じである場合（例：「1.1.0」）、マイクロサービスのDockerイメージが更新される保証はありません。
• バージョンがスナップショットの場合（例：「1.1.0-SNAPSHOT」）、DockerはそれぞれのZIPのアップロード時にイメージを更新します。

「-SNAPSHOT」という接尾辞は、そのイメージビルドが特定の時点でのアプリケーションのスナップショットであり、まだ開発中であることを意味します。 マイクロサービスが商用リリースの準備ができたら、「-SNAPSHOT」の接尾辞を削除し、一意（より大きい）のバージョン番号（例：「2.1.0」）でマイクロサービスをアップロードする必要があります。 この運用により、各リリースのバージョン一意性が維持され、意図しない上書きを防ぐことができます。

プロバイダー

リソース

RequestedResources

オプション

Probe

ExecAction

TCPSocketAction

HTTPGetAction

HttpHeader

Extension

分離とスケーリング

マイクロサービスでは次の分離レベルを使用できます。

• マルチテナント: マイクロサービスがスケーリングされていない限り、サブスクライブされたすべてのテナントに対してインスタンス化された単一のマイクロサービスDockerコンテナ。
• シングルテナント: サブスクライブされたテナントごとにインスタンス化された専用のマイクロサービスDockerコンテナ。

isolationの設定についてはマイクロサービスマニフェスト>設定を参照してください。

scale設定がNONEに設定されている場合、プラットフォームは、分離レベルごとにサービスのインスタンスがデフォルトで1つあることを保証します。マニフェストでreplicasの設定を定義することで、保証されるインスタンスの数を増やすことができます。スケーリングが有効 (AUTO設定)になっていると、CPU使用率が高い場合、マイクロサービスは（インスタンスをさらに作成して）水平方向に自動スケーリングされます。 自動スケーリングは、マイクロサービスを監視して、目的のパフォーマンスレベルで動作していることを確認します。必要に応じてクラスターを自動的にスケールアップし、不要な場合はスケールダウンします。

scaleとreplicas設定についてはマイクロサービスマニフェスト>設定を参照してください。

APIバージョン2へマイクロサービスの移行

リリース10.15では、Things CloudがマイクロサービスAPIバージョン2の提供を発表し、新しいセキュリティ要件に準拠するためにAPIバージョン1の廃止を発表します。 マイクロサービスAPIバージョン2では、特権を持つLinuxカーネルAPIの呼び出しを制限する改善されたマイクロサービスコンテナのセキュリティコンテキストが提供されます。 詳細については、マイクロサービスAPIバージョン2では、マイクロサービスコンテナに対して特定の機能のみが付与されることを意味します。

カーネルの機能に関する詳細は、Linuxマニュアルページを参照してください。APIバージョンの変更に伴い、マイクロサービスにNET_BIND_SERVICE機能が付与されます。

マイクロサービスの移行

新しいAPIバージョンにマイクロサービスを移行するには、以下の手順を実行してください。

1. マイクロサービスのマニフェストでAPIバージョンを2に変更します。マイクロサービスマニフェストを参照してください。

2. マイクロサービスをテスト環境にデプロイします。

3. マイクロサービスの機能をテストし、可能なエラーを分析します。

最も単純な場合、マイクロサービスのマニフェストでAPIバージョンを2に設定するだけで十分です。

しかしながら、以前は付与されていた特定のLinuxカーネルAPIの特権を使用しているマイクロサービスの場合、これらの特権の呼び出しが不要となるようにソースコードをリファクタリングする必要があります。

影響を受けるマイクロサービス

マイクロサービスのマニフェストのAPIバージョンフィールドを2に設定し、このサービスをThings Cloudのテスト環境にデプロイしてください。この環境はバージョン10.15以上である必要があります。マイクロサービスが期待どおりに機能することを確認してください。

環境のアップグレード後に、古いユーザー特権を使用し続けるマイクロサービス

マイクロサービスが非推奨のAPIバージョン1を使用している場合、この環境の設定によって影響を受ける可能性があります。 その場合、マイクロサービスをアップロードまたはサブスクライブすることができません。

セキュリティ

通常、マイクロサービスはREST APIを提供し、Things CloudはインバウンドRESTリクエスト用の軽いAPIゲートウェイ（プロキシ）を提供します。インバウンドWebSocketリクエストがサポートされています。 クライアントとマイクロサービスコンテナの間に位置するAPIゲートウェイは、次を提供します。

• 認可：すべての呼び出しは、Things Cloud認証情報を使用して、基本認証またはOAuth認証で認証されます。
• TLS終了：TLSインバウンドコールは終了し、クラスター内ではHTTPのみが使用されます。
• 計測：APIコールは、APIコールのテナント統計で計測されます。
• ルーティング：APIゲートウェイは、/service/<name>へのリクエストをマイクロサービス__にルーティングします。マイクロサービスコンテナとテナントオプションにルーティングされたリクエストは、リクエストヘッダーに追加されます。したがって、テナントオプション値として空白（" “）は許可されません。アプリケーションマニフェストでcontextPathが定義されている場合、APIゲートウェイは/service/<contextPath>のリクエストをルーティングします。

認証と認可

マイクロサービスへのリクエストは、Things Cloudがサポートする以下のような様々な認証方式を使用して認証することができます。

1. Basic authentication
2. OAI-セキュア
3. SSO
4. JWTトークン認証(非推奨)

Javaを使用して開発する場合は、Things Cloudで利用可能なすべての認証方法をサポートするために、マイクロサービス SDKは10.4.6以降のバージョンを使用することをお勧めします。

Things CloudがSDKを提供していない他のプログラミング言語の場合、Things Cloudプラットフォームで利用できるすべての認証方式へのサポートを実現するよう開発者にお勧めします。

Things Cloudは、RESTエンドポイント/user/currentUserを公開します。マイクロサービスは、C8Y_BASEURLオペレーティングシステム環境変数からThings Cloudアドレスを取得します。マイクロサービスは、RESTエンドポイント/user/currentUserを使用して、マイクロサービスが処理するHTTPリクエストに埋め込まれた資格情報が有効かどうか確認します。認証情報が正しい場合、/user/currentUserエンドポイントからの応答ステータスは200 OKとなります。認証情報が正しくない場合、応答に 401 Unauthorizedというステータスコードが含まれます。認証情報が正しいかどうかを確認するために、マイクロサービスは進行中のリクエストから認証情報をコピーして、/user/currentUserエンドポイントに送信します。

認証方法に応じて、認証情報は以下のような様々な方法でマイクロサービスに渡すことができます。

1. Authorization HTTPヘッダー
2. authorizationというクッキー
3. X-XSRF-TOKENというカスタムHTTPヘッダー
4. tfatokenというカスタムHTTPヘッダー

受信したリクエストにクッキー authorization が含まれている場合、マイクロサービスはそのクッキーとX-XSRF-TOKENというヘッダーを/user/currentUserのエンドポイントへのリクエストにコピーしなければなりません。 それ以外の場合は、Authorizationヘッダーをコピーする必要があります。これは、 /user/currentUserへのリクエストに常に含まれる tfatokenというヘッダーがリクエストに含まれている場合に必要となります。

認証情報の検証の流れは、以下の図で確認することができます。

例

マイクロサービスは、以下のヘッダーを持つHTTPリクエストを受信することができます（以下の例を参照）。認証処理は、基本認証とSMS基盤のTFAに基づいています。

GET https://cumulocity.default.svc.cluster.local/test HTTP/1.1
accept: */*
authorization: Basic dGVuYW50X2lkL3VzZXJuYW1lOnBhc3N3b3JkCg==
connection: close
content-length: 0
cookie: REQUEST_ORIGIN=
host: auth-scope-management.default.svc.cluster.local:80
tfatoken: 23b75292468e0ba7fe03245d502d9c29e21e8a997fc7dd7e1a1df7fe31cbfb17
x-forwarded-host: cumulocity.default.svc.cluster.local:80
x-forwarded-prefix: /service/auth
x-forwarded-proto: http
x-real-ip: 192.168.1.20

マイクロサービスは以下のリクエストを送信して、認証情報を検証します（c8y_baseurlがhttps://cumulocity:8111と同じであることが条件です）。

GET https://cumulocity:8111/user/currentUser HTTP/1.1
Accept: text/plain, application/json, application/*+json, */*
Authorization: Basic dGVuYW50X2lkL3VzZXJuYW1lOnBhc3N3b3JkCg==
Content-Length: 0
tfatoken: 23b75292468e0ba7fe03245d502d9c29e21e8a997fc7dd7e1a1df7fe31cbfb17

ユーザーがOAI-Secureで認証されている場合、以下のRESTリクエストでマイクロサービスに到達することができます。

GET https://cumulocity.default.svc.cluster.local/test HTTP/1.1
accept: */*
authorization: Basic dGVuYW50X2lkL3VzZXJuYW1lOjxmYWtlIHBhc3N3b3JkPgo=
connection: close
content-length: 0
cookie: authorization=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0YzAwMGVlOC1hYjY5LTRiMzYtYWNhNC0xNzM4ZGYwZWNhZGIiLCJpc3MiOiJjdW11bG9jaXR5LmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiLCJhdWQiOiJjdW11bG9jaXR5LmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiLCJzdWIiOiJhZG1pbiIsInRjaSI6IjMxMWM3YjZiLWM1MmQtNGEzMC1iZDFlLWNiODdlMjNlODQyOSIsImlhdCI6MTY0NjkyODgxMywibmJmIjoxNjQ2OTI4ODEzLCJleHAiOjE2NDgxMzg0MTMsInRmYSI6ZmFsc2UsInRlbiI6Im1hbmFnZW1lbnQiLCJ4c3JmVG9rZW4iOiJHU0l6VFB4b2JQS1FJQmV2Uk1SWiJ9.NL5b9-iHSc3SLaPu87oazBd2_kjNiwO9tM_bXS3qCUd0_wTZ-BKc3q6sRHTKO_LNbtCQg3G6-7ZhD6TyvqjTLsyiZTsgMRtAE7ZiRPtXaFOA0_SDQ9kG_MztAZ3U9O008akgXcjEEAdphVv5eey_lADrg1BmIlqiBFoKts2JGSv1xFtXKIxpcVtRDGUkb-2qb8OhaHamT7b3HL628NSiH4VqfO38vkLLkimHEz-roqmbFGQ355TvA3-s_erO96j3rHbBPDsluFqFN0eOTCidBffKt6OvyKw-_64MaHHs6R9Ulsv-LuY-YAvlTZVxYwFAi3yn3mWlpXEAzvGYHMrx8A
host: auth-scope-management.default.svc.cluster.local:80
user-agent: insomnia/2022.1.1
x-forwarded-host: cumulocity.default.svc.cluster.local:80
x-forwarded-prefix: /service/auth
x-forwarded-proto: http
x-real-ip: 192.168.1.20
x-xsrf-token: GSIzTPxobPKQIBevRMRZ

マイクロサービスは、上記のリクエストから認証情報を確認するために以下のリクエストを送信します。

GET https://cumulocity:8111/user/currentUser HTTP/1.1
Accept: text/plain, application/json, application/*+json, */*
Content-Length: 0
Cookie: authorization=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0YzAwMGVlOC1hYjY5LTRiMzYtYWNhNC0xNzM4ZGYwZWNhZGIiLCJpc3MiOiJjdW11bG9jaXR5LmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiLCJhdWQiOiJjdW11bG9jaXR5LmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiLCJzdWIiOiJhZG1pbiIsInRjaSI6IjMxMWM3YjZiLWM1MmQtNGEzMC1iZDFlLWNiODdlMjNlODQyOSIsImlhdCI6MTY0NjkyODgxMywibmJmIjoxNjQ2OTI4ODEzLCJleHAiOjE2NDgxMzg0MTMsInRmYSI6ZmFsc2UsInRlbiI6Im1hbmFnZW1lbnQiLCJ4c3JmVG9rZW4iOiJHU0l6VFB4b2JQS1FJQmV2Uk1SWiJ9.NL5b9-iHSc3SLaPu87oazBd2_kjNiwO9tM_bXS3qCUd0_wTZ-BKc3q6sRHTKO_LNbtCQg3G6-7ZhD6TyvqjTLsyiZTsgMRtAE7ZiRPtXaFOA0_SDQ9kG_MztAZ3U9O008akgXcjEEAdphVv5eey_lADrg1BmIlqiBFoKts2JGSv1xFtXKIxpcVtRDGUkb-2qb8OhaHamT7b3HL628NSiH4VqfO38vkLLkimHEz-roqmbFGQ355TvA3-s_erO96j3rHbBPDsluFqFN0eOTCidBffKt6OvyKw-_64MaHHs6R9Ulsv-LuY-YAvlTZVxYwFAi3yn3mWlpXEAzvGYHMrx8A
X-XSRF-TOKEN: GSIzTPxobPKQIBevRMRZ

/user/currentUser RESTエンドポイントへのリクエストに正しい認証情報が含まれている場合、応答のボディには、ユーザーアカウントに割り当てられたユーザーロールなどの様々な情報が含まれます。この情報は、マイクロサービスが承認処理を実行するために、非常に有用です。

マイクロサービスがHTTPリクエストを受け取ると、Things Cloudが公開するREST APIを使用する必要が生じることがあります。REST APIにアクセスするには、マイクロサービスから有効な認証情報を提供する必要があります。受信したRESTリクエストに含まれる認証情報を使用するか、マイクロサービスに加入しているテナントに属するリソースにアクセスするために作成された専用のユーザーアカウントを使用することができます。マイクロサービスRESTへの受信リクエストとともに提供される認証情報か、専用アカウントを使用するかの選択は、ユースケースに依存します。マイクロサービスが受信したユーザー認証情報を着信HTTPリクエストで利用するためには、上記のルールに従って認証情報をコピーする必要があります。

さらに、マイクロサービスから送信されるHTTPリクエストの多くは、HTTPヘッダーX-Cumulocity-Application-Keyを含んでいなければなりません。このヘッダーは、アクションがアプリケーションによって実行されることを示します。ヘッダーがない場合Things Cloudは、HTTPリクエストの発信元がIoTデバイスであると認識してしまいます。したがって、X-Cumulocity-Application-Keyのないリクエストは、デバイスの利用可能状態や課金データなどに影響を及ぼす可能性があります。

したがって、マイクロサービスは、Things CloudプラットフォームへのIoTデバイスからの要求をプロキシする場合のみX-Cumulocity-Application-Keyを含める必要があります。

マイクロサービスがX-Cumulocity-Application-Keyというヘッダーを含む場合は、そのヘッダーに正しいアプリケーションキーが含まれていなければなりません。次に、マイクロサービスは、Things Cloudプラットフォームが公開するエンドポイント/application/currentApplicationにRESTリクエストを送信して、アプリケーションキーを取得します。REST リクエストには、次の形式で基本認証のための認証情報を含める必要があります：tenantId/username:password。テナントID、ユーザー名、パスワードは、マイクロサービスが次のオペレーティングシステムの環境変数から読み取ります： C8Y_BOOTSTRAP_TENANT、C8Y_BOOTSTRAP_USER、C8Y_BOOTSTRAP_PASSWORD。パフォーマンスを上げるために、マイクロサービスはユーザー認証情報に関連するキャッシュ機構を実装する必要があります。

マイクロサービス認証とマルチテナント

通常、マイクロサービスは標準のThings Cloud認証メカニズムを使用します。これは2つのステップで実行されます。

1. マイクロサービスは、feature-microservice-hostingが有効になっているテナントで作成します。
2. マイクロサービスはテナントAPIにアクセスします。

マイクロサービスのインストール時には、新しいマイクロサービスを反映するアプリケーションが所有者テナント（通常はマネジメントテナントまたはエンタープライズテナント（親テナント））に作成されます。さらに、所有者テナントには、マイクロサービスがサブスクリプションを取得することを可能にするブートストラップユーザーが作成されます。 必要に応じて、プラットフォーム管理者は新規マイクロサービスに顧客を登録できます。登録の一環として、顧客テナント内にサービスユーザーがランダムな認証情報で作成されます。

マイクロサービス認証

認証は2つのレベルで関連します。

1. 所有者テナントレベルでは、マイクロサービスの唯一の認証は、自分のサブスクリプションにアクセスすることです。
2. 顧客のテナントにアクセスするために、マイクロサービスは、操作に必要な一連の権限をインストールします。

マイクロサービスは、管理テナント内のブートストラップユーザーに関連付けられ、サブスクリプションのみを返すようにします。 マイクロサービスは、顧客テナントで機能を実行するために必要な一連の権限にも関連付けられています。 これらの権限は、管理アプリケーション上に表示されています。 権限は、プラットフォーム管理者がマイクロサービスをテナントに関連付ける（それにサブスクライブする）際に作成されるサービスユーザーと関連付けられます。所有者テナントも、そのマイクロサービスの機能を使用する場合にはサブスクライブする必要があります。

ユーザーとロール

ユーザーには3つのタイプがあります。

• テナントユーザー: プロキシによって渡されたREST APIエンドポイント/service/<microservice-name>/<path>を介してマイクロサービスを呼び出すユーザー。
• サービスユーザー: マイクロサービスが、初期化ジョブまたは通常のジョブのような、REST APIコールとは関係なく、サブスクライブされたテナントにアクセスできるようにする生成されたユーザー。
• マイクロサービスブートストラップユーザー: サブスクライブされたテナントとサービスユーザーをリクエストするために、マイクロサービスに渡されたユーザー。

以下のロールタイプはユーザーのために定義されています。

• 必須ロール：Things Cloud REST APIへのアクセスを許可するために事前定義されたロール。 たとえば、マイクロサービスがサービスユーザーを使用してメジャーメントを作成する場合、メジャーメント管理者ロールをアプリケーションの必須ロールとして追加する必要があります。 必須ロールはサービスユーザーに追加されます。
• ロール: マイクロサービス開発者がテナントプラットフォームユーザーに提供するカスタムロール。 これらのロールは、管理アプリケーションを使用してテナントプラットフォームのユーザーまたはグループに割り当てたり、取り消すことができます。

UIに表示するには、カスタムロールがこの名前形式に従う必要があります。

ROLE__(READ|ADMIN|CREATE)

次のように、rolesプロパティのアプリケーションマニフェストに追加できます。

"roles": [
    "ROLE_MY_MICROSERVICE_READ",
    "ROLE_MY_MICROSERVICE_ADMIN"
]

ロールはマイクロサービスマニフェストで設定されます。ユーザーとロールについての詳細は、Things Cloud OpenAPI仕様仕様にあるユーザーAPIを確認してください。

マイクロサービスブートストラップ

各マイクロサービスは専用のブートストラップユーザーを受け取ります。これにより、プラットフォームがマイクロサービスを識別し、許可されたリソースにのみマイクロサービスをアクセスさせます。マイクロサービスランタイムは、プラットフォームAPIを介して取得することもできる環境変数として、ブートストラップユーザーとサービスユーザーの認証情報を提供します。分離レベルに応じて、環境変数が異なることに注意してください。

マルチテナントスコープでは、単一マイクロサービスデプロイメントを複数のテナントが再利用することがあります。そのため、サービスユーザー認証情報はハードコードされた環境プロパティとして提供されません。ただし、マルチテナント分離で実行されているマイクロサービスは、次のようにGETリクエストおよびブートストラップ認証情報を使用してすべてのサブスクリプションを取得できます。

GET /application/currentApplication/subscriptions
Host: ...
Authorization: Basic ...

ブートストラップユーザーの認証情報は、アプリケーション所有者の認証情報で認証されたGETリクエストで取得できます。

GET /application/applications/<APPLICATION_ID>/bootstrapUser
Host: ...
Authorization: Basic ...

マルチテナント分離での典型的なユーザー切り替えの例を以下に示します。このシナリオでは、マイクロサービスにサブスクライブしている各テナントにアラームを送信する必要があると仮定しています。

ユーザーは、マイクロサービス機能を使用して、サブスクライブされたすべてのテナントコールにアラームを発生させたいと考えています。

手順：

1. ユーザーはプラットフォームのエンドポイント/service/<microservice>/createAlarmsにリクエストを送信します。
2. プラットフォームはユーザー認証情報を確認し、リクエストをマイクロサービスに転送します。
3. マイクロサービスは（環境変数から）ブートストラップ認証情報を読み取り、それらを使用して、登録しているすべてのテナントのサービスユーザー認証情報を取得します。
4. マイクロサービスはサービスユーザー認証情報を繰り返し使用しながら、各テナントへのアラームを作成します。
5. マイクロサービスは結果をプラットフォームに返し、プラットフォームはそれをユーザーに返します。

暗号化

テナントオプションを暗号化するメカニズムがあり、暗号化されテナントオプションをマイクロサービスリクエストに挿入すると自動的に解読されます。

「credentials」で始まるカテゴリにテナントオプションが作成された場合、それは自動的に暗号化され、システムユーザーのみ暗号化されていないものを取得できます。たとえば、アプリケーションコンテキストパスに一致するカテゴリでテナントオプションを作成する場合、値はプラットフォーム上のマイクロサービスプロキシによってヘッダー(key => value)としてマイクロサービスに渡されます。暗号化されたオプションはすべて解読され、渡されます。さらに、マイクロサービスの実行時にオプションのエンドポイントを使用して、RESTを介してそのオプションを取得できます。

詳細についてはThings Cloud OpenAPI仕様 にあるThings Cloud OpenAPI仕様のテナントAPIを参照してください。

マイクロサービスのランタイム

プラットフォームにデプロイされたマイクロサービスには特定のランタイム環境があり、マイクロサービスが実行される特有のThings Cloud クラスターに関する詳細を理解する必要があります。たとえば、マイクロサービスは Things Cloud REST API のエンドポイントアドレスを知っておかなければなりません。この情報は環境変数によって提供され、コンテナの起動時に Things Cloud によって挿入されます。

環境変数

マイクロサービスでは、次の環境変数を使用します。

例

前提条件: マイクロサービスはパッケージ化され、Dockerリポジトリーにデプロイされています。次のコマンドでマイクロサービスイメージ名とタグを取得します。

$ docker images

環境変数を提供してマイクロサービスのDockerコンテナーを実行します。

$ docker run -–cap-drop=ALL -–cap-add=NET_BIND_SERVICE \
   -e C8Y_BOOTSTRAP_TENANT=<BOOTSTRAP_TENANT> \
   -e C8Y_BOOTSTRAP_USER=<BOOTSTRAP_USERNAME> \
   -e C8Y_BOOTSTRAP_PASSWORD=<BOOTSTRAP_USER_PASSWORD> \
   -e C8Y_MICROSERVICE_ISOLATION=MULTI_TENANT \
   -e C8Y_BASEURL=<URL> -i -t <DOCKER_REPOSITORY_IMAGE>:<TAG>

&, !, ;, \ などの特殊文字の前にバックスラッシュ()を使用します。

タイムゾーン変数

timezone変数を使用すると、マイクロサービスが使用するデフォルトのタイムゾーンが設定できます。 マイクロサービスのインストーラーは、次の設定に従って TZ 環境変数をマイクロサービスに挿入します。

• マイクロサービス所有者テナントのテナントオプション
• プラットフォームアプリケーション環境変数（MICROSERVICE_RUNTIME_TIMEZONE）

テナントオプションの優先度が高いため、両方の場所でパラメータが設定されている場合は、テナントオプションの値が使用されます。

例

マイクロサービスの所有者にテナントオプションがあると仮定します。

{
    "category" : "microservice.runtime",
    "key" : "timezone",
    "value" : "Europe/Warsaw"
}

Docker内でマイクロサービスをデプロイして実行すると、次の変数がマイクロサービス環境に渡されます。

TZ=Europe/Warsaw

Javaベースのマイクロサービスを使用する場合、この変数は自動的に読み取られ、Java処理に適用されます。追加の作業は不要です。他のプログラミング言語で開発されたマイクロサービスは、一部手動での作業が必要である場合があります。つまり、環境からTZ値を読み込み、それを使用して言語レベルでタイムゾーンをプログラム的に構成する必要があります。

プロキシ変数

プロキシ変数は、さまざまなプロトコルのプロキシURLを設定するために使用されます。Javaで記述されたマイクロサービスの場合、各変数を設定すると、対応するパラメータがJVM実行時に渡されます（詳細情報については Java Networking and Proxies ウェブページを参照して下さい）。

プロキシ変数は、インストール中にマイクロサービス環境に渡されます。マイクロサービスインストーラは、以下の設定に従って環境に変数を渡します。

• マイクロサービス所有者テナントのテナントオプション
• プラットフォームアプリケーション環境変数

テナントオプションは優先度が高いため、両方の場所でパラメータが設定されている場合は、テナントオプションの値が使用されます。

以下の表は、オプションとプロキシ変数の一覧です。

すべてのテナントオプションには次のカテゴリが含まれます: microservice.runtime

各プロトコル（HTTP、HTTPS、Socks）について、HOSTパラメーターが設定されている場合は、マイクロサービス環境変数がランタイムのみに渡されます。HOSTパラメーターが見つからない場合、同じプロトコルの他のパラメーターは処理されません。

例

マイクロサービス所有者テナントには次のテナントオプションがあります：

{ "category" : "microservice.runtime", "key" : "proxy.http.host", "value" : "10.11.12.13" }
{ "category" : "microservice.runtime", "key" : "proxy.http.port", "value" : "8080" }

そして、プラットフォームアプリケーションには次の環境変数があります：

MICROSERVICE_RUNTIME_PROXY_HTTP_PORT=8181

Docker内でマイクロサービスをデプロイして実行すると、次の変数がマイクロサービス環境に渡されます（ポート値に注意してください）:

PROXY_HTTP_HOST=10.11.12.13
PROXY_HTTP_PORT=8080

{ "category" : "microservice.runtime", "key" : "proxy.https.host", "value" : "10.11.12.13" }

そして、プラットフォームアプリケーションには次の環境変数があります:

MICROSERVICE_RUNTIME_PROXY_HTTPS_PORT=8181

Docker内でマイクロサービスをデプロイして実行すると、次の変数がマイクロサービス環境に渡されます:

PROXY_HTTP_HOST=10.11.12.13
PROXY_HTTP_PORT=8181        

{ "category" : "microservice.runtime", "key" : "proxy.http.port", "value" : "8080" }
{ "category" : "microservice.runtime", "key" : "proxy.http.non.proxy.hosts", "value" : "localhost" }

そして、プロキシホストは（テナントオプションにも環境変数にも）設定されていません。

Docker内でマイクロサービスをデプロイして実行しても、プロキシ環境変数は渡されません。

{ "category" : "microservice.runtime", "key" : "socks.http.host", "value" : "10.11.12.13" }  

Docker内でマイクロサービスをデプロイして実行すると、次の変数がマイクロサービス環境に渡されます(ホストパラメーターのみ)。

SOCKS_HTTP_HOST=10.11.12.13

プラットフォームアクセスおよびその他のマイクロサービス

マイクロサービスを実行しているThings Cloudプラットフォームに対してリクエストを実行するには、C8Y_BASEURL変数で指定されたホストにリクエストを送信する必要があります。

マイクロサービスは、プラットフォームで実行されている他のマイクロサービスに直接アクセスできません。 代わりに、マイクロサービスはプロキシとしてプラットフォームを使用する必要があります。他のアプリケーションへのアクセスに使用されるエンドポイントは<C8Y_BASEURL>/service/<OTHER_APPLICATION_NAME>/ です。

リクエストルーティング

リクエストは、分離レベル（明確にするため、現時点では自動スケーリングは無視されます）、サブスクリプション、認可に応じてマイクロサービスにリダイレクトされます。プラットフォームへの典型的なリクエストは次のようになります。

<METHOD>  /service/<MICROSERVICE>/<MICROSERVICE_ENDPOINT>
Host: ...
Authorization: Basic ...

認証情報は、リクエスト元のユーザーがマイクロサービスへのアクセスを許可されているかどうかを確認するために使用され、その後、テナントのサブスクリプションが確認されます。両方のチェックを無事通過すると、リクエストは、分離レベルがテナントごとの場合は専用のマイクロサービスデプロイメントにルーティングされ、マルチテナント分離の場合は共有デプロイメントにルーティングされます。

ルーティングされたリクエストの/service/<MICROSERVICE> 部分は削除されます。ただし、Authorizationヘッダーは変更されないため、リクエストはテナントプラットフォームユーザーとして実行されます。

<METHOD>  /<MICROSERVICE_ENDPOINT>
Host: ...
Authorization: Basic ...

マイクロサービスユーティリティツール

Things Cloud は、マイクロサービスのパッケージ化、デプロイメント、サブスクリプションを簡単にするユーティリティツールを提供しています。 このスクリプトには、Dockerと軽量で柔軟なJSONプロセッサーであるjqのローカルインストールが必要です。

前提条件

Docker

Dockerがインストールされていることを確認してください。Dockerのバージョンは1.2.6以上でなければなりません。

$ docker version
Client:
 Version:         1.12.6
 API version:     1.24
 OS/Arch:         linux/amd64

Server:
 Version:         1.12.6
 API version:     1.24
 OS/Arch:         linux/amd64

JSON プロセッサー

LinuxシステムにJSONプロセッサーをインストールするには、次のコマンドを実行します。

$ sudo yum install jq

macOSの場合、以下のコマンドを使用します。

$ brew install jq

Bash

マイクロサービスユーティリティツール（スクリプト）を実行するには、Bashのバージョンが4以降でなければなりません。次のコマンドでBashのバージョンを確認します。

$ bash --version

GNU bash, version 5.0.3(1)-release (x86_64-apple-darwin18.2.0)
Copyright (C) 2019 Free Software Foundation, Inc.

macOSシステムには、プリインストールされたBashのバージョン3.xが付属しています。したがって、マイクロサービススクリプトを実行するには、更新する必要があります。これを行うには、以下のコマンドを実行してください。

$ brew install bash
$ chsh -s /usr/local/bin/bash

bash --versionの実行中にBashのバージョンが変更されなかった場合、システムを再起動する必要があります。更新されたインタープリターは /usr/local/bin/bash にインストールされ、マイクロサービスユーティリティツール（スクリプト）の最初の行を次のように変更する必要があるので、注意してください。

#!/usr/local/bin/bash

or

#!

マイクロサービスユーティリティツールの構成設定

スクリプトはGitHubリポジトリ cumulocity-examplesにあります。

スクリプトを実行できるようにモードを変更します。

$ chmod +x microservice

ヘルプオプションを使用して、使用可能なすべての機能(goal)とオプションを確認します。

$ ./microservice help

パッケージ化

マイクロサービスをデプロイするには、Dockerイメージとしてパッケージ化する必要があります。それには、Dockerの image.tar と cumulocity.json ファイルをZIPファイルにパッケージ化します。

マイクロサービスをパッケージ化するには、次のディレクトリ構造が必要です。

/docker/Dockerfile      # Instructions to build the Docker image_
/docker/*               # All files within the directory will be included in the Docker build
/cumulocity.json        # The application manifest file

スクリプトは、このような構造を保持する親フォルダーで実行するか、-dirオプションを使用してディレクトリへのパスを渡すことで実行できます。 たとえば、「Hello World」マイクロサービスアプリケーションをパッケージ化するには、次のように実行します。

$ ./microservice pack --name hello-world

これにより、hello-world.zip という名前のZIPファイルと、エクスポートされたDockerイメージである中間の image.tar を作成します。

展開

マイクロサービスは、Things Cloud プラットフォームに正常にデプロイされると利用可能になります。これは、上記で指定されたようにパッケージ化されたマイクロサービスを使用してZIPファイルをアップロードすることによって行われます。ユーザーは、イメージをDockerレジストリに直接プッシュできません。

マイクロサービスアプリケーションのデプロイは非常に簡単で、以下のコマンドを実行するだけです。

$ ./microservice deploy -n hello-world -d <URL> -u <username> -p <password> -te <tenant>

マイクロサービスをデプロイするには、テナントとユーザーの認証情報が必ず必要です。 実行が成功すると、指定された名前でThings Cloud プラットフォーム上にアプリケーションが存在していなければ、新たに作成されます。 次に hello-world.zip ファイルをプラットフォームにアップロードします。アップロードされると、新しいアプリケーションは エコシステム > マイクロサービス で管理アプリケーション内に表示されます。

マニフェストファイルにマイクロサービスアプリケーション名が記載されていない場合、バージョン番号を除いたZIPファイル名から自動的に推論されます。

Things Cloud へのマイクロサービスのデプロイの詳細については、Things Cloudへのマイクロサービスのデプロイに関するユーザーガイドのマイクロサービスの管理を参照してください。

サブスクライブする

アプリケーションを使用するには、アプリケーションをサブスクライブする必要があります。次のコマンドを実行して、テナントをデプロイされたマイクロサービスにサブスクライブします。

$ ./microservice subscribe -n hello-world -d <URL> -u <username> -p <password> -te <tenant> -id <APPLICATION_ID>

IDパラメータで指定されたアプリケーションへのテナントサブスクリプションが作成されます。ユーザーが既にサブスクリプションされている場合は、警告メッセージが表示されます。

複数のGoal

Goalを複数同時に実行して、アプリケーションを1行でパッケージ化、デプロイ、登録できます。この場合、アプリケーションIDはスクリプトによって自動的に取得されます。

$ ./microservice pack deploy subscribe -n hello-world -d <URL> -u <username> -p <password> -te <tenant>

マイクロサービスの運用

Things Cloud は、マイクロサービスインスタンスを監視し、メトリックを保存することにより、マイクロサービスを管理します。マイクロサービスがメモリ制限を超えた場合、自動的に再起動されます。また、CPU使用率が高い場合、マイクロサービスは自動でスケーリングをします。詳細については、上記のスケーリングを確認してください。

トラブルシュート

よくある問題のいくつかを下記に記述しました。

マイクロサービスアプリケーションのアップロード時に「マイクロサービスアプリケーション名が正しくありません」というエラーが表示されます

マイクロサービスアプリケーションの名前には、小文字のアルファベット、数字、ダッシュのみを使用してください。名前の最大長は23文字です。

マイクロサービスを展開しましたが、エンドポイントへの全てのリクエストに対し「マイクロサービスが利用できません接続が拒否されました」というエラーメッセージが返されます。

マイクロサービスをアップロードした後、内部デプロイとコンテナの実行には数分かかる場合があります。完了すると、エラーメッセージが消えます。その間、コーヒーでもお楽しみください☕️

「イメージの引き出しに失敗しました… rpc error: code = Canceled desc = context canceled」というアラームが作成されました。

これは、ポッド内のコンテナー用に大きなDockerイメージを引き出すときに時々発生する場合があります。正常に引き出されると、通常に戻ります。

「ポッド同期エラー」というアラームが作成されました。

これは、Kubernetesが自動スケーリングを実行していて、ポッドを再起動しようとしているときに発生する場合があります。

「すべての述語に一致する使用可能なノードがありません: [Insufficient cpu …]」というアラームが作成されました。

あなたのコンテナのほかに他のコンテナが実行されており、これらはデフォルトでKubernetesを使用したプロビジョニングがされています。これらの追加コンテナが、単一ノードのCPU割合を占有している可能性があります。Kubernetesがこれを管理し、ポッドのステータスを保留中から実行中に変更します。