Update docs and refactoring (#85)

Motivation: triggered by #80 it became clear that documentation is in bad shape and needs to be improved. - generate readme from values.yaml and a template with [helm-docs](https://github.com/norwoodj/helm-docs) - while documenting, finding and fixing bugs and doing minimal refactoring (hence a minor version bump) Some configuration still needs improved documentation and testing strategies specifically for this helm chart. Since those require more effort, they will be done in separate PRs. --------- Co-authored-by: Brendan Le Glaunec <brendan@glaulabs.com>
gomods · Sep 20, 2024 · ee09531 · ee09531
1 parent 1044fcf
commit ee09531
Show file tree

Hide file tree

Showing 10 changed files with 323 additions and 76 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,6 @@
 ## Helm chart for Athens Go Proxy
 * [gomods/athens](https://github.com/gomods/athens)
+* [Chart README](charts/athens-proxy/README.md)
 * requires helm v3
 
 ```shell script

diff --git a/charts/athens-proxy/Chart.yaml b/charts/athens-proxy/Chart.yaml
@@ -1,7 +1,8 @@
 apiVersion: v1
 name: athens-proxy
-version: 0.13.0
+version: 0.14.0
 appVersion: v0.15.1
+kubeVersion: ">= 1.19"
 description: The proxy server for Go modules
 icon: https://raw.githubusercontent.com/gomods/athens/main/docs/static/banner.png
 keywords:

diff --git a/charts/athens-proxy/README.md b/charts/athens-proxy/README.md
@@ -1,4 +1,6 @@
-# Athens Proxy Helm Chart
+# Athens Proxy Helm Chart: athens-proxy
+
+![Version: 0.14.0](https://img.shields.io/badge/Version-0.14.0-informational?style=flat-square) ![AppVersion: v0.15.1](https://img.shields.io/badge/AppVersion-v0.15.1-informational?style=flat-square)
 
 ## What is Athens?
 
@@ -8,7 +10,7 @@ Athens provides a repository for [Go Modules](https://github.com/golang/go/wiki/
 
 ## Prerequisites
 
-* Kubernetes 1.10+
+Kubernetes: `>= 1.19`
 
 ## Requirements
 
@@ -25,14 +27,101 @@ $ helm repo add athens https://gomods.github.io/athens-charts
 $ helm repo update
 ```
 
-Next, install the chart with default values to `athens` namespace:  
+Next, install the chart with default values in the `athens` namespace:
 
 ```
 $ helm install athens/athens-proxy -n athens --namespace athens
 ```
 
 This will deploy a single Athens instance in the `athens` namespace with `disk` storage enabled. Additionally, a `ClusterIP` service will be created.
 
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| affinity | object | `{}` | see https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling |
+| annotations | object | `{}` | Add extra annotations to be added to the athens pods |
+| autoscaling.apiVersionOverride | string | `""` | Overwrite the API version used for HPA, uses 'autoscaling/v2' by default. see https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/horizontal-pod-autoscaler-v2/ |
+| autoscaling.behavior | object | `{}` | Define scaling behavior for HPA |
+| autoscaling.enabled | bool | `false` | Enable Horizontal Pod Autoscaling |
+| autoscaling.maxReplicas | int | `3` |  |
+| autoscaling.minReplicas | int | `1` |  |
+| autoscaling.targetCPUUtilizationPercentage | int | `80` |  |
+| autoscaling.targetMemoryUtilizationPercentage | int | `80` |  |
+| basicAuth.enabled | bool | `false` | If enabled, it expects to find the username and password in the named secret provided below |
+| basicAuth.passwordSecretKey | string | `"password"` |  |
+| basicAuth.secretName | string | `"athens-proxy-basic-auth"` | Secret name, containing the 'passwordSecretKey' and 'usernameSecretKey' |
+| basicAuth.usernameSecretKey | string | `"username"` |  |
+| configEnvVars | list | `[]` | Set environment variables to be passed to athens pods |
+| extraLabels | object | `{}` | Add extra labels to be added to all resources |
+| gitconfig.enabled | bool | `false` | If enabled, it expects to find git configuration in the named secret provided below. By default, gitconfig is disabled |
+| gitconfig.secretKey | string | `"gitconfig"` | Key in the kubernetes secret that contains git config data |
+| gitconfig.secretName | string | `"athens-proxy-gitconfig"` | Name of the kubernetes secret (in the same namespace as athens-proxy) that contains git config |
+| goGetWorkers | int | `3` | Specify the number of go workers |
+| image.pullPolicy | string | `"IfNotPresent"` | Specify a imagePullPolicy. see http://kubernetes.io/docs/user-guide/images/#pre-pulling-images |
+| image.pullSecrets | list | `[]` | Specify secrets containing credentials for pulling images |
+| image.registry | string | `"docker.io"` |  |
+| image.repository | string | `"gomods/athens"` |  |
+| image.runAsNonRoot | bool | `false` | Determine if the image should run as `root` or user `athens` |
+| ingress.annotations | object | `{}` |  |
+| ingress.className | string | `""` |  |
+| ingress.enabled | bool | `false` | Create an Ingress resource for athens |
+| ingress.hosts | list | `[]` | Provide an array of values for the ingress host mapping |
+| ingress.tls | list | `[]` |  |
+| initContainerSecurityContext | object | `{}` | Init container security context configuration |
+| intiContainerResources | object | `{}` | Define resources for the init container of athens |
+| jaeger.annotations | object | `{}` |  |
+| jaeger.enabled | bool | `false` | Deploy a jaeger "all-in-one" pod for tracing |
+| jaeger.image.repository | string | `"jaegertracing/all-in-one"` |  |
+| jaeger.image.tag | string | `"latest"` |  |
+| jaeger.type | string | `"ClusterIP"` | Type of service; valid values are "ClusterIP", "LoadBalancer", and "NodePort". |
+| jaeger.url | string | `""` | Specify the jaeger URL for the environment variable used by athens. With default settings, it uses the jaeger-collector-http port of the jaeger service. |
+| livenessProbe.failureThreshold | int | `3` |  |
+| livenessProbe.periodSeconds | int | `10` |  |
+| livenessProbe.successThreshold | int | `1` |  |
+| livenessProbe.timeoutSeconds | int | `1` |  |
+| metrics.serviceMonitor.enabled | bool | `false` | Create a ServiceMonitor for prometheus |
+| metrics.serviceScrape.enabled | bool | `false` | Create a VMServiceScrape for victoria |
+| netrc.enabled | bool | `false` | If enabled, it expects to find the content of a valid '.netrc' file in the named secret provided below |
+| netrc.existingSecret | string | `"netrcsecret"` | Secret name, containing the '.netrc' file |
+| nodeSelector | object | `{}` | see https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling |
+| priorityClassName | string | `""` | Priority class for pod scheduling. see API reference: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass |
+| replicaCount | int | `1` | Set the number of athens-proxy replicas, unless autoscaling is enabled |
+| resources | object | `{}` | Define resources for athens pods. see https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#resources |
+| securityContext | object | `{}` | Container security context configuration. see API reference: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#securitycontext-v1-core. This will override the `image.runAsNonRoot` settings in the specified container if `runAsUser` or `runAsGroup` are set |
+| service.annotations | object | `{}` | Add annotations to the service |
+| service.nodePort.port | int | `30080` | Available port in allowable range (e.g. 30000 - 32767 on minikube) |
+| service.servicePort | int | `80` | Port as exposed by the service |
+| service.type | string | `"ClusterIP"` | Type of service; valid values are "ClusterIP", "LoadBalancer", and "NodePort". "ClusterIP" is sufficient in the case when the Proxy will be used from within the cluster. To expose externally, consider a "NodePort" or "LoadBalancer" service or use an "Ingress". |
+| serviceAccount.annotations | object | `{}` |  |
+| serviceAccount.create | bool | `true` | Create a ServiceAccount |
+| sshGitServers | list | `[]` | Configuration for private git servers that will provide ssh and git config to athens in a ConfigMap |
+| storage.disk.persistence.accessMode | string | `"ReadWriteOnce"` |  |
+| storage.disk.persistence.enabled | bool | `false` | Note if you use disk.persistence.enabled, replicaCount should be set to 1 unless your access mode is 'ReadWriteMany' and strategy type must be 'Recreate' |
+| storage.disk.persistence.size | string | `"4Gi"` |  |
+| storage.disk.storageRoot | string | `"/var/lib/athens"` |  |
+| storage.gcp.bucket | string | `""` |  |
+| storage.gcp.projectID | string | `""` | For more information, see: https://docs.gomods.io/install/install-on-kubernetes/#google-cloud-storage you must set gcp projectID and bucket when running 'helm install' |
+| storage.gcp.serviceAccount | string | `""` | Set serviceAccount to a key which has read/write access to the GCS bucket. If you are running Athens inside GCP, you will most likely not need this as GCP figures out internal authentication between products for you. |
+| storage.minio.accessKey | string | `""` |  |
+| storage.minio.bucket | string | `""` |  |
+| storage.minio.endpoint | string | `""` | All these variables needs to be set when configuring athens to run with minio backend |
+| storage.minio.secretKey | string | `""` |  |
+| storage.mongo.url | string | `""` |  |
+| storage.s3.accessKey | string | `""` |  |
+| storage.s3.bucket | string | `""` |  |
+| storage.s3.forcePathStyle | bool | `false` |  |
+| storage.s3.region | string | `""` | You must set s3 bucket and region when running 'helm install' |
+| storage.s3.secretKey | string | `""` |  |
+| storage.s3.sessionToken | string | `""` |  |
+| storage.s3.useDefaultConfiguration | bool | `false` |  |
+| storage.type | string | `"disk"` | Storage type to use. For a single instance a PVC may be sufficient |
+| strategy.rollingUpdate.maxSurge | int | `1` |  |
+| strategy.rollingUpdate.maxUnavailable | int | `1` |  |
+| strategy.type | string | `"Recreate"` | Using RollingUpdate requires a shared storage |
+| tolerations | list | `[]` | see https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/#scheduling |
+| upstreamProxy.enabled | bool | `false` | This is where you can set the URL for the upstream module repository. If 'enabled' is set to true, Athens will try to download modules from the upstream when it doesn't find them in its own storage. Here's a non-exhaustive list of options you can set here:  - https://gocenter.io - https://proxy.golang.org |
+| upstreamProxy.url | string | `"https://gocenter.io"` |  |
 
 ## Advanced Configuration
 
@@ -66,7 +155,7 @@ configEnvVars:
 One or more of git servers can added to `sshGitServers`, and the corresponding config files (git config and ssh config) and ssh keys will be created. Athens then will use these configs and keys to download the source from the git servers.
 
 ```yaml
-sshGitServers: 
+sshGitServers:
   ## Private git servers over ssh
   ## to enable uncomment lines with single hash below
   ## hostname of the git server
@@ -81,3 +170,11 @@ sshGitServers:
     ## ssh port
     port: 22
 ```
+
+## Testing
+
+Using `chart-testing` to lint, install and test the chart on a local Kubernetes (Minikube, Rancher Desktop, ...)
+
+```shell
+ct lint-and-install --all
+```
diff --git a/charts/athens-proxy/README.md.gotmpl b/charts/athens-proxy/README.md.gotmpl
@@ -0,0 +1,96 @@
+{{- /* run `helm-docs` to generate README.md */ -}}
+
+# Athens Proxy Helm Chart: {{ template "chart.name" . }}
+
+{{ template "chart.versionBadge" . }}{{ template "chart.typeBadge" . }}{{ template "chart.appVersionBadge" . }}
+
+## What is Athens?
+
+[Athens](https://docs.gomods.io) is a repository for packages used by your go packages.
+
+Athens provides a repository for [Go Modules](https://github.com/golang/go/wiki/Modules) that you can run. It serves public code and your private code for you, so you don't have to pull directly from a version control system (VCS) like GitHub or GitLab.
+
+## Prerequisites
+
+{{ template "chart.kubeVersionLine" . }}
+
+## Requirements
+
+- A running Kubernetes cluster
+- [Kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed and setup to use the cluster
+- [Helm](https://helm.sh/) [installed](https://github.com/helm/helm#install) and setup to use the cluster (helm init) or [Tillerless Helm](https://github.com/rimusz/helm-tiller)
+
+## Deploy Athens
+
+The fastest way to install Athens using Helm is to deploy it from our public Helm chart repository. First, add the repository with this command:
+
+```console
+$ helm repo add athens https://gomods.github.io/athens-charts
+$ helm repo update
+```
+
+Next, install the chart with default values in the `athens` namespace:
+
+```
+$ helm install athens/athens-proxy -n athens --namespace athens
+```
+
+This will deploy a single Athens instance in the `athens` namespace with `disk` storage enabled. Additionally, a `ClusterIP` service will be created.
+
+{{ template "chart.valuesSection" . }}
+
+## Advanced Configuration
+
+For more advanced configuration options please check Athens [docs](https://docs.gomods.io/install/install-on-kubernetes/#advanced-configuration).
+
+Available options:
+- [Replicas](https://docs.gomods.io/install/install-on-kubernetes/#replicas)
+- [Access to private repositories via Github](https://docs.gomods.io/install/install-on-kubernetes/#give-athens-access-to-private-repositories-via-github-token-optional)
+- [Storage Providers](https://docs.gomods.io/install/install-on-kubernetes/#storage-providers)
+- [Kubernetes Service](https://docs.gomods.io/install/install-on-kubernetes/#kubernetes-service)
+- [Ingress Resource](https://docs.gomods.io/install/install-on-kubernetes/#ingress-resource)
+- [Upstream module repository](https://docs.gomods.io/install/install-on-kubernetes/#upstream-module-repository)
+- [.netrc file support](https://docs.gomods.io/install/install-on-kubernetes/#netrc-file-support)
+- [gitconfig support](https://docs.gomods.io/install/install-on-kubernetes/#gitconfig-support)
+
+### Pass extra configuration environment variables
+
+You can pass any extra environment variables supported in [config.dev.toml](../../../config.dev.toml).
+The example below shows how to set username/password for basic auth:
+
+```yaml
+configEnvVars:
+  - name: BASIC_AUTH_USER
+    value: "some_user"
+  - name: BASIC_AUTH_PASS
+    value: "some_password"
+```
+
+### Private git servers over ssh support
+
+One or more of git servers can added to `sshGitServers`, and the corresponding config files (git config and ssh config) and ssh keys will be created. Athens then will use these configs and keys to download the source from the git servers.
+
+```yaml
+sshGitServers: 
+  ## Private git servers over ssh
+  ## to enable uncomment lines with single hash below
+  ## hostname of the git server
+  - host: git.example.com
+    ## ssh username
+    user: git
+    ## ssh private key for the user
+    privateKey: |
+      -----BEGIN RSA PRIVATE KEY-----
+      ...
+      -----END RSA PRIVATE KEY-----
+    ## ssh port
+    port: 22
+```
+
+## Testing
+
+Using `chart-testing` to lint, install and test the chart on a local Kubernetes (Minikube, Rancher Desktop, ...)
+
+```shell
+ct lint-and-install --all
+```
diff --git a/charts/athens-proxy/ci/basic-values.yaml b/charts/athens-proxy/ci/basic-values.yaml
@@ -6,12 +6,19 @@ ingress:
       paths:
         - path: /
           pathType: ImplementationSpecific
-jaeger:
-  enabled: true
 extraLabels:
   athensIs: "awesome"
+annotations:
+  test.annotation: "athens-proxy"
+configEnvVars:
+  - name: KEY
+    value: "value"
 image:
   runAsNonRoot: true
 securityContext:
   allowPrivilegeEscalation: false
   runAsNonRoot: true
+jaeger:
+  enabled: true
+  annotations:
+    test.annotation: "jaeger"
diff --git a/charts/athens-proxy/templates/NOTES.txt b/charts/athens-proxy/templates/NOTES.txt
@@ -4,12 +4,12 @@ The Athens can be accessed via URL:
 Get the Athens URL by running these commands:
 {{- end }}
 {{- if (and .Values.ingress.enabled .Values.ingress.tls) }}
-{{- range .Values.ingress.hosts }}
-  https://{{ . }}
+{{- range .Values.ingress.tls }}
+  https://{{ .host }}
 {{- end }}
 {{- else if .Values.ingress.enabled }}
 {{- range .Values.ingress.hosts }}
-  http://{{ . }}
+  http://{{ .host }}
 {{- end }}
 {{- else if contains "NodePort" .Values.service.type }}
   export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ template "fullname" . }})

diff --git a/charts/athens-proxy/templates/deployment.yaml b/charts/athens-proxy/templates/deployment.yaml
@@ -8,11 +8,12 @@ spec:
   {{- if not .Values.autoscaling.enabled }}
   replicas: {{ .Values.replicaCount }}
   {{- end }}
-  {{- if .Values.strategy }}
+  {{- with .Values.strategy }}
   strategy:
-  {{- toYaml .Values.strategy | nindent 4 }}
-    {{- if eq .Values.strategy.type "Recreate" }}
-    rollingUpdate: null
+    {{- if eq .type "Recreate" }}
+    type: Recreate
+    {{- else }}
+    {{ toYaml . | nindent 4 }}
     {{- end }}
   {{- end }}
   selector:
@@ -187,7 +188,7 @@ spec:
         {{- end }}
         {{- if .Values.jaeger.enabled }}
         - name: ATHENS_TRACE_EXPORTER_URL
-          value: {{ .Values.jaeger.url | quote }}
+          value: {{ .Values.jaeger.url | default (print "http://" (include "fullname" .) "-jaeger:14268" ) | quote }}
         - name: ATHENS_TRACE_EXPORTER
           value: "jaeger"
         {{- end }}

diff --git a/charts/athens-proxy/templates/jaeger-deploy.yaml b/charts/athens-proxy/templates/jaeger-deploy.yaml
@@ -14,9 +14,11 @@ spec:
   template:
     metadata:
       labels:
-        app: {{ template "fullname" . }}-jaeger
-        chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
-        release: "{{ .Release.Name }}"
+        {{- include "athens.metaLabels" (dict "appSuffix" "-jaeger" "Values" .Values "Release" .Release "Chart" .Chart) | nindent 8 }}
+      {{- if .Values.jaeger.annotations }}
+      annotations:
+        {{- toYaml .Values.jaeger.annotations | nindent 8 }}
+      {{- end }}
     spec:
       containers:
         - env:

diff --git a/charts/athens-proxy/templates/test/test-connection.yaml b/charts/athens-proxy/templates/test/test-connection.yaml
@@ -10,6 +10,25 @@ spec:
   containers:
     - name: wget
       image: busybox
-      command: ['wget']
-      args: ['{{ include "fullname" . }}:{{ .Values.service.servicePort }}']
+      command: ['sh']
+      args:
+        - '-c'
+        - |
+          sleep 2;
+          wget {{ include "fullname" . }}:{{ .Values.service.servicePort }};
+          wget -O - {{ include "fullname" . }}:{{ .Values.service.servicePort }}/github.com/google/uuid/@v/v1.6.0.mod;
+    {{- if .Values.jaeger.enabled }}
+    - name: wget-jaeger
+      image: alpine
+      command: ['sh']
+      args:
+        - '-c'
+        # for query, see https://github.com/jaegertracing/jaeger/blob/f4c975cff3f61e46f9ec27d0f7449ef0ec44d067/cmd/query/app/http_handler.go#L113
+        - |
+          apk add jq;
+          sleep 5;
+          wget -O - "http://{{ include "fullname" . }}-jaeger:16686/api/services" | jq .;
+          wget -O - "http://{{ include "fullname" . }}-jaeger:16686/api/traces?service=proxy" | jq '.data|first';
+          wget -O - "http://{{ include "fullname" . }}-jaeger:14268/api/sampling?service=proxy" | jq .;
+    {{- end }}
   restartPolicy: Never