> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange/composite-chart-settings.md).

# Composite Chart Settings

Composite Helm chart settings.

Reference for the Composite chart (`openg2p-agri-composite`). Installing it: [Deployment: Exchange](https://docs.openg2p.org/products/open-agri-stack/deployment/exchange.md#composite). The Rancher form shows the groups below; settings marked "values only" are set in **Edit YAML**.

{% hint style="info" %}
**Source:** the chart [`composite/charts/openg2p-agri-composite`](https://github.com/openg2p/agri-stack/tree/develop/composite/charts/openg2p-agri-composite) ([values](https://github.com/openg2p/agri-stack/blob/develop/composite/charts/openg2p-agri-composite/values.yaml), [Rancher questions](https://github.com/openg2p/agri-stack/blob/develop/composite/charts/openg2p-agri-composite/questions.yaml)).
{% endhint %}

## Hostnames and ingress

| Value                                                                               | Default                                | Form                                                     |
| ----------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------- |
| `global.baseDomain`                                                                 | `<namespace>.openg2p.org`              | General: Base Domain                                     |
| `global.compositeHostname`                                                          | `agri-composite.<Base Domain>`         | General: Composite Hostname                              |
| `global.consoleHostname`                                                            | `agri-composite-console.<Base Domain>` | Console: Console Hostname                                |
| `global.namespace`                                                                  | Empty: the install namespace           | Values only; the `<namespace>` in every default hostname |
| `composite.istio.virtualservice.gateway`, `console.ui.istio.virtualservice.gateway` | `internal`                             | Values only                                              |

Both the API and the console are served through the Istio `internal` gateway, like the registries' partner APIs. The API answers at `/composite/v1/…`, `/ping` and `/docs` (OpenAPI UI).

**The internal API is not public.** `/composite/v1/internal/…` (the [consent templates](https://docs.openg2p.org/products/open-agri-stack/composite/api.md#internal-consent-templates) the Exchange CM reads) is reached only at the in-cluster Service (`http://agri-composite-api`). Two guards keep it off the public host:

| Guard          | How                                                                                                                                                                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| VirtualService | The first route, `internal-not-public`, answers `404` for `/composite/v1/internal` with an Istio `directResponse` (Istio 1.15 or later). With `rewriteUri` set, the chart blocks the public path that would reach it, and refuses a rewrite that routes the host into it |
| Backend        | A request carrying `x-forwarded-host` (set by the gateway) is answered `404`                                                                                                                                                                                             |

The [install test](https://docs.openg2p.org/products/open-agri-stack/deployment/testing.md) checks the path is `404` on the public URL.

## Consent mode and the Exchange CM

| Value                                        | Default                                                                 | Form                                                                                  |
| -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `composite.consent.mode`                     | `exchange`                                                              | Agri Stack exchange: Consent Mode                                                     |
| `composite.consent.exchangeCmUrl`            | `http://commons-services-cm-partner-api` (the CM in the same namespace) | Agri Stack exchange: Exchange Consent Manager URL. `/consent/v1/validate` is appended |
| `composite.consent.exchangeCmTimeoutSeconds` | `5`                                                                     | Agri Stack exchange: Exchange Consent Manager Timeout                                 |

Keep the mode `exchange`: the Composite presents the partner's consent (its `consent_id`, or a consent the partner signed), or asks the Exchange CM to look it up when the partner sent none, and gets one consent token per registry ([Composite as a partner](https://docs.openg2p.org/products/open-agri-stack/architecture/exchange.md#composite-as-a-partner)). A partner-signed consent must have been issued within the CM's freshness window (300 seconds by default), so partners sign a fresh consent for each request. If the Exchange CM is unreachable, the request fails closed (503). Request and response details: [consent mode](https://docs.openg2p.org/products/open-agri-stack/composite/request-handling.md#consent-mode).

The other mode, `passthrough`, sends the partner's consent to each registry unchanged (it needs a partner-signed consent), so each registry's Partner Management needs a scope policy for every partner. It suits only a single install where the registries share the Composite's commons.

## Registries

| Value                                          | Default                                  | Form                                                                                                                                              |
| ---------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `composite.registries.farmer-registry.url`     | Empty (required)                         | Integration: Farmer Registry Search URL                                                                                                           |
| `composite.registries.crop-sown-registry.url`  | Empty (required)                         | Integration: Crop Sown Registry Search URL                                                                                                        |
| `composite.registries.<controller>.partnerId`  | Empty                                    | Values only. The registry's PM partner ID: when set, the registry's response signature is verified against `PARTNER_<ID>` in the Exchange PM      |
| `composite.registries.<controller>.receiverId` | Empty: the controller ID                 | Values only. The `header.receiver_id` sent to it                                                                                                  |
| `global.compositePartnerId`                    | `agri-composite`                         | Integration: Composite Partner ID. The `sender_id` towards registries; partners send it as `receiver_id`. Its key must be in each department's PM |
| `global.partnerManagementApiUrl`               | `http://commons-services-pm-partner-api` | Integration: Partner Management URL. Partner keys and use-case policies, fetched as `PARTNER_<SENDER_ID>`                                         |

Each registry is a data controller ID mapped to its full DCI sync search URL. Partner Management holds no registry endpoints yet, so they are set here, and nothing about a registry is hard-coded. An empty URL makes that source fail (`error`); a use case whose sources name a controller not listed here does not load. The console reads each registry's data scope catalogue from the same host (`/partner/data_scopes`). A third registry is added under `composite.registries` in **Edit YAML** (the form shows the two that ship): [adding a registry](https://docs.openg2p.org/products/open-agri-stack/registries/adding-a-registry.md#step-4-register-the-endpoint-in-the-composite). Changing a registry setting rolls the pods.

## Use cases

| Value                                 | Default                 | Form                                                              |
| ------------------------------------- | ----------------------- | ----------------------------------------------------------------- |
| `composite.useCases`                  | `loan-profile`          | Values only: name → YAML text, one use case per entry             |
| `composite.existingUseCasesConfigMap` | Empty                   | General: Existing Use-Case ConfigMap                              |
| `composite.useCasesReloadSeconds`     | `30`                    | General: Use-Case Reload Interval (`0` = never; restart to apply) |
| `composite.useCasesMountPath`         | `/app/config/use-cases` | Values only                                                       |

The chart renders `composite.useCases` into the ConfigMap `<release>-use-cases`, mounted at `/app/config/use-cases`. Running pods pick up a change within the reload interval (about a minute after the ConfigMap updates), without a restart. Each file is validated strictly when loaded; only `published` use cases are served. To manage use cases elsewhere (e.g. GitOps), point `composite.existingUseCasesConfigMap` at your own ConfigMap with keys `<name>.yaml` (and any `.j2` template files).

Writing a use case and adding it: [Use-Case Configuration](https://docs.openg2p.org/products/open-agri-stack/composite/use-case-configuration.md). The default, `loan-profile`: [the `loan-profile` use case](https://docs.openg2p.org/products/open-agri-stack/composite/use-case-configuration.md#the-loan-profile-use-case).

## Signing key

| Value                                                                            | Default                                                    | Form                                |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------- | ----------------------------------- |
| `composite.signingKey.generate`                                                  | `true`                                                     | Signing key: Generate Signing Key   |
| `composite.signingKey.secretName`                                                | `agri-composite-signing`                                   | Signing key: Signing Key Secret     |
| `composite.signingKey.pemKey`, `p12Key`, `passwordKey`, `kidKey`, `algorithmKey` | `key.pem`, `composite.p12`, `password`, `kid`, `algorithm` | Values only: the keys in the Secret |

The Composite signs its calls to the registries and its answers to partners with this key, and serves its public key at `/.well-known/jwks.json`, where each department's Partner Management reads it.

* **Generated** (`generate: true`): on first install the chart creates the Secret with an EC P-256 key (`key.pem`) and a `kid` (`<partner ID>-<random>`), then reads it back on every upgrade, and keeps it on uninstall.
* **Your own:** create the Secret before installing, with a `.p12` (`composite.p12`, `password`, and optionally `kid` and `algorithm`). The chart leaves a Secret it did not create alone, and a `.p12` is used before a generated key. `kid` blank: the certificate's SHA-256 thumbprint; `algorithm: auto` takes it from the key type (EC → ES256, Ed25519 → EdDSA, RSA → RS256).

Replacing and rotating it: [Keys](https://docs.openg2p.org/products/open-agri-stack/administration/keys.md#composite-signing-key).

## Console

On by default: the read-only staff [console](https://docs.openg2p.org/products/open-agri-stack/composite/console.md). Off (`console.enabled: false`), nothing below is deployed, and the API serves the partner API only, with no database and no IAM.

| Value                                        | Default                                                                             | Form                                                               |
| -------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `console.enabled`                            | `true`                                                                              | Console: Enable Console                                            |
| `console.ui.image.tag`                       | `develop`                                                                           | Console: Console UI Image Tag                                      |
| `console.iam.providerApiUrl`                 | `http://commons-services-iam-staff-portal-api`                                      | Console: IAM Staff API URL (internal)                              |
| `console.iam.publicUrl`                      | `https://staff-iam.<Base Domain>`                                                   | Console: IAM Staff API URL (public)                                |
| `console.iam.redisUrl`                       | `redis://commons-redis-master:6379/0`                                               | Console: IAM Redis URL                                             |
| `console.iam.keycloakClientId`               | `agri-composite`                                                                    | Console: Keycloak Client ID (also its IAM application mnemonic)    |
| `console.iam.cookieDomain`                   | `.<Base Domain>`                                                                    | Console: Cookie Domain                                             |
| `console.db.hostname`, `dbname`, `user`      | `commons-postgresql`, `agri_composite`, `agri_composite_user`                       | Console: Database Host, Name, User                                 |
| `console.pmPortalUrl`, `console.cmPortalUrl` | `https://partner-management.<Base Domain>`, `https://consent-manager.<Base Domain>` | Console: portal links                                              |
| `console.activityRetentionDays`              | `90`                                                                                | Console: Call Log Retention (days); `0` keeps everything           |
| `console.catalogueCacheSeconds`              | `300`                                                                               | Values only: registry data scope catalogues are cached this long   |
| `console.db.createSecret`, `secretName`      | `true`, `agri-composite-db`                                                         | Values only: the database password Secret, generated once and kept |
| `console.keycloakInit.adminUsers`            | `[admin]`                                                                           | Values only: staff users given `AGRI_COMPOSITE_ADMIN`              |
| `console.iamRegister.runAsHook`              | `true`                                                                              | Values only: `false` in umbrella charts or helmfiles               |

With the console on, the chart runs Jobs that create the database and its user in the commons Postgres, the console's Keycloak client in the `staff` realm (roles `AGRI_COMPOSITE_ADMIN`, `AGRI_COMPOSITE_VIEWER`) and its IAM application. The call log holds the request ID, use case, partner, statuses, timings and the ID of the consent used, never the subject, the consent's content or any data.

## CORS

| Value                        | Default | Form                                                |
| ---------------------------- | ------- | --------------------------------------------------- |
| `composite.corsAllowOrigins` | empty   | Agri Stack exchange: Allowed Browser Origins (CORS) |

Browser origins allowed to call the Composite, comma-separated; empty for none. No browser calls the Composite by default: the Exchange CM's partner portal gets its consent templates from the CM, which reads them in the cluster. The chart renders it into `AGRI_COMPOSITE_CORS_ALLOW_ORIGINS` as a JSON list.

## Scaling and rate limits

| Value                                              | Default                                       | Form                                             |
| -------------------------------------------------- | --------------------------------------------- | ------------------------------------------------ |
| `composite.autoscaling.enabled`                    | `false`                                       | Scaling: Enable Autoscaling                      |
| `composite.autoscaling.minReplicas`, `maxReplicas` | `1`, `5` (at 70% CPU)                         | Scaling: Min Replicas, Max Replicas              |
| `composite.replicaCount`                           | `1`                                           | Scaling: Replica Count (when autoscaling is off) |
| `composite.workers`                                | `2`                                           | Scaling: Workers per Pod (gunicorn)              |
| `composite.resources`                              | Requests 100m CPU, 192Mi; limits 1 CPU, 512Mi | Values only                                      |

* Pods are stateless. Autoscaling on CPU is opt-in. Memory-based autoscaling is off on purpose: Python's memory does not shrink, so it would never scale back down.
* Each worker keeps its own pooled HTTP client, partner-key cache (300 seconds) and partner use-case policy cache (60 seconds, and never longer than PM's `Cache-Control`), each with last-known-good for 6 hours during a PM outage. A revoked grant can keep working until the policy cache expires.
* The image runs as uid 1001 with a read-only root filesystem. Startup never calls a registry; a registry being down only affects requests.

Rate limits ([design](https://docs.openg2p.org/products/open-agri-stack/composite/rate-limiting.md)):

| Value                                                      | Default                                                                                       | Form                               |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------- |
| `edgeRateLimit.enabled`                                    | `false` (it creates an EnvoyFilter in `istio-system`: the installing user needs rights there) | Rate Limits: Edge Rate Limit       |
| `edgeRateLimit.requests`                                   | `120`                                                                                         | Rate Limits: Edge Limit (Requests) |
| `edgeRateLimit.per`                                        | `1m` (`<n>s`, `<n>m`, `<n>h`)                                                                 | Rate Limits: Edge Limit Interval   |
| `edgeRateLimit.pathPrefix`                                 | `/composite/v1/use-cases`; empty = the whole hostname                                         | Values only                        |
| `edgeRateLimit.gatewayNamespace`, `gatewaySelector`        | `istio-system`, `istio: ingressgateway`                                                       | Values only                        |
| `composite.rateLimit.redis.url`                            | `redis://commons-redis-master:6379/0`; empty = per worker                                     | Rate Limits: Rate Limit Redis URL  |
| `composite.rateLimit.redis.keyPrefix`                      | `<release>:ratelimit:`                                                                        | Values only                        |
| `composite.rateLimit.redis.passwordSecret.name`, `key`     | empty (the commons Redis has no password), `redis-password`                                   | Values only                        |
| `composite.rateLimit.redis.timeoutSeconds`, `retrySeconds` | `0.25`, `10`                                                                                  | Values only                        |

* **Edge limit**: one token bucket for all partners on the use-case route, at the Istio ingress gateway, **per gateway pod** (two gateway pods allow up to twice `requests`). Over it: `429`, header `x-local-rate-limit: true`. The chart creates one EnvoyFilter, named `<namespace>-<release>-edge-ratelimit`, in `gatewayNamespace`: the user installing the chart needs create, update and delete on `envoyfilters.networking.istio.io` there. Installs in other namespaces get their own EnvoyFilter and do not affect each other. Not compatible with `composite.istio.virtualservice.rewriteUri` unless `pathPrefix` is empty.
* **Per partner, per use case** (`limits.rate_per_partner` in each use case): counted in Redis across all pods and workers. If Redis is unreachable, each worker counts on its own, logs a warning and tries Redis again after `retrySeconds`; partner calls are never refused for it (availability over exactness). With an empty URL each worker always counts on its own (up to pods × workers × the rate).

## Audit

| Value                    | Default                                   | Form                                                     |
| ------------------------ | ----------------------------------------- | -------------------------------------------------------- |
| `global.auditManagerUrl` | `http://commons-services-auditmanager:80` | Integration: Audit Manager URL. Empty turns auditing off |

The Composite posts CloudEvents to the Audit Manager's `/v1/auditmanager/events`. Events carry no data and no subject identifiers, and are linked by the request ID.

| Event         | When                                                             | Context                                                                                               |
| ------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `request`     | The request is accepted, or rejected before any source is called | Outcome (`success`, `denied`, `failure`) and reason code; the consent used (`consent_id`), once known |
| `source_call` | Each registry call                                               | Source, controller, status, attempts, duration                                                        |
| `response`    | Every response                                                   | HTTP status, duration, status per source, the consent used                                            |

Events are sent in the background; a failure is logged and never fails the request. A use case can limit which events it sends (`audit.events`).

## Sanity check

| Value                     | Default | Form                                                     |
| ------------------------- | ------- | -------------------------------------------------------- |
| `sanity.enabled`          | `true`  | Values only                                              |
| `sanity.failOnError`      | `true`  | Values only. `false` reports without failing the release |
| `sanity.readinessTimeout` | `180`   | Values only, seconds                                     |

After install and upgrade, a hook pings the API and lists the published use cases. A failure fails the release.

## Environment settings

The service reads its settings from environment variables with the prefix `AGRI_COMPOSITE_`. The chart sets them from the values above; extra ones go in `composite.envVars` (values only).

| Variable                                                                                                                                                                                        | Default                                                                                                                                                                                                     |                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_CASES_DIR`                                                                                                                                                                                 | `use-cases` (`/app/config/use-cases` in the chart)                                                                                                                                                          | Use-case directory                                                                                                                                                                                                                                          |
| `USE_CASES_RELOAD_SECONDS`                                                                                                                                                                      | `30`                                                                                                                                                                                                        | `0` = no reload                                                                                                                                                                                                                                             |
| `REGISTRIES`                                                                                                                                                                                    | `{}`                                                                                                                                                                                                        | JSON `{controller: {url, partner_id?, receiver_id?}}`, rendered from `composite.registries`                                                                                                                                                                 |
| `COMPOSITE_PARTNER_ID`                                                                                                                                                                          | `agri-composite`                                                                                                                                                                                            | The Composite's ID                                                                                                                                                                                                                                          |
| `SIGNING_P12_PATH`, `SIGNING_P12_PASSWORD`, `SIGNING_KID`, `SIGNING_ALGORITHM`                                                                                                                  | –, –, thumbprint, `auto`                                                                                                                                                                                    | The Composite's key, from the signing key Secret                                                                                                                                                                                                            |
| `PARTNER_MGMT_API_URL`                                                                                                                                                                          | `http://commons-services-pm-partner-api`                                                                                                                                                                    | Partner keys and use-case policies                                                                                                                                                                                                                          |
| `PARTNER_KEY_CACHE_TTL_SECONDS`, `PARTNER_KEY_HARD_TTL_SECONDS`, `PARTNER_KEY_NEGATIVE_TTL_SECONDS`, `PARTNER_KEY_REFRESH_COOLDOWN_SECONDS`, `PARTNER_KEY_FETCH_TIMEOUT_SECONDS`                | `300`, `21600`, `30`, `10`, `3.0`                                                                                                                                                                           | Partner key cache: soft TTL, last-known-good during a PM outage, cache of "unknown", refresh cooldown on an unknown `kid`, fetch timeout                                                                                                                    |
| `PARTNER_POLICY_CACHE_TTL_SECONDS`, `PARTNER_POLICY_HARD_TTL_SECONDS`, `PARTNER_POLICY_NEGATIVE_TTL_SECONDS`, `PARTNER_POLICY_REFRESH_COOLDOWN_SECONDS`, `PARTNER_POLICY_FETCH_TIMEOUT_SECONDS` | `60`, `21600`, `30`, `10`, `3.0` (the chart sets the first three; the hard TTL is in the Rancher form, **Partner Policy Hard TTL**: during a PM outage a revoked partner can be served for up to this long) | Partner use-case policy cache: soft TTL (also capped by PM's `Cache-Control`), last answer kept during a PM outage (then 503 `partner_policy_unavailable`), cache of "no grant", at most one PM call per partner per cooldown while PM fails, fetch timeout |
| `CRYPTO_ALLOWED_ALGORITHMS`                                                                                                                                                                     | `EdDSA,ES256,RS256`                                                                                                                                                                                         |                                                                                                                                                                                                                                                             |
| `REQUEST_MAX_SKEW_SECONDS`                                                                                                                                                                      | `300`                                                                                                                                                                                                       | How far `header.message_ts` may be from now (`0` disables)                                                                                                                                                                                                  |
| `DEFAULT_SOURCE_TIMEOUT_MS`, `DEFAULT_OVERALL_TIMEOUT_MS`                                                                                                                                       | `5000`, `10000`                                                                                                                                                                                             | Used when the use case does not set them                                                                                                                                                                                                                    |
| `HTTP_MAX_CONNECTIONS`, `HTTP_MAX_KEEPALIVE_CONNECTIONS`, `HTTP_KEEPALIVE_EXPIRY_SECONDS`                                                                                                       | `200`, `50`, `30`                                                                                                                                                                                           | One pooled client per worker                                                                                                                                                                                                                                |
| `CONSENT_MODE`                                                                                                                                                                                  | `exchange`                                                                                                                                                                                                  | An unknown value stops startup                                                                                                                                                                                                                              |
| `CONSENT_EXCHANGE_CM_URL`                                                                                                                                                                       | `http://commons-services-cm-partner-api`                                                                                                                                                                    | The Exchange CM partner API base URL (the CM in the Composite's own namespace)                                                                                                                                                                              |
| `CONSENT_EXCHANGE_CM_TIMEOUT_SECONDS`                                                                                                                                                           | `5.0`                                                                                                                                                                                                       |                                                                                                                                                                                                                                                             |
| `CORS_ALLOW_ORIGINS`                                                                                                                                                                            | `[]`                                                                                                                                                                                                        | A **JSON list**; a plain URL or an empty string stops startup                                                                                                                                                                                               |
| `CONSOLE_ENABLED`                                                                                                                                                                               | `false` (`true` in the chart)                                                                                                                                                                               | The console's admin API, IAM login and database (`DB_*`)                                                                                                                                                                                                    |
| `CONSOLE_PM_PORTAL_URL`, `CONSOLE_CM_PORTAL_URL`, `ACTIVITY_RETENTION_DAYS`, `CATALOGUE_CACHE_SECONDS`                                                                                          | –, –, `90`, `300`                                                                                                                                                                                           | Console settings                                                                                                                                                                                                                                            |
| `AUDIT_MANAGER_URL`                                                                                                                                                                             | Empty (off)                                                                                                                                                                                                 |                                                                                                                                                                                                                                                             |
| `AUDIT_TIMEOUT_SECONDS`, `AUDIT_SOURCE`                                                                                                                                                         | `2.0`, `/openg2p/agri-composite`                                                                                                                                                                            |                                                                                                                                                                                                                                                             |
| `NO_OF_WORKERS`                                                                                                                                                                                 | `2`                                                                                                                                                                                                         | gunicorn workers per pod                                                                                                                                                                                                                                    |
| `LOGGING_LEVEL`                                                                                                                                                                                 | `INFO` (chart)                                                                                                                                                                                              |                                                                                                                                                                                                                                                             |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/products/open-agri-stack/deployment/exchange/composite-chart-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
