Minor rewording, add some more hints

2 files changed, 34 insertions, 25 deletions

diff --git a/script/helm/garage/README.md b/script/helm/garage/README.md
index 1921509a..c2eb086f 100644
--- a/script/helm/garage/README.md
+++ b/script/helm/garage/README.md
@@ -20,9 +20,9 @@ S3-compatible object store for small self-hosted geo-distributed deployments
 | garage.bootstrapPeers | list | `[]` | This is not required if you use the integrated kubernetes discovery |
 | garage.compressionLevel | string | `"1"` | zstd compression level of stored blocks https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/#compression-level |
 | garage.dbEngine | string | `"lmdb"` | Can be changed for better performance on certain systems https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/#db-engine-since-v0-8-0 |
-| garage.existingConfigMap | string | `""` | if not empty string, allow using an existing ConfigMap for the garage.toml if set, ignores garage.toml |
-| garage.garageTomlString | string | `""` | String Template for the garage configuration if set, ignores above values Values can be templated ref: https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/ |
-| garage.kubernetesSkipCrd | bool | `false` |  |
+| garage.existingConfigMap | string | `""` | if not empty string, allow using an existing ConfigMap for the garage.toml, if set, ignores garage.toml |
+| garage.garageTomlString | string | `""` | String Template for the garage configuration if set, ignores above values. Values can be templated, see https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/ |
+| garage.kubernetesSkipCrd | bool | `false` | Set to true if you want to use k8s discovery but install the CRDs manually outside of the helm chart, for example if you operate at namespace level without cluster ressources |
 | garage.replicationMode | string | `"3"` | Default to 3 replicas, see the replication_mode section at https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/#replication-mode |
 | garage.rpcBindAddr | string | `"[::]:3901"` |  |
 | garage.rpcSecret | string | `""` | If not given, a random secret will be generated and stored in a Secret object |
@@ -31,16 +31,16 @@ S3-compatible object store for small self-hosted geo-distributed deployments
 | garage.s3.web.index | string | `"index.html"` |  |
 | garage.s3.web.rootDomain | string | `".web.garage.tld"` |  |
 | image.pullPolicy | string | `"IfNotPresent"` |  |
-| image.repository | string | `"dxflrs/amd64_garage"` |  |
-| image.tag | string | `""` | please prefer using the chart version and not this tag |
-| imagePullSecrets | list | `[]` |  |
-| ingress.s3.api.annotations | object | `{}` | Rely either on the className or the annotation below but not both replace "nginx" by an Ingress controller you can find examples here https://kubernetes.io/docs/concepts/services-networking/ingress-controllers className: "nginx" |
+| image.repository | string | `"dxflrs/amd64_garage"` | default to amd64 docker image |
+| image.tag | string | `""` | set the image tag, please prefer using the chart version and not this to avoid compatibility issues |
+| imagePullSecrets | list | `[]` | set if you need credentials to pull your custom image |
+| ingress.s3.api.annotations | object | `{}` | Rely _either_ on the className or the annotation below but not both! If you want to use the className, set className: "nginx" and replace "nginx" by an Ingress controller name, examples [here](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers). |
 | ingress.s3.api.enabled | bool | `false` |  |
-| ingress.s3.api.hosts[0] | object | `{"host":"s3.garage.tld","paths":[{"path":"/","pathType":"Prefix"}]}` | garage S3 API endpoint |
+| ingress.s3.api.hosts[0] | object | `{"host":"s3.garage.tld","paths":[{"path":"/","pathType":"Prefix"}]}` | garage S3 API endpoint, to be used with awscli for example |
 | ingress.s3.api.hosts[1] | object | `{"host":"*.s3.garage.tld","paths":[{"path":"/","pathType":"Prefix"}]}` | garage S3 API endpoint, DNS style bucket access |
 | ingress.s3.api.labels | object | `{}` |  |
 | ingress.s3.api.tls | list | `[]` |  |
-| ingress.s3.web.annotations | object | `{}` | Rely either on the className or the annotation below but not both replace "nginx" by an Ingress controller you can find examples here https://kubernetes.io/docs/concepts/services-networking/ingress-controllers className: "nginx" |
+| ingress.s3.web.annotations | object | `{}` | Rely _either_ on the className or the annotation below but not both! If you want to use the className, set className: "nginx" and replace "nginx" by an Ingress controller name, examples [here](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers). |
 | ingress.s3.web.enabled | bool | `false` |  |
 | ingress.s3.web.hosts[0] | object | `{"host":"*.web.garage.tld","paths":[{"path":"/","pathType":"Prefix"}]}` | wildcard website access with bucket name prefix |
 | ingress.s3.web.hosts[1] | object | `{"host":"mywebpage.example.com","paths":[{"path":"/","pathType":"Prefix"}]}` | specific bucket access with FQDN bucket |
@@ -58,7 +58,7 @@ S3-compatible object store for small self-hosted geo-distributed deployments
 | monitoring.metrics.serviceMonitor.scheme | string | `"http"` |  |
 | monitoring.metrics.serviceMonitor.scrapeTimeout | string | `"10s"` |  |
 | monitoring.metrics.serviceMonitor.tlsConfig | object | `{}` |  |
-| monitoring.tracing.sink | string | `""` |  |
+| monitoring.tracing.sink | string | `""` | specify a sink endpoint for OpenTelemetry Traces, eg. `http://localhost:4317` |
 | nameOverride | string | `""` |  |
 | nodeSelector | object | `{}` |  |
 | persistence.data.hostPath | string | `"/var/lib/garage/data"` |  |
