博客 | NGINX

玛拉： 现在在您附近的工作站上运行

Jason Schmidt 缩略图
杰森·施密特
2022 年 4 月 22 日发布

当我们开始开展NGINX 现代应用参考架构(MARA) 项目时，我们选择 AWS 作为我们的 IaaS 提供商，因为我们已经熟悉该平台，并且可以使用部门预算来支付费用。 当然，并不是每个人都有相同的经验或预算，你们中的许多人要求我们提供在本地运行 MARA 的选项——在基于实验室的环境中，甚至在工作站上——使用 Kubernetes 发行版，例如K3s 、 Canonical MicroK8s和minikube 。

我们听到了您的声音，今天我们很高兴地宣布我们已经在 MicroK8s 上测试了 MARA，并提供了说明，以便您可以自行部署！

显示在工作站上运行的 NGINX 现代应用参考架构的拓扑图

为什么我们选择 MicroK8s 进行测试？ 因为它以易于部署且内存占用低的模型提供了 MARA 所需的 DNS、存储和出口功能。 借助 MicroK8s，我们可以轻松、反复地迭代测试场景，以确定提供合理性能水平的部署的最低要求。

我们的期望是，这项工作将促进我们对其他 Kubernetes 发行版的测试；有关各种发行版的当前状态的信息，请参阅我们的GitHub repo 。 如果您有喜欢的发行版并希望将其列在列表中，我们邀请您进行分叉、测试和创建拉取请求！

处理资源限制

在本地运行 MARA 的最大限制是内存和 CPU。 在初步测试期间，我们发现内存耗尽的大部分问题都与 Elasticsearch 有关。 在内存极小（少于16 GB ）的配置中，Kibana 几乎无法使用。 为了解决这个问题，我们在 MARA 配置文件中提供了设置，消除了完整 Elasticsearch 部署通常具有的冗余保护。 虽然这会增加故障模式的数量，但这是资源受限环境中必要的权衡。

CPU 的限制与我们示例Bank of Sirius应用所承受的负载量直接相关。 MARA 部署包括Locust ，用于在 Bank of Sirius 上产生负载，并通过用户控制设置用户数量和新用户的生成率。

请注意，增加 Sirius 银行的负载也会影响系统的其余部分。 如果用户数量或生成率过高，MARA 性能就会下降到组件可能崩溃或停转的程度。 导致此行为的值取决于可用的 CPU，但您可以预期部署至少具有要求中指定的容量，可以处理最多 64 个用户创建的负载以及一次 16 个用户的跨度率。

在 MicroK8s 上部署 MARA

了解了这些背景知识后，您已准备好在 MicroK8s 上启动 MARA！

要求

  • 在运行Ubuntu 20.04 (Focal)或更高版本的系统（裸机 Linux 服务器、虚拟化服务器或云）上具有root访问权限，至少具备以下条件：

    • 20 GB 磁盘
    • 16 GB 内存
    • 相当于 4 个 CPU

  • 本地系统上的 Python 3 虚拟环境，包含 MARA 所需的所有库和二进制文件。 如果尚未安装 Python 3，请运行以下命令：

    $  sudo apt update$  sudo apt install -y python3-venv

  • MicroK8s 集成的MetalLB负载均衡器至少有一个免费的 IPv4 地址分配给 NGINX Ingress Controller 出口。 如果您通过本地主机访问 Sirius 银行应用，则任何可用的私有（符合RFC 1918标准的）地址都是可以接受的。 例如，如果您的网络是 192.168.100.0/24，则可以使用 10.10.10.10 之类的地址。

  • Pulumi 帐户和访问令牌。 如果您还没有这些，您可以在部署 MARA的第 1 步中创建它们。

    请注意，虽然 Pulumi 允许您将状态文件存储在与 S3 兼容的对象存储或本地文件系统中，但 MARA 在撰写本文时不支持此功能。 此限制将在 MARA 或 Pulumi 的未来版本中消除。

