Forwarding Events with Fluentd

• A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

• The tctl admin tool and tsh client tool version >= 11.3.1, which you can download by visiting the customer portal.

  tctl version
  Teleport v11.3.1 go1.19
  tsh version
  Teleport v11.3.1 go1.19

• A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.

• The tctl admin tool and tsh client tool version >= 11.2.1. To download these tools, visit the Downloads page.

  tctl version
  Teleport v11.2.1 go1.19
  tsh version
  Teleport v11.2.1 go1.19

curl -L -O https://get.gravitational.com/teleport-event-handler-v11.3.1-darwin-amd64-bin.tar.gz
tar -zxvf teleport-event-handler-v11.3.1-darwin-amd64-bin.tar.gz

We currently only build the event handler plugin for amd64 machines. If your macOS machine uses Apple silicon, you will need to install Rosetta before you can run the event handler plugin. You can also build from source.

To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add:

helm repo add teleport https://charts.releases.teleport.dev

To update the cache of charts from the remote repository, run helm repo update:

helm repo update

Ensure that you have Docker installed and running.

Run the following commands to build the plugin:

git clone https://github.com/gravitational/teleport-plugins.git --depth 1
cd teleport-plugins/event-handler/build.assets
make build

You can find the compiled binary within your clone of the teleport-plugins repo, with the file path, event-handler/build/teleport-event-handler.

Run the configure command to generate a sample configuration. Replace teleport.example.com:443 with the DNS name and HTTPS port of Teleport's Proxy Service:

./teleport-event-handler configure . teleport.example.com:443

Run the configure command to generate a sample configuration. Assign TELEPORT_CLUSTER_ADDRESS to the DNS name and port of your Teleport Auth Service or Proxy Service:

TELEPORT_CLUSTER_ADDRESS=mytenant.teleport.sh:443
docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:11.3.1 configure . ${TELEPORT_CLUSTER_ADDRESS?}

In order to connect to Fluentd, you'll need to have the root certificate and the client credentials available as a secret. Use the following command to create that secret in Kubernetes:

kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key

This will pack the content of ca.crt, client.crt, and client.key into the secret, so the Helm Chart can mount them to their appropriate path.

Retrieve your github configuration resource:

tctl get github/github > github.yaml

Edit github.yaml, adding teleport-event-handler-impersonator to the teams_to_roles section. The team you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest team possible within your organization. This team must also include your user.

Here is an example:

  teams_to_roles:
    - organization: octocats 
      team: admins 
      roles:
        - access
+       - teleport-event-handler-impersonator

Apply your changes:

tctl create -f github.yaml

Retrieve your saml configuration resource:

tctl get saml/mysaml > saml.yaml

Edit saml.yaml, adding teleport-event-handler-impersonator to the attributes_to_roles section. The attribute you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  attributes_to_roles:
    - name: "groups" 
      value: "my-group" 
      roles:
        - access
+       - teleport-event-handler-impersonator

Apply your changes:

tctl create -f saml.yaml

Retrieve your oidc configuration resource:

tctl get oidc/myoidc > oidc.yaml

Edit oidc.yaml, adding teleport-event-handler-impersonator to the claims_to_roles section. The claim you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  claims_to_roles:
    - name: "groups" 
      value: "my-group" 
      roles:
        - access
+       - teleport-event-handler-impersonator

Apply your changes:

tctl create -f saml.yaml

tctl auth sign --user=teleport-event-handler --out=identity

The above sequence should result in one PEM-encoded file, identity.

If you are planning to use the Helm Chart, you'll need to generate the keys with the file format, then create a secret in Kubernetes.

Create the identity using the following command:

tctl auth sign --format=file --user=teleport-event-handler --out=identity

Then create the Kubernetes secret:

kubectl create secret generic teleport-event-handler-identity --from-file=auth_id=identity

These commands should result in a PEM-encoded file, identity, and a secret in Kubernetes with the name teleport-event-handler-identity.

storage = "./storage"
timeout = "10s"
batch = 20
namespace = "default"

[forward.fluentd]
ca = "/home/sasha/scripts/event-handler/ca.crt"
cert = "/home/sasha/scripts/event-handler/client.crt"
key = "/home/sasha/scripts/event-handler/client.key"
url = "https://localhost:8888/test.log"

[teleport]
addr = "example.teleport.com:443"
client_key = "auth.key"
client_crt = "auth.crt"
root_cas = "auth.cas"

To start the event handler, run the following command:

./teleport-event-handler start --config teleport-event-handler.toml

Use the following template to create teleport-plugin-event-handler-values.yaml:

eventHandler:
  storagePath: "./storage"
  timeout: "10s"
  batch: 20
  namespace: "default"

teleport:
  address: "example.teleport.com:443"
  identitySecretName: teleport-event-handler-identity

fluentd:
  url: "https://fluentd.fluentd.svc.cluster.local/events.log"
  sessionUrl: "https://fluentd.fluentd.svc.cluster.local/session.log"
  certificate:
    secretName: "teleport-event-handler-client-tls"
    caPath: "ca.crt"
    certPath: "client.crt"
    keyPath: "client.key"

persistentVolumeClaim:
  enabled: true

To start the event handler in Kubernetes, run the following command:

helm install teleport-plugin-event-handler teleport/teleport-plugin-event-handler \  --values teleport-plugin-event-handler-values.yaml \  --version 11.3.1