Install Athens on Kubernetes

When you follow the instructions in the Walkthrough, you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the Athens proxy for a short period of time, as you will quickly run out of memory and Athens won’t persist modules between restarts. In order to run a more production-like proxy, you may with to run Athens on a Kubernetes cluster. To aid in deployment of the Athens proxy on Kubernetes, a Helm chart has been provided. This guide will walk you through installing Athens on a Kubernetes cluster using Helm.


In order to install Athens on your Kubernetes cluster, there are a few prerequisites that you must satisfy. If you already have completed the following steps, please continue to configuring helm. This guide assumes you have already created a Kubernetes cluster.

Install the Kubernetes CLI

In order to interact with your Kubernetes Cluster, you will need to install kubectl.

Install The Helm CLI

Helm is a tool for installing pre-configured applications on Kubernetes. Install helm by running the following command:


brew install kubernetes-helm


  1. Download the latest Helm release.
  2. Decompress the tar file.
  3. Copy helm.exe to a directory on your PATH.


curl | bash

Configure Helm

If your cluster has already been configured to use Helm, please continue to deploy Athens.

If not, please read on.

RBAC Cluster

If your cluster has RBAC enabled, you will need to create a ServiceAccount, ClusterRole and ClusterRoleBinding for Helm to use. The following command will create these and initialize Helm.

kubectl create -f
helm init --service-account tiller

Non RBAC Cluster

If your cluster has does not have RBAC enabled, you can simply initialize Helm.

helm init

Before deploying Athens, you will need to wait for the Tiller pod to become Ready. You can check the status by watching the pods in kube-system:

$ kubectl get pods -n kube-system -w
NAME                                    READY     STATUS    RESTARTS   AGE
tiller-deploy-5456568744-76c6s          1/1       Running   0          5s

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:

$ helm repo add gomods
$ helm repo update

Next, install the chart with default values to athens namespace:

$ helm install gomods/athens-proxy -n athens --namespace athens

This will deploy a single Athens instance in the default namespace with disk storage enabled. Additionally, a ClusterIP service will be created.

Advanced Configuration


By default, the chart will install Athens with a replica count of 1. To change this, change the replicaCount value:

helm install gomods/athens-proxy -n athens --namespace athens --set replicaCount=3

Give Athens access to private repositories via Github Token (Optional)

  1. Create a token at
  2. Provide the token to the Athens proxy either through the config.toml file (the GithubToken field) or by setting the ATHENS_GITHUB_TOKEN environment variable.

Storage Providers

The Helm chart currently supports running Athens with two different storage providers: disk and mongo. The default behavior is to use the disk storage provider.

Disk Storage Configuration

When using the disk storage provider, you can configure a number of options regarding data persistence. By default, Athens will deploy using an emptyDir volume. This probably isn’t sufficient for production use cases, so the chart also allows you to configure persistence via a PersistentVolumeClaim. The chart currently allows you to set the following values:

  enabled: false
  accessMode: ReadWriteOnce
  size: 4Gi

Add it to override-values.yaml file and run:

helm install gomods/athens-proxy -n athens --namespace athens -f override-values.yaml

enabled is used to turn on the PVC feature of the chart, while the other values relate directly to the values defined in the PersistentVolumeClaim documentation.

Mongo DB Configuration

To use the Mongo DB storage provider, you will first need a MongoDB instance. Once you have deployed MongoDB, you can configure Athens using the connection string via storage.mongo.url. You will also need to set storage.type to “mongo”.

helm install gomods/athens-proxy -n athens --namespace athens --set storage.type=mongo --set storage.mongo.url=<some-mongodb-connection-string>

S3 Configuration

To use S3 storage with Athens, set storage.type to s3 and set storage.s3.region and storage.s3.bucket to the desired AWS region and S3 bucket name, respectively. By default, Athens will attempt to load AWS credentials using the AWS SDK from the chain of environment variables, shared credentials files, and EC2 instance credentials. To manually specify AWS credentials, set storage.s3.access_key_id, storage.s3.secret_access_key, and change storage.s3.useDefaultConfiguration to false.

helm install gomods/athens-proxy -n athens --namespace athens --set storage.type=s3 --set storage.s3.region=<your-aws-region> --set storage.s3.bucket=<your-bucket>

Kubernetes Service

By default, a Kubernetes ClusterIP service is created for the Athens proxy. “ClusterIP” is sufficient in the case when the Athens proxy will be used from within the cluster. To expose Athens outside of the cluster, consider using a “NodePort” or “LoadBalancer” service. This can be changed by setting the service.type value when installing the chart. For example, to deploy Athens using a NodePort service, the following command could be used:

helm install gomods/athens-proxy -n athens --namespace athens --set service.type=NodePort

Ingress Resource

The chart can optionally create a Kubernetes Ingress Resource for you as well. To enable this feature, set the ingress.enabled resource to true.

helm install gomods/athens-proxy -n athens --namespace athens --set ingress.enabled=true

Further configuration values are available in the values.yaml file:

  enabled: true
  annotations: "letsencrypt-prod" "true" "true" nginx
    - secretName:
        - "

Example above sets automatic creation/retrieval of TLS certificates from Let’s Encrypt with cert-manager and uses nginx-ingress controller to expose Athens externally to internet.

Add it to override-values.yaml file and run:

helm install gomods/athens-proxy -n athens --namespace athens -f override-values.yaml

Upstream module repository

You can set the URL for the upstream module repository then Athens will try to download modules from the upstream when it doesn’t find them in its own storage.

You have a few good options for what you can set as an upstream:

  • to use JFrog’s GoCenter
  • to use the Go Module Mirror
  • The URL to any other Athens server

The example below shows you how to set GoCenter up as upstream module repository:

  enabled: true
  url: ""

Add it to override-values.yaml file and run:

helm install gomods/athens-proxy -n athens --namespace athens -f override-values.yaml

.netrc file support

A .netrc file can be shared as a secret to allow the access to private modules. The secret must be created from a netrc file using the following command (the name of the file must be netrc):

kubectl create secret generic netrcsecret --from-file=./netrc

In order to instruct athens to fetch and use the secret, netrc.enabled flag must be set to true:

helm install gomods/athens-proxy -n athens --namespace athens --set netrc.enabled=true
Fork me on GitHub