安装 Athens

Go的生态系统一直是联合的,完全开放的。任何拥有GitHub或GitLab(或任何其他支持的VCS)帐户的人都可以轻松地通过git push(或类似命令)来提供库服务。 无需创建额外的帐户或设置凭据。

一个联合的生态系统

我们认为Athens应该保持社区的联合与开放,并且用户在构建应用程序和库时,无需更改工作流。 因此,为确保社区能够保持联合与开放,我们已为每个人提供了轻松安装Athens的方式,以便:

-任何人都可以运行自己的全功能镜像,无论是公共镜像还是私有镜像 -任何组织都可以运行自己的私有镜像,这样他们就可以像管理公共代码一样管理自己的私有代码

不变性

如您所知,go getgo mod download 命令将直接从GitHub等版本控制系统中获取软件包。 这个方式对于软件包开发人员和相关应用程序都非常好,但是与此同时,我们长期以来一直遇到一个基本问题。即,版本控制系统中的代码即使在提交之后也可以随时更改。例如,包开发人员可以运行"git push -f"并覆盖项目中依赖的提交或标记。在这些情况下,您经常会看到校验和验证错误,相关例子可参见这里

Athens通过将代码存储在其自己的不可变数据库中 来防止这些问题的发生。下面是当你运行go get时,发生的交互情况:

  1. go get向Athens请求一个模块
  2. Athens接受请求并开始搜寻该模块
  3. 首先,在后端存储中查找,如果找到了这个模块,Athens将立即返回(1)中发出请求的go get 客户端
  4. 如果找不到这个模块,则从版本控制系统中获取模块,保存在后端存储中,然后返回到(1)中的客户端

一旦将模块保存到存储中,Athens就不会更改任何内容,因此Athens具有以下两个重要属性:

  • 对某个模块的一个版本,Athens永远只调用 go mod download 一次 。换句话说,对于任何给定的模块和版本,Athens只会执行步骤(4)一次。
  • Athens处理存储的策略为仅追加,因此一旦模块被保存,它就永远不会改变,即使开发人员在GitHub上对其进行了更改

发布规则

我们遵循semver语义化版本号。 同时我们的Docker镜像打上了下列标签以表示镜像的稳定性:

  • latest = 最新的稳定版本
  • canary = mater分支最新构建出的版本

我们强烈建议您使用带标签的发行版镜像,例如 gomods/athens:v0.3.0, 而不是使用latest或canary标签的镜像。

拓展资源

为了确保易于安装,我们尝试提供尽可能多的方式来安装和运行Athens:

安装 Athens 的子部分

从源代码构建版本化的Athens二进制文件

您只需执行以下几个命令即可轻松实现构建Athens二进制文件:

Bash

git clone https://github.com/gomods/athens
cd athens
make build-ver VERSION="0.2.0"

PowerShell

git clone https://github.com/gomods/athens
cd athens
$env:GO111MODULE="on"
$env:GOPROXY="https://proxy.golang.org"
$version = "0.2.0"
$date = (Get-Date).ToUniversalTime()
go build -ldflags "-X github.com/gomods/athens/pkg/build.version=$version -X github.com/gomods/athens/pkg/build.buildDate=$date" -o athens ./cmd/proxy

这将生成一个名为athens的二进制文件. 你可以通过下列命令打印版本以及构建时间:

 ./athens -version

which should return something like:

Build Details:
        Version:        0.2.0
        Date:           2018-12-13-20:51:06-UTC

在Kubernetes上安装Athens

当您按照Walkthrough中的说明进行操作时, 最终会得到使用内存作为存储的Athens。 这仅适用于短时间试用Athens,因为您将很快耗尽内存,并且Athens在两次重启之间不会保留储存的模块(modules)。 为了使Athens运行在一个更接近生产级别的环境上, 您可能需要在 Kubernetes 集群上运行Athens. 为了帮助在Kubernetes上部署Athens,, 我们提供了一个 Helm chart . 本指南将指导您使用Helm将Athens安装在Kubernetes集群上。


