シナリオC: リマインダのJiraチケットの申告

メンテナンス・リマインダ・イベントが発生するたびにJiraチケットを自動的に提出します。このシナリオでは、今後のデータベース・メンテナンスのリマインダがOracle Cloud Infrastructureから発生すると、オンコール・エンジニア用のJiraチケットが作成されます。

このシナリオでは、ファンクションJiraチケットのファイル(およびJira資格証明を格納するシークレットの作成)、そのファンクションおよびオプションの電子メールをサブスクリプションとしてトピックに追加し、メンテナンス・リマインダ・イベントが発生したときにそのトピックにメッセージを送信するルールを作成します(Autonomous Container Databaseイベント・タイプを参照)。メッセージがトピックのサブスクリプションにファン・アウトされます。これには、機能に加えてグループの電子メール・アドレスが含まれます。ファンクションは、メッセージの受信時に呼び出されます。

ファンクション以外はすべて、コンソールで設定できます。または、Oracle Cloud Infrastructure CLIまたはAPIを使用して、個別の操作を自分で実行することもできます。

ノート

通知サービスには、ファンクションが呼び出された後にそのファンクションに関する情報はありません。詳細は、ファンクションが呼出しまたは実行されない場合のトラブルシューティング情報を参照してください。

この図は、リマインダ・イベントが発生したときにファンクションを使用してJiraチケットを提出するシナリオのコンテキストでの通知を示しています。

このシナリオの詳細は、OCIイベント、通知およびファンクションを使用したJira自動チケット発行および関連するGitHubリポジトリを参照してください。

必須IAMポリシー

Oracle Cloud Infrastructureを使用するには、管理者によってポリシーでセキュリティ・アクセス権が付与されている必要があります。このアクセス権は、コンソール、あるいはSDK、CLIまたはその他のツールを使用したREST APIのいずれを使用している場合でも必要です。権限を持っていない、または認可されていないというメッセージが表示された場合は、持っているアクセス権のタイプと作業しているコンパートメントを管理者に確認してください。

管理者グループのメンバーであれば、このシナリオを実行するために必要なアクセス権はすでに持っています。そうでない場合は、イベント通知およびファンクションにアクセスする必要があります。ファンクションをトピックのサブスクリプションとして追加するには、そのファンクションに対してFN_INVOCATION権限を持っている必要があります。Jira資格証明にアクセスするには、ファンクションがシークレットの読取りを許可されている必要があります。このシナリオでは、この認可を提供するステップについて説明します。

タスク1: シークレットへの資格証明の格納

