# teleport-plugin-event-handler Chart Reference

The `teleport-plugin-event-handler` Helm chart is used to configure the Event Handler Teleport plugin which allows users to send events and session logs to a Fluentd instance for further processing or storage.

You can [browse the source on GitHub](https://github.com/gravitational/teleport/tree/v18.7.3/examples/chart/event-handler).

This reference details available values for the `teleport-plugin-event-handler` chart.

---

WARNING

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

---

## `teleport`

`teleport` contains the configuration describing how the plugin connects to your Teleport cluster.

### `teleport.address`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`teleport.address` is the address of the Teleport cluster the plugin connects to. The address must contain both the domain name and the port of the Teleport cluster. It can be either the address of the auth servers or the proxy servers.

For example:

- joining a Proxy: `teleport.example.com:443` or `teleport.example.com:3080`
- joining an Auth: `teleport-auth.example.com:3025`

When the address is empty, `tbot.teleportProxyAddress` or `tbot.teleportAuthAddress` will be used if they are set.

### `teleport.identitySecretName`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`teleport.identitySecretName` is the name of the Kubernetes secret that contains the credentials for the connection to your Teleport cluster.

The secret should be in the following format:

```
apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: teleport-plugin-event-handler-identity
data:
  auth_id: #...

```

Check out the [Export Events with Fluentd ](https://goteleport.com/docs/zero-trust-access/export-audit-events/fluentd.md)guide for more information about how to acquire these credentials.

### `teleport.identitySecretPath`

| Type     | Default     |
| -------- | ----------- |
| `string` | `"auth_id"` |

`teleport.identitySecretPath` is the key in the Kubernetes secret specified by `teleport.identitySecretName` that holds the credentials for the connection to your Teleport cluster. If the secret has the path, `"auth_id"`, you can omit this field.

## `eventHandler`

`eventHandler` contains the configuration used by the plugin to forward Teleport events.

### `eventHandler.storagePath`

| Type     | Default                                             |
| -------- | --------------------------------------------------- |
| `string` | `"/var/lib/teleport/plugins/event-handler/storage"` |

`eventHandler.storagePath` is the storage directory for the event handler.

### `eventHandler.timeout`

| Type     | Default |
| -------- | ------- |
| `string` | `"10s"` |

`eventHandler.timeout` is the polling timeout.

### `eventHandler.batch`

| Type  | Default |
| ----- | ------- |
| `int` | `20`    |

`eventHandler.batch` is the fetch batch size.

### `eventHandler.windowSize`

| Type     | Default |
| -------- | ------- |
| `string` | `"24h"` |

`eventHandler.windowSize` configures the duration of the time window for the event handler to request events from Teleport. By default, this is set to 24 hours. Reduce the window size if the events backend cannot manage the event volume for the default window size. The window size should be specified as a duration string, parsed by Go's time.ParseDuration.

### `eventHandler.debug`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`eventHandler.debug` enables debug logging.

### `eventHandler.types`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`eventHandler.types` is the list of event types to forward. When unset, the event handler forwards all events.

### `eventHandler.skipEventTypes`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`eventHandler.skipEventTypes` is the list of audit event types to skip.

### `eventHandler.skipSessionTypes`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`eventHandler.skipSessionTypes` is the list of session recording event types to skip. When unset, the event handler skips noisy and binary events.

See the [Teleport-event-handler README](https://github.com/gravitational/teleport/blob/1d2bd5eb8fc3500deb7d7108f6835efde98b7b24/integrations/event-handler/README.md) for a list of default skipped events.

### `eventHandler.startTime`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`eventHandler.startTime` is the start time to start ingestion from (RFC3339 format).

### `eventHandler.dryRun`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`eventHandler.dryRun` enables dry run without sending events to Fluentd.

### `eventHandler.concurrency`

| Type  | Default |
| ----- | ------- |
| `int` | `5`     |

`eventHandler.concurrency` is the number of concurrent sessions to process. By default, this is set to 5.

#### `eventHandler.lock.enabled`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`eventHandler.lock.enabled` controls whether user auto-locking is enabled.

#### `eventHandler.lock.failedAttemptsCount`

| Type  | Default |
| ----- | ------- |
| `int` | `3`     |

`eventHandler.lock.failedAttemptsCount` is the number of failed attempts in the `lockPeriod` which triggers locking. By default, this is set to 3.

#### `eventHandler.lock.period`

| Type     | Default |
| -------- | ------- |
| `string` | `"1m"`  |

`eventHandler.lock.period` is the time period where `lock-failed-attempts-count` failed attempts will trigger locking. By default, this is set to 1 minute.

#### `eventHandler.lock.for`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`eventHandler.lock.for` is the time period for which user gets lock.

## `fluentd`

`fluentd` contains the configuration for the Fluentd forwarder.

### `fluentd.url`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`fluentd.url` is the Fluentd URL where the events will be sent.

### `fluentd.sessionUrl`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`fluentd.sessionUrl` is the Fluentd URL where the session logs will be sent.

### `fluentd.certificate`

`fluentd.certificate` contains the configuration for the plugin's Fluentd client certificates. When `certManager.enabled` is true, `cert-manager` will use its own secrets, so this section is unused.

#### `fluentd.certificate.secretName`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`fluentd.certificate.secretName` is the secret containing the credentials to connect to Fluentd. It must contain the CA certificate, the client key and the client certificate.

#### `fluentd.certificate.caPath`

| Type     | Default    |
| -------- | ---------- |
| `string` | `"ca.crt"` |

`fluentd.certificate.caPath` is the name of the key which contains the CA certificate inside the secret.

#### `fluentd.certificate.certPath`

| Type     | Default        |
| -------- | -------------- |
| `string` | `"client.crt"` |

`fluentd.certificate.certPath` is the name of the key which contains the client's certificate inside the secret.

#### `fluentd.certificate.keyPath`

| Type     | Default        |
| -------- | -------------- |
| `string` | `"client.key"` |

`fluentd.certificate.keyPath` is the name of the key which contains the client's private key inside the secret.

### `fluentd.maxConnections`

| Type  | Default |
| ----- | ------- |
| `int` | `0`     |

`fluentd.maxConnections` is the maximum number of connections to Fluentd. By default, or when set to 0, this becomes `eventHandler.concurrency` \* 2.

## `tbot`

`tbot` controls the optional tbot deployment that obtains and renews credentials for the plugin to connect to Teleport. Only default and mandatory values are described here, see the tbot chart reference for the full list of supported values.

### `tbot.enabled`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`tbot.enabled` controls if tbot should be deployed with the event handler plugin.

### `tbot.clusterName`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`tbot.clusterName` is the name of the Teleport cluster tbot and the event handler plugin will join. Setting this value is mandatory when tbot is enabled.

### `tbot.teleportProxyAddress`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`tbot.teleportProxyAddress` is the teleport Proxy Service address the bot will connect to. This must contain the port number, usually 443 or 3080 for Proxy Service. Connecting to the Proxy Service is the most common and recommended way to connect to Teleport. This is mandatory to connect to Teleport Enterprise (Cloud).

This setting is mutually exclusive with `teleportAuthAddress`.

For example:

```
tbot:
  teleportProxyAddress: "test.teleport.sh:443"

```

### `tbot.teleportAuthAddress`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`tbot.teleportAuthAddress` is the teleport Auth Service address the bot will connect to. This must contain the port number, usually 3025 for Auth Service. Direct Auth Service connection should be used when you are deploying the bot in the same Kubernetes cluster than your `teleport-cluster` Helm release and have direct access to the Auth Service. Else, you should prefer connecting via the Proxy Service.

This setting is mutually exclusive with `teleportProxyAddress`.

For example:

```
teleportAuthAddress: "teleport-auth.teleport-namespace.svc.cluster.local:3025"

```

### `tbot.joinMethod`

| Type     | Default        |
| -------- | -------------- |
| `string` | `"kubernetes"` |

`tbot.joinMethod` describes how tbot joins the Teleport cluster. See [the join method reference](https://goteleport.com/docs/reference/deployment/join-methods.md) for a list of supported values and detailed explanations.

### `tbot.token`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`tbot.token` is the name of the token used by tbot to join the Teleport cluster. This value is not sensitive unless the `joinMethod` is set to `"token"`. If unset, defaults to `[release name]-tbot`. If `crd.create` is set to true, then a TeleportProvisionToken will be created with the provided token name.

## `crd`

`crd` controls whether the chart creates custom resources managed by the Teleport Kubernetes Operator. If enabled, the chart will create TeleportRoleV8, TeleportBotV1, and TeleportProvisionToken resources to automatically connect the plugin to Teleport.

---

INTERACTION WITH TELEPORT KUBERNETES OPERATOR

The Teleport Kubernetes Operator must already be enabled in the Teleport cluster for the custom resources to be applied successfully. In addition, the custom resources must be deployed in the same namespace as the Teleport Kubernetes Operator.

---

### `crd.create`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`crd.create` controls if the chart should create the Operator custom resources to automatically bootstrap the plugin.

### `crd.namespace`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`crd.namespace` optionally overrides the Kubernetes namespace that the custom resources are created in. This should match the namespace in which the Teleport Kubernetes Operator is running. Defaults to the release namespace.

### `crd.tokenSpecOverride`

`crd.tokenSpecOverride` optionally overrides the join token spec for tbot to use to join the Teleport cluster.

When tbot is enabled, the default configuration uses the `kubernetes` in\_cluster join method. By default, the service account for tbot will be allowed for all `kubernetes` join types: in\_cluster, JWKS, OIDC.

You can also configure the token to use other supported join methods. The token specification must match `tbot.joinMethod` for the plugin to correctly join the cluster. See [the join method reference](https://goteleport.com/docs/reference/deployment/join-methods.md) for a list of supported values and detailed explanations.

---

OTHER JOIN METHODS

When not using the `kubernetes` join method, or when tbot is not enabled, you must specify `join_method`. Ensure all necessary fields for the join token are present for the Operator to correctly create the Teleport token resource.

---

Example (Kubernetes JWKS join method):

```
tokenSpecOverride:
  join_method: kubernetes
  kubernetes:
    type: static_jwks
    static_jwks:
      jwks: |
        # Place the kubernetes JWKS here (`kubectl get --raw /openid/v1/jwks`)
        {"keys":[--snip--]}

```

Example (Kubernetes OIDC join method):

```
tokenSpecOverride:
  join_method: kubernetes
  kubernetes:
    type: oidc
    oidc:
      # Insert the OIDC issuer value here, it will vary depending on your
      # cluster and cloud provider.
      issuer: https://oidc.eks.us-west-2.amazonaws.com/id/my-cluster

```

## `certManager`

`certManager` controls whether the chart uses `cert-manager` to provision TLS certificates for mTLS connection between the plugin and Fluentd. If enabled, `cert-manager` will create two Kubernetes secrets in the plugin's release namespace: the Fluentd server credentials (CA cert, server cert, server key) and the plugin client credentials (CA cert, client cert, client key). The TLS certificates use PKCS#8 encoding and ECDSA encryption.

---

INSTALLING CERT MANAGER

You must install and configure `cert-manager` in your Kubernetes cluster yourself.

See the [cert-manager Helm install instructions](https://cert-manager.io/docs/installation/helm/) for more information.

---

### `certManager.enabled`

| Type   | Default |
| ------ | ------- |
| `bool` | `false` |

`certManager.enabled` controls if `cert-manager` should be used to provision TLS certificates for the plugin.

### `certManager.issuer`

`certManager.issuer` is the `cert-manager` `Issuer` or `ClusterIssuer` that will issue the Fluentd server and client certificates.

#### `certManager.issuer.create`

| Type   | Default |
| ------ | ------- |
| `bool` | `true`  |

`certManager.issuer.create` controls if the chart should create a private CA issuer to issue the Fluentd server and client certificates.

See the [cert-manager Bootstrapping CA Issuers documentation ](https://cert-manager.io/docs/configuration/selfsigned/#bootstrapping-ca-issuers)for more information.

---

CREATING THE CA ISSUER WITH THE CHART

If `certManager.issuer.create` is true, the chart will create a new private CA issuer. This means existing Fluentd deployments may need to be restarted to load the new certificates. As such, it is recommended to use your own issuer in production.

See the [cert-manager Issuers documentation ](https://cert-manager.io/docs/configuration/issuers/)for more information.

---

#### `certManager.issuer.name`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`certManager.issuer.name` is the `Name` of the issuer. Unused if `certManager.issuer.create` is true.

---

CONFIGURING YOUR OWN ISSUER

If `certManager.issuer.create` is false, you must install and configure an appropriate issuer yourself. If configuring an `Issuer` resource, it should be in the same namespace as the plugin's release namespace. Alternatively, you can use `ClusterIssuer` for a cluster-wide issuer.

See the [cert-manager Issuers documentation ](https://cert-manager.io/docs/configuration/issuers/)for more information.

---

#### `certManager.issuer.kind`

| Type     | Default    |
| -------- | ---------- |
| `string` | `"Issuer"` |

`certManager.issuer.kind` is the `Kind` of the issuer. Unused if `certManager.issuer.create` is true. Defaults to 'Issuer' to keep permissions scoped to the plugin's release namespace.

#### `certManager.issuer.group`

| Type     | Default             |
| -------- | ------------------- |
| `string` | `"cert-manager.io"` |

`certManager.issuer.group` is the `Group` of the issuer. Unused if `certManager.issuer.create` is true. Defaults to 'cert-manager.io' to use built-in issuers.

### `certManager.dnsNames`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`certManager.dnsNames` is the DNS names for the Fluentd forwarder, populating the SANs extension of the server certificate.

### `certManager.ipAddresses`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`certManager.ipAddresses` is the IP addresses for the Fluentd forwarder, populating the SANs extension of the server certificate.

### `certManager.ttl`

| Type     | Default    |
| -------- | ---------- |
| `string` | `"87600h"` |

`certManager.ttl` is the time-to-live duration for the TLS certificates. Defaults to 87600 hours (10 years).

### `certManager.renewBefore`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`certManager.renewBefore` is the time before `certManager.ttl` to renew the TLS certificates. This must be less than `certManager.ttl`. When empty, defaults to 1/3 of the issued certificate's time-to-live duration. For example, if a certificate is valid for 60 minutes, `cert-manager` will renew the certificate 20 minutes before expiration.

## `annotations`

`annotations` contains annotations to apply to the different Kubernetes objects created by the chart. See [the Kubernetes annotation documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) for more details.

### `annotations.config`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`annotations.config` are annotations to set on the ConfigMap.

### `annotations.deployment`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`annotations.deployment` are annotations to set on the Deployment.

### `annotations.pod`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`annotations.pod` are annotations to set on the Pods.

### `annotations.certSecret`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`annotations.certSecret` are annotations to set on the certificate secrets generated by cert-manager v1.5+ when `certManager.enabled` is true

## `extraLabels`

`extraLabels` contains additional Kubernetes labels to apply on the resources created by the chart. See [the Kubernetes label documentation ](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)for more information.

### `extraLabels.config`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`extraLabels.config` are labels to set on the ConfigMap.

### `extraLabels.deployment`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`extraLabels.deployment` are labels to set on the Deployment.

### `extraLabels.pod`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`extraLabels.pod` are labels to set on the Pods.

### `extraLabels.certSecret`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`extraLabels.certSecret` are labels to set on the certificate secrets generated by cert-manager v1.5+ when `certManager.enabled` is true.

## `image`

`image` sets the container image used for plugin pods created by the chart.

You can override this to use your own plugin image rather than a Teleport-published image.

### `image.repository`

| Type     | Default                                                        |
| -------- | -------------------------------------------------------------- |
| `string` | `"public.ecr.aws/gravitational/teleport-plugin-event-handler"` |

`image.repository` is the image repository.

### `image.pullPolicy`

| Type     | Default          |
| -------- | ---------------- |
| `string` | `"IfNotPresent"` |

`image.pullPolicy` is the [Kubernetes image pull policy](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy).

### `image.tag`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`image.tag` Overrides the image tag whose default is the chart appVersion.

Normally, the version of the Teleport plugin matches the version of the chart. If you install chart version 15.0.0, you'll use the plugin version 15.0.0. Upgrading the plugin is done by upgrading the chart.

---

WARNING

`image.tag` is intended for development and custom tags. This MUST NOT be used to control the plugin version in a typical deployment. This chart is designed to run a specific plugin version. You will face compatibility issues trying to run a different version with it.

If you want to run the Teleport plugin version `X.Y.Z`, you should use `helm install --version X.Y.Z` instead.

---

## `imagePullSecrets`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`imagePullSecrets` is a list of secrets containing authorization tokens which can be optionally used to access a private Docker registry.

See the [Kubernetes reference](https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod) for more details.

## `nameOverride`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`nameOverride` optionally overrides the name of the chart, used together with the release name when giving a name to resources.

## `fullnameOverride`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`fullnameOverride` optionally overrides the full name of resources.

## `podSecurityContext`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`podSecurityContext` sets the pod security context for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) for more details.

To unset the security context, set it to `null` or `~`.

## `securityContext`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`securityContext` sets the container security context for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) for more details.

To unset the security context, set it to `null` or `~`.

## `resources`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`resources` sets the resource requests/limits for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) for more details.

## `nodeSelector`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`nodeSelector` sets the node selector for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for more details.

## `tls`

`tls` contains settings for mounting your own TLS material in the event-handler pod. The event-handler does not expose a TLS server, so this is only used to trust CAs.

### `tls.existingCASecretName`

| Type     | Default |
| -------- | ------- |
| `string` | `""`    |

`tls.existingCASecretName` sets the `SSL_CERT_FILE` environment variable to load a trusted CA or bundle in PEM format into Teleport pods. The injected CA will be used to validate TLS communications with the Proxy Service.

You must create a secret containing the CA certs in the same namespace as Teleport using a command like:

```
$ kubectl create secret generic my-root-ca --from-file=ca.pem=/path/to/root-ca.pem
```

### `tls.existingCASecretKeyName`

| Type     | Default    |
| -------- | ---------- |
| `string` | `"ca.pem"` |

`tls.existingCASecretKeyName` determines which key in the CA secret will be used as a trusted CA bundle file.

## `tolerations`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`tolerations` sets the tolerations for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) for more details.

## `affinity`

| Type     | Default |
| -------- | ------- |
| `object` | `{}`    |

`affinity` sets the affinities for any pods created by the chart. See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) for more details.

## `volumes`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`volumes` sets the volumes mounted into the main event-handler pod. See [the Kubernetes volume documentation](https://kubernetes.io/docs/concepts/storage/volumes/) for more details.

For example:

```
- name: storage
  persistentVolumeClaim:
    claimName: teleport-plugin-event-handler

```

## `volumeMounts`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`volumeMounts` sets the volume mounts for the main event-handler container. See [the Kubernetes volume documentation](https://kubernetes.io/docs/concepts/storage/volumes/) for more details.

For example:

```
- name: storage
  mountPath: "/var/lib/teleport/plugins/event-handler/storage"

```

## `extraArgs`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`extraArgs` contains extra arguments to pass to `teleport-plugin start` for the main event-handler container.

## `extraEnv`

| Type   | Default |
| ------ | ------- |
| `list` | `[]`    |

`extraEnv` contains extra environment variables to set in the main event-handler container.

For example:

```
extraEnv:
  - name: HTTPS_PROXY
    value: "http://username:password@my.proxy.host:3128"

```