安装并配置MicroK8s

  1. 安装MicroK8s：

    $ sudo snap install microk8s --classicmicrok8s (1.23/stable) v1.23.3 from Canonical✓ installed

  2. 设置运行microk8s命令所需的权限。 为了 <用户名>，替换您的帐户 根 系统权限：

    $ sudo usermod -a -G microk8s <username>$ sudo chown -f -R <username> ~/.kube
$ newgrp microk8s

  3. 注销您的 root特权帐户并重新登录以使新权限生效。

  4. 启用DNS 、存储和MetalLB的 MicroK8s 附加组件。

    在提示符下，指定形式为X . X . X . X ‑ X . X . X . Y的 IP 地址范围来表示：

    • 实际的私有 IP 地址范围（例如，192.168.100.100-192.168.100.110 （下面使用的值）
    • 单个私有 IP 地址（例如，192.168.100.100-192.168.100.100 ）
    $ microk8s enable dns storage metallbEnabling DNS
Applying manifest
...
Restarting kubelet
DNS is enabled
Enabling default storage class
...
Storage will be available soon
Enabling MetalLB
Enter each IP address range delimited by comma (e.g. '10.64.140.43-10.64.140.49,192.168.0.105-192.168.0.111'): 192.168.100.100-192.168.100.110
Applying Metallb manifest
...
MetalLB is enabled

  5. 确认 MicroK8s 正在运行：

    $ microk8s statusmicrok8s is running
high-availability: no
  datastore master nodes: 127.0.0.1:19001
  datastore standby nodes: none
addons:
  enabled:
    dns           # CoreDNS
    ha-cluster    # Configure high availability on the current node
    metallb       # Loadbalancer for your Kubernetes cluster
    storage       # Storage class; allocates storage from host directory
...

  6. 将 MicroK8s 配置加载到大多数实用程序希望找到的文件中（ ~/.kube/config ），并在目录和文件上设置推荐的权限：

    $ microk8s config > ~/.kube/config$ sudo chmod 0644 ~/.kube/config

克隆 MARA Repo 并设置 MicroK8s 集群

  1. 克隆 MARA 存储库并初始化 Bank of Sirius 子模块：

    $ git clone https://github.com/nginxinc/kic-reference-architectures.git$ cd kic-reference-architectures/
$ git submodule update --init --recursive --remote

  2. 在克隆的 MARA repo 的根目录中工作（您在上一步中更改了那里的目录），为 MicroK8s 集群设置 Python 虚拟环境：

    $ ./bin/setup_venv.sh

    此命令会生成一个较长的跟踪。 如果有错误，请查看 MARA GitHub repo 中的已知问题/注意事项部分以获取建议。

  3. 激活 Python 虚拟环境。 该命令设置您的PATH和其他环境变量以使用虚拟环境：

    $ source ./pulumi/python/venv/bin/activate

  4. 确认 MicroK8s 集群已正确配置以进行 MARA 部署：

    $ ./bin/testcap.sh
This script will perform testing on the current kubernetes installation using the currently active kubernetes configuration and context.
Any failures should be investigated, as they will indicate that the installation does not meet the minimum set of capabilities required to run MARA.

...
==============================================================
| All tests passed! This system meets the basic requirements |
| to deploy MARA.                                            |
==============================================================

部署 MARA

本节用于部署 MARA 的start.sh脚本包含需要额外操作才能成功部署的选项。 为了简单起见，我们这里假设一个基本部署：

  • 使用 kubeconfig 文件而不是其他受支持的部署选项之一。 有关其他选项的详细信息，请参阅我们的 GitHub 存储库中的入门指南。
  • 使用我们已经测试过 MARA 的最新版本的 NGINX 开源版本（不一定是最新版本）。
  • 使用基于 NGINX 开源的 NGINX Ingress Controller。 如果您想使用基于 NGINX Plus 的 NGINX Ingress Controller，则必须使用来自 Kubernetes 集群中的 F5 Docker 注册表的基于 NGINX Plus 的映像。 请参阅下面步骤 3中的第一个“注意！”以了解更多信息。
  • 使用单个标准 Kubernetes 上下文。 请参阅步骤 3 中的第二个“注意！” 。

