[OCI]OCI Events、Notifications、Functionsを使用した自動 Jira チケッティング (2020/08/31)

8月 30, 2020

OCI Events、Notifications、Functionsを使用した自動 Jira チケッティング (2020/08/31)

https://blogs.oracle.com/cloud-infrastructure/automated-jira-ticketing-using-oci-events,-notifications,-and-functions
投稿者：Mayur Raleraskar | Solutions Architect
私が仕事をしている顧客の多くは、Oracle Notificationsサービスを使用して、
Oracle Cloud Infrastructureアプリケーションで発生したイベントについて開発者やDevOpsチームにアラートを出しています。
イベントは、コンピュート・インスタンスの再起動、バケットに作成されたオブジェクトなど、
さまざまなタイプの異なるリソースに対応しています。
Notificationsサービスはすでに、Email、Functions、Slack、PagerDutyなどの多くのサービスとすぐに使える統合機能を提供しています。
これらの顧客の多くは、これらのイベントを追跡するために Atlassian の Jira などのチケットシステムを使用しており、
アラートが発生したときに自動的に Jira のチケットを提出する最良の方法について問い合わせがありました。

このブログでは、Oracle Cloud InfrastructureでOracle Functionsを使用し、
Functionsコードから直接Jira APIを呼び出すことで、イベントやアラートが発生したときにJiraチケットを自動的にファイルする方法を紹介します。

プロセスの概要

このエンド・ツー・エンドのワークフローを具体的に示すために、
Autonomous Transaction Processing Databaseのメンテナンス・リマインダー・イベントを例に説明します。
メンテナンス・リマインダー・イベントは、Autonomous Transaction Processing Databaseのメンテナンスが予定されているときに生成されます。
このイベントが発生すると、オンコールのエンジニアにJiraチケットを作成して通知します。
また、電子メールを送信して、チーム全体に同様のことを知らせることもできます。
このソリューションには、Oracle Cloud Infrastructure のイベントサービス、通知サービス、および Functions を使用しています。

Autonomous Transaction Processing Databaseは、バックアップ、チューニング、スケーリングなどの
ありふれたデータベース管理タスクをすでに自動化しています。
このソリューションは、この自動化を改善するものです。

End-to-End Flow

Autonomous Transaction Processing メンテナンスリマインダーイベントのイベントルールは、対象アクションとしてNotificationを持っています。
このNotificationは、その2つのサブスクリプションとしてFunctionsと電子メールを持っています。
Autonomous Transaction Processing Maintenance Reminderイベントが発生するたびに、
CloudEvent JSON（CNCF準拠でオープン）を入力データとしてNotificationをトリガーします。
Notificationはその後、そのすべてのサブスクリプションにそれをファンアウトします。
FunctionsはこのCloudEventを取り、メンテナンスウィンドウ中にATPを見落とす責任のあるオンコールエンジニアのためのチケットを作成するためにJira Cloudに信号を送ります。

次の図は、データの流れを示しています。

図1：自動化されたJira発券データフロー

前提条件

Oracle Cloud Infrastructure上のサーバーレスFunctionに精通していること。
Oracle Cloud Web Consoleに精通していること
Oracle Cloud上でFunctions開発を行うためのツール、Oracle Cloud CLI、fn CLI、Dockerのローカルインストールが可能な方。
Javaの基本的な知識も推奨されますが、必須ではありません。

Oracle Cloud上のサーバーレスFunctionsに初めて触れる方は、
リファレンスの「Oracle Cloud Infrastructure Functions」のセクションを参照してください。

ステップの概要

Oracle Cloud InfrastructureにVaultとSecretsを作成して、Jiraの資格情報を保存します。
サーバれす Functionのコードを開発します。
適切なIdentity and Access Management (IAM) ポリシーを使用して、Oracle Cloud にFunctionをデプロイします。
Functionをテストします。
Notification トピックを作成し、Functionに接続します。
クラウドイベントルールを作成し、それをNotificationに接続します。

詳細なステップ

ステップ1: Oracle Cloud InfrastructureでVaultとシークレットを作成して、Jiraの資格情報を保存

私たちのFunctionはJira Cloud APIにアクセスするため、Jira Cloudの資格情報を安全に保存および取得する方法が必要です。
Oracle Cloud Vaults とシークレットを使用すると、これを簡単に実現することができます。
次のスクリーンショットのように、コンソールでシークレットを作成します。

図2：Oracle Cloud Infrastructure Web Consoleでのシークレットの作成

この例では、APIトークンを使用したBasic認証を使用しています。
Jiraのシークレットがフォーマットになっていることを確認してください。

このFunctionでは、Oracle Cloud Software Development Kit (SDK)を使用して安全にシークレットを取得し、
Jira Cloud APIを呼び出してチケットを作成しています。
このシークレットについては、アット・レストとイン・トランジットの暗号化を使用しています。
Jira APIの呼び出しにもHTTPSを使用しているので、エンドツーエンドのセキュリティが確保されています。