Vaultサービスを使用したシークレットの作成の詳細は、Vaultでのシークレットの作成を参照してください。

    1. ナビゲーション・メニューを開き、「アイデンティティとセキュリティ」「Vault」の順にクリックします。
    2. 「リスト範囲」「コンパートメント」リストで、シークレットを作成するコンパートメントの名前をクリックします。
    3. コンパートメント内のボールトのリストから、次のいずれかを実行します。

      • シークレットを作成するボールトの名前をクリックします。

      • 新しいボールトを作成するにはの手順に従ってシークレットに新しいボールトを作成し、そのボールトの名前をクリックします。

    4. 「シークレット」をクリックし、「シークレットの作成」をクリックします。
    5. 「Create Secret」パネルで、「Create in Compartment」リストからコンパートメントを選択します。(シークレットは、ボールトが含まれるコンパートメントの外部に存在できます。)
    6. シークレットを識別する「名前」を入力します。機密情報を入力しないでください。

      名前の例: jira_auth_plain_text

    7. シークレットの識別に役立つ簡単な「説明」を入力します。機密情報を入力しないでください。

      説明の例: jira_auth_plain_text

    8. ボールトへのインポート中にシークレット・コンテンツの暗号化に使用するマスター暗号化キーを選択します。(キーは同じボールトに属する必要があります。)
    9. 「シークレット・タイプ・テンプレート」で、「プレーン・テキスト」を選択します。
    10. 「シークレット・コンテンツ」に、ログイン電子メールと認証トークンをコロンで区切って、Jira資格証明を次の形式で入力します:

      <your-jira-cloud-login-email>:<your-jira-cloud-auth-token>

    11. 「Create Secret」をクリックします。
    12. シークレットを安全にフェッチするためにファンクション・コードで使用するためのシークレットOCIDに注意してください。
  • ノート

    ボールトへのインポート中にシークレットを暗号化するには、対称キーを指定する必要があります。非対称キーではシークレットを暗号化できません。さらに、指定したボールトにキーが存在する必要があります。

    oci vault secret create-base64コマンドおよび必須パラメータを使用して、Jira資格証明を格納するシークレットを作成します:

    oci vault secret create-base64 --compartment-id <target_compartment_id> --secret-name <secret_name> --vault-id <target_vault_id> --description <secret_description_text> --key-id <encryption_key_id> --secret-content-content <base64_encoded_secret_content> --secret-content-name <unique_content_name> --secret-content-stage <secret_version_rotation_state>

    For a complete list of parameters and values for CLI commands, see the CLI Command Reference.

  • CreateSecret操作を実行してシークレットを作成します。

    例:

    POST /20180608/secrets
    Host: <managementEndpoint>
    <authorization and other headers>
    {
      "vaultId": "<vault_OCID>",
      "compartmentId": "<compartment_OCID>",
      "secretName": "jira_auth_plain_text",
      "description": "jira_auth_plain_text",
      "keyId": "<key_OCID>",
      "secretContent": 
        {
          "content": "<base64_encoded_secret_contents>",
          "contentType": "BASE64"
        }
    }
    ノート

    各リージョンには、シークレットの作成、更新およびリスト操作のための一意のエンドポイントがあります。このエンドポイントは、コントロール・プレーンURLまたはシークレット管理エンドポイントと呼ばれます。各リージョンには、シークレット・コンテンツの取得に関連する操作に対応する一意のエンドポイントもあります。このエンドポイントは、データ・プレーンURLまたはシークレット取得エンドポイントと呼ばれます。リージョン・エンドポイントの詳細は、APIドキュメントを参照してください。

    APIの使用およびリクエストの署名の詳細は、REST APIのドキュメントおよびセキュリティ資格証明を参照してください。SDKの詳細は、SDKおよびCLIを参照してください。

タスク2: ファンクションの作成

この項では、ファンクションの作成のコード・サンプルを示し、Vaultサービスを使用して作成されたシークレットでJira資格証明にアクセスするファンクションを認可するステップについて説明します。

ファンクション・コードのサンプル

次のコード・サンプルは、Jiraチケットを提出する関数用です。

getSecretForOcidを含む行にシークレットOCIDを追加します。

ファンクションの作成およびデプロイの手順は、ファンクションの作成およびデプロイを参照してください。

public String handleRequest(CloudEvent cloudEvent) {
 
    // Json body of Cloud event from Oracle Event Service in serialized into cloudEvent object by Fn SDK implicitly
    System.err.println("Inside Java jira function with input as " + cloudEvent.getEventType() + "  " + cloudEvent.getData().getResourceName());
 
    String response = jiraCreateTicket(cloudEvent);
 
    if (response != null) return response;
 
    return null;
}
 
