K8s Serverless (EKS Fargate) - Install

This guide explains how to install the EKS Fargate Collection Agent with Foundry.

Foundry, documented below, is now the supported way to install and manage the EKS Fargate Collection Agent.

If you already run the manual sidecar collector, follow Migrate to Foundry to move it over.

Prerequisites

An EKS cluster with a Fargate profile that selects the collector's namespace and your applications' namespaces.
kubectl configured to reach the cluster.
A SigNoz to send data to: SigNoz Cloud or a self-hosted SigNoz.

Install the Collection Agent

Foundry is an open-source CLI that runs your self-hosted observability stack as code. One declarative config provisions the infrastructure, installs the SigNoz backend, and sets up OpenTelemetry collection on bare metal, containers, or Kubernetes. Learn more about Foundry.

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 with one document for the deployment collector described in How it works. collector.kind: deployment selects it:

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: deployment
    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/deployment/deployment.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>: A name for this cluster, unique across the clusters that send to the same SigNoz, which becomes k8s.cluster.name and names the cluster in the SigNoz Kubernetes views.
<DEPLOYMENT_ENVIRONMENT>: Your deployment environment, for example staging or production, which becomes deployment.environment on the collected telemetry.

For every option of this casting, see the EKS Fargate Kustomize example.

The foundry.signoz.io/kubernetes-namespace annotation under metadata sets the namespace the deployment collector is applied to. A Fargate profile must select that namespace, or the deployment collector's pod stays Pending. The default is:

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/kubernetes-namespace: signoz   # namespace to apply into, created by the apply

The namespace defaults to metadata.name. The example's annotations table describes it.

Step 3: Deploy

Run this from the directory that contains casting.yaml:

foundryctl cast -f casting.yaml

This command:

writes the kustomize root pours/collectionagent/collector/deployment;
applies it with kubectl apply -k to the cluster of your current kubectl context;
creates the collector's namespace on the first apply, signoz from metadata.name in this casting. The root holds the namespace, the collector's service account and RBAC, its config, its Service, and its Deployment.

Run the same command again after editing casting.yaml to apply the change.

To run kubectl directly, generate the kustomize root and apply it. Run this from the directory that contains casting.yaml:

foundryctl forge -f casting.yaml   # writes the kustomize root under pours/collectionagent/collector/deployment
kubectl apply -k pours/collectionagent/collector/deployment

To see the manifests before you apply them, run kubectl kustomize pours/collectionagent/collector/deployment.

Step 4: Verify the Collection Agent

Run this on the machine where you use kubectl to check that the deployment collector's pod is running on a Fargate node, in the namespace from metadata.name:

kubectl get pods -n signoz -o wide

The output should look similar to the following, with one signoz-collector-deployment pod on a node whose name starts with fargate-. Pod suffixes, IP addresses, and node names vary:

NAME                                           READY   STATUS    RESTARTS   AGE   IP           NODE                                 NOMINATED NODE   READINESS GATES
signoz-collector-deployment-6d9c7b8f5c-k2x9p   1/1     Running   0          2m    10.0.12.34   fargate-ip-10-0-12-34.ec2.internal   <none>           <none>

In SigNoz, open the Kubernetes Monitoring views under Infrastructure Monitoring. The Clusters view lists your cluster under the name you set as <CLUSTER_NAME>, and the Pods and Nodes views fill in as data arrives. Check Logs Explorer to confirm Kubernetes events are flowing.

Step 5: Add the sidecar to your workloads (optional)

The sidecar receives an application's telemetry inside its own pod, and Collector Sidecar shows how to add it to your workloads. Skip this step if your applications send to the deployment collector's Service.

Customize the Collection Agent

Every change follows the same loop: edit casting.yaml, then run foundryctl cast -f casting.yaml again. For the sidecar, forge and apply as Collector Sidecar shows, then restart the workloads that run it.

Collector settings (image, environment): set them in the collector's spec (see spec fields). For example, to pin the collector image:
```
spec:
  collector:
    spec:
      image: otel/opentelemetry-collector-contrib:0.139.0
```

Collector config (receivers, processors, pipelines): add it under spec.collector.spec.config.data, keyed collector/deployment/deployment.yaml in the deployment collector's document or collector/sidecar/sidecar.yaml in the sidecar's. It merges into the generated config (see custom config files). For example, to scrape kubelet metrics every 60s:

