jira-service-desk-operator

Kubernetes operator for Jira Service Desk

About

Jira service desk(JSD) operator is used to automate the process of setting up JSD for alertmanager in a k8s native way. By using CRDs it lets you:

1. Manage Projects
2. Manage customer/organization for projects
3. Configure Issues

It uses Jira REST API in it's underlying layer and can be extended to perform other tasks that are supported via the REST API.

Project

We support the following CRUD operation on project via our Jira Service Desk Operator:

• Create - Creates a new projects with the provided fields
• Update - Updates an existing project with the updated fields
• Delete - Removes and deletes the project

Examples for Project Custom Resource can be found here.

Limitations

• We only support creating three types of JSD projects via our operator i.e Business, ServiceDesk, Software. The details and differences between these project types can be viewed here.

• Following are the immutable fields that cannot be updated:

  • ProjectTemplateKey
  • ProjectTypeKey
  • LeadAccountId
  • CategoryId
  • NotificationScheme
  • PermissionScheme
  • IssueSecurityScheme
  • OpenAccess

  You can read more about these fields on Jira Service Desk api docs.

Customer

We support the following CRUD operations on customer via our Jira Service Desk Operator

• Create - Create a new customer and assign the projects mentioned in the CR
• Update - Only updates(add/remove) the associated projects mentioned in the CR
• Delete - Remove all the project associations and deletes the customer

Examples for Customer Custom Resource can be found here.

Limitations

• Jira Service Desk Operator can access only those customers which are created through it. Customers that are manually created and added in the projects can’t be accessed later with the Jira Service Desk Operator.
• Each custom resource is associated to a single customer.
• You can not update customer name and email.
• Once a customer is created, no signup link is sent to the customer email. The customer then has to signup on the help center manually with his provided email to access the projects associated with him on the customer portal.

To resolve the sign up link limitation during customer creation, we have introduced the legacy customer flag in customer CR. When the flag is true, customer is created using the Jira legacy API and a signup link is sent to his email. However, customer name can't be set while creating a legacy customer. The customer name is set equivalent to customer email by default. Once the customer signs up using the signup link, the customer name is updated to the new provided value during the signup.

Usage

Prerequisites

• Atlassian account
• API Token to access Jira REST API (https://id.atlassian.com/manage-profile/security/api-tokens)

Create secret

Create the following secret which is required for jira-service-desk-operator:

kind: Secret
apiVersion: v1
metadata:
  name: jira-service-desk-config
  namespace: default
data:
  JIRA_SERVICE_DESK_API_TOKEN: <API_TOKEN>
  #Example: https://stakater-cloud.atlassian.net/
  JIRA_SERVICE_DESK_API_BASE_URL: <JSD_BASE_URL>
  JIRA_SERVICE_DESK_EMAIL: <EMAIL>
type: Opaque

Deploy operator

• Make sure that certman is deployed in your cluster since webhooks require certman to generate valid certs since webhooks serve using HTTPS
• To install certman

$ kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.16.1/cert-manager.yaml

• Deploy operator

$ oc apply -f bundle/manifests

Local Development

• Operator-sdk v1.20.0 is required for local development.

1. Create jira-service-desk-config secret

2. Run make run ENABLE_WEBHOOKS=false WATCH_NAMESPACE=default OPERATOR_NAMESPACE=default where WATCH_NAMESPACE denotes the namespaces that the operator is supposed to watch and OPERATOR_NAMESPACE is the namespace in which it's supposed to be deployed.

3. Before committing your changes run the following to ensure that everything is verified and up-to-date:

   • make verify
   • make bundle
   • make packagemanifests

Running Tests

Pre-requisites

1. Create a namespace with the name test
2. Create jira-service-desk-config secret in test namespace

To run tests

Use the following command to run tests: make test OPERATOR_NAMESPACE=test USE_EXISTING_CLUSTER=true