> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/secret/projections/best-practices.md).

# Best practices

Use these practices to keep projections secure, readable, and predictable across environments.

### Keep secrets out of resource files

* Store credentials and tokens in Secrets.
* Reference secret values in projections.
* Avoid plain text values in templates.

```yaml
projection:
  secrets:
    - id: "postgres-credentials"
      contextAlias: "db"
  projections:
    envVars:
      - key: "DATABASE_URL"
        value: "postgresql://{{.secrets.db.username}}:{{.secrets.db.password}}@{{.secrets.db.host}}:{{.secrets.db.port}}/{{.secrets.db.database}}"
```

### Use clear aliases

Use short, meaningful `contextAlias` values.

Good aliases make templates easier to read and debug.

```yaml
projection:
  secrets:
    - id: "api-credentials"
      contextAlias: "api"
  depots:
    - name: "sales-warehouse"
      contextAlias: "warehouse"
```

### Pick the right template engine

* Use `go-template` for most stack-level templates.
* Use `liquid` when you need Liquid syntax.
* Use `none` for static values.

Match the syntax to the selected engine.

```yaml
templateType: "go-template"
value: "{{.secrets.db.url}}"
```

### Keep generated output focused

Project only the values your workload needs.

Too many inputs make templates harder to test and maintain.

* Limit referenced Secrets and Depots.
* Generate only required files and variables.
* Split unrelated concerns into separate templates.

### Use reserved paths carefully

Avoid writing files into reserved DataOS paths unless the runtime expects them.

Reserved paths include:

* `/etc/dataos/config`
* `/etc/dataos/secret`
* `/etc/dataos/work`

Use explicit custom directories for app-specific files.

```yaml
projections:
  files:
    - name: "app-config.yaml"
      directory: "/etc/app/config"
      value: |
        log_level: info
```

### Add defaults for optional values

Use defaults when values may be missing across environments.

This keeps templates portable.

```yaml
spark.sql.adaptive.enabled={{.stackSpec.adaptiveQueryExecution | default "true"}}
```

### Test before deployment

Validate projection logic locally before attaching it to a workload.

1. Test the template with `dataos develop use`.
2. Validate the full resource with `dataos develop resource`.
3. Review generated output before deployment.

### Avoid leaking sensitive output

* Do not print rendered secrets in logs.
* Do not expose generated config files in debug output.
* Restrict depot secret access with specific `secretPurposes`.

```yaml
projection:
  depots:
    - name: "my-postgres-depot"
      contextAlias: "postgres"
      includeSecrets: true
      secretPurposes: ["r"]
```

### Keep templates reusable

Design templates so the same resource works across tenants and environments.

* Use runtime context instead of hardcoded tenant values.
* Prefer aliases over repeated object paths.
* Keep static strings outside templated expressions when possible.

```yaml
value: "--env={{.defaultProjections.dataOsInstanceTenantId}}"
```

### Review generated arguments and files together

Arguments, files, and environment variables should agree on paths and values.

Misaligned output causes runtime errors that are hard to trace.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/resources/secret/projections/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.