Using the Mailroom chart

The Mailroom Chart handles incoming email.

Configuration

image:
  repository: registry.gitlab.com/gitlab-org/build/cng/gitlab-mailroom
  # tag: v0.9.1
  pullSecrets: []
  # pullPolicy: IfNotPresent

enabled: true

init:
  image: {}
    # repository:
    # tag:
  resources:
    requests:
      cpu: 50m

annotations: {}

# Tolerations for pod scheduling
tolerations: []
affinity: {}
podLabels: {}

hpa:
  minReplicas: 1
  maxReplicas: 2
  cpu:
    targetAverageUtilization: 75

  # Note that the HPA is limited to autoscaling/v2beta1, autoscaling/v2beta2 and autoscaling/v2
  customMetrics: []
  behavior: {}

networkpolicy:
  enabled: false
  egress:
    enabled: false
    rules: []
  ingress:
    enabled: false
    rules: []
  annotations: {}

resources:
  # limits:
  #  cpu: 1
  #  memory: 2G
  requests:
    cpu: 50m
    memory: 150M

## Allow to overwrite under which User and Group we're running.
securityContext:
  runAsUser: 1000
  fsGroup: 1000

## Enable deployment to use a serviceAccount
serviceAccount:
  enabled: false
  create: false
  annotations: {}
  ## Name to be used for serviceAccount, otherwise defaults to chart fullname
  # name:

Configuring KEDA

This keda section enables the installation of KEDA ScaledObjects instead of regular HorizontalPodAutoscalers. This configuration is optional and can be used when there is a need for autoscaling based on custom or external metrics.

Most settings default to the values set in the hpa section where applicable.

If the following are true, CPU and memory triggers are added automatically based on the CPU and memory thresholds set in the hpa section:

• triggers is not set.
• The corresponding request.cpu.request or request.memory.request setting is also set to a non-zero value.

If no triggers are set, the ScaledObject is not created.

Refer to the KEDA documentation for more details about those settings.

Incoming email

By default, incoming email is disabled. There are two methods for reading incoming email:

• IMAP
• Microsoft Graph

First, enable it by setting the common settings. Then configure the IMAP settings or Microsoft Graph settings.

These methods can be configured in values.yaml. See the following examples:

• Incoming email with IMAP
• Incoming email with Microsoft Graph

IMAP

To enable incoming e-mail for IMAP, provide details of your IMAP server and access credentials using the global.appConfig.incomingEmail settings.

In addition, the requirements for the IMAP email account should be reviewed to ensure that the targeted IMAP account can be used by GitLab for receiving email. Several common email services are also documented on the same page to aid in setting up incoming email.

The IMAP password will still need to be created as a Kubernetes Secret as described in the secrets guide.

Microsoft Graph

See the GitLab documentation on creating an Azure Active Directory application.

Provide the tenant ID, client ID, and client secret. You can find details for these settings in the command line options.

Create a Kubernetes secret containing the client secret as described in the secrets guide.

Reply-by-email

To use the reply-by-email feature, where users can reply to notification emails to comment on issues and MRs, you need to configure both outgoing email and incoming email settings.

Service Desk email

By default, the Service Desk email is disabled.

As with incoming e-mail, enable it by setting the common settings. Then configure the IMAP settings or Microsoft Graph settings.

These options can also be configured in values.yaml. See the following examples:

• Service Desk with IMAP
• Service Desk with Microsoft Graph

Service Desk email requires that Incoming email be configured.

IMAP

Provide details of your IMAP server and access credentials using the global.appConfig.serviceDeskEmail settings. You can find details for these settings in the command line options.

Create a Kubernetes secret containing IMAP password as described in the secrets guide.

Microsoft Graph

See the GitLab documentation on creating an Azure Active Directory application.

Provide the tenant ID, client ID, and client secret using the global.appConfig.serviceDeskEmail settings. You can find details for these settings in the command line options.

You will also have to create a Kubernetes secret containing the client secret as described in the secrets guide.

Asymmetric token verification

With the webhook delivery method, mailroom signs each delivery with a token that GitLab verifies. By default, mailroom and GitLab share the authToken secret. A mailroom deployed outside this chart can instead sign tokens with an ES256 private key. GitLab then needs only the matching public key, so the private key never leaves that mailroom.

To trust public keys, store them as fields of one secret, and list the fields in publicKeyFiles.keys. Each field holds one PEM-encoded public key:

global:
  appConfig:
    incomingEmail:
      publicKeyFiles:
        secret: incoming-email-mailroom-public-keys
        keys: [current.pub]

Configure global.appConfig.serviceDeskEmail.publicKeyFiles the same way for Service Desk email.

The chart mounts the listed fields into the Webservice pods and adds them under public_key_files in gitlab.yml. The authToken stays configured alongside them. GitLab picks the check for each token from its key ID, so it accepts both token types at the same time. You can run the chart mailroom and an external mailroom side by side.

Rotate a public key

GitLab trusts every key listed in keys. To rotate keys without rejecting valid tokens, trust the new key first, switch the signer, and then remove the old key.

1. Add the new public key to the secret under a new field. Leave the existing fields unchanged. GitLab matches keys by their content, so the field name is only a label.

2. Add the new field to keys, keep the old one, and run helm upgrade:

   yaml

   global:
     appConfig:
       incomingEmail:
         publicKeyFiles:
           secret: incoming-email-mailroom-public-keys
           keys: [next.pub, current.pub]

   GitLab now accepts tokens signed with either key. Webservice reads the keys only at startup. Changing keys changes gitlab.yml, which restarts the Webservice pods and loads the new key. Changing only the secret does not restart the pods and has no effect.

3. Switch the mailroom that signs tokens to the new private key.

4. After no tokens are signed with the old key, remove its field from keys and run helm upgrade. Then delete the field from the secret.

To roll back, switch the signer back to the old key before you remove the new key from keys.

serviceAccount

This section controls if a ServiceAccount should be created and if the default access token should be mounted in pods.

affinity

For more information, see affinity.