前提条件

为了在Kubernetes集群上安装Athens,您必须满足一些前提条件.如果您已经完成以下步骤,请继续执行配置Helm. 本指南假设您已经创建了Kubernetes集群.

安装Kubernetes CLI

为了与Kubernetes集群进行交互,您需要 安装 kubectl

安装Helm CLI

Helm 是用于在Kubernetes上安装预先配置好的应用程序的工具。 可以通过运行以下命令来安装helm

MacOS

brew install kubernetes-helm

Windows

  1. 下载最新版本的 Helm release
  2. 解压tar文件。
  3. 拷贝 helm.exe 到系统 PATH 中的一个目录下.

Linux

curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get | bash

配置Helm

如果您的集群已配置为使用Helm,请继续部署Athens.

如果没有,请继续阅读。

RBAC 集群

如果您的集群启用了RBAC,则需要创建ServiceAccount,ClusterRole和ClusterRoleBinding以供Helm使用。 以下命令将创建它们并初始化Helm。

kubectl create -f https://raw.githubusercontent.com/Azure/helm-charts/master/docs/prerequisities/helm-rbac-config.yaml
helm init --service-account tiller

非RBAC 集群

如果您的集群没有启用rbac,则可以轻松初始化helm。

helm init

在部署Athens之前, 你需要等待Tiller的pod变成 Ready状态. 您可以通过查看 kube-system中的Pod来检查状态:

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

部署Athens

使用Helm安装Athens的最快方法是从我们的公共Helm Chart库中进行部署。 首先,使用以下命令添加库

$ helm repo add gomods https://gomods.github.io/athens-charts
$ helm repo update

接下来,将含有默认值的chart安装到athens命名空间:

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

这将在athens命名空间中部署一个启用了disk本地存储的Athens实例。此外,还将创建一个ClusterIP服务。

高级配置

多副本

默认情况下,该chart将安装副本数量为1的athens。要更改此设置,请更改replicaCount值:

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

资源

默认情况下,该chart将在没有特定资源请求或限制的情况下安装athens。 要更改此设置,请更改resources值:

helm install gomods/athens-proxy -n athens --namespace athens \
  --set resources.requests.cpu=100m \
  --set resources.requests.memory=64Mi \
  --set resources.limits.cpu=100m \
  --set resources.limits.memory=64Mi

有关更多信息,请参阅Kubernetes文档中的管理容器的计算资源

通过Github令牌(Token)授予athens访问私有存储库的权限(可选)

  1. https://github.com/settings/tokens 上创建一个令牌(Token)
  2. 通过 config.toml 文件 ( GithubToken 字段) 或 通过设置ATHENS_GITHUB_TOKEN 环境变量,将令牌提供给Athens代理.

存储提供程序(storage provider)

Helm chart目前支持使用两个不同的存储提供程序来运行Athens:diskmongo。 默认使用的是disk存储提供程序。

磁盘存储配置

当使用disk存储提供程序时,可以配置许多有关数据持久性的选项。默认情况下,雅典将使用emptyDir卷进行部署。这可能不足以满足生产用例,因此该chart还允许您通过PersistentVolumeClaim配置持久性。该chart目前允许您设置以下值:

persistence:
  enabled: false
  accessMode: ReadWriteOnce
  size: 4Gi
  storageClass:

将其添加到override values.yaml文件并运行:

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

enabled用于打开chart的PVC功能,而其他值直接与PersistentVolumeClaim中定义的值相关。

Mongo DB 配置

要使用Mongo DB存储提供程序,您首先需要一个MongoDB实例。当部署了MongoDB后,就可以通过storage.mongo.url字段使用连接字符串配置Athens。 您还需将storage.type设置为“mongo”。

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

S3 配置

要在Athens中使用S3存储,请将storage.type设置为s3,并将storage.s3.regionstorage.s3.bucket分别设置为所使用的AWS区域和S3存储桶名称。 默认情况下,Athens将尝试使用AWS SDK从环境变量、共享凭证文件(shared credentials files)和EC2实例凭证组成的链中加载AWS凭证。 要手动指定AWS凭证,请设置storage.s3.access_key_idstorage.s3.secret_access_key,并将storage.s3.useDefaultConfiguration更改为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>

