diff --git a/.github/workflows/docker_release.yml b/.github/workflows/docker_release.yml
index 02a8440a88..19ed13cccb 100644
--- a/.github/workflows/docker_release.yml
+++ b/.github/workflows/docker_release.yml
@@ -10,6 +10,12 @@ jobs:
steps:
- uses: actions/checkout@v2
+ - name: Filter Helm Releases
+ run: |
+ echo "Detected that GitHub release is for the Helm chart... aborting this build as a result."
+ exit 1
+ if: startsWith(github.ref, 'refs/tags/helm-v')
+
- name: Build
run: |
docker build \
@@ -31,4 +37,4 @@ jobs:
if: github.event.action == 'released'
run: |
echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u $GITHUB_ACTOR --password-stdin
- docker push ghcr.io/hyperledger/firefly:latest
\ No newline at end of file
+ docker push ghcr.io/hyperledger/firefly:latest
diff --git a/.github/workflows/helm.yml b/.github/workflows/helm.yml
index 9679d4bf14..8b256a6543 100644
--- a/.github/workflows/helm.yml
+++ b/.github/workflows/helm.yml
@@ -1,13 +1,22 @@
name: Helm
on:
+ push:
+ tags:
+ - "helm-v*"
+ branches:
+ - main
+ paths:
+ - "deploy/charts/**/*"
+ - ".github/workflows/helm.yml"
pull_request:
branches:
- main
paths:
- "deploy/charts/**/*"
+ - ".github/workflows/helm.yml"
jobs:
- helm:
+ test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
@@ -15,7 +24,7 @@ jobs:
- name: setup helm
uses: azure/setup-helm@v1
with:
- version: 3.6.0
+ version: 3.7.2
- name: setup chart-testing tool
uses: helm/chart-testing-action@v2.0.1
@@ -53,3 +62,44 @@ jobs:
if: ${{ failure() }}
run: |
kubectl get pod -A
+ release:
+ needs: test
+ if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/helm-v') || github.ref == 'refs/heads/main')
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+
+ - name: chart-version
+ run: |
+ CHART_VERSION=$(helm show chart deploy/charts/firefly | grep '^version:' | awk '{ printf("%s", $2) }')
+ echo "CHART_VERSION=${CHART_VERSION}" >> $GITHUB_ENV
+
+ - name: head-version
+ if: github.ref == 'refs/heads/main'
+ run: |
+ BUILD_TAG=${{ env.CHART_VERSION }}-$(date +"%Y%m%d")-$GITHUB_RUN_NUMBER
+ echo "PUBLISH_VERSION=${BUILD_TAG}" >> $GITHUB_ENV
+
+ - name: release-version
+ if: startsWith(github.ref, 'refs/tags/helm-v')
+ run: |
+ TAG_VERSION=$(echo -n "${GITHUB_REF##*/}" | sed 's/helm-v//g')
+ if [[ "$TAG_VERSION" != "${{ env.CHART_VERSION }}" ]]; then
+ echo "Release tag version [$TAG_VERSION] does not match the chart's version [${{ env.CHART_VERSION }}]"
+ exit 1
+ fi
+ echo "PUBLISH_VERSION=${{ env.CHART_VERSION }}" >> $GITHUB_ENV
+
+ - name: setup helm
+ uses: azure/setup-helm@v1
+ with:
+ version: 3.7.2
+
+ - name: helm publish
+ run: |
+ echo ${{ secrets.GITHUB_TOKEN }} | helm registry login ghcr.io -u $GITHUB_ACTOR --password-stdin
+
+ helm package --version ${{ env.PUBLISH_VERSION }} ./deploy/charts/firefly
+ helm push firefly-${{ env.PUBLISH_VERSION }}.tgz oci://ghcr.io/hyperledger/helm
+ env:
+ HELM_EXPERIMENTAL_OCI: "1"
diff --git a/deploy/charts/firefly/Chart.yaml b/deploy/charts/firefly/Chart.yaml
index 825fb24099..e77c2ec974 100644
--- a/deploy/charts/firefly/Chart.yaml
+++ b/deploy/charts/firefly/Chart.yaml
@@ -2,8 +2,8 @@ apiVersion: v2
name: firefly
description: A Helm chart for deploying FireFly and FireFly HTTPS Dataexchange onto Kubernetes.
type: application
-appVersion: "0.11.2"
-version: "0.1.0"
+appVersion: "0.11.4"
+version: "0.0.1"
maintainers:
- name: hfuss
diff --git a/deploy/charts/firefly/README.md b/deploy/charts/firefly/README.md
index 6931c1b082..14e8285de8 100644
--- a/deploy/charts/firefly/README.md
+++ b/deploy/charts/firefly/README.md
@@ -1,27 +1,529 @@
# FireFly
-A bare-bones Helm chart for installing a [FireFly](https://github.com/hyperledger/firefly) node with robust templating of its configuration
-for development and production scenarios. Additionally, includes FireFly's [default DataExchange](https://github.com/hyperledger/firefly-dataexchange-https) component
-for simple, private messaging using HTTPS backed with mTLS.
+[Hyperledger FireFly](https://hyperledger.github.io/firefly/) is an implementation of a [multi-party system](https://github.com/hyperledger/firefly#multi-party-systems)
+that simplifies data orchestration on top of blockchain and other peer-to-peer technologies.
+
+This chart bootstraps a FireFly deployment on a [Kubernetes](https://kubernetes.io/) cluster using the [Helm](https://helm.sh/)
+package manager. It can be used to deploy a FireFly node for a single organization within a multi-party system.
+
+### Table of Contents
+
+* [Prerequisites](#prerequisites)
+* [Get Repo Info](#get-repo-info)
+* [Install Chart](#install-chart)
+* [Uninstall Chart](#uninstall-chart)
+* [Upgrading Chart](#upgrading-chart)
+* [Using as a Dependency](#using-as-a-dependency)
+* [Deployment Architecture](#deployment-architecture)
+* [Configuration](#configuration)
+ * [Configuration File Templating](#configuration-file-templating)
+ * [Additional Environment Variables](#additional-environment-variables)
+ * [Ethereum](#ethereum)
+ * [Smart Contract Deployment](#smart-contract-deployment)
+ * [Fabric](#fabric)
+ * [Chaincode](#chaincode)
+ * [Identity Management](#identity-management)
+ * [Ingress Example](#ingress-example)
+ * [Database Migrations](#database-migrations)
+ * [Auto-Registration](#auto-registration)
+ * [DataExchange HTTPS and cert-manager](#dataexchange-https-and-cert-manager)
+ * [Tokens via ERC1155 Connector](#tokens-via-erc1155-connector)
+ * [Prometheus Support](#prometheus-support)
+* [Automated Deployments](#automated-deployments)
+ * [GitOps](#gitops)
+ * [Flux V2](#flux-v2)
+ * [ArgoCD](#argocd)
+ * [Terraform](#terraform)
+
+
## Prerequisites
-* Kubernetes 1.14+
-* Helm 3.6.0
+* Kubernetes 1.18+
+* Helm 3.7+
* PV provisioner support in the underlying infrastructure
* _Recommended:_ cert-manager 1.4+
-## Installing the Chart
+## Get Repo Info
+
+Helm's [experimental OCI registry support](https://helm.sh/docs/topics/registries/) is used for publishing and retrieving
+the FireFly chart, as a result one must log into [GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
+to download the chart:
+
+```shell
+export HELM_EXPERIMENTAL_OCI=1
+
+helm registry login ghcr.io
+```
+
+> **NOTE**: it is recommended to use a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
+> when authenticating to the GHCR registry as opposed to using your GitHub password.
+
+## Install Chart
+
+```shell
+helm install [RELEASE_NAME] --version 0.0.1 oci://ghcr.io/hyperledger/helm/firefly
+```
+
+_See [configuration](#Configuration) below._
+
+_See [helm install](https://helm.sh/docs/helm/helm_install/) for command documentation._
+
+## Uninstall Chart
+
+```shell
+helm uninstall [RELEASE_NAME]
+```
+
+_See [helm uninstall](https://helm.sh/docs/helm/helm_uninstall/) for command documentation._
+
+## Upgrading Chart
+
+```shell
+helm upgrade [RELEASE_NAME] --install --version 0.0.2 oci://ghcr.io/hyperledger/helm/firefly
+```
+
+_See [helm upgrade](https://helm.sh/docs/helm/helm_upgrade/) for command documentation._
+
+## Using as a Dependency
+
+You can also use the FireFly chart within your own parent chart's `Chart.yaml`:
+
+```yaml
+dependencies:
+ # ...
+ - name: firefly
+ repository: "oci://ghcr.io/hyperledger/helm/"
+ version: 0.0.1
+```
+
+Then download the chart dependency into your parent chart:
+
+```shell
+helm dep up path/to/parent-chart
+```
+
+_See [helm dependency](https://helm.sh/docs/helm/helm_dependency/) for command documentation._
+
+
+## Deployment Architecture
+
+FireFly provides a REST API with an event-driven paradigm that makes building multi-party interactions via
+decentralized applications simpler. In order to do so, FireFly leverages extensible [connector plugins](https://hyperledger.github.io/firefly/architecture/plugin_architecture.html) that enable
+swapping out the underlying blockchain and off-chain infrastructure easily.
+
+As a result, a [FireFly node](https://hyperledger.github.io/firefly/architecture/node_component_architecture.html)
+has several infrastructural dependencies:
+
+* Blockchain connector (either Fabconnect -> Fabric, or Ethconnect -> Ethereum) for a [_private_ blockchain](https://hyperledger.github.io/firefly/keyconcepts/blockchain_protocols.html)
+* A Fabric chaincode or Ethereum smart contract deployed to the underlying blockchain
+* [Private data exchange](https://hyperledger.github.io/firefly/keyconcepts/data_exchange.html) (HTTPS + mTLS)
+* Database (PostgreSQL)
+* [Shared storage](https://hyperledger.github.io/firefly/keyconcepts/broadcast.html#shared-data) (IPFS)
+* Optional tokens connector (ERC1155)
+
+
+
+
+
+As depicted above, the chart only aims to provide a means for deploying FireFly core, and then optionally [FireFly Ethconnect](ttps://github.com/hyperledger/firefly-ethconnect), [FireFly Fabconnect](ttps://github.com/hyperledger/firefly-fabconnect),
+[FireFly DataExchange HTTPS](https://github.com/hyperledger/firefly-dataexchange-https) and the [FireFly Tokens ERC1155](https://github.com/hyperledger/firefly-tokens-erc1155) microservices.
+
+> **NOTE**: support for deploying Ethconnect, Fabconnect, and Tokens ERC1155 is under development and will be included
+> as part of the chart for its `0.1.0` release.
+
+All other infrastructural dependencies such as the blockchain, PostgreSQL, and IPFS are considered out of scope for the chart,
+and must be pre-provisioned in order for FireFly to be fully functioning.
+
+## Configuration
+
+The following describes how to use the chart's values to configure various aspects of the FireFly deployment.
+
+### Configuration File Templating
+
+FireFly itself has a robust YAML configuration file (usually named `firefly.core`) powered by [Viper](https://github.com/spf13/viper)
+that allows one to define all the necessary configuration for the FireFly server, and the underlying
+connectors it will use.
+
+The chart provides a top-level `config` value which then contains sub-values such as `postgresUrl`, `ipfsApiUrl`,
+`organizationName`, `adminEnabled`, etc. These sub-values are meant to provide an opinionated, safe way of templating
+the `firefly.core` file. Based on which values are set, it will correctly configure the various connector plugins as well
+as determine if additional ports will be exposed such as the admin, debug, and metrics ports.
+
+The following values are required in order for FireFly to startup correctly:
+* `config.organizationName`
+* `config.organizationKey`
+* `config.postgresUrl`
+* `config.ipfsApiUrl` and `config.ipfsGatewayUrl`
+* either:
+ * `config.ethconnectUrl` and `config.fireflyContractAddress`
+ * or, `config.fabconnectUrl` and `config.fabconnectSigner`
+
+You can find documentation regarding each of these values, as well as all the other `config` values,
+in the comments of the default [`values.yaml`](values.yaml). You can see how the values are used for
+templating the `firefly.core` file by looking at the `firefly.coreConfig` helper function in [`_helpers.tpl`](templates/_helpers.tpl).
+
+> **NOTE**: although `config.dataexchangeUrl` is available, by default `dataexchange.enabled` is `true` which will
+> deploy a DataExchange HTTPS and automatically configure FireFly to use it.
+
+If you would rather customize the templating of the `firefly.core` with your own values, you can use `config.templateOverride`:
+
+```yaml
+config:
+ templateOverride: |
+ org:
+ name: {{ .Values.global.myOrgNameValue }}
+ # etc. ...
+```
+
+See [`config.go`](../../../internal/config/config.go) for all available FireFly configuration options.
+
+### Additional Environment Variables
+
+If there are configurations you want to set via your own `ConfigMaps` or `Secrets`, it is recommended to do so
+via environment variables which can be provided with the `core.extraEnv` list value. FireFly will automatically override
+its config via environment variables prefixed with `FIREFLY_`. For example, if you want to set to the config value
+`log.level` you would set the env var `FIREFLY_LOG_LEVEL`.
+
+For a more detailed example using `core.extraEnv`, one could provide basic auth credentials for IPFS from a `Secret`
+like so:
+
+```yaml
+core:
+ extraEnv:
+ - name: FIREFLY_PUBLICSTORAGE_IPFS_API_AUTH_USERNAME
+ valueFrom:
+ secretKeyRef:
+ name: my-ipfs-basic-auth
+ key: username
+ - name: FIREFLY_PUBLICSTORAGE_IPFS_API_AUTH_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: my-ipfs-basic-auth
+ key: password
+```
+
+### Ethereum
+
+Configuring FireFly to use an [Ethereum](https://ethereum.org/en/) blockchain such as [Geth](https://geth.ethereum.org/),
+[Quorum](https://github.com/ConsenSys/quorum), or [Hyperledger Besu](https://www.hyperledger.org/use/besu) requires first
+having an instance of [FireFly Ethconnect](https://github.com/hyperledger/firefly-ethconnect) deployed and connected to
+the JSONRPC port of an Ethereum node in the underlying network.
+
+As was noted in [Deployment Architecture](#deployment-architecture), the chart will include support for deploying Ethconnect
+as part of its `0.1.0` release. See [#272](https://github.com/hyperledger/firefly/issues/272) to track its progress. For now,
+you can either deploy Ethconnect yourself or use a cloud provider like [Kaleido](https://www.kaleido.io) which provides
+Ethconnect alongside its Ethereum nodes.
+
+Once you have an Ethconnect instance ready, FireFly then needs three pieces of configuration:
+
+* `config.organizationKey`: the Ethereum address of the organization's wallet / key which will be used for signing transactions
+* `config.ethconnectUrl`: the HTTP/S URL of the Ethconnect instance FireFly will use
+* `config.fireflyContractAddress`: the Ethconnect URI representing the deployed FireFly smart contract i.e.
+ `/instances/0x965b92929108df1c77c156ba73d00ca851dcd2e1`. See [Smart Contract Deployment](#smart-contract-deployment)
+ for how to you can deploy the contract yourself.
+
+These will enable the FireFly deployment to connect to the Ethereum blockchain and submit batch pin transactions via
+its smart contract on behalf of the organization it's representing.
+
+#### Smart Contract Deployment
+
+Currently, the chart offers no way for one to manage the [FireFly smart contract](../../../smart_contracts/ethereum/solidity_firefly/contracts/Firefly.sol).
+Instead, the chart assumes it is already pre-provisioned via Ethconnect by one of the organizations.
+
+If you have the contract available as gateway contract on Ethconnect, you can then deploy it via the API:
```shell
-# Deploy a FireFly node w/ some dummy values
-$ helm install acme-firefly ./deploy/charts/firefly \
- --set dataexchange.tlsSecret.name=acme-dx-tls \
- --set config.organizationName=acme \
- --set config.organizationKey="0xeb7284ce905e0665b7d42cabe31c76c45da1d331" \
- --set config.fireflyContractAddress="0xeb7284ce905e0665b7d42cabe31c76c45da1d254"
+curl -v \
+ -X POST \
+ -H 'Content-Type: application/json' \
+ -d '{}' \
+ "${ETHCONNECT_URL/gateways/${FF_CONTRACT_GATEWAY}?ff-from=${ORG_WALLET_ADDRESS}&ff-sync=true"
```
-> **Note**: FireFly requires additional configuration for its blockchain, database, and publicstorage plugins in order to be fully functional. See [it-values.yaml](ci/it-values.yaml) for an example.
+The JSON returned by the API will have the Ethereum address of the smart contract in the `address` field.
+
+> **NOTE**: the FireFly smart contract only needs to be deployed by one organization within the blockchain
+> network. All organizations within a FireFly network must use the same smart contract instance in order for
+> transactions to work properly.
+
+If the contract is not available as a gateway contract on your Ethconnect instance, see the
+Ethconnect docs for [deploying a contract](https://github.com/hyperledger/firefly-ethconnect#yaml-to-deploy-a-contract).
+
+### Fabric
+
+Configuring FireFly to use a [Hyperledger Fabric](https://www.hyperledger.org/use/fabric) blockchain requires first
+having an instance of [FireFly Fabconnect](https://github.com/hyperledger/firefly-fabconnect) deployed and connected to
+the gRPC port of a Fabric peer in the underlying network.
+
+As was noted in [Deployment Architecture](#deployment-architecture), the chart will include support for deploying Fabconnect
+as part of its `0.1.0` release. See [#272](https://github.com/hyperledger/firefly/issues/272) to track its progress. For now,
+you can either deploy Fabconnect yourself or use a cloud provider like [Kaleido](https://www.kaleido.io) which provides
+Fabconnect alongside its Fabric peer nodes.
+
+Once you have a Fabconnect instance ready, FireFly then needs three pieces of configuration:
+
+* `config.organizationKey`: the name of the organization's Fabric identity which will be used for signing transactions
+* `config.fabconnectUrl`: the HTTP/S URL of the Fabconnect instance FireFly will use
+* `config.fabconnectSigner`: the name of the organization's Fabric identity which will be used for signing transactions.
+ See [Identity Management](#identity-management) for how to you can create and enroll the identity using Fabconnect.
+
+These will enable the FireFly deployment to connect to the Fabric blockchain and submit batch pin transactions via
+its chaincode on behalf of the organization it's representing.
+
+#### Chaincode
+
+By default, the chart assumes the [FireFly chaincode](../../../smart_contracts/fabric/firefly-go/) is deployed to the
+`default-channel` with the name `firefly_go`. If the chaincode was deployed to a different channel or with a different
+name you can set `config.fabconnectChannel` and `config.fireflyChaincode` accordingly.
+
+For deploying the chaincode yourself, consult the [Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/latest/deploy_chaincode.html).
+
+#### Identity Management
+
+The Fabric identity FireFly will use for signing transactions on behalf of the organization must be pre-enrolled with
+the Fabric CA before deploying FireFly and registration its organization. Fabconnect provides an `/identities` REST API
+which makes creating an identity and enrolling it easy. For example, the following Bash script performs the necessary
+API calls to create and enroll an identity named `${ORG_NAME}`:
+
+```shell
+identityRegistrationResponse=$(curl --fail -s \
+ -X POST \
+ -H 'Content-Type: application/json' \
+ -d "{ \"name\": \"${ORG_NAME}\", \"type\": \"client\" }" \
+ "${FABCONNECT_URL}/identities")
+
+enrollmentSecret=$(echo -n $identityRegistrationResponse | jq -r .secret)
+curl --fail -s \
+ -X POST \
+ -H 'Content-Type: application/json' \
+ -d "{ \"secret\": \"${enrollmentSecret}\" }" \
+ "${FABCONNECT_URL}/identities/${ORG_NAME}/enroll" | jq -r
+```
+
+You can use Bash or whatever scripting / programming language you prefer to enroll the identity. If you wish to enroll
+the identity without having to first deploying Fabconnect, please consult the [Fabric CA documentation](https://hyperledger-fabric-ca.readthedocs.io/en/latest/deployguide/use_CA.html).
+
+### Ingress Example
+
+If you have an [`Ingress` controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) deployed
+to your cluster, and the chart supports deploying an [`Ingress`](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+for the FireFly REST API and websocket subscriptions. For example, if you are using the [`ingress-nginx` controller](https://kubernetes.github.io/ingress-nginx/)
+alongside [`cert-manager`](https://cert-manager.io/) you can secure FireFly with TLS and the necessary settings:
+
+```yaml
+core:
+ ingress:
+ enabled: true
+ className: nginx # assuming you are using the default ingressClassName for nginx-ingress
+ annotations:
+ # recommended for handling blob data transfers and broadcasts
+ nginx.ingress.kubernetes.io/proxy-body-size: 128m
+ # example cert-manager ClusterIssuer for Let's Encrypt
+ cert-manager.io/cluster-issuer: letsencrypt-prod
+ hosts:
+ - host: firefly.acme.org
+ tls:
+ - secretName: firefly-tls
+ hosts:
+ - firefly.acme.org
+```
+
+### Database Migrations
+
+The database schema FireFly uses for its state must be configured via [migrations](https://www.prisma.io/dataguide/types/relational/what-are-database-migrations).
+The chart offers the ability to automatically apply the migrations matching the version of FireFly in use via a `Job`:
+
+```yaml
+core:
+ jobs:
+ postgresMigrations:
+ enabled: true
+```
+
+The `Job` will be named with the FireFly version in use, and will be automatically replaced and re-run whenever the
+version is updated indicating the expected schema could have potentially changed.
+
+Additionally, FireFly itself can apply its own schema migrations. However, this is not recommended for production use
+where an organization could have multiple FireFly nodes sharing the same database:
+
+```yaml
+config:
+ postgresAutomigrate: true
+```
+
+It is recommended to use the migrations `Job` from above in favor of the automatic migrations.
+
+### Auto-Registration
+
+FireFly requires that the organizations within the multi-party system, as well as the individual FireFly
+nodes be [registered](https://hyperledger.github.io/firefly/keyconcepts/broadcast.html#firefly-built-in-broadcasts) with
+the rest of the network. This can be accomplished using the [FireFly REST API](https://hyperledger.github.io/firefly/swagger/swagger.html#/default/postNewOrganizationSelf),
+however the chart offers a registration `Job` which will ensure the organization is registered before then
+registering the node:
+
+```yaml
+core:
+ jobs:
+ registration:
+ enabled: true
+```
+
+### DataExchange HTTPS and cert-manager
+
+The DataExchange HTTPS uses mTLS to securely send messages to other peers. By default, the
+chart assumes an mTLS certificate with the proper `subject` and `commonName` is provided
+via `dataexchange.tlsSecret.name`.
+
+However, the chart offers the ability to automatically provision and wire up the DataExchange
+with an mTLS certificate using [cert-manager](https://cert-manager.io/):
+
+```yaml
+dataexchange:
+ tlsSecret:
+ enabled: false
+
+ certificate:
+ enabled: true
+ issuerRef:
+ name: selfsigned-ca
+ kind: ClusterIssuer
+```
+
+> **NOTE**: the certificate cannot be signed by a self-signed or public CA issuer because cert-manager will not set the
+> `subject` and `commonName` properly (see https://github.com/jetstack/cert-manager/issues/3651). We recommend using
+> an internal CA issuer instead. An example setup of a CA issuer signed by a self-signed issuer can be found [here](../../manifests/tls-issuers.yaml).
+
+If your DataExchange HTTPS is communicating via `Ingresses`, you will need to enable TLS passthrough
+in order for mTLS to work. For example, when using [ingress-nginx](https://kubernetes.github.io/ingress-nginx/) an
+annotation can be set on the `Ingress`:
+
+```yaml
+ ingress:
+ enabled: true
+ annotations:
+ nginx.ingress.kubernetes.io/ssl-passthrough: "true"
+ class: nginx
+ hosts:
+ - host: firefly-dx.acme.org
+```
+
+> **NOTE**: the `tls` section of the `Ingress` does not need to be configured since mTLS is required. Instead,
+> it assumes the provided `hosts` must match the `tls[0].hosts` and that the secret is either pre-made or
+> provided by cert-manager.
+
+### Tokens via ERC1155 Connector
+
+Chart support for the [ERC1155 token connector](https://github.com/hyperledger/firefly-tokens-erc1155) is coming soon.
+See [#272](https://github.com/hyperledger/firefly/issues/272) for updates on its progress.
+
+### Prometheus Support
+
+FireFly comes with an [metrics endpoint](https://prometheus.io/docs/instrumenting/exposition_formats/#text-format-example)
+exposed on a separate HTTP server for [Prometheus](https://prometheus.io/) scraping.
+
+By default, the FireFly Prometheus metrics server is enabled. You can turn the server off, or configure its exposed port
+and path using the following values:
+
+```yaml
+config:
+ metricsEnabled: true
+ metricsPath: /metrics
+
+core:
+ service:
+ metricsPort: 5100
+```
+
+Additionally, if you are managing Prometheus via the [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator),
+you can enable a [`ServiceMonitor`](https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/user-guides/getting-started.md#related-resources)
+for FireFly with:
+
+```yaml
+core:
+ metrics:
+ serviceMonitor:
+ enabled: true
+```
+
+## Automated Deployments
+
+Due to Helm's OCI registry support being experimental, below describes how to configure
+common deployment automation tooling for consuming the FireFly chart.
+
+### GitOps
+
+#### Flux V2
+
+[Flux V2](https://fluxcd.io/docs/) is a GitOps controller for Kubernetes which currently [does not support Helm OCI registries](https://github.com/fluxcd/source-controller/issues/124).
+Instead, one can use a [`GitRepository`](https://fluxcd.io/docs/components/source/gitrepositories/) resource pointed at a specific release tag:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+ name: firefly-helm
+spec:
+ interval: 10m
+ url: "https://github.com/hyperledger/firefly"
+ ref:
+ tag: helm-v0.1.0
+ ignore: |
+ /*
+ !/deploy/charts/firefly
+```
+
+then within a [`HelmRelease`](https://fluxcd.io/docs/components/helm/helmreleases/) resource you can refer to the chart via the `GitRepostiory`:
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+ name: firefly
+spec:
+ chart:
+ spec:
+ chart: /deploy/charts/firefly
+ sourceRef:
+ name: firefly-helm
+ kind: GitRepository
+ interval: 1m
+ values: |
+ # ...
+```
+
+#### ArgoCD
+
+[ArgoCD](https://argo-cd.readthedocs.io/en/stable/) is another GitOps controller for Kubernetes which does support OCI
+Helm registries. In order to use the FireFly Helm chart via an ArgoCD [`Application`](https://argo-cd.readthedocs.io/en/stable/user-guide/helm/#declarative),
+you must first add the OCI Helm registry for Hyperledger. For example, you can do so using the [CLI](https://argo-cd.readthedocs.io/en/stable/user-guide/commands/argocd_repo_add/):
+
+```shell
+argocd repo add ghcr.io/hyperledger/helm --type helm --name hyperledger --enable-oci --username ${USERNAME} --password ${PAT}
+```
+
+To declaratively add the registry consult the [documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#repositories).
+
+### Terraform
+
+[Terraform](https://www.terraform.io/) is a CLI tool that enables engineers to "plan" and "apply" infrastructure defined
+as code in the [HCL language](https://github.com/hashicorp/hcl). Terraform offers a [Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs)
+for managing Helm releases and their values declaratively. Terraform [does not currently support OCI registries](https://github.com/hashicorp/terraform-provider-helm/issues/633).
+
+As a result, you can configure Terraform to use the FireFly chart by either:
+
+1. Creating a wrapper parent chart with the FireFly chart dependency pre-downloaded and [vendored](https://medium.com/plain-and-simple/dependency-vendoring-dd765be75655).
+ See [Using as a Dependency](#using-as-a-dependency) for more information.
-More documentation around parameters and configuration details to come soon.
+2. Pre-downloading the FireFly chart directly using:
+ ```shell
+ helm pull --version 0.0.1 oci://ghcr.io/hyperledger/helm/firefly
+ ```
+ then referring to via its filepath location:
+ ```hcl
+ resource "helm_release" "firefly" {
+ name = "firefly"
+ chart = "firefly-0.0.1.tgz"
+ // ...
+ }
+ ```
\ No newline at end of file
diff --git a/deploy/charts/firefly/templates/core/ingress.yaml b/deploy/charts/firefly/templates/core/ingress.yaml
index 75798e332e..b246862185 100644
--- a/deploy/charts/firefly/templates/core/ingress.yaml
+++ b/deploy/charts/firefly/templates/core/ingress.yaml
@@ -8,10 +8,8 @@
{{- end }}
{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
apiVersion: networking.k8s.io/v1
-{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
-apiVersion: networking.k8s.io/v1beta1
{{- else -}}
-apiVersion: extensions/v1beta1
+apiVersion: networking.k8s.io/v1beta1
{{- end }}
kind: Ingress
metadata:
diff --git a/deploy/charts/firefly/templates/core/migration-job.yaml b/deploy/charts/firefly/templates/core/job-migrations.yaml
similarity index 77%
rename from deploy/charts/firefly/templates/core/migration-job.yaml
rename to deploy/charts/firefly/templates/core/job-migrations.yaml
index 860761b7ba..0aea2c36ee 100644
--- a/deploy/charts/firefly/templates/core/migration-job.yaml
+++ b/deploy/charts/firefly/templates/core/job-migrations.yaml
@@ -1,8 +1,8 @@
-{{- if .Values.config.postgresMigrationJob -}}
+{{- if .Values.core.jobs.postgresMigrations.enabled -}}
apiVersion: batch/v1
kind: Job
metadata:
- name: "{{ template "firefly.fullname" . }}-{{ .Values.core.image.tag }}-migrations"
+ name: "{{ template "firefly.fullname" . }}-{{ .Values.core.image.tag | default (printf "v%s" .Chart.AppVersion) }}-migrations"
spec:
backoffLimit: 5
activeDeadlineSeconds: 12000
@@ -10,7 +10,7 @@ spec:
spec:
containers:
- name: migration
- image: "{{ .Values.core.image.repository }}:{{ .Values.core.image.tag | default .Chart.AppVersion }}"
+ image: "{{ .Values.core.image.repository }}:{{ .Values.core.image.tag | default (printf "v%s" .Chart.AppVersion) }}"
command:
- sh
- -ce
diff --git a/deploy/charts/firefly/templates/core/registration-job.yaml b/deploy/charts/firefly/templates/core/job-registration.yaml
similarity index 84%
rename from deploy/charts/firefly/templates/core/registration-job.yaml
rename to deploy/charts/firefly/templates/core/job-registration.yaml
index 51968bb741..f501bdaf80 100644
--- a/deploy/charts/firefly/templates/core/registration-job.yaml
+++ b/deploy/charts/firefly/templates/core/job-registration.yaml
@@ -1,4 +1,4 @@
-{{- if .Values.config.registrationJob -}}
+{{- if .Values.core.jobs.registration.enabled -}}
apiVersion: batch/v1
kind: Job
metadata:
@@ -10,7 +10,7 @@ spec:
spec:
containers:
- name: registration
- image: "{{ .Values.core.image.repository }}:{{ .Values.core.image.tag | default .Chart.AppVersion }}"
+ image: "{{ .Values.core.image.repository }}:{{ .Values.core.image.tag | default (printf "v%s" .Chart.AppVersion) }}"
command:
- sh
- -ce
diff --git a/deploy/charts/firefly/templates/core/secret.yaml b/deploy/charts/firefly/templates/core/secret.yaml
index b3b88843c0..4b3cf3e684 100644
--- a/deploy/charts/firefly/templates/core/secret.yaml
+++ b/deploy/charts/firefly/templates/core/secret.yaml
@@ -5,7 +5,7 @@ metadata:
labels:
{{- include "firefly.coreLabels" . | nindent 4 }}
stringData:
- {{- if and .Values.config.postgresUrl .Values.config.postgresMigrationJob }}
+ {{- if and .Values.config.postgresUrl .Values.core.jobs.postgresMigrations.enabled }}
psql_url: {{ tpl .Values.config.postgresUrl . }}
{{- end }}
firefly.core: |
diff --git a/deploy/charts/firefly/templates/dataexchange/certificate.yaml b/deploy/charts/firefly/templates/dataexchange/certificate.yaml
index 0f71cc7124..1740899c56 100644
--- a/deploy/charts/firefly/templates/dataexchange/certificate.yaml
+++ b/deploy/charts/firefly/templates/dataexchange/certificate.yaml
@@ -12,7 +12,7 @@ metadata:
spec:
# NOTE: issuer should always be an internal / self-signed CA so that the subject is included
# LetsEncrypt will not work w/ DX currently bc those certs cannot have subject, etc. configured.
- # Nor will a self-signed cert due to https://github.com/jetstack/cert-manager/issues/3651 d
+ # Nor will a self-signed cert due to https://github.com/jetstack/cert-manager/issues/3651
issuerRef:
{{- toYaml .Values.dataexchange.certificate.issuerRef | nindent 4 }}
secretName: "{{ include "firefly.fullname" . }}-dx-tls"
diff --git a/deploy/charts/firefly/templates/dataexchange/ingress.yaml b/deploy/charts/firefly/templates/dataexchange/ingress.yaml
index ec53a0c189..3918f08f34 100644
--- a/deploy/charts/firefly/templates/dataexchange/ingress.yaml
+++ b/deploy/charts/firefly/templates/dataexchange/ingress.yaml
@@ -8,10 +8,8 @@
{{- end }}
{{- if semverCompare ">=1.19-0" .Capabilities.KubeVersion.GitVersion -}}
apiVersion: networking.k8s.io/v1
-{{- else if semverCompare ">=1.14-0" .Capabilities.KubeVersion.GitVersion -}}
-apiVersion: networking.k8s.io/v1beta1
{{- else -}}
-apiVersion: extensions/v1beta1
+apiVersion: networking.k8s.io/v1beta1
{{- end }}
kind: Ingress
metadata:
diff --git a/deploy/charts/firefly/values.yaml b/deploy/charts/firefly/values.yaml
index 68f5951a65..4f5fdeaf04 100644
--- a/deploy/charts/firefly/values.yaml
+++ b/deploy/charts/firefly/values.yaml
@@ -34,9 +34,6 @@ config:
# Whether or not to apply schema migrations automatically on startup, not recommended for production
postgresAutomigrate: false
- # Whether to create a migration job to perform migrations each time a new tag is pushed for the FireFly image (supports DB creation)
- postgresMigrationJob: false
-
# The URL of the HTTPS DataExchange for the node to use for the dataexchange plugin i.e. private messaging, only needed if `dataexchange.enabled` is set to false
dataexchangeUrl: ""
@@ -103,10 +100,6 @@ config:
# The Fabric to use for signing transactions, must be pre-registered and enrolled
fabconnectSigner: ""
- # Whether to use a Job to perform auto-registration of the FireFly runtime.
- # Note registration will not be successful until the new node has caught up with the head of the chain.
- registrationJob: false
-
# The following values can be used to override the templating of specific plugin sections, in the case where
# the user wants greater control to template the sections using global values, additional helpers, etc. OR if they
# want to use other plugin types i.e. `fabric` which currently do not exist at the time of writing.
@@ -202,6 +195,16 @@ core:
affinity: {}
+ jobs:
+ # Whether to create a migration job to perform migrations each time a new tag is pushed for the FireFly image (supports DB creation)
+ postgresMigrations:
+ enabled: false
+
+ # Whether to use a Job to perform auto-registration of the FireFly runtime.
+ # Note registration will not be successful until the new node has caught up with the head of the chain.
+ registration:
+ enabled: false
+
# Configures the properties of the StatefulSet, Service, and optionally Ingress used to deploy and expose FireFly HTTPS DataExchange
dataexchange:
diff --git a/docs/keyconcepts/blockchain_protocols.md b/docs/keyconcepts/blockchain_protocols.md
index 9b4bebb679..6fab8ea29c 100644
--- a/docs/keyconcepts/blockchain_protocols.md
+++ b/docs/keyconcepts/blockchain_protocols.md
@@ -85,10 +85,10 @@ There are sub-communities building the blockchain interfaces for each of the "bi
- Repo: [hyperledger/firefly-ethconnect](https://github.com/hyperledger/firefly-ethconnect)
- Hyperledger Fabric
- Status: Under active development
- - Repo: [hyperledger/firefly-fabricconnect](https://github.com/hyperledger/firefly-fabricconnect)
+ - Repo: [hyperledger/firefly-fabconnect](https://github.com/hyperledger/firefly-fabconnect)
- Corda
- Status: Core transactions+events proved out. Seeking contributors
- - Repo: [hyperledger/firefly-fabricconnect](https://github.com/hyperledger/firefly-fabricconnect)
+ - Repo: [hyperledger/firefly-cordaconnect](https://github.com/hyperledger/firefly-cordaconnect)
> _Each FireFly network is tied to a single blockchain technology. Watch this space for
> evolution of pluggable bridges for tokens, assets and data between networks through
diff --git a/images/helm_chart_deployment_architecture.jpg b/images/helm_chart_deployment_architecture.jpg
new file mode 100644
index 0000000000..da8b2bd53c
Binary files /dev/null and b/images/helm_chart_deployment_architecture.jpg differ