OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Integrating with Jira

If you are using Jira, you can forward alerts from Red Hat Advanced Cluster Security for Kubernetes to Jira.

The following steps represent a high-level workflow for integrating Red Hat Advanced Cluster Security for Kubernetes with Jira:

  1. Setup a user in Jira.

  2. Use the Jira URL, username, and password to integrate Jira with Red Hat Advanced Cluster Security for Kubernetes.

  3. Identify policies for which you want to send notifications, and update the notification settings for those policies.

Configuring Jira

Start by creating a new user, and assign appropriate roles and permissions.

Prerequisites

  • You need a Jira account with permissions to create and edit issues in the project with which you are integrating.

Procedure

Configuring Red Hat Advanced Cluster Security for Kubernetes

Create a new integration in Red Hat Advanced Cluster Security for Kubernetes by using the Jira server URL and user credentials.

Procedure

  1. On the RHACS portal, navigate to Platform Configuration → Integrations.

  2. Scroll down to the Notifier Integrations section and select Jira Software.

  3. Click New Integration.

  4. Enter a name for Integration Name.

  5. Enter the user credentials in the Username and Password or API Token boxes.

  6. For Issue Type, enter a valid Jira Issue Type, for example Task, Sub-task, or Bug.

  7. Enter the Jira server URL in the Jira URL box.

  8. Enter the key of the project in which you want to create issues in the Default Project box.

  9. Use the Annotation Key For Project box to create issues in different Jira projects.

  10. If you use custom priorities in your Jira project, use the Priority Mapping toggle to configure custom priorities.

  11. If you use mandatory custom fields in your JIRA project, enter them as JSON values in the Default Fields JSON (Necessary If Required Fields) box. For example:

    {
  "customfield_10004": 3,
  "customfield_20005": "Alerts",
}

  12. Select Test (checkmark icon) to test that the integration with Jira is working.

  13. Select Create (save icon) to create the configuration.

Creating issues in different Jira projects

You can configure Red Hat Advanced Cluster Security for Kubernetes to to create issues in different Jira projects so that they directly go to the right team.

Prerequisites

  • You must have an account with access to each project that you want to send the alerts to.

Procedure

  1. Add an annotation similar to the following in your deployment YAML file:

    jira/project-key: <jira_project_key>

  2. Use the annotation key jira/project-key in the Annotation Key For Project field when you configure Red Hat Advanced Cluster Security for Kubernetes.

After the configuration is complete, if a deployment has an annotation in the YAML file, Red Hat Advanced Cluster Security for Kubernetes sends the alert to the project specified for that annotation. Otherwise, an alert is sent to the default project.

Configuring custom priorities in Jira

If you are using custom priorities in your Jira project, you can configure them in Red Hat Advanced Cluster Security for Kubernetes.

Procedure

  1. While configuring Jira integration in Red Hat Advanced Cluster Security for Kubernetes, turn on the Priority Mapping toggle. Red Hat Advanced Cluster Security for Kubernetes gets the JIRA project schema, and auto fills the values for the CRITICAL_SEVERITY, HIGH_SEVERITY, MEDIUM_SEVERITY, and LOW_SEVERITY fields.

  2. Verify or update the priority values based on your JIRA project configuration.

  3. Select Test (checkmark icon) to test that the integration with Jira is working.

  4. Select Create (save icon) to create the configuration.

If you get an error, follow the instructions in the Troubleshooting Jira integration section.

Configuring policy notifications

Enable alert notifications for system policies.

Procedure

  1. On the RHACS portal, navigate to Platform Configuration → Policies.

  2. Select one or more policies for which you want to send alerts.

  3. Under Bulk actions, select Enable notification.

  4. In the Enable notification window, select the Jira notifier.

    If you have not configured any other integrations, the system displays a message that no notifiers are configured.

  5. Click Enable.

  • Red Hat Advanced Cluster Security for Kubernetes sends notifications on an opt-in basis. To receive notifications, you must first assign a notifier to the policy.

  • Notifications are only sent once for a given alert. If you have assigned a notifier to a policy, you will not receive a notification unless a violation generates a new alert.

  • Red Hat Advanced Cluster Security for Kubernetes creates a new alert for the following scenarios:

    • A policy violation occurs for the first time in a deployment.

    • A runtime-phase policy violation occurs in a deployment after you resolved the previous runtime alert for a policy in that deployment.

Troubleshooting Jira integration

If you are using custom priorities or mandatory custom fields in your Jira project, you may get an error when you try to integrate Red Hat Advanced Cluster Security for Kubernetes with Jira Software. This error might be because of the mismatch between the severity and the priority field values.

If you do not know the custom priority values in your JIRA project, use the roxctl CLI to enable debug logging for JIRA integration.

Procedure

  1. To get the custom priority values from your JIRA project, run the following command to turn on debug logging for JIRA integration:

    $ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Debug --modules notifiers/jira

  2. Follow the instructions to configure Red Hat Advanced Cluster Security for Kubernetes for Jira integration. When you test the integration, even if the integration test fails, the generated log includes your JIRA project schema and the custom priorities.

  3. To save the debugging information as a compressed .zip file, run the following command:

    $ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug dump

  4. Unzip the .zip file to retrieve the custom priority values in use in your JIRA project.

  5. To turn off debug logging, run the following command:

    $ roxctl -e "$ROX_CENTRAL_ADDRESS" central debug log --level Info

  6. Configure Red Hat Advanced Cluster Security for Kubernetes for Jira integration again and use the priority values to configure custom priorities.