Minio 配置

若要在Athens中使用S3存储,请将storage.type设置为minio。您需要设置storage.minio.endpoint 作为minio安装的URL。这个URL也可以是kubernetes内部地址的(例如minio-service.default.svc)。您需要在minio安装过程中创建一个桶(bucket)或使用现有的一个桶。桶需要在storage.minio.bucket中引用。最后,Athens需要在storage.minio.accesskeystorage.minio.secretkey中设置您的minio的身份验证凭据。

helm install gomods/athens-proxy -n athens --namespace athens --set storage.type=minio --set storage.minio.endpoint=<your-minio-endpoint> --set storage.minio.bucket=<your-bucket> --set storage.minio.accessKey=<your-minio-access-key> --set storage.minio.secretKey=<your-minio-secret-key>

Kubernetes 服务

默认情况下,Kubernetes中为Athens创建了一个ClusterIP 服务。在Kubernetes集群内使用Athens的场景下,clusterip就足够用了。如果要在Kubernetes集群外提供Athens的服务,请考虑使用“nodeport”或“loadbalancer”。可以在安装chart时通过设置service.type值来更改此设置。例如,要使用nodeport服务部署Athens,可以使用以下命令:

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

Ingress 资源

该chart可以选择性为您的创建一个Kubernetes Ingress 资源。要启用此功能,请将ingress.enabled资源设置为true。

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

values.yaml文件中提供了更多配置选项:

ingress:
  enabled: true
  annotations:
    certmanager.k8s.io/cluster-issuer: "letsencrypt-prod"
    kubernetes.io/tls-acme: "true"
    ingress.kubernetes.io/force-ssl-redirect: "true"
    kubernetes.io/ingress.class: nginx
  hosts:
    - athens.mydomain.com
  tls:
    - secretName: athens.mydomain.com
      hosts:
        - "athens.mydomain.com

上述的示例使用cert-managerLet’s Encrypt设置TLS证书的自动创建/检索。 并使用nginx-ingress controller 将Athens对外暴露于互联网中。

将其添加到override-values.yaml文件中并运行:

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

上游的模块(module)库

您可以为上游模块库设置URL,然后当Athens在自己的存储中找不到某个模块(module)时,它将尝试从上游模块库中下载该模块。

对于可用的为上游模块库,一下是几个好的选择:

  • https://gocenter.io 使用JFrog的GoCenter
  • https://proxy.golang.org 使用Go Module 镜像
  • 指向任何其他Athens服务器的URL

以下示例显示了如何将GoCenter设置为上游模块库:

upstreamProxy:
  enabled: true
  url: "https://gocenter.io"

将其添加到 override-values.yaml 文件里并运行:

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

.netrc文件支持

.netrc文件可以作为密钥共享,以允许访问私有模块。 使用以下命令从netrc文件创建密钥(文件的名称必须为netrc):

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

为了指导athens获取并使用密钥,netrc.enabled标志必须设置为true:

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

gitconfig支持

gitconfig可以作为私钥共享,以允许访问私有git库中的模块。 例如,您可以使用GitHub,Gitlab和其他git服务上的个人访问令牌(token),通过HTTPS配置对私有存储库的访问。

首先,准备你的gitconfig文件:

cat << EOF > /tmp/gitconfig
[url "https://user:token@git.example.com/"]
    insteadOf = ssh://git@git.example.com/
    insteadOf = https://git.example.com/
EOF

接下来,使用上面创建的文件创建密钥:

kubectl create secret generic athens-proxy-gitconfig --from-file=gitconfig=/tmp/gitconfig

为了使athens使用密钥,请设置适当的标志(或values.yaml中的参数):

helm install gomods/athens-proxy --name athens --namespace athens \
    --set gitconfig.enabled=true \
    --set gitconfig.secretName=athens-proxy-gitconfig \
    --set gitconfig.secretKey=gitconfig

