Annotations

Annotations are key-value pairs in metadata.annotations that provide deployment-specific configuration to Foundry. They are inputs to the generation process - Foundry reads them during forge and uses them to populate templates and configure behavior.

How annotations work

Annotations live in the casting file's metadata block:

apiVersion: v1alpha1
metadata:
  name: signoz
  annotations:
    foundry.signoz.io/some-key: some-value
spec:
  deployment:
    mode: systemd
    flavor: binary

During forge, Foundry reads annotation values and injects them into the generated output. For example, systemd annotations set binary paths in the generated .service files. ECS annotations populate Terraform variables in the generated terraform.tfvars.json.

Annotations vs patches

Annotations and patches serve different roles in the generation pipeline:

	Annotations	Patches
Where	metadata.annotations	spec.patches
When	Before generation - Foundry reads them as input	After generation - Foundry applies them to output
What	Deployment-specific parameters (paths, IDs, ARNs) that Foundry needs to generate files correctly	Modifications to already-generated files (resource limits, storage classes, scheduling)
Validated	Yes - Foundry reads and uses them during template execution	No - Foundry passes them through as-is

In short: annotations tell Foundry how to generate, patches tell Foundry what to change after generating.

When to use which

Use annotations when Foundry needs the value during generation. These are typically infrastructure identifiers, file paths, or settings that determine the shape of the generated output. You cannot achieve the same result with patches because the value must exist before files are generated.

Use patches when you want to modify a generated file after the fact. These are typically platform-specific tuning (resource limits, scheduling, service types) that Foundry doesn't need to understand.

Which castings use annotations

Not all deployment modes require annotations. Most modes (Docker Compose, Docker Swarm, Kubernetes Kustomize, Render, Coolify, Railway) work with just metadata.name and spec.deployment.

Casting	Required	Annotations
Systemd (binary)	Yes	Binary paths for SigNoz, ingester, and PostgreSQL
ECS EC2 (Terraform)	Yes	AWS region, cluster ID, subnets, security groups, IAM roles, S3 bucket
Kubernetes (Helm)	No	Optional chart repo and chart name overrides

For the complete list of annotation keys and their descriptions, see Casting File Reference.

Annotation catalog

Foundry's annotations are defined centrally: the Annotation value object lives in api/v1alpha1, and the entries (key, default, mode, description) live with their Kind - the Installation catalog is in api/v1alpha1/installation. Each entry records the mode it applies to; an annotation set outside its mode is ignored, and omitting one falls back to its default.

Systemd (binary)

Absolute paths to the component binaries the generated .service units exec.

Annotation	Default	Description
foundry.signoz.io/signoz-binary-path	/opt/signoz/bin/signoz	Absolute path to the SigNoz server binary.
foundry.signoz.io/ingester-binary-path	/opt/ingester/bin/signoz-otel-collector	Absolute path to the SigNoz OTel Collector (ingester) binary.
foundry.signoz.io/metastore-postgres-binary-path	/usr/bin/postgres	Absolute path to the PostgreSQL server binary; its bindir also holds initdb and pg_ctl.
foundry.signoz.io/telemetrystore-clickhouse-binary-path	/usr/bin/clickhouse	Absolute path to the ClickHouse binary, run as clickhouse server.
foundry.signoz.io/telemetrykeeper-clickhousekeeper-binary-path	/usr/bin/clickhouse	Absolute path to the ClickHouse binary, run as clickhouse keeper.

Next steps

• Patches - post-generation modifications
• Casting - the full casting file structure
• Casting file reference - complete annotation reference