> 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/g2p-bridge/deployment/helm-charts.md). # Helm Chart The entire G2P Bridge subsystem — and everything it depends on — installs from a **single Helm chart**, [`openg2p-bridge`](https://gitlab.com/openg2p/g2p-bridge/g2p-bridge/-/tree/develop/deployment/charts/openg2p-bridge), in the `g2p-bridge` repository. There are no longer separate charts per service or a separate chart for the Example Bank; one `helm install` brings up the complete, working subsystem. {% hint style="info" %} This page describes the chart itself. For the end-to-end install flow (Infrastructure → Environment → G2P Bridge), follow the [Deployment](/products/g2p-bridge/deployment.md) guide — it assumes the Kubernetes infrastructure and the **commons** environment are already set up. The commons release provides the shared **PostgreSQL** and **Istio** gateway that this chart depends on. Partner signatures are verified against the **Partner Manager (PM)** service (`GET /keys`, no Keycloak at runtime); the trial's `pm-seed` Job onboards the test partners in PM (which does require a `partner_manager` Keycloak client for the onboarding step). {% endhint %} ## Versions For the chart version, runtime image tags, last-modified date and change history (including legacy versions), see the main [Versions](/products/g2p-bridge/versions.md) page. ## Key features * **One chart, complete install.** Partner API, Beneficiary-Portal API, Celery beat producer and Celery workers, Redis, the PostgreSQL database/role and the Keycloak client are all created by this one chart. * **Bundled Example Bank simulator** (toggle with `exampleBank.enabled`) so the end-to-end digital-cash flow can be demonstrated out of the box. * **Digital cash without PBMS or Registry.** For pure digital cash transfer the chart needs neither the PBMS nor the Registry database. The sponsor/treasury account is set in Helm values, and the same values seed the Example Bank. In-kind disbursements (goods/services) — which do need PBMS/Registry — are gated behind a single switch, `global.g2pBridgeInKindEnabled`. * **Keycloak client provisioning** through the `keycloak-init` subchart (creates the `g2p-bridge` OIDC client). See [Keycloak Client](/products/g2p-bridge/deployment/keycloak-client.md). * **Namespace-derived hostnames.** Every ingress hostname is derived from the install namespace by default (e.g. `g2p-bridge..openg2p.org`) — no need to set it. Override `global.namespace` only to use a hostname segment that differs from the Kubernetes namespace. * **Single Celery image** run as either beat producer or worker, selected by the chart at runtime. * **Rancher-ready** — ships a `questions.yaml` so all changeable values are exposed as a form in the Rancher catalog UI. ## What the chart contains ### Workloads deployed Images are published to the project's **GitLab Container Registry**, `registry.gitlab.com/openg2p/g2p-bridge/g2p-bridge/` (the `` shown below). These moved from Docker Hub (`openg2p/openg2p-bridge-*`) with the GitLab migration; the exact tags per version are on the [Releases](https://gitlab.com/openg2p/g2p-bridge/g2p-bridge/-/releases) page. | Component | Image `` | Notes | | ------------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Partner API | `partner-api` | REST API consumed by upstream systems (e.g. PBMS) to hand over disbursement instructions. | | Bene-Portal API | `bene-portal-api` | REST API for the OpenG2P Beneficiary Portal. | | Celery Beat Producer | `celery` | Single replica. Schedules periodic tasks. | | Celery Workers | `celery` | Same image as beat; scale horizontally for volume. | | Example Bank API | `example-bank-api` | Bundled simulator (only if `exampleBank.enabled`). | | Example Bank Celery (beat + workers) | `example-bank-celery-beat-producers`, `example-bank-celery-workers` | Bundled simulator background tasks. | ### Dependency subcharts | Subchart | Purpose | Condition | | --------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------- | | `common` | OpenG2P common Helm library (naming, images, istio helpers). | always | | `postgres-init` | Creates the Bridge database + role (and the Example Bank DB when enabled) inside the shared `commons-postgresql`. | `postgres-init.enabled` | | `redis` | Broker/result backend for Celery. | `redis.enabled` | | `keycloak-init` | Creates the `g2p-bridge` OIDC client and stores its secret. | `keycloak-init.enabled` | {% hint style="info" %} **Database naming follows the NSR convention.** The Bridge database and role are derived from the Helm **release name** (dashes become underscores) — e.g. a release named `g2p-bridge` gets the database `g2p_bridge` and role `g2p_bridge_user`. The Bridge does **not** create its own PostgreSQL instance; it uses the shared `commons-postgresql` in the namespace. {% endhint %} {% hint style="info" %} **DB migration & password-sync (self-healing).** The API images run `migrate &&` serve — a **fail-loud** startup: if the schema migration fails the pod crash-loops (and the install is marked failed) rather than silently serving an un-migrated DB. Because `commons-postgresql` is persistent, a role's password can drift from its regenerated Secret across reinstalls; a **pre-upgrade `db-password-sync` hook** (`dbPasswordSync.enabled`, default `true`) re-syncs the Bridge (and Example Bank) DB role passwords to their Secrets before the apps start, so migrations always authenticate. So a pod stuck in `CrashLoopBackOff` on install usually means a DB problem, not an infra one. {% endhint %} ## Key parameters to change All changeable values are surfaced in `questions.yaml` (the Rancher form) and documented in `values.yaml`. The most important ones: ### General | Value | Default | Description | | --------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `global.namespace` | *(install namespace)* | Hostname segment for all ingress hosts. Empty = auto-derived from the release namespace; set only to use a different segment. | | `global.g2pBridgeHostname` | `g2p-bridge..openg2p.org` | Partner API hostname. | | `global.benePortalHostname` | `g2p-bridge-bene-portal..openg2p.org` | Beneficiary Portal API hostname. | ### Disbursement mode (digital cash vs in-kind) | Value | Default | Description | | ------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `global.g2pBridgeInKindEnabled` | `false` | `false` = pure digital cash (no PBMS/Registry needed). `true` enables geo targeting, warehouse & agency allocation and requires the PBMS and Registry databases. | | `global.sponsorBankConfigurations.default` | (see below) | Sponsor/treasury account used for digital cash. Single source of truth — also used to seed the Example Bank. | | `global.seedTreasuryAccount` | `true` | Seed the treasury account into the bundled Example Bank (it has no account-creation API). | The `sponsorBankConfigurations.default` block: ```yaml global: sponsorBankConfigurations: default: sponsor_bank_code: EXAMPLE program_account_number: "SPONSOR0001" program_account_branch_code: "" account_currency: USD available_balance: "10000000" # opening balance seeded into Example Bank account_holder_name: Program Treasury ``` See [Example Bank & Treasury Account](/products/g2p-bridge/deployment/deployment-of-example-bank.md) for how this single block drives both the Bridge and the Example Bank. ### Example Bank | Value | Default | Description | | ---------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- | | `exampleBank.enabled` | `true` | Deploy the bundled simulator. **Disable for production** (you connect a real sponsor bank instead). | | `global.exampleBankHostname` | `example-bank..openg2p.org` | Example Bank API hostname. | ### Partner signatures (signing key) | Value | Default | Description | | -------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `global.g2pBridgeCryptoBackend` | `partner-mgmt` | Crypto backend. `partner-mgmt` = verify inbound signatures against keys fetched from the Partner Manager (PM) service. (`local` is a legacy option.) | | `global.partnerManagementApiUrl` | `http://commons-services-pm-partner-api` | PM key-fetch base URL (unauthenticated) the Bridge verifies against. | | `global.g2pBridgeSignatureValidationEnabled` | `true` | Verify partner signatures on the Partner API (inbound). | | `global.g2pBridgeCryptoAllowedAlgorithms` | `RS256` | Allowed JWS signature algorithms (verification allow-list). RS256 only by default; `none` and HMAC (`HS*`) are always rejected. PM can store `ES256`/`EdDSA` keys, but the Bridge accepts a signature only if its `alg` is in this list. | | `global.g2pBridgeSparSignRequestsEnabled` | `true` | Sign the Bridge's resolve requests to SPAR (outbound, uses the `.p12`). | | `global.g2pBridgeSigningAlgorithm` | `RS256` | Algorithm the Bridge signs its outbound SPAR requests with (must be one SPAR accepts). | | `global.g2pBridgeSigningKey.mode` | `demo` | Where the outbound `.p12` comes from: `demo` / `inline` / `existing`. | | `global.testPartnerEnabled` | `true` | Trial: run the `pm-seed` Job to onboard the test partners (incl. `PARTNER_G2P_BRIDGE`) in PM. Set `false` for production. | The bundled `demo` signing key is **public/test-only** — supply your own for production and onboard partner certs. See [Partner Signing Key](/products/g2p-bridge/deployment/partner-signing-key.md) (generating a `.p12`, feeding it via Rancher, demo → production) and [Onboarding Partners](/products/g2p-bridge/deployment/onboarding-partners.md) (trusting partners that call the Bridge, and registering the Bridge with SPAR). For **how** the Bridge registers its own key and verifies partner signatures against Partner Manager — with sequence diagrams — see [Partner APIs → Integration with Partner Manager (PM)](/products/g2p-bridge/design-specifications/partner-apis.md#integration-with-partner-manager-pm). ### Databases (in-kind only) `global.PBMSDB*` and `global.registryDB*` point at the PBMS and Registry databases. They are only consulted when `g2pBridgeInKindEnabled: true`, and the corresponding questions are hidden in the Rancher form otherwise. ## How it is run The recommended path is the **automated, Rancher-driven** flow described in the [Deployment](/products/g2p-bridge/deployment.md) guide (Infrastructure → Environment → install the "OpenG2P Bridge" chart from the Rancher UI). The form is generated from this chart's `questions.yaml`, so all changeable values above appear as fields. The command-line install below is intended for **advanced / developer** use. ### Using the CLI ```bash # 1. Clone the consolidated repo git clone https://gitlab.com/openg2p/g2p-bridge/g2p-bridge.git cd g2p-bridge/deployment/charts/openg2p-bridge # 2. Build chart dependencies (common, postgres-init, redis, keycloak-init) helm dependency build # 3. Install (release name 'g2p-bridge' -> DB 'g2p_bridge', role 'g2p_bridge_user') helm install g2p-bridge . -n # Hostnames auto-derive from . Add --set global.namespace= # only if the hostname segment must differ from the namespace. # Override more values with your own file: helm install g2p-bridge . -n -f my-values.yaml ``` Upgrade after changing values (a values/route-only change needs no pod restart): ```bash helm upgrade g2p-bridge . -n -f my-values.yaml ``` Check status: ```bash helm status g2p-bridge -n kubectl get pods,svc -n ``` ### Access links With `global.namespace=trial` and default hostnames: * Partner API — `https://g2p-bridge.trial.openg2p.org/api/g2p-bridge` (Swagger at `/api/g2p-bridge/docs`, health at `/api/g2p-bridge/ping`) * Bene-Portal API — `https://g2p-bridge-bene-portal.trial.openg2p.org/api/bene-portal` * Example Bank API — `https://example-bank.trial.openg2p.org/api/example-bank` (Swagger at `/api/example-bank/docs`) {% hint style="warning" %} The bare API base path (e.g. `/api/g2p-bridge/`) returns a 404 — there is no route there by design. Use `/docs`, `/ping`, or a specific endpoint such as `/create_disbursement_envelopes`. {% endhint %} ### Post-install: load the dashboards (optional) The chart can provision a read-only Postgres role for the platform Superset — `supersetReadOnly.enabled` creates the `superset_ro` role and a `-superset-ro` Secret. Loading the bundled monitoring dashboards (downloading the bundle, importing, the read-only password, re-import and teardown) is a manual admin step documented in one place: [Dashboards (Superset)](/products/g2p-bridge/deployment/dashboards.md). ## Teardown To completely remove a release — including the PostgreSQL database/role that `helm uninstall` leaves behind — use the bundled uninstall script. See [Teardown / Uninstall](/products/g2p-bridge/deployment/teardown.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 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://docs.openg2p.org/products/g2p-bridge/deployment/helm-charts.md?ask=&goal= ``` `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.