Chapter 15. Integrating with Jira
Chapter 15. 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: Setup a user in Jira. Use the Jira URL, username, and password to integrate Jira with Red Hat Advanced Cluster Security for Kubernetes. Identify policies for which you want to send notifications, and update the notification settings for those policies. 15.1. 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 Create a user in Jira which have access to the projects for which you want to create issues: To create a new user, see the Jira documentation topic Create, edit, or remove a user . To give users access to project roles and applications, see the Jira documentation topic Assign users to groups, project roles, and applications . Note If you are using Jira Software Cloud, after you create the user, you must create a token for the user: Go to https://id.atlassian.com/manage/api-tokens , to generate a new token. Use the token as password when you configure Red Hat Advanced Cluster Security for Kubernetes. 15.2. 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 In the RHACS portal, go to Platform Configuration Integrations . Scroll down to the Notifier Integrations section and select Jira Software . Click New integration . Enter a name for Integration name . Enter the user credentials in the Username and Password or API token fields. For Issue type , enter a valid Jira Issue Type , for example Task , Sub-task , or Bug . Enter the Jira server URL in the Jira URL field. Enter the key of the project in which you want to create issues in the Default project field. Optional: Use the Annotation key for project field to create issues in different Jira projects by completing the following steps. You can use annotations to dynamically create issues. Add an annotation similar to the following example in your namespace or deployment YAML file, where jira/project-key is the annotation key that you specify in your Jira integration. You can create an annotation for the deployment or the namespace. annotations: # ... jira/project-key: <jira_project_key> # ... Use the annotation key jira/project-key in the Annotation key for project field. If you use custom priorities in your Jira project, use the Priority Mapping toggle to configure custom priorities. If you use mandatory custom fields in your Jira project, enter them as JSON values in the Default Fields JSON field. For example: { "customfield_10004": 3, "customfield_20005": "Alerts", } Select Test to test that the integration with Jira is working. Select Create to generate the configuration. 15.2.1. Creating issues in different Jira projects You can configure Red Hat Advanced Cluster Security for Kubernetes to create issues in different Jira projects so that they directly go to the correct team. After completing the configuration, if a deployment has an annotation in the YAML file, RHACS creates issues in the project specified for that annotation. Otherwise, RHACS creates issues in the default project. Prerequisites You must have an account with access to each project that you want to send the alerts to. Procedure Add an annotation similar to the following example in your namespace or deployment YAML file: annotations: # ... jira/project-key: <jira_project_key> # ... Use the annotation key jira/project-key in the Annotation key for project field when you configure Red Hat Advanced Cluster Security for Kubernetes. 15.2.2. 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 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. Verify or update the priority values based on your JIRA project configuration. Select Test to test that the integration with Jira is working. Select Create to generate the configuration. Note If you get an error, follow the instructions in the Troubleshooting Jira integration section. 15.3. Configuring policy notifications Enable alert notifications for system policies. Procedure In the RHACS portal, go to Platform Configuration Policy Management . Select one or more policies for which you want to send alerts. Under Bulk actions , select Enable notification . In the Enable notification window, select the Jira notifier. Note If you have not configured any other integrations, the system displays a message that no notifiers are configured. Click Enable . Note 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 runtime alert for a policy in that deployment. 15.4. 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 To get the custom priority values from your JIRA project, run the following command to turn on debug logging for JIRA integration: USD roxctl -e "USDROX_CENTRAL_ADDRESS" central debug log --level Debug --modules notifiers/jira 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. To save the debugging information as a compressed .zip file, run the following command: USD roxctl -e "USDROX_CENTRAL_ADDRESS" central debug dump Unzip the .zip file to retrieve the custom priority values in use in your JIRA project. To turn off debug logging, run the following command: USD roxctl -e "USDROX_CENTRAL_ADDRESS" central debug log --level Info Configure Red Hat Advanced Cluster Security for Kubernetes for Jira integration again and use the priority values to configure custom priorities.
annotations: jira/project-key: <jira_project_key> { "customfield_10004": 3, "customfield_20005": "Alerts", } annotations: jira/project-key: <jira_project_key> roxctl -e "USDROX_CENTRAL_ADDRESS" central debug log --level Debug --modules notifiers/jira roxctl -e "USDROX_CENTRAL_ADDRESS" central debug dump roxctl -e "USDROX_CENTRAL_ADDRESS" central debug log --level Info