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

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

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

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

ノート

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

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

このシナリオの詳細は、「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. シークレットを識別する名前を入力します。機密情報の入力は避けてください。

      nameの例: jira_auth_plain_text

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

      例の説明: jira_auth_plain_text

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

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

    11. 「シークレットの作成」を選択します。
    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>

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

  • 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. 「トピックの作成」パネルを開きます: 「トピック」リスト・ページで、「トピックの作成」を選択します。リスト・ページの検索に関するヘルプが必要な場合は、トピックのリストを参照してください。
    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. 前に作成したトピック(例の名前はメンテナンス・トピック)を選択します: 「トピック」リスト・ページで、作業するトピックを選択します。リスト・ページまたはトピックの検索に関するヘルプが必要な場合は、トピックのリストを参照してください。
    2. ファンクション・サブスクリプションを作成します。
      1. 「サブスクリプションの作成」パネルを開きます: トピックの詳細ページで、「サブスクリプションの作成」を選択します。
        「サブスクリプションの作成」パネルが開きます。
      2. 「プロトコル」で、「ファンクション」を選択します。
      3. 残りのフィールドに入力します。
        フィールド Description
        ファンクション・コンパートメント ファンクションを含むコンパートメントを選択します。
        ファンクション・アプリケーション 関数を含むアプリケーションを選択します。
        関数 関数を選択します。
      4. 「作成」を選択します。
        新しいファンクション・サブスクリプションの確認は必要ありません。
    3. 電子メール・サブスクリプションを作成します。
      1. 「サブスクリプションの作成」パネルを開きます: トピックの詳細ページで、「サブスクリプションの作成」を選択します。
        「サブスクリプションの作成」パネルが開きます。
      2. 「プロトコル」で、「電子メール」を選択します。
      3. 残りのフィールドに入力します。
        フィールド Description
        電子メール 電子メール・アドレスを入力してください。
      4. 「作成」を選択します。
      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
          }
        ]
      }
    }