共享团队实例

当您按照Walkthrough中的说明进行操作时,Athens最终使用的是本地存储空间。 这仅适用于短期试用Athens,因为您将很快耗尽内存,并且Athens在两次重启之间不会保留模块。 本指南将帮助您以一种更适合的方式运行Athens,以用于提供一个实例供开发团队共享的场景。

我们将使用Docker来运行Athens,因此首先请确保您已经安装Docker.

选择存储提供程序

Athens目前支持许多存储驱动程序。 对于本机使用,建议从使用本地磁盘作为存储提供程序开始使用。对于其他提供商,请参阅 the Storage Provider documentation.

使用本地磁盘作为存储安装Athens

为了使用本地磁盘存储来运行Athens,您接下来需要确定要将模块持久化的位置。 在下面的示例中,我们将在当前目录中创建一个名为athens-storage的新目录。现在您可以在启用磁盘存储的情况下运行Athen。 要启用本地磁盘存储,您需要在运行Docker容器时设置ATHENS_STORAGE_TYPEATHENS_DISK_STORAGE_ROOT环境变量。

为了简单起见,下面的示例使用:latest Docker标记,但是我们强烈建议您在环境启动并运行后切换到使用正式版本(例如:v0.3.0)。

Bash

export ATHENS_STORAGE=~/athens-storage
mkdir -p $ATHENS_STORAGE
docker run -d -v $ATHENS_STORAGE:/var/lib/athens \
   -e ATHENS_DISK_STORAGE_ROOT=/var/lib/athens \
   -e ATHENS_STORAGE_TYPE=disk \
   --name athens-proxy \
   --restart always \
   -p 3000:3000 \
   gomods/athens:latest

PowerShell

$env:ATHENS_STORAGE = "$(Join-Path $pwd athens-storage)"
md -Path $env:ATHENS_STORAGE
docker run -d -v "$($env:ATHENS_STORAGE):/var/lib/athens" `
   -e ATHENS_DISK_STORAGE_ROOT=/var/lib/athens `
   -e ATHENS_STORAGE_TYPE=disk `
   --name athens-proxy `
   --restart always `
   -p 3000:3000 `
   gomods/athens:latest

注意:如果您之前尚未使用Docker for Windows挂载此驱动器,则可能会提示您允许访问

Athens现在应该作为带有本地目录athens-storage的Docker容器运行。当Athens检索模块(module)时,它们将被存储在先前创建的目录中。首先,让我们确认雅典是否在运行:

$ docker ps
CONTAINER ID        IMAGE                               COMMAND           PORTS                    NAMES
f0429b81a4f9        gomods/athens:latest   "/bin/app"        0.0.0.0:3000->3000/tcp   athens-proxy

现在,我们可以从安装了Go v1.12+的任何机器上使用Athens。 要验证这一点,请尝试以下示例:

Bash

$ export GO111MODULE=on
$ export GOPROXY=http://127.0.0.1:3000
$ git clone https://github.com/athens-artifacts/walkthrough.git
$ cd walkthrough
$ go run .
go: downloading github.com/athens-artifacts/samplelib v1.0.0
The 🦁 says rawr!

PowerShell

$env:GO111MODULE = "on"
$env:GOPROXY = "http://127.0.0.1:3000"
git clone https://github.com/athens-artifacts/walkthrough.git
cd walkthrough
$ go run .
go: downloading github.com/athens-artifacts/samplelib v1.0.0
The 🦁 says rawr!

我们可以通过检查Docker日志来验证Athens是否处理了此请求:

$ docker logs -f athens-proxy
time="2018-08-21T17:28:53Z" level=warning msg="Unless you set SESSION_SECRET env variable, your session storage is not protected!"
time="2018-08-21T17:28:53Z" level=info msg="Starting application at 0.0.0.0:3000"
handler: GET /github.com/athens-artifacts/samplelib/@v/v1.0.0.info [200]
handler: GET /github.com/athens-artifacts/samplelib/@v/v1.0.0.mod [200]
handler: GET /github.com/athens-artifacts/samplelib/@v/v1.0.0.zip [200]

