mirror of
https://github.com/gomods/athens
synced 2026-02-03 11:00:32 +00:00
replace the proxy with its name (#823)
This commit is contained in:
Michal Pristas
committed by
Aaron Schlesinger
Aaron Schlesinger
parent
0af7a685f3
commit
3a190df2db
@@ -43,7 +43,7 @@ We also run an experimental server for public use, so you can get started with A
|
||||
|
||||
Here are some other ways to get involved:
|
||||
|
||||
- Read the full [walkthrough](/walkthrough) with setting up, running and testing the proxy
|
||||
- Read the full [walkthrough](/walkthrough) with setting up, running and testing the Athens proxy
|
||||
explores this in greater depth.
|
||||
* Join our [weekly development meeting](/contributing/community/developer-meetings/)! It's a great way to meet folks working on the project, ask questions or just hang out. All are welcome to join and participate.
|
||||
* Check out our issue queue for [good first issues](https://github.com/gomods/athens/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)
|
||||
|
||||
@@ -19,7 +19,7 @@ weight: 1
|
||||
Username: test
|
||||
Password for 'test':
|
||||
|
||||
3. Once we've properly authenticated we want to share the .subversion directory with the proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container.
|
||||
3. Once we've properly authenticated we want to share the .subversion directory with the Athens proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container.
|
||||
|
||||
**Bash**
|
||||
|
||||
@@ -142,7 +142,7 @@ weight: 1
|
||||
user=proxyuser1
|
||||
password=proxypass1
|
||||
|
||||
5. Once we've properly setup our authentication we want to share the bazaar configuration directory with the proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container.
|
||||
5. Once we've properly setup our authentication we want to share the bazaar configuration directory with the Athens proxy server in order to reuse those credentials. Below we're setting it as a volume on our proxy container.
|
||||
|
||||
**Bash**
|
||||
|
||||
|
||||
@@ -10,8 +10,8 @@ This section of the documentation details the design of Athens. You can read the
|
||||
|
||||
We've split this section into two major sections:
|
||||
|
||||
1. [Proxy internals](./proxy) - basics of the proxy architecture and major features
|
||||
2. [Communication flow](./communication) - how the proxy interacts with the outside world to fetch and store code, respond to user requests, and so on
|
||||
1. [Proxy internals](./proxy) - basics of the Athens proxy architecture and major features
|
||||
2. [Communication flow](./communication) - how the Athens proxy interacts with the outside world to fetch and store code, respond to user requests, and so on
|
||||
|
||||
## How to Read this Section
|
||||
|
||||
|
||||
@@ -10,14 +10,14 @@ Only one project dared to challenge their power...Athens. Athens possessed a str
|
||||
|
||||
### Clean plate
|
||||
|
||||
At the beginning, there's theoretical state when a storage of the proxy is empty.
|
||||
At the beginning, there's theoretical state when a storage of the Athens proxy is empty.
|
||||
|
||||
When User makes a request at this ancient time, it works as described on the flow below.
|
||||
|
||||
- User runs `go get` to acquire new module.
|
||||
- Go CLI contacts the proxy asking for module M, version v1.0
|
||||
- The proxy checks whether or not it has this module in its storage. It does not.
|
||||
- The proxy downloads code from the underlying VCS and converts it into the Go Module format.
|
||||
- Go CLI contacts the Athens proxy asking for module M, version v1.0
|
||||
- The Athens proxy checks whether or not it has this module in its storage. It does not.
|
||||
- The Athens proxy downloads code from the underlying VCS and converts it into the Go Module format.
|
||||
- After it receives all the bits, it stores it into its own storage and serves it to the User.
|
||||
- User receives module and is happy.
|
||||
|
||||
@@ -27,6 +27,6 @@ The process from the user using `go get` all the way to the user downloading a m
|
||||
|
||||
### Happy path
|
||||
|
||||
Now that the proxy is aware of module M at version v1.0, it can serve that module immediately to the user, without fetching it from the VCS.
|
||||
Now that the Athens proxy is aware of module M at version v1.0, it can serve that module immediately to the user, without fetching it from the VCS.
|
||||
|
||||
|
||||
|
||||
@@ -5,14 +5,14 @@ date: 2018-02-11T15:59:56-05:00
|
||||
|
||||
## The Athens Proxy
|
||||
|
||||
The proxy has two primary use cases:
|
||||
The Athens proxy has two primary use cases:
|
||||
|
||||
- Internal deployments
|
||||
- Public mirror deployments
|
||||
|
||||
This document details features of the proxy that you can use to achieve either use case.
|
||||
This document details features of the Athens proxy that you can use to achieve either use case.
|
||||
|
||||
## The Role of the Proxy
|
||||
## The Role of the Athens proxy
|
||||
|
||||
We intend proxies to be deployed primarily inside of enterprises to:
|
||||
|
||||
@@ -24,11 +24,11 @@ Importantly, a proxy is not intended to be a complete _mirror_ of an upstream pr
|
||||
|
||||
## Cache Misses
|
||||
|
||||
When a user requests a module `MxV1` from a proxy and the proxy doesn't have `MxV1` in its cache, it first determines whether `MxV1` is private or not private.
|
||||
When a user requests a module `MxV1` from a proxy and the Athens proxy doesn't have `MxV1` in its cache, it first determines whether `MxV1` is private or not private.
|
||||
|
||||
If it's private, it immediately does a cache fill operation from the internal VCS.
|
||||
|
||||
If it's not private, the proxy consults its exclude list for non-private modules (see below). If `MxV1` is on the exclude list, the proxy returns 404 and does nothing else. If `MxV1` is not on the exclude list, the proxy executes the following algorithm:
|
||||
If it's not private, the Athens proxy consults its exclude list for non-private modules (see below). If `MxV1` is on the exclude list, the Athens proxy returns 404 and does nothing else. If `MxV1` is not on the exclude list, the Athens proxy executes the following algorithm:
|
||||
|
||||
```
|
||||
upstreamDetails := lookUpstream(MxV1)
|
||||
@@ -47,18 +47,18 @@ _In a later version of the project, we may implement an event stream on proxies
|
||||
|
||||
## Exclude Lists and Private Module Filters
|
||||
|
||||
To accommodate private (i.e. enterprise) deployments, the proxy maintains two important access control mechanisms:
|
||||
To accommodate private (i.e. enterprise) deployments, the Athens proxy maintains two important access control mechanisms:
|
||||
|
||||
- Private module filters
|
||||
- Exclude lists for public modules
|
||||
|
||||
### Private Module Filters
|
||||
|
||||
Private module filters are string globs that tell the proxy what is a private module. For example, the string `github.internal.com/**` tells the proxy:
|
||||
Private module filters are string globs that tell the Athens proxy what is a private module. For example, the string `github.internal.com/**` tells the Athens proxy:
|
||||
|
||||
- To never make requests to the public internet (i.e. to upstream proxies) regarding this module
|
||||
- To download module code (in its cache filling mechanism) from the VCS at `github.internal.com`
|
||||
|
||||
### Exclude Lists for Public Modules
|
||||
|
||||
Exclude lists for public modules are also globs that tell the proxy what modules it should never download from any upstream proxy. For example, the string `github.com/arschles/**` tells the proxy to always return `404 Not Found` to clients.
|
||||
Exclude lists for public modules are also globs that tell the Athens proxy what modules it should never download from any upstream proxy. For example, the string `github.com/arschles/**` tells the Athens proxy to always return `404 Not Found` to clients.
|
||||
|
||||
+3
-3
@@ -12,7 +12,7 @@ A registry is generally run by one entity, is one logical server that provides a
|
||||
|
||||
That's most definitely not what we in the Athens community are going for, and that would harm our community if we did go down that path.
|
||||
|
||||
First and foremost, Athens is an _implementation_ of the [Go Modules download API](./intro/protocol). Not only does the standard Go toolchain support any implementation of that API, the proxy is designed to talk to any other server that implements that API as well. That allows Athens to talk to other proxies in the community.
|
||||
First and foremost, Athens is an _implementation_ of the [Go Modules download API](./intro/protocol). Not only does the standard Go toolchain support any implementation of that API, the Athens proxy is designed to talk to any other server that implements that API as well. That allows Athens to talk to other proxies in the community.
|
||||
|
||||
Finally, we're purposefully building this project - and working with the toolchain folks - in a way that everyone who wants to write a proxy can participate.
|
||||
|
||||
@@ -42,7 +42,7 @@ To repeat, "datastore" means a CDN (we currently have support for Google Cloud S
|
||||
|
||||
One final note - we use "caching" in lots of our docs, and that's technically wrong because no data is evicted or expires. We'll need to update that terminology.
|
||||
|
||||
### Can the proxy authenticate to private repositories?
|
||||
### Can the Athens proxy authenticate to private repositories?
|
||||
|
||||
_TL;DR: yes, with proper authentication configuration defined on the Athens proxy host._
|
||||
|
||||
@@ -67,5 +67,5 @@ To try out tracing with Jaeger, do the following:
|
||||
- Run the walkthrough tutorial
|
||||
- Open `http://localhost:16686/search`
|
||||
|
||||
Observability is not a hard requirement for the proxy. So, if the infrastructure is not properly set up, they will fail with an information log. For eg. if Jaeger is not running / if the wrong URL to the exporter is provided, proxy will continue to run. However, it will not collect any traces or metrics (when the exporter backend is unavailable).
|
||||
Observability is not a hard requirement for the Athens proxy. So, if the infrastructure is not properly set up, they will fail with an information log. For eg. if Jaeger is not running / if the wrong URL to the exporter is provided, proxy will continue to run. However, it will not collect any traces or metrics (when the exporter backend is unavailable).
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Installing an Athens Instance on Kubernetes
|
||||
weight: 1
|
||||
---
|
||||
|
||||
When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the 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](https://kubernetes.io/) cluster. To aid in deployment of the Athens proxy on Kubernetes, a [Helm](https://www.helm.sh/) chart has been provided. This guide will walk you through installing Athens on a Kubernetes cluster using Helm.
|
||||
When you follow the instructions in the [Walkthrough](/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](https://kubernetes.io/) cluster. To aid in deployment of the Athens proxy on Kubernetes, a [Helm](https://www.helm.sh/) chart has been provided. This guide will walk you through installing Athens on a Kubernetes cluster using Helm.
|
||||
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Configure Helm](#configure-helm)
|
||||
@@ -91,7 +91,7 @@ This will deploy a single Athens instance in the `default` namespace with `disk`
|
||||
|
||||
### Give Athens access to private repositories via Github Token (Optional)
|
||||
1. Create a token at https://github.com/settings/tokens
|
||||
2. Provide the token to the proxy either through the config.toml file or by setting the `ATHENS_GITHUB_TOKEN` environment variable.
|
||||
2. Provide the token to the Athens proxy either through the config.toml file or by setting the `ATHENS_GITHUB_TOKEN` environment variable.
|
||||
|
||||
### Storage Providers
|
||||
|
||||
@@ -121,7 +121,7 @@ helm install ./charts/proxy -n athens --set storage.type=mongo --set storage.mon
|
||||
|
||||
### Kuberentes Service
|
||||
|
||||
By default, a Kubernetes `ClusterIP` service is created for the Athens proxy. "ClusterIP" is sufficient in the case when the 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:
|
||||
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:
|
||||
|
||||
```console
|
||||
helm install ./charts/proxy -n athens --set service.type=NodePort
|
||||
|
||||
@@ -4,7 +4,7 @@ description: Installing an Athens Instance For Your Development Team
|
||||
weight: 2
|
||||
---
|
||||
|
||||
When you follow the instructions in the [Walkthrough](/walkthrough), you end up with an Athens Proxy that uses in-memory storage. This is only suitable for trying out the proxy for a short period of time, as you will quickly run out of memory and Athens won't persist modules between restarts. This guide will help you get Athens running in a more suitable manner for scenarios like providing an instance for your development team to share.
|
||||
When you follow the instructions in the [Walkthrough](/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. This guide will help you get Athens running in a more suitable manner for scenarios like providing an instance for your development team to share.
|
||||
|
||||
We will use Docker to run the Athens proxy, so first make sure you have Docker [installed](https://docs.docker.com/install/).
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ INFO[0000] Exporter not specified. Traces won't be exported
|
||||
INFO[0000] Starting application at http://127.0.0.1:3000
|
||||
```
|
||||
|
||||
Next, you will need to configure Go to use the proxy!
|
||||
Next, you will need to configure Go to use the Athens proxy!
|
||||
|
||||
**Bash**
|
||||
```bash
|
||||
|
||||
+13
-13
@@ -6,8 +6,8 @@ menu: shortcuts
|
||||
|
||||
First, make sure you have [Go 1.11 installed](https://gophersource.com/setup/) and that GOPATH/bin is on your path.
|
||||
|
||||
## Without the proxy
|
||||
Let's review what everything looks like in Go 1.11 without the proxy in the picture:
|
||||
## Without the Athens proxy
|
||||
Let's review what everything looks like in Go 1.11 without the Athens proxy in the picture:
|
||||
|
||||
**Bash**
|
||||
```console
|
||||
@@ -31,14 +31,14 @@ The 🦁 says rawr!
|
||||
The end result of running this command is that Go downloaded the package source and packaged
|
||||
it into a module, saving it in the Go Modules cache.
|
||||
|
||||
Now that we have seen Go Modules in action without the proxy, let's take a look at
|
||||
how the proxy changes the workflow and the output.
|
||||
Now that we have seen Go Modules in action without the Athens proxy, let's take a look at
|
||||
how the Athens proxy changes the workflow and the output.
|
||||
|
||||
## With the proxy
|
||||
## With the Athens proxy
|
||||
Using the most simple installation possible, let's walk through how to use the
|
||||
Athens proxy, and figure out what is happening at each step.
|
||||
|
||||
Before moving on, let's clear our Go Modules cache so that we can see the proxy
|
||||
Before moving on, let's clear our Go Modules cache so that we can see the Athens proxy
|
||||
in action without any caches populated:
|
||||
|
||||
**Bash**
|
||||
@@ -82,7 +82,7 @@ The Athens proxy is now running in the background and is listening for requests
|
||||
from localhost (127.0.0.1) on port 3000.
|
||||
|
||||
Since we didn't provide any specific configuration
|
||||
the proxy is using in-memory storage, which is only suitable for trying out the proxy
|
||||
the Athens proxy is using in-memory storage, which is only suitable for trying out the Athens proxy
|
||||
for a short period of time, as you will quickly run out of memory and the storage
|
||||
doesn't persist between restarts.
|
||||
|
||||
@@ -118,9 +118,9 @@ docker run -d -v "$($env:ATHENS-STORAGE):/var/lib/athens" `
|
||||
```
|
||||
|
||||
Next, you will need to enable the [Go Modules](https://github.com/golang/go/wiki/Modules)
|
||||
feature and configure Go to use the proxy!
|
||||
feature and configure Go to use the Athens proxy!
|
||||
|
||||
### Using the proxy
|
||||
### Using the Athens proxy
|
||||
**Bash**
|
||||
```bash
|
||||
export GO111MODULE=on
|
||||
@@ -142,7 +142,7 @@ Possible values are:
|
||||
|
||||
The `GOPROXY` environment variable tells the `go` binary that instead of talking to
|
||||
the version control system, such as github.com, directly when resolving your package
|
||||
dependencies, instead it should communicate with a proxy. The proxy implements
|
||||
dependencies, instead it should communicate with a proxy. The Athens proxy implements
|
||||
the [Go Download Protocol](/intro/protocol), and is responsible for listing available
|
||||
versions for a package in addition to providing a zip of particular package versions.
|
||||
|
||||
@@ -181,7 +181,7 @@ Let's break down what is happening here:
|
||||
running this, our cache is empty and Go keeps looking.
|
||||
1. Go requests **github.com/athens-artifacts/samplelib@v1.0.0** from our proxy because
|
||||
it is set in the GOPROXY environment variable.
|
||||
1. The proxy checks its own storage (in this case is in-memory) for the package and doesn't find it. So it
|
||||
1. The Athens proxy checks its own storage (in this case is in-memory) for the package and doesn't find it. So it
|
||||
retrieves it from github.com and then saves it for subsequent requests.
|
||||
1. Go downloads the module zip and puts it in the Go Modules cache
|
||||
GOPATH/pkg/mod.
|
||||
@@ -195,9 +195,9 @@ The 🦁 says rawr!
|
||||
```
|
||||
|
||||
No additional output is printed because Go found **github.com/athens-artifacts/samplelib@v1.0.0** in the Go Module
|
||||
cache and did not need to request it from the proxy.
|
||||
cache and did not need to request it from the Athens proxy.
|
||||
|
||||
Lastly, quitting from the proxy. This cannot be done directly because we are starting the proxy in the background, thus we must kill it by finding it's process ID and killing it manually.
|
||||
Lastly, quitting from the Athens proxy. This cannot be done directly because we are starting the Athens proxy in the background, thus we must kill it by finding it's process ID and killing it manually.
|
||||
|
||||
**Bash**
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user