@@ -66,13 +66,13 @@ S3-compatible object store for small self-hosted geo-distributed deployments
 | persistence.enabled | bool | `true` |  |
 | persistence.meta.hostPath | string | `"/var/lib/garage/meta"` |  |
 | persistence.meta.size | string | `"100Mi"` |  |
-| podAnnotations | object | `{}` |  |
+| podAnnotations | object | `{}` | additonal pod annotations |
 | podSecurityContext.fsGroup | int | `1000` |  |
 | podSecurityContext.runAsGroup | int | `1000` |  |
 | podSecurityContext.runAsNonRoot | bool | `true` |  |
 | podSecurityContext.runAsUser | int | `1000` |  |
 | resources | object | `{}` |  |
-| securityContext.capabilities | object | `{"drop":["ALL"]}` | The default security context is heavily restricted feel free to tune it to your requirements |
+| securityContext.capabilities | object | `{"drop":["ALL"]}` | The default security context is heavily restricted, feel free to tune it to your requirements |
 | securityContext.readOnlyRootFilesystem | bool | `true` |  |
 | service.s3.api.port | int | `3900` |  |
 | service.s3.web.port | int | `3902` |  |
diff --git a/script/helm/garage/values.yaml b/script/helm/garage/values.yaml
index c128df55..38715e38 100644
--- a/script/helm/garage/values.yaml
+++ b/script/helm/garage/values.yaml
@@ -26,6 +26,8 @@ garage:
   rpcSecret: ""
   # -- This is not required if you use the integrated kubernetes discovery
   bootstrapPeers: []
+  # -- Set to true if you want to use k8s discovery but install the CRDs manually outside
+  # of the helm chart, for example if you operate at namespace level without cluster ressources
   kubernetesSkipCrd: false
   s3:
     api:
@@ -35,14 +37,14 @@ garage:
       rootDomain: ".web.garage.tld"
       index: "index.html"
 
-  # -- if not empty string, allow using an existing ConfigMap for the garage.toml
+  # -- if not empty string, allow using an existing ConfigMap for the garage.toml,
   # if set, ignores garage.toml
   existingConfigMap: ""
 
   # -- String Template for the garage configuration
-  # if set, ignores above values
-  # Values can be templated
-  # ref: https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/
+  # if set, ignores above values.
+  # Values can be templated,
+  # see https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/
   garageTomlString: ""
 
 # Data persistence
@@ -69,8 +71,10 @@ deployment:
   podManagementPolicy: OrderedReady
 
 image:
+  # -- default to amd64 docker image
   repository: dxflrs/amd64_garage
-  # -- please prefer using the chart version and not this tag
+  # -- set the image tag, please prefer using the chart version and not this
+  # to avoid compatibility issues
   tag: ""
   pullPolicy: IfNotPresent
 
@@ -79,6 +83,7 @@ initImage:
   tag: stable
   pullPolicy: IfNotPresent
 
+# -- set if you need credentials to pull your custom image
 imagePullSecrets: []
 nameOverride: ""
 fullnameOverride: ""
@@ -92,6 +97,7 @@ serviceAccount:
   # If not set and create is true, a name is generated using the fullname template
   name: ""
 
+# -- additonal pod annotations
 podAnnotations: {}
 
 podSecurityContext:
@@ -101,7 +107,7 @@ podSecurityContext:
   runAsNonRoot: true
 
 securityContext:
-  # -- The default security context is heavily restricted
+  # -- The default security context is heavily restricted,
   # feel free to tune it to your requirements
   capabilities:
     drop:
@@ -125,16 +131,17 @@ ingress:
   s3:
     api:
       enabled: false
-      # -- Rely either on the className or the annotation below but not both
-      # replace "nginx" by an Ingress controller
-      # you can find examples here https://kubernetes.io/docs/concepts/services-networking/ingress-controllers
+      # -- Rely _either_ on the className or the annotation below but not both!
+      # If you want to use the className, set
       # className: "nginx"
+      # and replace "nginx" by an Ingress controller name,
+      # examples [here](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers).
       annotations: {}
         # kubernetes.io/ingress.class: "nginx"
         # kubernetes.io/tls-acme: "true"
       labels: {}
       hosts:
-        # -- garage S3 API endpoint
+        # -- garage S3 API endpoint, to be used with awscli for example
         - host: "s3.garage.tld"
           paths:
             - path: /
@@ -150,10 +157,11 @@ ingress:
       #      - kubernetes.docker.internal
     web:
       enabled: false
-      # -- Rely either on the className or the annotation below but not both
-      # replace "nginx" by an Ingress controller
-      # you can find examples here https://kubernetes.io/docs/concepts/services-networking/ingress-controllers
+      # -- Rely _either_ on the className or the annotation below but not both!
+      # If you want to use the className, set
       # className: "nginx"
+      # and replace "nginx" by an Ingress controller name,
+      # examples [here](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers).
       annotations: {}
         # kubernetes.io/ingress.class: nginx
         # kubernetes.io/tls-acme: "true"
@@ -212,4 +220,5 @@ monitoring:
       scrapeTimeout: 10s
       relabelings: []
   tracing:
+    # -- specify a sink endpoint for OpenTelemetry Traces, eg. `http://localhost:4317`
     sink: ""