private String jiraCreateTicket(CloudEvent cloudEvent) {
 
    try {
        //create jira ticket body as per CloudEvent
        String jsonBodyJira = getJiraApiBody(cloudEvent);
 
        String jiraCloudEndpoint = System.getenv().get("JIRA_CLOUD_URL");
        String ocidForSecretForJiraAuthToken = System.getenv().get("JIRA_CLOUD_SECRET_OCID");
        String jiraAuthToken= getSecretForOcid(ocidForSecretForJiraAuthToken); // base64 encoded form of <YourJiraUsername:YourJiraAuthToken>
 
        // actual REST call to JIRA cloud
        OkHttpClient client = new OkHttpClient().newBuilder()
                .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, jsonBodyJira);
        Request request = new Request.Builder()
                .url(jiraCloudEndpoint)
                .method("POST", body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", "Basic "+ jiraAuthToken)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
 
    } catch (JsonProcessingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
    return null;
}
ファンクションによるシークレットへのアクセスの承認

動的グループを使用して、ファンクションにシークレットの読取り権限を付与します。以前に作成したシークレットに格納されているJira資格証明にアクセスするには、ファンクションにこの認可が必要です。

シークレットへのアクセスをファンクションに認可するには(コンソール)
  1. 関数OCID (形式はocid1.fnfunc.oc1.iad.exampleuniqueID)を見つけてノートにとります。
  2. 動的グループに関数を含めます。関連する動的グループで、次のルールを指定します:
    resource.id = '<function-ocid>'

    または、すべての機能を含む動的グループを作成できます。

    ALL{resource.type='fnfunc', resource.compartment.id='<compartment_OCID>'}
  3. シークレットへの動的グループ・アクセス権の付与: 次のポリシーを追加します:
    allow dynamic-group <dynamic-group-name> to read secret-family in tenancy

他のOracle Cloud Infrastructureリソース(コンピュート・インスタンスなど)へのアクセスをファンクションに認可するには、動的グループにファンクションを含め、それらのリソースへのアクセス権を動的グループに付与するポリシーを作成します。詳細は、実行しているファンクションからの他のOracle Cloud Infrastructureリソースへのアクセスを参照してください。

動的グループの詳細は、動的グループの管理を参照してください。

タスク3: トピックの作成

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

    1. 「トピックの作成」パネルを開きます。
      1. ナビゲーション・メニューを開き、「開発者サービス」をクリックします。「アプリケーション統合」で、「通知」をクリックします。
      2. 操作権限を持つコンパートメントを選択します。
      3. 「トピックの作成」をクリックします。
    2. 「名前」に、「メンテナンス・トピック」と入力します。
    3. 「作成」をクリックします。
  • oci ons Topic createコマンドおよび必須パラメータを使用してトピックを作成します:

    oci ons topic create --name <name> --compartment-id <compartment_OCID>

    例:

    oci ons topic create --name "Maintenance Topic" --compartment-id "<compartment-ocid>"

    CLIコマンドのパラメータおよび値の完全なリストは、通知のコマンドライン・リファレンスを参照してください。

  • CreateTopic操作を実行してトピックを作成します。

    例:

    POST /20181201/topics
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "name": "Maintenance Topic",
      "compartmentId": "<compartment_OCID>"
    }

タスク4: サブスクリプションの作成

ファンクション・サブスクリプションを作成する前に、ファンクションをデプロイする必要があります。

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

    1. 前に作成したトピックを選択します。
      1. ナビゲーション・メニューを開き、「開発者サービス」をクリックします。「アプリケーション統合」で、「通知」をクリックします。
      2. 操作権限を持つコンパートメントを選択します。
      3. 前に作成したトピックの名前(例の名前はメンテナンス・トピック)をクリックします。
    2. ファンクション・サブスクリプションを作成します。
      1. 「サブスクリプションの作成」パネルを開きます: トピックの詳細ページで、「サブスクリプションの作成」をクリックします。
        「サブスクリプションの作成」パネルが開きます。
      2. 「プロトコル」で、「ファンクション」を選択します。
      3. 残りのフィールドに入力します。
        フィールド 摘要
        ファンクション・コンパートメント ファンクションを含むコンパートメントを選択します。
        機能アプリケーション ファンクションを含むアプリケーションを選択します。
        関数 関数を選択します。
      4. 「Create」をクリックします。
        新しいファンクション・サブスクリプションの確認は必要ありません。
    3. Eメール・サブスクリプションを作成します。
      1. 「サブスクリプションの作成」パネルを開きます: トピックの詳細ページで、「サブスクリプションの作成」をクリックします。
        「サブスクリプションの作成」パネルが開きます。
      2. 「プロトコル」で、「電子メール」を選択します。
      3. 残りのフィールドに入力します。
        フィールド 摘要
        電子メール 電子メール・アドレスを入力してください。
      4. 「Create」をクリックします。
      5. 新しい電子メール・サブスクリプションの確認:電子メールを開き、確認URLに移動します。
  • ノート

    電子メール・サブスクリプションの作成後、確認します。

    oci ons Subscription createコマンドおよび必須パラメータを使用して、各サブスクリプションを作成します:

    oci ons subscription create --protocol <subscription_type> --subscription-endpoint <endpoint> --compartment-id <compartment_OCID> --topic-id <topic_OCID>

    ファンクション・サブスクリプションの例:

    oci ons subscription create --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

    Eメール・サブスクリプションの例:

    oci ons subscription create --protocol "EMAIL" --subscription-endpoint "maintenance.team@example.com" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

    CLIコマンドのパラメータおよび値の完全なリストは、通知のコマンドライン・リファレンスを参照してください。

  • ノート

    電子メール・サブスクリプションの作成後、確認します。

    CreateSubscription操作を実行して、各サブスクリプションを作成します。

    ファンクション・サブスクリプションの例:

    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "ORACLE_FUNCTIONS",
      "endpoint": "<function_OCID>"
    }

    Eメール・サブスクリプションの例:

    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "EMAIL",
      "endpoint": "maintenance.team@example.com"
    }

