Configure Email Server

TestGen can be configured to use an email server that implements the Simple Mail Transfer Protocol (SMTP), like Amazon Simple Email Service (SES), Azure Communication Services, or Google Workspace SMTP Relay Service.

This enables users to set up email notifications for profiling runs, test runs, monitor anomalies, and quality scorecards.

Prerequisites

• TestGen instance installed using dk-installer.exe, as outlined in Install on Windows, or dk-installer, as outlined in Install on Mac/Linux or Install Enterprise, or with Helm, as outlined in Install on Kubernetes.
• Connection details for an SMTP email server: host, port, sender email address, and the connection security the server expects (see Email server settings).
• A username and password, if the server requires them.
• A client certificate and its private key file, in PEM format, if the server authorizes senders by certificate.

Configure the email server

DockerPipKubernetes

1. Navigate to the directory that contains the docker-compose.yml file for TestGen.

   • If the instance was installed using dk-installer.exe, the file can be located under "AppData\Local\DataKitchenApps".
   • If the instance was installed using dk-installer, the file can be located in the folder from which the Python installer was executed.

2. Add the following lines under the x-common-variables section. Leave out TG_SMTP_USERNAME and TG_SMTP_PASSWORD if the server authorizes senders by IP address or by client certificate.

   x-common-variables: &common-variables
    TG_SMTP_ENDPOINT: <host>
    TG_SMTP_PORT: <port>
    TG_SMTP_SECURITY: <ssl, starttls, or none>
    TG_SMTP_USERNAME: <username>
    TG_SMTP_PASSWORD: <password>
    TG_EMAIL_FROM_ADDRESS: <sender email address>
   

3. Optional. To present a client certificate to the server:

   1. Add the certificate and key as bind mounts on the engine service.

      services:
        engine:
          volumes:
            - type: bind
              source: <path to certificate file>
              target: /dk/smtp/client.crt
            - type: bind
              source: <path to key file>
              target: /dk/smtp/client.key
      

   2. Add the following lines under the x-common-variables section. Leave out TG_SMTP_CLIENT_KEY_PASSWORD if the key is not encrypted.

      x-common-variables: &common-variables
       TG_SMTP_CLIENT_CERT_FILE: /dk/smtp/client.crt
       TG_SMTP_CLIENT_KEY_FILE: /dk/smtp/client.key
       TG_SMTP_CLIENT_KEY_PASSWORD: <key passphrase>
      

4. Restart the application.

   docker compose up -d --wait
   

1. Open the ~/.testgen/config.env file in a text editor.

2. Add the following lines (one variable per line, no quotes). Leave out TG_SMTP_USERNAME and TG_SMTP_PASSWORD if the server authorizes senders by IP address or by client certificate.

   TG_SMTP_ENDPOINT=<host>
   TG_SMTP_PORT=<port>
   TG_SMTP_SECURITY=<ssl, starttls, or none>
   TG_SMTP_USERNAME=<username>
   TG_SMTP_PASSWORD=<password>
   TG_EMAIL_FROM_ADDRESS=<sender email address>
   

3. Optional. To present a client certificate to the server, add the paths to the certificate and key files. Leave out TG_SMTP_CLIENT_KEY_PASSWORD if the key is not encrypted.

   TG_SMTP_CLIENT_CERT_FILE=<path to certificate file>
   TG_SMTP_CLIENT_KEY_FILE=<path to key file>
   TG_SMTP_CLIENT_KEY_PASSWORD=<key passphrase>
   

4. Restart the application. Stop the running TestGen process with Ctrl+C in the terminal where it is running, then start it again.

   python3 dk-installer.py tg start
   

1. Open the values-tg-app.yaml file used for the installation.

2. Add the following under the testgen section. Leave out username and password if the server authorizes senders by IP address or by client certificate.

   testgen:
     emailNotifications:
       fromAddress: <sender email address>
       smtp:
         endpoint: <host>
         port: <port>
         username: <username>
         password: <password>
   

3. Set the connection security by adding the following at the top level of the file. Leave this out if the server expects ssl, which is the default.

   extraEnv:
     - name: TG_SMTP_SECURITY
       value: <starttls or none>
   

4. Optional. To present a client certificate to the server:

   1. Store the certificate and key in a secret.

   2. Add the following entries to the extraEnv list. Leave out TG_SMTP_CLIENT_KEY_PASSWORD if the key is not encrypted.

      extraEnv:
        - name: TG_SMTP_CLIENT_CERT_FILE
          value: /dk/smtp/client.crt
        - name: TG_SMTP_CLIENT_KEY_FILE
          value: /dk/smtp/client.key
        - name: TG_SMTP_CLIENT_KEY_PASSWORD
          value: <key passphrase>
      

   3. Mount the secret by adding the following at the top level of the file.

      extraVolumes:
        - name: smtp-client-certificate
          secret:
            secretName: <secret name>
      extraVolumeMounts:
        - name: smtp-client-certificate
          mountPath: /dk/smtp
          readOnly: true
      

5. Apply the change.

   helm upgrade -n datakitchen dk-tg-app datakitchen-testgen/testgen \
       --values values-tg-app.yaml --wait
   

Reference

Email server settings

Environment variable	Helm key	Description
TG_SMTP_ENDPOINT	smtp.endpoint	Host name of the email server.
TG_SMTP_PORT	smtp.port	Port of the email server.
TG_SMTP_SECURITY	(set through extraEnv)	How the connection is secured: ssl (typically port 465), starttls (typically port 587 or 25), or none for an unencrypted connection. Defaults to ssl.
TG_SMTP_USERNAME	smtp.username	Username for the email server. Set together with the password, or leave both unset for a relay that does not take credentials.
TG_SMTP_PASSWORD	smtp.password	Password for the email server.
TG_EMAIL_FROM_ADDRESS	fromAddress	Sender address for notification emails.
TG_SMTP_CLIENT_CERT_FILE	(set through extraEnv)	Path to a client certificate to present to the server. Set together with the key file. Requires ssl or starttls.
TG_SMTP_CLIENT_KEY_FILE	(set through extraEnv)	Path to the private key for the client certificate.
TG_SMTP_CLIENT_KEY_PASSWORD	(set through extraEnv)	Passphrase for the private key. Required if the key is encrypted.

Helm keys are under testgen.emailNotifications.

Provider notes

• Microsoft 365 and Azure Communication Services accept only STARTTLS, so set TG_SMTP_SECURITY to starttls.
• Amazon SES and Google Workspace accept both ssl and starttls, depending on the port.
• Microsoft 365 SMTP relay and Direct Send authorize senders without a username and password. A relay connector authorized by static IP address needs no further setup. A connector authorized by certificate requires a certificate from a commercial certificate authority whose Subject or Subject Alternative Name contains a verified accepted domain in the tenant; a self-signed certificate is rejected.

Related topics

• Notifications