现在,如果查看athens_storage文件夹的内容,您将会看到与samplelib模块相关的新增文件。

Bash

$ ls -lr $ATHENS_STORAGE/github.com/athens-artifacts/samplelib/v1.0.0/
total 24
-rwxr-xr-x  1 jeremyrickard  wheel    50 Aug 21 10:52 v1.0.0.info
-rwxr-xr-x  1 jeremyrickard  wheel  2391 Aug 21 10:52 source.zip
-rwxr-xr-x  1 jeremyrickard  wheel    45 Aug 21 10:52 go.mod

PowerShell

$ dir $env:ATHENS_STORAGE\github.com\athens-artifacts\samplelib\v1.0.0\


    Directory: C:\athens-storage\github.com\athens-artifacts\samplelib\v1.0.0


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        8/21/2018   3:31 PM             45 go.mod
-a----        8/21/2018   3:31 PM           2391 source.zip
-a----        8/21/2018   3:31 PM             50 v1.0.0.info

重新启动Athens后,它将在该位置提供模块(module),而无需重新下载。 为了验证这一点,我们需要首先删除Athens容器。

docker rm -f athens-proxy

接下来,我们需要清除本地Go模块中的缓存。 这是必要的,以便您本地的Go命令行工具从Athens重新下载该模块。 以下命令将清除本地存储中的模块:

Bash

sudo rm -fr "$(go env GOPATH)/pkg/mod"

PowerShell

rm -recurse -force $(go env GOPATH)\pkg\mod

现在,我们重新运行Athens容器

Bash

docker run -d -v $ATHENS_STORAGE:/var/lib/athens \
   -e ATHENS_DISK_STORAGE_ROOT=/var/lib/athens \
   -e ATHENS_STORAGE_TYPE=disk \
   --name athens-proxy \
   --restart always \
   -p 3000:3000 \
   gomods/athens:latest

PowerShell

docker run -d -v "$($env:ATHENS_STORAGE):/var/lib/athens" `
   -e ATHENS_DISK_STORAGE_ROOT=/var/lib/athens `
   -e ATHENS_STORAGE_TYPE=disk `
   --name athens-proxy `
   --restart always `
   -p 3000:3000 `
   gomods/athens:latest

当我们重新运行我们的Go示例时,Go cli将再次从Athens下载模块。然而,Athens不需要重新检索模块。它将从本地磁盘中获取。

Bash

$ ls -lr $ATHENS_STORAGE/github.com/athens-artifacts/samplelib/v1.0.0/
total 24
-rwxr-xr-x  1 jeremyrickard  wheel    50 Aug 21 10:52 v1.0.0.info
-rwxr-xr-x  1 jeremyrickard  wheel  2391 Aug 21 10:52 source.zip
-rwxr-xr-x  1 jeremyrickard  wheel    45 Aug 21 10:52 go.mod

PowerShell

$ dir $env:ATHENS_STORAGE\github.com\athens-artifacts\samplelib\v1.0.0\


    Directory: C:\athens-storage\github.com\athens-artifacts\samplelib\v1.0.0


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        8/21/2018   3:31 PM             45 go.mod
-a----        8/21/2018   3:31 PM           2391 source.zip
-a----        8/21/2018   3:31 PM             50 v1.0.0.info

请注意文件的时间戳并没有更改

下一步:

在Azure Container Instances上安装Athens

当您按照Walkthrough中的说明进行操作时,Athens最终使用的是本地存储空间。 这仅适用于短期试用Athens,因为您将很快耗尽内存,并且Athens在两次重启之间不会保留模块。 本指南将帮助您以一种更适合的方式运行Athens,以用于提供一个实例供开发团队共享的场景。

在本文中,我们将展示如何在 Azure Container Instances (ACI) 上运行Athens.

选择存储提供商(Provider)