タスク5: イベント・ルールの作成

  • この項では、データベース・サービスがデータベース・メンテナンス・リマインダに対してイベントを発行するたびにトピックにメッセージを送信するルールの作成について説明します。

    1. ナビゲーション・メニューを開き、「監視および管理」をクリックします。「イベント・サービス」で、「ルール」をクリックします。
    2. 作業の権限があるコンパートメントを選択し、「ルールの作成」をクリックします。

      イベントは、このコンパートメントに作成したルールと、このコンパートメントおよび子コンパートメントのリソースから発行されたイベント・メッセージを比較します。

    3. 次を入力します。
      • 表示名: ルールのわかりやすい名前を指定します。この名前は後で変更できます。機密情報を入力しないでください。

        例: メンテナンス・リマインダ

      • 説明: ルールの機能に関する説明を指定します。この説明は後で変更できます。機密情報の入力は避けてください。

        例: メンテナンス・トピックにメッセージを送信します

    4. 「ルール条件」で、データベース・リマインダ・イベントのフィルタを作成します:
      • 「サービス名」で、「データベース」を選択します。
      • 「イベント・タイプ」で、「Autonomous Container Database - メンテナンス・リマインダ」を選択します。
    5. 「アクション」で、以前に作成したトピックを選択します:
      1. 「通知」を選択します。
      2. 「通知コンパートメント」を選択します。
      3. 以前に作成したトピックを選択します。
    6. 「ルールの作成」をクリックします。
  • メンテナンス・リマインダによってトリガーされ、このトピックを宛先として参照するルールを作成します。

    1. 前に作成したトピックを参照して、次を含むファイルaction.jsonを作成します。

      例:

      {
        "actions": [
            {
              "actionType": "ONS",
              "description": "string",
              "isEnabled": true,
              "topicId": "<topic_OCID>"
            }
        ]
      }
    2. コマンド・プロンプトを開き、oci events rule createコマンドを実行します。

      例:

      oci events rule create --display-name <friendly_name> --is-enabled true --condition "{\"eventType\":[\"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"]}" --compartment-id <compartment_OCID> --actions file://action.json

      CLIコマンドのパラメータおよび値の完全なリストは、CLIコマンド・リファレンスを参照してください。

      CLIを使用したルールの作成の詳細は、イベント・ルールの作成を参照してください。

  • CreateRule操作を実行して、イベント・ルールを作成します。

    例:

    POST /20181201/rules
    Host: events.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    
    {
      "displayName": "Maintenance Reminder",
      "condition": "{
        \"eventType\": \"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"
        }",
      "compartmentId": "<compartment_OCID>",
      "isEnabled": true,
      "actions": {
        "actions": [
          {
            "actionType": "ONS",
            "topicId": "<topic_OCID>",
            "isEnabled": true
          }
        ]
      }
    }