diff --git a/README.md b/README.md index aa7d3de..6cd0d3f 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ Tails is primarily used as a sidecar to your collector. The goal of Tails is to > NOTE: Make sure to use the appropriate docker container for your environment (currently an amd and arm image are published) +For example usage in Kubernetes, visit the example [here](examples/kubernetes/README.md) + ## Collector configuration At a minimum for tails to function, you must use the [remotetap processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/remotetapprocessor) in your collector's configuration. Tails expects to connect to the collector's remotetap processor on _port 12001_ (this will be configurable in the future). It is also recommended to use the [opampextension](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/opampextension) so that you can view the health and configuration for your collector. Here's a minimum sample configuration for a collector with these configured (tested with version 0.97.0 of the collector): diff --git a/examples/kubernetes/README.md b/examples/kubernetes/README.md new file mode 100644 index 0000000..5c68f2c --- /dev/null +++ b/examples/kubernetes/README.md @@ -0,0 +1,66 @@ +# Kubernetes Walkthrough + +To get started with tails, you'll need at least the remotetap processor and optionally the opamp extension. You can view the collector.yaml file for a complete example YAML file that works with the OpenTelemetry Operator, this will also work with a non-operator collector. + +> [!NOTE] +> Be sure you are using at least collector version 0.103.0 + +## Add Remote Tap Processor + +```yaml +processors: + remotetap: + endpoint: localhost:12001 +``` + +## (Optional) Add OpAMP Extension + +```yaml +extensions: + opamp: + server: + ws: + endpoint: ws://127.0.0.1:4000/v1/opamp + tls: + insecure: true +``` + +## Update service pipeline(s) + +The remote tap processor's placement in the pipeline is important. If you want to see all the un-filtered data put it first in the pipeline. If you want to see the data post-filtering and enrichment put it last. + +```yaml +service: + extensions: [opamp] + pipelines: + traces: + processors: [..., remotetap] +``` + +## Add the additional tails container + +> [!WARNING] +> It's recommended to replace the SECRET_KEY_BASE with a randomly generated 64 byte string. You can do this with `openssl rand -base64 64` + +```yaml +additionalContainers: + - name: tails + image: ghcr.io/jaronoff97/tails:v0.0.8 + env: + - name: SECRET_KEY_BASE + value: nErlTbssfnJxvjjujVKgDO/q84XAggf6/kN6b926qjRFK+uasVyd/+oACdXLm38l + ports: + - containerPort: 4000 +``` + +## Apply your new config + +Apply the configuration either via `kubectl apply -f ` or with helm. + +## Port forward to view the UI + +```bash +kubectl port-forward pod/ 4000:4000 +``` + +You should now be able to visit http://localhost:4000 diff --git a/examples/kubernetes/collector.yaml b/examples/kubernetes/collector.yaml new file mode 100644 index 0000000..d22d489 --- /dev/null +++ b/examples/kubernetes/collector.yaml @@ -0,0 +1,44 @@ +apiVersion: opentelemetry.io/v1beta1 +kind: OpenTelemetryCollector +metadata: + name: tails-example +spec: + image: ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.103.0 + additionalContainers: + - name: tails + image: ghcr.io/jaronoff97/tails:v0.0.8 + env: + - name: SECRET_KEY_BASE + value: agbCd+/i9v3Ep8D6HPZVTN+ukg+dzZbOkrdgbBCC+P8nLzDUhihMv/fdF2Nz30lX + ports: + - containerPort: 4000 + config: + extensions: + opamp: + server: + ws: + endpoint: ws://127.0.0.1:4000/v1/opamp + tls: + insecure: true + receivers: + otlp: + protocols: + grpc: {} + http: {} + processors: + remotetap: + endpoint: localhost:12001 + batch: + send_batch_size: 10000 + timeout: 10s + + exporters: + debug: {} + + service: + extensions: [opamp] + pipelines: + traces: + receivers: [otlp] + processors: [remotetap, batch] + exporters: [debug]