K8s Serverless (EKS Fargate) - Collector Sidecar

The sidecar runs the OpenTelemetry Collector inside each application pod you add it to. It receives the pod's traces, metrics, and logs over OTLP on localhost, adds the pod's Kubernetes resource attributes to every signal, and exports them to SigNoz. Pods without the sidecar keep sending to the deployment collector's Service.

Prerequisites

The deployment collector, installed as the install guide shows.

Install the Collection Agent

Step 1: Install foundryctl

Run this on the machine where you use kubectl:

curl -fsSL https://signoz.io/foundry.sh | bash

For manual install (Windows PowerShell, air-gapped, etc.) or PATH setup, see the Foundry getting-started guide.

Step 2: Create casting.yaml

Create a file named casting.yaml in your application's kustomization directory, the one that holds its kustomization.yaml, so pours/ lands beside it after Step 3. Give it this content:

Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key as shown in Cloud → Self-Hosted.

apiVersion: v1alpha1
kind: CollectionAgent
metadata:
  name: signoz
spec:
  deployment:
    platform: aws
    mode: kubernetes-serverless
    flavor: kustomize
  collector:
    kind: sidecar
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: https://ingest.<region>.signoz.cloud:443
        SIGNOZ_INGESTION_KEY: <your-ingestion-key>
        K8S_CLUSTER_NAME: <CLUSTER_NAME>
        OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<DEPLOYMENT_ENVIRONMENT>
      config:
        data:
          collector/sidecar/sidecar.yaml: |
            exporters:
              otlphttp/signoz:
                headers:
                  signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}

Verify these values:

<region>: Your SigNoz Cloud region.
<your-ingestion-key>: Your SigNoz Cloud ingestion key.
<CLUSTER_NAME>: The same value as in the deployment collector's casting.yaml, which becomes k8s.cluster.name on every signal.
<DEPLOYMENT_ENVIRONMENT>: Your deployment environment, for example staging or production, which becomes deployment.environment on the collected telemetry.

Step 3: Generate the sidecar files

Run this from the directory that contains casting.yaml to write the sidecar's files to pours/collectionagent/collector/sidecar:

foundryctl forge -f casting.yaml

Step 4: Add the sidecar to your workloads

Pick one of the two ways below to add the sidecar to each workload that takes it.

The sidecar's permissions go to the namespace's default service account. If your workloads run under service accounts of their own, create signoz-rolebinding.yaml beside kustomization.yaml:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: signoz-collector-sidecar
subjects:
  - kind: ServiceAccount
    name: <your-service-account>
  - kind: ServiceAccount
    name: default

Verify these values:

<your-service-account>: The service account of a workload that takes the sidecar, from serviceAccountName in its pod template; add one subject per account, and keep default while any such workload runs under it.

Edit your application's kustomization.yaml to add the sidecar's directory, a patch for each workload that takes the sidecar, and the rolebinding file:

 namespace: <your-namespace>
 resources:
+  - pours/collectionagent/collector/sidecar
 patches:
+  - path: pours/collectionagent/collector/sidecar/patch.yaml
+    target:
+      kind: <your-workload-kind>
+      name: <your-workload>
+  - path: pours/collectionagent/collector/sidecar/patch-cronjob.yaml
+    target:
+      kind: CronJob
+      name: <your-cronjob>
+  - path: signoz-rolebinding.yaml

Verify these values:

<your-namespace>: Your application's namespace.
<your-workload-kind>: The kind of a workload that takes the sidecar: Deployment, StatefulSet, DaemonSet, or Job.
<your-workload>: That workload's name, from its manifest, with one target for each workload.
<your-cronjob>: The name of a CronJob that takes the sidecar.

Leave out the patch-cronjob.yaml entry if no CronJob takes the sidecar, and the signoz-rolebinding.yaml entry if you did not create that file. The kustomization's namespace: places the sidecar's config and permissions in your application's namespace.

Run this on the machine where you use kubectl to apply your application:

kubectl apply -k <overlay>

Verify these values:

<overlay>: The directory that holds your application's kustomization.yaml, relative to where you run the command.

Open pours/collectionagent/collector/sidecar/patch.yaml. Add its initContainers entry and its volumes entry to the pod template of each workload that takes the sidecar. In a CronJob, the pod template sits under spec.jobTemplate.

Then run this from the directory that contains casting.yaml to apply the sidecar's config and permissions to your application's namespace:

kubectl -n <your-namespace> apply -k pours/collectionagent/collector/sidecar

Verify these values:

<your-namespace>: Your application's namespace.

The sidecar's permissions go to the namespace's default service account. Workloads that run under service accounts of their own take the sidecar through a Kustomize patch, with signoz-rolebinding.yaml.

Apply your application as usual.

Step 5: Verify the sidecar

Run this on the machine where you use kubectl to check that a workload's pods run the sidecar:

kubectl -n <your-namespace> get pods -l <your-pod-selector> -o jsonpath='{.items[*].spec.initContainers[*].name}'

Verify these values:

<your-namespace>: Your application's namespace.
<your-pod-selector>: A label selector for the workload's pods, from spec.selector.matchLabels in its manifest.

The output lists signoz-collector-sidecar once per pod.

Once your application sends to the sidecar, as Send Data from Applications to the Collector shows, its traces, metrics, and logs appear in SigNoz with the k8s.pod.name and k8s.namespace.name resource attributes.

Apply Changes

After a change to the sidecar's casting.yaml, follow the way you added the sidecar:

With a Kustomize patch: forge again, apply your application again, and restart each workload that runs the sidecar.
With the pod template: forge again, apply the sidecar's files again, copy the two entries again if they changed, and restart each workload that runs the sidecar.

Troubleshooting

A workload's pods have no sidecar

In Step 5, the kubectl get pods check prints nothing for a workload.

Cause: with the Kustomize patch, no target in your application's kustomization.yaml names the workload's kind and name, so the patch is not applied to it. With the pod template, the workload's template lacks the two entries.

Fix: add a target with the workload's kind and name, or copy the two entries into its template, then apply your application again.

After the fix, the check prints signoz-collector-sidecar once per pod.

K8s Serverless (EKS Fargate) - Collector Sidecar

Prerequisites

Install the Collection Agent

Step 1: Install foundryctl

Step 2: Create casting.yaml

Step 3: Generate the sidecar files

Step 4: Add the sidecar to your workloads

Step 5: Verify the sidecar

Apply Changes

Troubleshooting

A workload's pods have no sidecar

Next Steps