シークレットが作成されたら、その OCID を便利に保管しておきます。Function作成時に必要になります。

Jira Cloud Rest API を初めて使用する場合は、Jira Cloud のドキュメントを参照してください。

ステップ2：サーバーレスFunctionのコードを開発

このFunctionのJavaコードはすでにGitHubに用意されています。
コードに飛び込む前に、質問に答える必要があります。
Oracle Cloud Event サービスによってFunctionが呼び出されたとき、Functionへの入力は何ですか？

前述したように、JSON は CloudEvent フォーマットに準拠しています。
以下の画像のように、Oracle Cloud Consoleのイベント作成Webページから開発用のJSONの例を取得することができます。

図3：イベントルール作成のためのWebコンソール画面

コードの詳細については、GitHub repo の README.md を参照してください。
特に、シークレットの保存や取得に使用するFunctionや Oracle Cloud SDK の詳細については、GitHub repo の README.md を参照してください。

ステップ3: 適切なIAMポリシーでOracle Cloud InfrastructureにFunctionを導入

Oracle Cloud シークレットサービスを Oracle Cloud プラットフォームのどこでも使用するには、
Functionを IAM プリンシパルとして認証する必要があります。
私たちのFunctionでは、Secrets サービスを使用するためにリソースプリンシパル認証を使用しているため、
動的グループを作成し、適切なポリシーを設定する必要があります。

まず、動的グループ、例えば fn_dg を作成します。
私は、特定のコンパートメント内の特定のタイプのすべてのリソース（この場合、Oracle Functions）を動的グループに含めたいと考えています。
定義は以下の例のようになる。

ALL{resource.type=’fnfunc’, resource.compartment.id=’ocid1.cmpt.x’}

次に、動的グループに適切なポリシーを与えます。
ポリシーは、テナントレベルまたはコンパートメントレベルで適用できます。

allow dynamic-group fn_dg to read secret-family in tenancy

では、次の fn CLI スクリプトを使用して、Oracle Cloud Infrastructure にFunctionを作成してデプロイします。
コメントと一緒にコードに目を通します。
Oracle Cloud のリージョン、コンパートメント、ユーザーなどに固有の環境に合わせて、コードに示されているように変更します。

OCI_CMPT_OCID='ocid1.compartment.oc1..XXXX' # OCID of OCI compartment where you want your function to reside
OCI_CONFIG_USER_PROFILE=yourPrefferedProfile # You need to have this user profile in your OCI CLI and hence in your ~/.oci/config
OCI_USERNAME=yourOciUserName
OCI_USER_EMAIL='XXXX@XXXX.com'
OCI_AUTH_TOKEN='ociAuthTokenForSelectedUser' # Your OCI generated auth token
OCI_DOCKER_REGISTRY_URL=iad.ocir.io # OCI dokcer registry URL. It is region specific e.g. for Ashburn iad.ocir.io
OCI_TENANCY_NAME=intrandallbarnes # Your OCI tenancy name

FN_CONTEXT=fn_cmpt
FN_OCI_PLATFORM_URL='https://functions.us-ashburn-1.oraclecloud.com' # this is the OCI fn service url, again this is region specific
FN_DOCKER_REPO_NAME=docker_repo_faas # Your docker repo name
FN_DOCKER_REPO_URL=$OCI_DOCKER_REGISTRY_URL/$OCI_TENANCY_NAME/$FN_DOCKER_REPO_NAME
FN_OCI_SUBNET_OCID='ocid1.subnet.oc1.iad.XXXX'
FN_APP_NAME=fn_app_jira # Name for the application for the function. Application is a logical container for functions in fn platform.
FN_JIRA_SECRET_OCID='ocid1.vaultsecret.oc1.iad.XXXX'
FN_GITHUB_REPO_NAME=oci_fn_jira_integration
FN_GITHUB_URL="https://github.com/mayur-oci/$FN_GITHUB_REPO_NAME.git"\\\\FN_CLOUD_EVENT_JSON_GIST~='https://gist.githubusercontent.com/mayur-oci/784f67e16dd10d5a3a699ec586a1a368/raw/7cf017ac090b1f9de6d2caa0e600fd7800ee4d76/CloudEvent.json'\\\\\\\\fn create context $FN_CONTEXT
fn use context $FN_CONTEXT
fn update context oracle.compartment-id $OCI_CMPT_OCID
fn update context api-url $FN_OCI_PLATFORM_URL
fn update context registry $FN_DOCKER_REPO_URL
fn update context oracle.profile $OCI_USER_PROFILE # make sure to update your local ~./oci/config file with api and other credentials for this non-admin user

# You need to login, to allow you to push the function docker image to registry, when you build and deploy the function code
docker login -u $OCI_TENANCY_NAME/$OCI_USER_EMAIL -p $OCI_AUTH_TOKEN $OCI_DOCKER_REGISTRY_URL

