From f7da298784eeb5296ec95e409d46a3d72d1433e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Thu, 6 May 2021 17:13:38 +0200 Subject: [PATCH] docs: add docs for the Kubernetes chart --- README.md | 3 +- charts/mercure/README.md | 60 +++++++++++++++++++ charts/mercure/README.md.gotmpl | 19 ++++++ docs/hub/install.md | 11 ++++ .../chat/chart/mercure-example-chat/README.md | 45 ++++++++++++++ release.sh | 11 ++++ 6 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 charts/mercure/README.md create mode 100644 charts/mercure/README.md.gotmpl create mode 100644 examples/chat/chart/mercure-example-chat/README.md diff --git a/README.md b/README.md index 3b60227b..65806f33 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ Mercure is a protocol allowing to push data updates to web browsers and other HT It is especially useful to publish async and real-time updates of resources served through web APIs, to reactive web and mobile apps. [![Awesome](https://awesome.re/badge.svg)](docs/ecosystem/awesome.md) +[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/mercure)](https://artifacthub.io/packages/search?repo=mercure) [![PkgGoDev](https://pkg.go.dev/badge/github.com/dunglas/mercure)](https://pkg.go.dev/github.com/dunglas/mercure) ![CI](https://github.com/dunglas/mercure/workflows/CI/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/dunglas/mercure/badge.svg?branch=master)](https://coveralls.io/github/dunglas/mercure?branch=master) @@ -28,7 +29,7 @@ In addition, a managed and high-scalability version of the Mercure.rocks hub is See [CONTRIBUTING.md](CONTRIBUTING.md). -## License and Copyright +## License and Copyright See https://mercure.rocks/docs/hub/license. diff --git a/charts/mercure/README.md b/charts/mercure/README.md new file mode 100644 index 00000000..213864e4 --- /dev/null +++ b/charts/mercure/README.md @@ -0,0 +1,60 @@ +# Mercure Chart for Kubernetes + +![Version: 0.11.3](https://img.shields.io/badge/Version-0.11.3-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: v0.11.3](https://img.shields.io/badge/AppVersion-v0.11.3-informational?style=flat-square) + +A Helm chart to install a Mercure Hub in a Kubernetes cluster. Mercure is a protocol to push data updates to web browsers and other HTTP clients in a convenient, fast, reliable and battery-efficient way. + +[Learn more about Mercure.](https://mercure.rocks) + +## Installing the Chart + +To install the chart with the release name `my-release`, run the following commands: + + helm repo add mercure https://chart.mercure.rocks + helm install my-release mercure/mercure + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| affinity | object | `{}` | [Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) configuration. See the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling) for details. | +| autoscaling | object | Disabled by default. | Autoscaling must not be enabled unless you are using [the High Availability version](https://mercure.rocks/docs/hub/cluster) (see [values.yaml](values.yaml) for details). | +| debug | bool | `false` | Enable the debug mode. | +| dev | bool | `false` | Enable the development mode, including the debug UI and the demo. | +| extraDirectives | string | `""` | Extra Mercure directives to include in the Caddyfile. | +| fullnameOverride | string | `""` | A name to substitute for the full names of resources. | +| image.pullPolicy | string | `"IfNotPresent"` | [Image pull policy](https://kubernetes.io/docs/concepts/containers/images/#updating-images) for updating already existing images on a node. | +| image.repository | string | `"dunglas/mercure"` | Name of the image repository to pull the container image from. | +| image.tag | string | `""` | Overrides the image tag whose default is the chart appVersion. | +| imagePullSecrets | list | `[]` | Reference to one or more secrets to be used when [pulling images](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-pod-that-uses-your-secret) (from private registries). | +| ingress.annotations | object | `{}` | Annotations to be added to the ingress. | +| ingress.className | string | `""` | Ingress [class name](https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class). | +| ingress.enabled | bool | `false` | Enable [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/). | +| ingress.hosts[0].host | string | `"mercure-example.local"` | | +| ingress.hosts[0].paths[0].path | string | `"/"` | | +| ingress.hosts[0].paths[0].pathType | string | `"ImplementationSpecific"` | | +| ingress.tls | list | See [values.yaml](values.yaml). | Ingress TLS configuration. | +| license | string | `""` | The license key for [the High Availability version](https://mercure.rocks/docs/hub/cluster) (not necessary is you use the FOSS version). | +| nameOverride | string | `""` | A name in place of the chart name for `app:` labels. | +| nodeSelector | object | `{}` | [Node selector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) configuration. | +| persistence | object | `{"accessMode":"ReadWriteOnce","enabled":false,"existingClaim":"","size":"1Gi","storageClass":""}` | Enable persistence using [Persistent Volume Claims](http://kubernetes.io/docs/user-guide/persistent-volumes/), only useful if you the BoltDB transport. | +| persistence.accessMode | string | `"ReadWriteOnce"` | A manually managed Persistent Volume and Claim. Requires `persistence.enabled: true` If defined, PVC must be created manually before volume will be bound. | +| persistence.existingClaim | string | `""` | a manually managed Persistent Volume Claim -- Requires `persistence.enabled: true` -- If defined, PVC must be created manually before volume will be bound | +| persistence.storageClass | string | `""` | Mercure Data Persistent Volume Storage Class. If defined, `storageClassName: ` If set to `"-"``, `storageClassName: ""``, which disables dynamic provisioning. If undefined (the default) or set to `null`, no `storageClassName` spec is set, choosing the default provisioner. | +| podAnnotations | object | `{}` | Annotations to be added to pods. | +| podSecurityContext | object | `{}` | Pod [security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod). See the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context) for details. | +| publisherJwtAlg | string | `"HS256"` | The JWT algorithm to use for publishers. | +| publisherJwtKey | string | `""` | The JWT key to use for publishers, a random key will be generated if empty. | +| replicaCount | int | `1` | The number of replicas (pods) to launch, must be 1 unless you are using [the High Availability version](https://mercure.rocks/docs/hub/cluster). | +| resources | object | No requests or limits. | Container resource [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). See the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources) for details. | +| securityContext | object | `{}` | Container [security context](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container). See the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#security-context-1) for details. | +| service.port | int | `80` | Service port. | +| service.type | string | `"ClusterIP"` | Kubernetes [service type](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). | +| serviceAccount.annotations | object | `{}` | Annotations to add to the service account. | +| serviceAccount.create | bool | `true` | Specifies whether a service account should be created. | +| serviceAccount.name | string | `""` | The name of the service account to use. If not set and create is true, a name is generated using the fullname template. | +| subscriberJwtAlg | string | `"HS256"` | The JWT algorithm to use for subscribers. | +| subscriberJwtKey | string | `""` | The JWT key to use for subscribers, a random key will be generated if empty. | +| tolerations | list | `[]` | [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) for node taints. See the [API reference](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling) for details. | +| transportUrl | string | `"bolt:///data/mercure.db"` | The URL representation of the transport to use. | + diff --git a/charts/mercure/README.md.gotmpl b/charts/mercure/README.md.gotmpl new file mode 100644 index 00000000..881cfbfb --- /dev/null +++ b/charts/mercure/README.md.gotmpl @@ -0,0 +1,19 @@ +# Mercure Chart for Kubernetes + +{{ template "chart.badgesSection" . }} + +{{ template "chart.description" . }} + +[Learn more about Mercure.](https://mercure.rocks) + +## Installing the Chart + +To install the chart with the release name `my-release`, run the following commands: + + helm repo add mercure https://chart.mercure.rocks + helm install my-release mercure/{{ template "chart.name" . }} + +{{ template "chart.requirementsSection" . }} + +{{ template "chart.valuesSection" . }} + diff --git a/docs/hub/install.md b/docs/hub/install.md index 1dc740ac..cd404d3b 100644 --- a/docs/hub/install.md +++ b/docs/hub/install.md @@ -83,6 +83,17 @@ This can be done like that: The Docker image is based on [the Caddy Server Docker image](https://registry.hub.docker.com/_/caddy). See [the configuration section](config.md) and [the documentation of the Docker image for Caddy](https://registry.hub.docker.com/_/caddy) to learn how to configure it to fit your needs. +## Kubernetes + +Use [the Helm package manager](https://helm.sh/) to install Mercure on a Kubernetes cluster: + +To install the chart with the release name `my-release`, run the following commands: + + helm repo add mercure https://chart.mercure.rocks + helm install my-release mercure/mercure + +See [the list of available values](https://github.com/dunglas/mercure/blob/main/charts/mercure/README.md) for this chart. + ## Docker Compose If you prefer to use `docker-compose` to run the Mercure.rocks hub, here's a sample service definition: diff --git a/examples/chat/chart/mercure-example-chat/README.md b/examples/chat/chart/mercure-example-chat/README.md new file mode 100644 index 00000000..a9946ada --- /dev/null +++ b/examples/chat/chart/mercure-example-chat/README.md @@ -0,0 +1,45 @@ +# mercure-example-chat + +![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.1.0](https://img.shields.io/badge/AppVersion-0.1.0-informational?style=flat-square) + +A minimalist chat system, using Mercure and the Flask microframework to handle cookie authentication + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| affinity | object | `{}` | | +| autoscaling.enabled | bool | `false` | | +| autoscaling.maxReplicas | int | `100` | | +| autoscaling.minReplicas | int | `1` | | +| autoscaling.targetCPUUtilizationPercentage | int | `80` | | +| cookieDomain | string | `".mercure.rocks"` | | +| fullnameOverride | string | `""` | | +| hubUrl | string | `"https://demo.mercure.rocks/.well-known/mercure"` | | +| image.pullPolicy | string | `"Always"` | | +| image.repository | string | `"dunglas/mercure-example-chat"` | | +| image.tag | string | `"latest"` | | +| imagePullSecrets | list | `[]` | | +| ingress.annotations | object | `{}` | | +| ingress.enabled | bool | `false` | | +| ingress.hosts[0].host | string | `"chart-example.local"` | | +| ingress.hosts[0].paths | list | `[]` | | +| ingress.tls | list | `[]` | | +| jwtKey | string | `"!ChangeMe!"` | | +| messageUriTemplate | string | `"https://chat.example.com/messages/{id}"` | | +| nameOverride | string | `""` | | +| nodeSelector | object | `{}` | | +| podAnnotations | object | `{}` | | +| podSecurityContext | object | `{}` | | +| replicaCount | int | `1` | | +| resources | object | `{}` | | +| securityContext | object | `{}` | | +| service.port | int | `80` | | +| service.type | string | `"ClusterIP"` | | +| serviceAccount.annotations | object | `{}` | | +| serviceAccount.create | bool | `true` | | +| serviceAccount.name | string | `""` | | +| tolerations | list | `[]` | | + +---------------------------------------------- +Autogenerated from chart metadata using [helm-docs v1.5.0](https://github.com/norwoodj/helm-docs/releases/v1.5.0) diff --git a/release.sh b/release.sh index fd71b6ed..2221e4c5 100755 --- a/release.sh +++ b/release.sh @@ -9,6 +9,16 @@ set -o errtrace set -o pipefail set -o xtrace +if ! type "git" > /dev/null; then + echo "The \"git\" command must be installed." + exit 1 +fi + +if ! type "helm-docs" > /dev/null; then + echo "The \"helm-docs\" command (https://github.com/norwoodj/helm-docs) must be installed." + exit 1 +fi + if [ $# -ne 1 ]; then echo "Usage: ./release.sh version" >&2 exit 1 @@ -28,6 +38,7 @@ go get "github.com/dunglas/mercure@v$1" cd - sed -i '' -e "s/^version: .*$/version: $1/" -e "s/^appVersion: .*$/appVersion: \"v$1\"/" helm/mercure/Chart.yaml +helm-docs git commit -S -a -m "chore: prepare release $1"