> 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/composite.md). # Composite Installing the Composite in the Exchange: the chart and all its options (hostnames, consent mode, registries, use cases, signing key, console, CORS, scaling, audit, environment settings). Installing the [Composite](/products/open-agri-stack/exchange/composite.md), the partners' entry point and part of the [Exchange](/products/open-agri-stack/architecture/exchange.md). It runs in the Exchange namespace (`agrix`), next to the Exchange CM it asks for consent tokens. {% hint style="info" %} **Source code:** [agri-stack/composite](https://github.com/openg2p/agri-stack/tree/develop/composite): the service ([`backend/`](https://github.com/openg2p/agri-stack/tree/develop/composite/backend)), the chart ([`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)), use cases ([`use-cases/`](https://github.com/openg2p/agri-stack/tree/develop/composite/use-cases)) and console ([`ui/`](https://github.com/openg2p/agri-stack/tree/develop/composite/ui)). {% endhint %} ## What to install | # | What | Release | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | 1 | The [Exchange](/products/open-agri-stack/deployment/exchange.md) commons, ready | — | | 2 | **Agri Stack Composite** (`openg2p-agri-composite`, image `openg2p/openg2p-agri-composite-api`) from **Apps → Charts**, in `agrix` | e.g. `agri-composite` | | 3 | The [Exchange setup](/products/open-agri-stack/deployment/after-install.md#exchange-setup): creates the signing key Secret and restarts the Composite | — | The Composite starts without its signing key Secret: describing use cases works, and every query fails with `signing_unavailable` until the Exchange setup has run. ## Form fields to choose The defaults work for a demo. Only the registries' search URLs have no default and are required: | Field | Value | Why | | ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- | | Farmer Registry Search URL | `https://partner-fr.trial.openg2p.org/dci/registry/sync/search` | The Farmer Registry's partner API, in its department | | Crop Sown Registry Search URL | `https://partner-csr.dept1.openg2p.org/dci/registry/sync/search` | The Crop Sown Registry's partner API, in its department | Use the departments' public hostnames, never in-cluster service names: each department is reached as a separate organisation would be. ## For production Every hostname is `.`. Set **Base Domain** (`global.baseDomain`) to the same value as the commons install; it defaults to ``. | Field | Value | Why | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Image Tag, Console UI Image Tag | A released version | `develop` images move | | Composite Hostname | `agri-composite.` | Partners call it; the partner portal finds the use cases there | | Allowed Browser Origins (CORS) | `https://` | The partner portal reads the use-case list from the browser | | Console Hostname, IAM Staff API URL (public), Cookie Domain | Under the Exchange domain | The console's login | | Partner Management Portal URL, Consent Manager Portal URL | Under the Exchange domain | Links shown in the console | | Enable Autoscaling, Min/Max Replicas | On, sized to the load | [Scaling](#scaling-and-rate-limits) | | Signing key | Generated by the Exchange setup, or your own `.p12` onboarded in the Exchange PM first | [Signing key](#signing-key) | | Partners' use-case policies | In the Exchange PM, for the real partners only | Who may call a use case is set there, not in the chart. Revoke test partners' use-case policies (e.g. `bank-a` from the [partner test](/products/open-agri-stack/deployment/testing.md#partner-test-public-apis)) | ## All options Every option of the chart, by group. The Rancher form shows the groups below; options marked "values only" are set in **Edit YAML**. ### Hostnames and ingress | Value | Default | Form | | ----------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------- | | `global.baseDomain` | `.openg2p.org` | General: Base Domain | | `global.compositeHostname` | `agri-composite.` | General: Composite Hostname | | `global.consoleHostname` | `agri-composite-console.` | Console: Console Hostname | | `global.namespace` | Empty: the install namespace | Values only; the `` 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). ### 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 ([how departments trust the Exchange](/products/open-agri-stack/architecture/exchange.md#how-departments-trust-it)). 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](/products/open-agri-stack/exchange/composite.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..partnerId` | Empty | Values only. The registry's PM partner ID: when set, the registry's response signature is verified against `PARTNER_` in the Exchange PM | | `composite.registries..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 every PM | | `global.partnerManagementApiUrl` | `http://commons-services-pm-partner-api` | Integration: Partner Management URL. Partner keys and use-case policies, fetched as `PARTNER_` | 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 data source](/products/open-agri-stack/exchange/composite/adding-a-data-source.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 `-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 `.yaml` (and any `.j2` template files). **Adding a use case.** In **Edit YAML**, add an entry under `composite.useCases` (or a key to your own ConfigMap), written in the [use-case file format](/products/open-agri-stack/exchange/composite/use-case-configuration.md). Then rerun the [Exchange setup](/products/open-agri-stack/deployment/after-install.md#exchange-setup) if it reads new data scopes or has a new purpose, so each department's scope policy for the Composite covers it. A partner calls it only when its use-case policy in the Exchange PM grants it (`name@major`, e.g. `loan-profile@1`): raise and approve a policy request there ([access policies](/platform/platform-services/partner-management/functional-specifications.md#access-policies)). **The shipped use case**, `loan-profile` (version `1.0.0`, purpose `credit-assessment`): | | | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Input** | A farmer by `FAYDA_FAN` or `FARMER_ID`; optional `crop_year` and `season` | | **Sources** | `farmer` (Farmer Registry, mandatory); then `season_summaries` and `crop_seasons` (Crop Sown Registry, optional, both depending on `farmer`) | | **Returns** | The farmer's identity and location, land parcels and total land, declared main crops, crop seasons, season summaries and total area sown | | **Who may call it** | Partners with a policy for `loan-profile@1` in the Exchange PM; the [partner test](/products/open-agri-stack/deployment/testing.md#partner-test-public-apis) grants it to `bank-a` | | **Rate limit** | 60 per minute per partner | The scopes it needs from each registry: [Farmer Registry](/products/open-agri-stack/architecture/registries.md#farmer-data-the-composite-reads), [Crop Sown Registry](/products/open-agri-stack/architecture/registries.md#crop-data-the-composite-reads). The file, setting by setting: [the `loan-profile` use case](/products/open-agri-stack/exchange/composite/use-case-configuration.md#the-loan-profile-use-case). ### Signing key | Value | Default | Form | | ---------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------- | | `composite.signingKey.secretName` | `agri-composite-signing` | Signing key: Signing Key Secret | | `composite.signingKey.p12Key`, `passwordKey`, `kidKey`, `algorithmKey` | `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. The [Exchange setup](/products/open-agri-stack/deployment/after-install.md#exchange-setup) generates it, creates the Secret and registers the key in each PM. To bring your own key instead, first onboard it in the Exchange PM as `PARTNER_AGRI_COMPOSITE` with its `kid`, then create the Secret. The Exchange setup keeps a Secret whose key the Exchange PM already serves and adds that key to each department PM; a Secret whose key the Exchange PM does not serve is replaced with a generated key. ```bash kubectl -n agrix create secret generic agri-composite-signing \ --from-file=composite.p12=./composite.p12 --from-literal=password='' \ --from-literal=kid=agri-composite-2026-01 --from-literal=algorithm=auto ``` `kid` must match the kid registered for the Composite in PM (blank: the certificate's SHA-256 thumbprint). `algorithm: auto` takes it from the key type (EC → ES256, Ed25519 → EdDSA, RSA → RS256). ### Console On by default: the read-only staff [console](/products/open-agri-stack/exchange/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.` | 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` | `.` | 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.`, `https://consent-manager.` | 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` | `https://consent-partner-portal.` | Agri Stack exchange: Allowed Browser Origins (CORS) | Browser origins allowed to call the Composite, comma-separated; empty for none. The default is the Exchange CM's partner portal, which reads the published use cases. 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. * **Rate limits** are set per use case (`limits.rate_per_partner`, e.g. `60/min`) and counted per pod and worker: with N pods and W workers, a partner can make up to N × W times the configured rate. Limits across pods and daily quotas are not built. * The image runs as uid 1001 with a read-only root filesystem. Startup never calls a registry; a registry being down only affects requests. ### 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) | | ## Check ```bash helm -n agrix list curl -s https://agri-composite.agrix.openg2p.org/composite/v1/use-cases ``` The release `deployed` (the sanity hook passed) and `loan-profile` listed. Queries work once the [Exchange setup](/products/open-agri-stack/deployment/after-install.md#exchange-setup) has run; then follow [Testing](/products/open-agri-stack/deployment/testing.md). --- # 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/composite.md?ask=&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.