# Create application for the function
# The subnets specified should be public so that it can hit Jira Cloud endpoint over the internet
# and also have appropriate rules in its security list and route table
# If single subnet, it is recommended that the subnet is multi-AD, for HA.
OCI_SUBNETID_LIST_JSON=[\"$FN_OCI_SUBNET_OCID\"]
fn create app $FN_APP_NAME --annotation oracle.com/oci/subnetIds=$OCI_SUBNETID_LIST_JSON

git clone $FN_GITHUB_URL
cd $FN_GITHUB_REPO_NAME # cd into your function code directory you cloned from github

# Build and deploy the function in the application fn_app_jira
fn deploy --verbose --app $FN_APP_NAME # the name of function is as per func.yaml, for this example it is 'fn-jira-ticket-creation'

fn update function $FN_APP_NAME fn-jira-ticket-creation --memory 512 --timeout 60

# Set up config values for this function
fn config function $FN_APP_NAME fn-jira-ticket-creation JIRA_CLOUD_SECRET_OCID $FN_JIRA_SECRET_OCID
fn config function $FN_APP_NAME fn-jira-ticket-creation JIRA_CLOUD_URL https://oci-jira-integration.atlassian.net/rest/api/3/issue\\\\fn config function $FN_APP_NAME fn-jira-ticket-creation JIRA_PROJECT_ID ONFJ

# For development and debugging purposes invoke the function as below.
echo -n "$(curl -s $FN_CLOUD_EVENT_JSON_GIST)" | fn -v invoke fn_app_jira fn-jira-ticket-creation

スクリプトを実行した後、コンソールでFunctionとそのアプリケーションが表示されるはずです。

図4: スクリプトから作成されたFunction

ステップ4：Functionのテスト

このFunctionはOracle Cloudプラットフォームで生成されたイベントであるため、
開発時にFunctionを呼び出すためのイベントを任意に生成することはできません。
では、本番環境へのデプロイ前にFunctionを開発してテストするにはどうすればよいのでしょうか。

手っ取り早く簡単な方法があります。
前のスニペットですでに示したように、以下のダミーのイベント入力でfn CLIからFunctionを呼び出すことができます。

echo -n "$(curl -s $FN_CLOUD_EVENT_JSON_GIST)" | fn -v invoke fn_app_jira fn-jira-ticket-creation

また、開発ボックス上でのローカルテストのために、JUnit をコードと一緒に使うこともできます。
テストや開発の目的では、実際のイベントにFunctionをフックする必要はありません。

ステップ5：通知トピックを作成して機能につなげる

ここでは、topicForDBMaintainanceReminderという名前のトピックを、2つのサブスクリプションとともに作成します。
1 つは前のステップで開発した fn-jira-ticket-creation Functionで、もう 1 つはこの通知に興味のある受信者のメールアドレスです。
Oracle Notificationサービスは、イベントのファンアウトを複数のサブスクライバに簡単に実現するのに役立ちます。

図5：Oracle Notification Serviceのトピックとサブスクリプション

メッセージの発行ボタンに注意してください。Console から Notification+Function の統合を簡単にテストしてデバッグすることができます。すでにサンプルの CloudEvent JSON があります。このサンプル JSON に対して、このトピックにメッセージを公開することができます。

図 6: トピックに関するメッセージ公開のサンプル

発行ボタンをクリックすると、fn-jira-ticket-creation Functionが呼び出され、メールが送信されます。

ステップ6: クラウドイベントルールを作成し、通知に接続

イベントルールを作成するためには、適切なイベントタイプと条件を選択する必要があります。
条件では、イベントを作成するAutonomous Transaction Processing DatabaseのOCID値をリソースIDとして選択します。
[アクション］ドロップダウンで、［通知］のオプションを選択します。

そして、次のスクリーンショットに示すように、右のコンパートメントとNotificationトピックの名前を選択します。

図 7：Notificationトピックをアクションとしたイベントルールの作成

次に、イベントルールを作成します。

まとめ

その結果、現在では、このデータベースメンテナンスイベントを、Notificationトピックを介して
Oracle Functionと電子メールアドレスでつなぎ合わせています。
Oracle Cloud Infrastructure から今後のデータベースメンテナンスのリマインダーが来るたびに、
オンコールエンジニア用の Jira チケットが作成されます。

図 8: Jira タスクの例

また、Notificationサービスでは、イベント発生時にメールを送信します。

Oracle Cloud Infrastructureの3つの使いやすいビルディング・ブロックの助けを借りて、1つの手作業のプロセスを効率化します。
イベント、Notification、およびFunctionです。
また、SlackとPageDutyをサブスクリプションとしてNotificationsトピックに簡単に追加することもできます。

監査イベントやComputeサービスに関連するイベントなど、他のタイプのOracle Cloud EventsやNotificationsに対しても、
同じソリューション設計を簡単に拡張することができます。
また、Eventを直接Functionsに接続することもできますが、Notificationsサービスを使用してファンアウトすることはできません。

ご不明な点がありましたら、私のメールにお気軽にお問い合わせください。

このブログを検索

Oracle Cloud Infrastructure Blog(翻訳)