在MicroK8s集群中部署MARA：

  1. 运行start.sh脚本。

    如果您尚未将工作站配置为使用 Pulumi，您将被引导登录 Pulumi（如有必要，创建一个帐户），然后提示输入与您的 Pulumi 帐户关联的 API 令牌。

    $ ./bin/start.shAdding to [/home/ubuntu/kic-reference-architectures/bin/venv/bin] to PATH
Manage your Pulumi stacks by logging in.
Run `pulumi login --help` for alternative login options.
Enter your access token from https://app.pulumi.com/account/tokens
    or hit <ENTER> to log in using your browser            : <token>

Please read the documentation for more details.

  2. 选择部署类型，在提示符下输入k以使用 kubeconfig 文件构建部署。 忽略有关make和 Docker 未安装的警告 – 部署将使用来自注册表的 NGINX Ingress Controller 映像。

    Type a for AWS, k for kubeconfig? k
Calling kubeconfig startup script
make is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.
docker is not installed - it must be installed if you intend to build NGINX Kubernetes Ingress Controller from source.

  3. 在提示符下，指定要创建的 Pulumi 堆栈的名称（此处为mara ）。 它在您的 Pulumi 帐户中必须是唯一的。

    Enter the name of the Pulumi stack to use in all projects: maraSubmodule source found
Configuring all Pulumi projects to use the stack: mara
Created stack 'mara'

NOTICE! Currently the deployment via kubeconfig only supports pulling images from the registry! A JWT is required in order to access the NGINX Plus repository. This should be placed in a file in the extras directory in the root, in a file named jwt.token

See https://docs.nginx.com/nginx-ingress-controller/installation/using-the-jwt-token-docker-secret/ for more details and examples.

No JWT found; writing placeholder manifest

NOTICE! When using a kubeconfig file you need to ensure that your environment is configured to connect to Kubernetes properly. If you have multiple kubernetes contexts (or custom contexts) you may need to remove them and replace them with a simple ~/.kube/config file. This will be addressed in a future release.

  4. 在提示符下，指定 kubeconfig 文件的完整路径和集群的名称。 它们在这里 /家/<用户名>/.kube/配置 和 microk8s-集群。

    Provide an absolute path to your kubeconfig filevalue: /home/<username>/.kube/config
Provide your clustername
value: microk8s-cluster
Attempting to connect to kubernetes cluster

  5. 在下一个提示符下指定集群的完全限定域名 (FQDN)。 该脚本使用 FQDN 有两个目的：配置 NGINX Ingress Controller 和创建自签名证书（第二种用途意味着该值不能是 IP 地址）。 如果您用不同的 FQDN 替换mara.example.com ，请记住在以下步骤中也使用它。

    6. Create a fqdn for your deploymentvalue: mara.example.com

  6. 指定 Grafana 管理员密码：

    Create a password for the grafana admin user; this password will be used to access the Grafana dashboardThis should be an alphanumeric string without any shell special characters; it is presented in plain text due to current limitations with Pulumi secrets. You will need this password to access the Grafana dashboard.
value: <password>

    7. 出现安装过程的跟踪信息，显示每个步骤的以下信息：

    • 描述步骤中执行的关键操作的横幅（例如， Logstore表示 Elasticsearch 部署的开始）
    • Pulumi 将要执行的任务列表
    • 每个 Pulumi 任务的实时状态指示器
    • Pulumi 和 MARA 生成的诊断信息，例如定义的主机名和 IP 地址
    • 受影响的资源数量
    • 已过时间

    当最后一步（针对 Bank of Sirius）完成时，跟踪会报告 MetalLB 分配给 NGINX Ingress Controller 的 IP 地址（此处192.168.100.100) 和您为部署选择的 FQDN（此处为mara.example.com ）以及有关部署的其他信息。

    The startup process has finished successfully