spec:
  collector:
    spec:
      config:
        data:
          collector/deployment/deployment.yaml: |
            receivers:
              receiver_creator:
                receivers:
                  kubeletstats:
                    config:
                      collection_interval: 60s

Manifests (resources, annotations): add patches under spec.patches against the files under collectionagent/collector/deployment/, such as workload.yaml for the deployment collector, or against collectionagent/collector/sidecar/patch.yaml for the sidecar's container. For example, to give the deployment collector more CPU and memory:

spec:
  patches:
    - target: collectionagent/collector/deployment/workload.yaml
      operations:
        - op: replace
          path: /spec/template/spec/containers/0/resources
          value:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: 500m
              memory: 1Gi

Each run regenerates the files under pours/, so keep every change in casting.yaml.

To run the collectors through the OpenTelemetry Operator instead, see OpenTelemetry Operator.

Troubleshooting

Collector pod stays Pending

In Step 4, the deployment collector's pod stays Pending. Run this on the machine where you use kubectl to see why the pod is unscheduled:

kubectl describe pod -n signoz <pod-name>

Replace <pod-name> with the pod's name from kubectl get pods -n signoz. The events show FailedScheduling.

Cause: no Fargate profile selects the collector's namespace, so no Fargate node is started for the pod.

Fix: add a Fargate profile that selects the namespace, then run this on the machine where you use kubectl to recreate the pod:

kubectl rollout restart -n signoz deployment/signoz-collector-deployment

After the fix, kubectl get pods -n signoz -o wide shows the pod as Running on a fargate- node.

The pods view stays empty

In Step 4, the Pods view in SigNoz stays empty. Run this on the machine where you use kubectl to read the deployment collector's logs:

kubectl logs -n signoz deployment/signoz-collector-deployment --since=10m

The logs show errors from the kubelet scrapes: a 403, or a 404 on /api/v1/nodes/<node-name>/proxy/stats/summary.

Cause: with a 403, the collector's service account is not allowed through the Kubernetes API server's node proxy. With a 404, the kubelet on that node does not serve its stats through the proxy.

Fix: for a 403, run this on the machine where you use kubectl. It prints yes once the ClusterRole Foundry generates is in place:

kubectl auth can-i get nodes/proxy --as=system:serviceaccount:signoz:signoz-collector-deployment

If it prints no, run Step 3 again. For a 404, scrape the kubelets directly, as the example's API-server proxy section shows.

After the fix, the Pods view in SigNoz lists your pods.

foundryctl cast stops with `unsupported collector kind "agent"`

In Step 3, foundryctl cast -f casting.yaml stops before it applies anything, with the message unsupported collector kind "agent".

Cause: the document has no collector.kind, so the collector kind defaults to agent, and on EKS Fargate the collector kinds are deployment and sidecar.

Fix: add kind: deployment under spec.collector, as in Step 2, or kind: sidecar in the sidecar's document, then run Step 3 again.

After the fix, kubectl get pods -n signoz shows the deployment collector's pod.

foundryctl cast rejects a patch

In Step 3, foundryctl cast -f casting.yaml stops before it applies anything, with failed to apply patch for target "<target>" and one of these causes:

doc is missing key: <path>: missing value
doc is missing path: <path>: missing value
patch target "<target>" did not match any generated material

Cause: the patch's target or path does not exist in what Foundry generates for EKS Fargate.

Fix: remove the patch from casting.yaml, then run this from the directory that contains it:

foundryctl forge -f casting.yaml

Take the target and path from the files under pours/collectionagent/collector/, add the patch back, and run Step 3 again.

After the fix, kubectl get pods -n signoz shows the deployment collector's pod.

foundryctl cast reaches the wrong cluster or none

In Step 3, foundryctl cast -f casting.yaml applies to another cluster or cannot reach one. Run this on the machine where you run foundryctl to see which cluster it uses:

kubectl config current-context

Cause: foundryctl cast applies to the cluster of your current kubectl context.

Fix: switch to the right context with kubectl config use-context <context-name>, then run Step 3 again. Replace <context-name> with a context from kubectl config get-contexts.

After the fix, kubectl get pods -n signoz shows the deployment collector's pod on that cluster.

Send data from your applications

Kubelet and cluster metrics and Kubernetes events flow as soon as the deployment collector is running. To send traces, metrics, and logs from your applications to the sidecar in their own pod or to the deployment collector's Service, see Send Data from Applications to the Collector.