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