Next Steps:
1. Map the IP address (192.168.100.100) of your Ingress Controller with your FQDN (mara.example.com).
2. Use the ./bin/test-forward.sh program to establish tunnels you can use to connect to the management tools.
3. Use kubectl, k9s, or the Kubernetes dashboard to explore your deployment.

To review your configuration options, including the passwords defined, you can access the pulumi secrets via the following commands:

Main Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/config

Bank of Sirius (Example Application) Configuration: pulumi config -C /jenkins/workspace/jaytest/bin/../pulumi/python/kubernetes/applications/sirius

K8 Loadbalancer IP: kubectl get services --namespace nginx-ingress

Please see the documentation in the github repository for more information

  7. 在用于解析 FQDN 的工具（例如本地/etc/hosts文件或 DNS 服务器）中创建上一步报告的 FQDN 和 IP 地址之间的映射。

  8. 验证对 MARA 部署的请求是否成功。 包含-k选项，以便curl接受自签名证书。 要显示有关证书的更多信息，请添加-v选项。

    $ curl  -k -I https://mara.example.comHTTP/1.1 200 OK
Server: nginx/1.21.5
Date: Day, DD Mon YYYY hh:mm:ss TZ
Content-Type: text/html; charset=utf-8
Content-Length: 7016
Connection: keep-alive

  9. 在浏览器中导航到https://mara.example.com以显示 Sirius 银行网站。 在撰写本文时，使用许多浏览器（包括 Firefox 和 Safari），您可以安全地点击有关使用自签名证书的站点的警告。 我们建议您不要使用 Chrome——由于最近的安全变化，它可能会禁止您访问该网站。

  10. 运行test-forward.sh脚本来设置 Kubernetes 端口转发，以便您可以访问 MARA 管理套件中的工具 – Elasticsearch 、 Grafana 、 Kibana 、 Locust和Prometheus 。 该脚本确定适当的服务名称并运行kubectl命令将其转发到本地端口。

    笔记： 为了使端口转发正常工作，您的浏览器必须与运行此命令的命令 shell 在同一系统上运行。 如果没有（例如，因为您正在使用虚拟化环境），命令似乎成功了，但端口转发实际上不起作用。 有关更多信息，请参阅我们的 GitHub 存储库中的访问 MARA 中的管理工具。

    $ ./bin/test-forward.shConnections Details
====================================
Kibana:        http://localhost:5601
Grafana:       http://localhost:3000
Locust:        http://localhost:8089
Prometheus:    http://localhost:9090
Elasticsearch: http://localhost:9200
====================================

Issue Ctrl-C to Exit

概括

就是这样！ 按照这些说明，大约 20 分钟内，您的环境中即可启动并运行有效的 MARA 部署。 此时，您可以像任何其他 Kubernetes应用一样与 Bank of Sirius应用进行交互。 一个好的起点是使用内置的可观察性工具来测试当您使用 Locust 生成不同数量的负载时环境的行为。

我们的目标是让尽可能多的 Kubernetes 用户能够使用 MARA。 不喜欢我们对某些组件做出的选择？ 如果您想分享，我们鼓励您替换您的组件并打开拉取请求。 此外，请在我们的仓库的“问题和讨论”页面上分享想法并提出问题 - 包括我们所做的任何有疑问的假设。

相关文章

这篇文章是系列文章的一部分。 随着我们不断增加 MARA 的功能，我们会在博客上发布详细信息：

阅读有关 F5 NGINX 的更多博客文章 ›

“这篇博文可能引用了不再可用和/或不再支持的产品。 有关 F5 NGINX 产品和解决方案的最新信息，请探索我们的NGINX 产品系列。 NGINX 现在是 F5 的一部分。 所有之前的 NGINX.com 链接都将重定向至 F5.com 上的类似 NGINX 内容。”