Athens目前支持许多存储驱动。 为了在ACI上能快捷的使用,我们建议使用本地磁盘作为存储。如果希望更持久的存储数据,我们建议使用MongoDB或其他持久化存储架构。 对于其他提供商,请参阅 storage provider documentation.

必需的环境变量

在执行以下任何命令之前,请确保在系统上设置了下列环境变量:

  • AZURE_ATHENS_RESOURCE_GROUP - 指定用于安装容器的 Azure Resource Group 。在安装Athens之前,你需要设置该环境变量。 -有关如何创建资源组(resource group)的详细信息,详见此处
  • AZURE_ATHENS_CONTAINER_NAME - 容器的名称。 应为字母和数字,可以包含“-”和“uu”字符
  • LOCATION - 指定用于安装容器的 Azure region 。有关详细列表,请参见上一链接, 同时这里有一个有用的备忘表,你可以立即使用,而不必阅读任何文档:
    • 北美: eastus2
    • 欧洲: westeurope
    • 亚洲: southeastasia
  • AZURE_ATHENS_DNS_NAME - 要分配给容器的DNS名称。它必须在您设置的区域(region)内是全局唯一的 (LOCATION)

使用本地磁盘驱动进行安装

az container create \
-g "${AZURE_ATHENS_RESOURCE_GROUP}" \
-n "${AZURE_ATHENS_CONTAINER_NAME}-${LOCATION}" \
--image gomods/athens:v0.3.0 \
-e "ATHENS_STORAGE_TYPE=disk" "ATHENS_DISK_STORAGE_ROOT=/var/lib/athens" \
--ip-address=Public \
--dns-name="${AZURE_ATHENS_DNS_NAME}" \
--ports="3000" \
--location=${LOCATION}

创建ACI容器后,您将看到一个JSON Blob对象,其中包含该容器的公有IP地址. 您还将看到正在运行的容器的 fully qualified domain name (FQDN) (以 AZURE_ATHENS_DNS_NAME为前缀)。

使用MongoDB驱动进行安装

首先,请确保您设置了以下环境变量:

  • AZURE_ATHENS_MONGO_URL - MongoDB 连接字符串。例如: mongodb://username:password@mongo.server.com/?ssl=true

然后运行下列创建的命令:

az container create \
-g "${AZURE_ATHENS_RESOURCE_GROUP}" \
-n "${AZURE_ATHENS_CONTAINER_NAME}-${LOCATION}" \
--image gomods/athens:v0.3.0 \
-e "ATHENS_STORAGE_TYPE=mongo" "ATHENS_MONGO_STORAGE_URL=${AZURE_ATHENS_MONGO_URL}" \
--ip-address=Public \
--dns-name="${AZURE_ATHENS_DNS_NAME}" \
--ports="3000" \
--location=${LOCATION}

创建ACI容器后,您将看到一个JSON Blob对象,其中包含该容器的公有IP地址. 您还将看到正在运行的容器的 fully qualified domain name (FQDN) (以 AZURE_ATHENS_DNS_NAME为前缀)。

使用.netrc文件管理私人仓库

通过.netrc文件认证访问私有仓库

  1. 创建一个.netrc文件,如下所示:

    machine <ip or fqdn>

    login <username>

    password <user password>

  2. 通过环境变量通知Athens该文件的位置:

    ATHENS_NETRC_PATH=<location/to/.netrc>

  3. Athens将文件复制到home目录,并覆盖home目录中的任何.netrc文件。或者,如果Athens服务器的主机在home目录中已经存在一个.netrc文件,则身份验证可开箱即用。

通过.hgrc认证访问Mercurial私有存储库

  1. 创建带有身份验证数据的.hgrc文件

  2. 通过环境变量通知Athens该文件的位置

    ATHENS_HGRC_PATH=<location/to/.hgrc>

  3. Athens将会把文件复制到home目录,并覆盖home目录中的任何.hgrc文件。或者,如果Athens服务器的主机在home目录中已经存在一个.hgrc文件,则身份验证可开箱即用。

Fork me on GitHub