翟志军 Jack Zhai

从法庭到代码：谁主张谁举证的工程实践

Sat, 13 Sep 2025 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2025-09-13-applying-the-burden-of-proof-principle/ -

2023年，与开发商打了不少官司。学习了不少庭审知识。发现有些实践或者原则放到软件工程中也是有效的。就比如谁主张谁举证这一基本原则。

谁主张谁举证就是当事人对自己提出的主张提供证据并加以证明。

举例来说，张三说隔壁老王侵占了自己的宅基地。张三必须自己拿证据来证明自己说的事实。而不是让老王拿证据出来证明自己没有侵占。

在软件工程中，服务A调用服务B，出问题了。服务A认为是服务B的问题，这时，根据谁主张谁举证原则，服务A的开发应该自己找出证据来证明自己的观点是正确的，而不应该让服务B来提供证据证明自己没有问题。

因为如果让服务B证明自己没有问题，怎么证明自己没有问题呢？怎么证明，证据都不够充分。而且会浪费服务B的团队人力。

所以，在团队中，让大家达成“谁主张谁举证”的共识会带来以下好处：

节约团队的人力。如果服务A能提供有效证据，那么就不需要服务B去证明自己没有问题了。
倒逼团队形成故障现场保留的习惯，比如打印良好的日志等

不过，我们需要注意的是，“谁主张谁举证”并不意味着，服务B团队不配合服务A一起排查问题。在一个公司里，基本的团队协作原则与底线是要有的。

那是不是所有的场景都是谁主张谁举证？

也有特殊情况。有些场景，是需要进行举证责任倒置的。开发商要拿证据来证明自己的转供电是合法的，而不应该让业主拿证据来证明开发商转供电不合法。也就是证据只能是“被告方”能提供的情况下，我们就不是谁主张谁举证了。

以上只是我个人的思维实验。

在工作中，作为DevOps工程师，我经常遇到开发者质疑云厂商的Redis或者RDS出了问题。

根据我过往的经验，只是质疑，没有证据的情况，大多是开发者自己代码的问题。通常我会自己看看监控的同时，会要求他们加日志，然后想办法复现问题。

最后，一个公司一个团队里，如何低成本的达成谁主张谁举证这个共识？

我目前还没有答案。

- https://showme.codes/zh-cn/2025-09-13-applying-the-burden-of-proof-principle/ - showme.codes

An Example Implement Ansible Deployment on Github Action

Mon, 22 Apr 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/en/2024-04-22-github-actions-ansible/ -


- name: write secrets into json
  run: |
    echo "${{ toJSON(secrets) }}" > _github_secrets.json    
- name: write github repo vars into json
  run: |
    echo "${{ toJSON(vars) }}" > _github_vars.json    
- name: write ssh private key
  run: |
    echo "${{ secrets.STAG_SSH_PRIVATE_KEY }}" > ${{ github.workspace }}/.ssh_private_key.pem
    chmod 0400 ${{ github.workspace }}/.ssh_private_key.pem    
- name: write ssl certificate
  run: |
    echo "${{ secrets.showmecodes_TLS_CERTIFICATES }}" > ${{ github.workspace }}/showmecodes.ai.pem
    echo "${{ secrets.showmecodes_TLS_KEY }}" > ${{ github.workspace }}/showmecodes.ai.key    
- name: deploy showmecodes to stag
  uses: dawidd6/action-ansible-playbook@v2
  with:
    playbook: playbook-showmecodes.yml
    key: ${{ secrets.STAG_SSH_PRIVATE_KEY }}
    options: |
      --inventory env_vars/${{env.APP_ENV}}/hosts.yaml
      --extra-vars "app_backend_zip_path=${{ needs.init_build_version.outputs.backendArtifactName }} app_frontend_zip_path=${{ needs.init_build_version.outputs.fontendStagArtifactName }} app_version=${{ needs.init_build_version.outputs.VERSION }} ansible_ssh_private_key_file=${{ github.workspace }}/.ssh_private_key.pem showmecodes_tls_certificate_file=${{ github.workspace }}/showmecodes.ai.pem showmecodes_tls_private_key_file=${{ github.workspace }}/showmecodes.ai.key" --extra-vars=@_github_vars.json --extra-vars=@_github_secrets.json

- https://showme.codes/en/2024-04-22-github-actions-ansible/ - showme.codes

Web前端构建之依赖版本管理最佳实践

Tue, 12 Mar 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-03-12-frontend-engineering/ -

本文需要读者懂一点点前端的构建知识：

package.json文件的作用之一是管理外部依赖；

.npmrc是npm命令默认配置，放在工程根目录。

Web前端构建一直都是一个不难，但是非常烦人的问题，在DevOps、CI/CD领域。

烦人的是偶尔发生这样的事情：

开发在本地构建通过，但是流水构建失败。这时前端开发人员会经常报怨Pipeline不稳定；
流水线构建通过，但是在生产环境上启动不了，或者出现运行错误；
不使用Docker可以启动，但是打包成Docker镜像后启动就失败。

这类问题，不是今天解决了，明天就不会发生。而是你根本不知道它什么时候又发生。

据我观察，绝大多数时候都是依赖版本管理没有做好导致的。

Web前端的依赖版本管理包括以下几个维度：

node的版本
外部依赖的版本

我们需要在开发环境，构建环境，运行环境保证它们的版本是一致的。这样，在本地开发环境测试通过，那么，在其它环境就理论上也应该能通过。

接下来是具体的最佳实践。

保证Node版本一致

要保证Node版本一致，就要保证所有的环境使用同一个版本的node。而且是要具体到某一个精确的版本，如v20.11.1，而不是20这样一个粗略版本。

以下是我们以v20.11.1为例。

设置开发环境

设置开发环境的node的版本，需要在package.json中加入：

{
  "engines": {
    "node": "v20.11.1",
    "npm": "10.2.4"
  },
}

这时，如果存在开发环境与配置的版本不匹配的情况，执行npm install，会出现以下警告，但是命令还是会继续执行：

npm WARN EBADENGINE Unsupported engine {
npm WARN EBADENGINE   package: 'gpt@0.0.1',
npm WARN EBADENGINE   required: { node: 'v20.10.1', npm: '10.2.4' },
npm WARN EBADENGINE   current: { node: 'v20.11.1', npm: '10.2.4' }
npm WARN EBADENGINE }

希望强制要求版本一致，就在根目录的.npmrc文件加入：

engine-strict=true

发生版本不一致的情况，报错日志如下，且命令会停止执行：

npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node/npm: gpt@0.0.1
npm ERR! notsup Not compatible with your version of node/npm: gpt@0.0.1
npm ERR! notsup Required: {"node":"v20.10.1","npm":"10.2.4"}
npm ERR! notsup Actual:   {"npm":"10.2.4","node":"v16.0.1"}

设置构建环境

我们以Github Actions为例。在设置node环境时，应设置为：

- name: Setup Node
  uses: actions/setup-node@v3
  with:
    node-version: '20.11.1'

设置运行环境

运行环境分两种：虚拟机环境、容器运行时。

在虚拟机环境下，要避免apt install node-20，尽量使用能指定精确node版本的方式安装NodeJS（比如从官网上下载20.11.1的包安装）。

容器运行时环境，选择的镜像的Tag要与构建环境的版本完全一致，而不是随便选一个20版本的。

保证外部依赖版本的一致

由于Node的依赖管理默认配置下非常的宽松，默认情况下使用的就是自动升级策略。

当开发在本地执行: npm i @babel/core，npm会在package.json文件中加入"@babel/core": "^7.11.6",。^代表将来再次执行npm i时，npm有权自动升级它的小版本。

这一行为，导致项目一开始构建是成功的，但是过一段时间又构建失败的偶尔事件。

这种偶发性，不仅给构建工程带来不必要的浪费，还让软件变得不可靠。想想建设在沙子上的大厦会是怎样。

所以，我们推崇以下管理方法。

限制依赖下载源

限制的方法是在.npmrc中加入配置：

registry=https://registry.npmjs.org

从源头就控制软件供应链的一致性。

默认使用准确版本

正如前文所述，在执行 npm install <package> 安装依赖时，默认情况下会在package.json文件中使用^符号来指定版本范围。不过，我们可以通过添加 --save-exact 参数来避免这种情况，即运行 npm install <package> --save-exact，这样package.json文件中就不会出现^符号，而是会锁定安装的精确版本号。

我们不可能让开发人员100%做到每次执行命令都加--save-exact参数。

所以，我们需要更改npm默认的行为，在.npmrc文件中增加配置：

save-exact=true

将package-lock.json加入到版本库中

package-lock.json文件是npm专门用于固定依赖版本的。如果你使用的是pnpm，相对应的文件就是：pnpm-lock.yaml。

node工程中，除了使用package-lock.json锁定版本，还可以使用npm-shrinkwrap.json。

它们具有相同格式，都放在项目的根目录，目的都是为了锁定依赖版本。区别是npm-shrinkwrap.json会被发布到制品库，而package-lock.json不会。且引用它的package会忽略这个文件。

而且当同一个工程根目录下，同时存在它们时，package-lock.json会被忽略。

使用PNPM代替npm？

这篇文章对PNPM，npm和Yarn三个依赖管理工具进行对比，读者自行判断选择相应的工具。但是，可以确定的是不要使用cnpm。

不论使用哪种工具，以上的实践都是类似的。

后记

作者作为一个Web前端的外行写下本文，有不足的或者错误的，还请补充和指正，多谢。

- https://showme.codes/zh-cn/2024-03-12-frontend-engineering/ - showme.codes

优秀的DevOps工程师应该具有什么特质？

Tue, 12 Mar 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-03-12-devops-characters/ -

这是我最近面试时遇到的一个非常好的问题：

在你的心目中，优秀的DevOps工程师应该是什么样的？

很长一段时间里，我没有想到这个问题。所以，当HR问起时，我边思考边回答。

我已经不记得原话，本文就当作从性格角度思考“优秀的DevOps工程师应该具有什么特质”。

首先，优秀的DevOps工程师，TA应该是严谨的。

一个严谨的特质的人才会主动考虑软件工程化过程中的各种可能。

其次，TA应该对手工操作产生“生理性上的不适”，即追求自动化极致。

一个再怎么严谨的人，如果是手工操作，面对复杂的线上环境的运维，TA的能力也是有限的。TA必须自动化所有能自动化的东西，并争取自动化所有的内容，TA才能有可能“驯服野兽”。

然后，TA应该是一个节约的人，即节俭。

因为浪费导致企业不必要损失，是否要避免这个损失，很多时间里是一个DevOps工程师的选择问题。

最后，TA应该是一个热爱这个领域的人。我常常忘记自己对这个领域的热爱。以致于我忘记回答。

只有热爱，才能产生自驱力，驱动TA去成长，去不断思考。即使你再严谨，你也有考虑不到的地方，只有热爱，TA才会探索到TA不知道他不知道的。

以上只是我个人的看法，欢迎一起讨论。

- https://showme.codes/zh-cn/2024-03-12-devops-characters/ - showme.codes

Two Patterns for Rollback

Wed, 06 Mar 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/en/2024-03-06-two-patterns-for-rollback/ -

Rollback is an operations and maintenance procedure. It usually occurs when a problem is discovered during deployment, and the target environment needs to be reverted to its pre-deployment state.

In my opinion, there are two patterns for rollback. One of them is to perform a reverse operation step by step, which I call the Reverse Operation Pattern.

Rollback Pattern Based on Reverse Operation

Probably due to the inertia of the past manual operation mindset, I found that quite a few people only know this one pattern.

For example, the operation of manually deploying an Nginx configuration is as follows:

SSH into the target server
Navigate to the /etc/nginx/sites-enabled/ directory where Nginx is stored
Edit the target configuration file vim example.443.conf
Add a location configuration
Reload Nginx to apply the configuration changes

In the rollback scenario using the reverse-operation pattern, how should we roll back? Steps 1, 2, 3, and 5 are the same as in deployment. Step 4 requires the operator to find the configuration and remove it.

At this point, the operator may make a mistake in the operation, and it may be difficult to perceive when the mistake is made because it is a manual operation.

Then, some people think it would be better if the above steps could be automatically rolled back.

But how can we automate the rollback? We need to design the corresponding automated rollback script at the time of deployment. When needed, trigger its automatic rollback.

However, this rollback scheme is not generalizable, and it increases the cost of operations and maintenance. Because the average person maintaining an Nginx configuration change is very reluctant to write a rollback script, and they themselves may not be able to write a correct, reliable automated rollback script.

Then, someone might think, “Can I implement a platform to automatically generate the rollback code?”

The answer is yes. You have to pre-define each step action, such as defining the Nginx configuration change as an action in the platform. Then define its inverse action.

If you are implementing a similar platform project, you will know that the amount of work is endless because the operations are endless.

You can say that the platform can provide the ability to customize the step action, but then you will also encounter the problem of “they themselves may not be able to write a correct and reliable automation rollback script.” And, since it’s a platform, it’s the platform’s responsibility to define the actions.

So, this is an industry dilemma.

During the interview process, the interviewer usually assumes that I will encounter the same dilemma. However, I won’t encounter this problem at all.

Version-based Rollback Pattern

When I was explaining this pattern, many people couldn’t understand it.

Let’s take the case of deploying an Nginx configuration, but automate the deployment through Ansible. Assume that the following deployment script already exists:

- hosts: prod-nginx
  gather_facts: yes
  become: true
  vars_files:
    - common_vars/nginx.yaml

  roles:
    # Nginx deployment logic, which is declarative and idempotent
    - ansible-role-nginx

The above code means roughly: deploy Nginx to a list of prod-nginx hosts and use the configuration in the common_vars/nginx.yaml file.

The configuration of nginx.yaml is as follows:

nginx_vhosts:
  - listen: "80"
    server_name: "*.example.com"
    return: "301 https://{{example_domain}}$request_uri"
    filename: "example.80.conf"

We version the above code (commit it to Git and build it via automation) to get version number: v1.0.1.

When there’s a need to modify the configuration on the line, such as in the case of “Rollback Mode for Reverse Operations,” we accomplish this by appending the appropriate configuration to the nginx.yaml file. It will resemble the following structure:

nginx_vhosts:
- listen: "80"
  server_name: "*.example.com"
  return: "301 https://{{example_domain}}$request_uri"
  filename: "example.80.conf"
- listen: "80"
  server_name: "*.abc.com"
  return: "301 https://{{example_domain}}$request_uri"
  filename: "abc.80.conf"

Subsequently, the code is integrated into the codebase, resulting in the version number: v1.1.0.

During deployment, the v1.1.0 code is simply deployed.

With the version-based rollback mode, reverting is straightforward. It involves executing the code from v1.0.1 (the preceding version of v1.1.0) again.

Creating a platform based on this pattern is equally straightforward. The platform isn’t concerned with the specifics of the operation; its primary objective is to select the last correct version of the code for execution, thus facilitating the rollback process without encountering various issues associated with “reverse operation based on rollback mode” implementations.

This simplicity also facilitates the standardization of the platform’s deployment process.

However, it’s essential to note that the version-based rollback mode necessitates idempotent, declarative deployment code execution. Idempotent implies that running the same code multiple times yields the same outcome.

Summary

The version-based rollback model essentially constitutes deployment, utilizing an earlier version of deployment in lieu of traditional “rollback” procedures.

In conclusion, I trust this article has sparked some fresh perspectives.

- https://showme.codes/en/2024-03-06-two-patterns-for-rollback/ - showme.codes

回滚的两种模式

Tue, 05 Mar 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-03-05-rollback-pattern/ -

回滚是一种运维操作。通常发生在部署过程中发现问题，需要将目标环境恢复到部署前的状态。

在我看来，回滚有两种模式。其中一种是一步步执行反向操作，我称之为反向操作模式。

基于反向操作的回滚模式

可能是由于过去手工运维的思维方式的惯性，我发现不少人只知道这一种模式。

比如使用手工部署Nginx的配置的操作如下：

SSH登录到目标服务器
进入到存放Nginx的/etc/nginx/sites-enabled/目录
编辑目标配置文件vim example.443.conf
增加一个location配置
reload nginx使配置生效

在反向操作模式的回滚方案中，我们应该该如何回滚呢？1，2，3，5步骤与部署时一致。第4步，需要操作人员找到该配置，并删除。

这时，操作人员在操作时就可能会出错，而且出错了，你可能很难觉察到。因为他是手工操作的。

那么，有人就想，以上步骤能自动回滚就好了。

可是，该如何自动回滚呢？我们需要在部署时就设计好相应的自动化回滚脚本。当需要时，就触发其自动回滚。

然而这个回滚方案的方案是无法通用的，而且增加了运维成本。因为普通的运维人员对于一个Nginx的配置的变更，是非常不愿意写回滚的脚本的，而且，他本人也不一定能写出正确的、可靠的自动化回滚脚本。

那么，有人就会想了，我能否实现自动生成回滚代码的平台？

答案是可以的。你必须预先定义每一个步骤动作，比如在平台上将Nginx配置的修改作为一个动作定义。然后再定义它的反操作。

如果你是实现过类似平台项目，你会知道，这工作量是无穷无尽的。因为运维的操作是无穷无尽的。

你可以说平台可以提供自定义步骤动作的能力，那么你同样会遇到“他本人也不一定能写出正确的、可靠的自动化回滚脚本”的问题。而且，既然是平台了，定义操作的责任就应该是平台的责任。

所以，这是一个业界的难题。

在面试过程中，面试官通常假设我也会遇到同样的难题。然而，我根本不会遇到这个问题。

基于版本的回滚模式

我在解释这个模式时，很多人无法理解。

还是以部署Nginx配置为案例。但是通过Ansible来实现自动化部署。假设已经存在以下部署脚本：

- hosts: prod-nginx
  gather_facts: yes
  become: true
  vars_files: 
		# Nginx的配置
    - common_vars/nginx.yaml
  roles:
	 # Nginx的部署逻辑，是声明式的、幂等的。
    - ansible-role-nginx

以上代码含义大概是：部署Nginx到prod-nginx主机列表上，并使用common_vars/nginx.yaml文件中的配置。

nginx.yaml的配置如下：

nginx_vhosts:
- listen: "80"
  server_name: "*.example.com"
  return: "301 https://{{example_domain}}$request_uri"
  filename: "example.80.conf"

我们对以上代码版本化（提前到Git中，并通过自动化构建），得到版本号：v1.0.1。

现在我们需要像“反向操作的回滚模式”中的案例那样修改线上的配置时，我们的做法是在nginx.yaml配置增加相应的配置，最终效果如下：

nginx_vhosts:
- listen: "80"
  server_name: "*.example.com"
  return: "301 https://{{example_domain}}$request_uri"
  filename: "example.80.conf"
- listen: "80"
  server_name: "*.abc.com"
  return: "301 https://{{example_domain}}$request_uri"
  filename: "abc.80.conf"

然后将代码push到代码库中，经过构建，我们得到版本号：v1.1.0。

部署时，使用v1.1.0的代码部署即可。

基于版本的回滚模式，回滚就很简单了。就是再执行一次v1.0.1版本（v1.1.0的上一个版本）的代码就可以了。

基于这种模式实现平台化，也非常简单。平台不需要关心具体运行的内容，就要选择上一个正确的版本的代码执行，就完成了回滚。不会遇到“基于反向操作的回滚模式”的实现过程遇到的各种问题。

也因为这种简单化，平台实现部署的标准化，也非常简单。

但是，基于版本的回滚模式是有前提的，你的部署代码的执行必须是幂等的、声明式的。幂等的，指的是同一份代码，运行多次，得到的结果是一样的。

小结

基于版本的回滚模式准确来说，也是部署。也就是它使用老版本部署代替传统的“回滚”。

最后，希望这篇文章能给读者新的启发。

- https://showme.codes/zh-cn/2024-03-05-rollback-pattern/ - showme.codes

Jenkins kubernetes插件的原理

Mon, 26 Feb 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-02-26-jenkins-kubernetes-plugin/ -

如何使用

使用Kubernetes插件时，我们需要做三件事情：

根据官方文档，在Jenkins上加入kubernetes配置。
在Jenkinsfile中加入kubernetes agent的申明。
指定容器执行你的业务脚本。

关于第2点，kubernetes agent的申明又有两种方式。一种是脚本式的，代码样例如下：

podTemplate(containers: […]) {
  node(POD_LABEL) {
    stage('Run shell') {
      container('mycontainer') {
        sh 'echo hello world'
}}}}

一种是申明式，代码样例如下：

pipeline {
  stages {
    stage('Run maven') {
      agent {
        kubernetes {
              yaml """
                apiVersion: v1
                kind: Pod
                metadata:
                  labels:
                    app: jenkins-agent
                spec:
                  containers:
                  - name: maven
                    image: maven:alpine
                    command:
                    - cat
                    tty: true
                  - name: busybox
                    image: busybox
                    command:
                    - cat
                    tty: true
                """  
        }}
      steps {
        container('maven') {
          sh 'mvn -version'
}}}}}

笔者推荐使用申明式。yaml配置部分看起来并不优雅，这是另一个话题。咱们今后再讲。

原理

我们都知道Jenkins是master/agent的架构。而master与agent之间通信方法有两种：

通过JNLP协议：需要启动JNLP客户端主动连接master。这是Kubernetes插件使用的方式。
通过SSH协议：master使用SSH主动连接agent机器。

Kubernetes插件的具体的做法就是连接到Kubernetes集群，然后启动一个Pod。Pod中包含一个JNLP客户端，容器名约定为：jnlp。jnlp 会主动连接Jenkins master。

所以，当你发现Jenkins任务的日志中，一直在等待jnlp连接时，我们可以这样查问题：

查看相应的Pod是否存活。
jnlp 容器连接不上master：大概率是配置不对。

可是，我们看到上面的示例代码中，都没有叫jnlp的容器呢。这是因为Jenkins kubernates插件在真正创建pod前，为我们混入了默认的jnlp的容器定义。也就是，最终执行的yaml其实是：

apiVersion: v1
kind: Pod
metadata:
  labels:
    some-label: some-label-value
spec:
  containers:
  - name: jnlp
    image: jenkins/jnlp-slave:alpine
    args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)']
  - name: maven
    image: maven:alpine
    command:
    - cat
    tty: true
...省略其它

最后，pod启动后，pod中的jnlp容器会连上Jenkins master。当pipeline运行到以下代码：

container('maven') {
 sh 'mvn -version'
}

kubernates插件会找到名为maven的容器，然后将闭包内的代码发给它执行。

以上基本就是kubernates插件全部。

更换jnlp实现

当我们知道它的原理后，我们也就可以更换jnlp的实现镜像了。比如有些同学是在arm架构的机器上执行Kubernetes的，那么，他可以创建一个基于arm架构的jnlp镜像，然后，加入到yaml中。比如：

containers:
  - name: jnlp
    image: supercom.com/jnlp-arm-agent:1.0
    args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)']

小结

总的来说，它的原理无非就是创建pod，pod中的jnlp容器连接到Jenkins master，然后Jenkins master根据需要，将需要执行的命令发送给相应的容器执行。

附录

Jenkins kubernetes源码：https://github.com/jenkinsci/kubernetes-plugin
混入jnlp容器的代码位置：org.csanchez.jenkins.plugins.kubernetes.PodTemplateBuilder#build()
创建pod的代码位置：org.csanchez.jenkins.plugins.kubernetes.KubernetesLauncher#launch

- https://showme.codes/zh-cn/2024-02-26-jenkins-kubernetes-plugin/ - showme.codes

K8s工程化：K8s中的Java应用出现OOM后怎么办？

Mon, 26 Feb 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-2-26-jvm-oom-kubernetes/ -

完整代码在文末

背景

前段时间，线上系统出现了两次持续时间比较长的事故。这两次事故暴露我在某些方面的不足。同时，也意识到在SRE这个领域，经验的重要性。

事故过程中，我们发现大量的FullGC。当时，我们想到了要dump内存出来分析，可惜发现没有加-XX:HeapDumpPath参数。同时，我们也发现，如果dump出来了，我们也没法拿到dump出来的文件。因为我们的应用是跑在K8s中的。

方案调研

经复盘，我们得到一个action：在Java应用出现OOM时，将内存dump出来，并持久化，并且方便分析。

这个action可以细分为两个任务：

OOM时，dump内存出来；
提供一种途径方便分析。

经过权衡，任务2的优先级是可以降低的。puvad只要把任务1做好就可以。所以，这两个任务最终变成：在Java应用出现OOM时，将内存dump到NAS中。

笔者在网上搜索一通，看到的方案基本就是启动一个sidecar容器，与应用共享一个目录。然后监控这个目录，发现内容就上传到s3这类对象存储中。

这种方案的问题在于：

sidecar在传输过程，有出现问题的风险；
为了OOM这个小概率事件启动一个sidecar，资源有点浪费。

个人觉得，Java应用的Pod应该只负责将OOM时的内存dump到NAS即可，其它事情应该由其它Pod完成。

具体实现

以下方案是基于Helm自动化部署。如果你使用的是其它自动化部署工具，思路大体相同。

准备NFS服务

这部分不是本文范畴。

Java应用启动时参数配置

在Dockerfile中必须将变量$JAVA_OPTS加入到启动参数中。

FROM openjdk:11.0.12-jre-buster
COPY target/app.jar /app.jar
CMD java -jar $JAVA_OPTS /app.jar

加入InitContainers

作用：创建符合指定规则的Dump目录（注意DUMP_FOLDER变量的定义）。如下代码，在init容器启动后，它会创建目录：/nfs/dump/default/jvm-oom-example/10.233.66.38 。在应用出现OOM，内存文件会被dump在此目录下。

initContainers:
- name: init
  image: registry.cn-shenzhen.aliyuncs.com/aliacs-app-catalog/busybox:1.30.1
  command: ['sh', '-c', 'echo $DUMP_FOLDER;mkdir -p $DUMP_FOLDER']
  {{- with .Values.volumeMounts }}
  volumeMounts:
  {{- toYaml . | nindent 12 }}
  {{- end }}
  env:
  - name: MY_NODE_NAME
      valueFrom:
      fieldRef:
          fieldPath: spec.nodeName
  - name: MY_POD_NAME
      valueFrom:
      fieldRef:
          fieldPath: metadata.name
  - name: MY_POD_NAMESPACE
      valueFrom:
      fieldRef:
          fieldPath: metadata.namespace
  - name: MY_POD_IP
      valueFrom:
      fieldRef:
          fieldPath: status.podIP
  - name: DUMP_FOLDER
      value: "/nfs/dump/$(MY_POD_NAMESPACE)/{{ include "app.fullname" . }}/$(MY_POD_IP)"

配置应用容器

我们要做的，其实就是设置JAVA_OPTS环境变量。这里要注意的是JAVA_OPTS可以由三部分组成的：

内存大小设置，比如：-Xmx640M Xms640M 这类；
GC算法设置，比如：-XX:+UseSerialGC
JVM日志设置，比如：-XX:ErrorFile=/dump/hs_err_pid%p.log -XX:HeapDumpPath=/dump。

1,2部分应该是由用户决定。第3部分是由平台决定的。

所以，我们的配置JAVA_OPTS分成两部分：DUMP_ARGS 和用户的JVM配置。代码如下：

containers:
- name: {{ .Chart.Name }}
  {{- with .Values.volumeMounts }}
  volumeMounts:
    {{- toYaml . | nindent 12 }}
  {{- end }}
  env:
    - name: MY_NODE_NAME
      valueFrom:
        fieldRef:
          fieldPath: spec.nodeName
    - name: MY_POD_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
    - name: MY_POD_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: MY_POD_IP
      valueFrom:
        fieldRef:
          fieldPath: status.podIP
    - name: DUMP_FOLDER
      value: "/nfs/dump/$(MY_POD_NAMESPACE)/{{ include "app.fullname" . }}/$(MY_POD_IP)"
    - name: DUMP_ARGS
      value: "-XX:ErrorFile=$(DUMP_FOLDER)/hs_err_pid.log  -XX:HeapDumpPath=$(DUMP_FOLDER) -XX:+HeapDumpOnOutOfMemoryError"
    - name: JAVA_OPTS
      value: "{{.Values.javaOpts}} $(DUMP_ARGS)"

最终效果

[vagrant@k8s-3 jvm-oom]$ pwd
/persistentvolumes/dump/default/jvm-oom
[vagrant@k8s-3 jvm-oom]$ tree
.
├── 10.233.66.37
└── 10.233.66.38
    └── java_pid6.hprof

小结

这个方案并不是没有缺点。比如每次Pod启动都会创建一个目录，不论是否出现OOM。当然，这个缺点的解决方案也很简单，另启一个Pod负责清理就好了。

完成代码地址：https://github.com/zacker330/jvm-oom-example

- https://showme.codes/zh-cn/2024-2-26-jvm-oom-kubernetes/ - showme.codes

Kubernetes包管理器Helm的本质

Mon, 26 Feb 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-2-26-theory-of-helm/ -

“本质”类的文章，通常很难带流量。而且写起来非常吃力。

那我为什么还要写？写作是对自己的锻炼。写作是让自己的思想更有深度的一种有效方式。

如果你觉得这篇文章对你有帮助，也你麻烦你转发这篇文章，这是对我的帮助。谢谢。

Kubernetes 的包管理器的本质

“Helm 是 Kubernetes 的包管理器”。Helm的官方网站如是说。

那什么是“Kubernetes 的包管理器”？

我们假设需要在没包管理器的场景下部署资源，你需要一个个文件手工地执行kubectl apply -f abc.yaml，abc.yaml就是Kubernetes的资源的定义文件。

文件内容如下：

---
apiVersion: apps/v1
kind: Deployment
metadata:
	name: abc
	labels:
		app.kubernetes.io/name: abc
spec:
	replicas: 1
	selector:
		matchLabels:
			app.kubernetes.io/name: abc

当需要卸载资源呢？你又需要手工执行kubectl delete -f abc.yaml。

所以每次发布，你都必须有一个发布记录，记录下哪些YAML要执行apply，哪些yaml要执行delete。而且delete后，你还要记得将那个文件从文件夹中删除。

如果每次手工执行，工作量大不说，还很容易出错。所以，有人会想到使用Shell脚本或者Python脚本来解决这些问题。

当你通过Shell脚本或者Python脚本能自动化解决以上问题时，实际上就等于实现了一个Kubernetes 的包管理器。

当我们真正理解以上所说的Kubernetes资源的部署问题后，你就明白了Kubernetes 的包管理器其实就两个核心功能：

自动化执行Kubenetes资源更新；
跟踪Kubenetes资源更新记录（本质还是版本化）。

我们在选择包管理器时，务必要从这两个角度考虑。像Grafana公司Tanka，并不是一开始就实现“跟踪Kubenetes资源更新记录”功能，具体可以看：https://github.com/grafana/tanka/issues/88 。

Helm是如何实现包管理的

注：本文讲的是Helm3。Helm2与Helm3存在较大差异。

Helm的包：Chart

假如存在一个微服务x，我们将其部署到Kubernetes中，需要准备Deployment、HPA、Service的这三种资源的YAML文件。这三个文件，统一放在一个文件夹中。

Helm本身是一个命令行工具。通过package子命令，可以将整个文件夹打包成一个tgz的压缩包。打包命令为：helm package x-service --version 1.0 。打包结果是一个tgz包。如下图：

这个tgz包，我们称之为Chart包。本质上它就是Kubernetes的资源文件的一个集合。

我们可以将Chart包上传到Nexus这类制品管理工具进行版本化控制。这涉及到Chart的管理的工程实践，不在本文范围。

在有了Chart包以后，我们可以通过命令helm install <release> <chart路径>将svc安装到指定的Kubernetes集群上。如x-svc的部署指令将会是：helm install x-svc ./x-svc-1.0.tgz。

release是Helm的一个概念，即发布名。每执行一次helm install，对于Helm来说就是创建一个release。通常我们使用应用名作为发布名。

release这个概念在资源变更跟踪中环节非常重要。后面会反复使用此概念。

使用模板技术解决Chart的规模性问题

实际工作中，我们还会有y-svc、z-svc……n个服务。我们是不是每个服务要创建一个Chart？另外，每个服务都将被部署到三个环境中，那么，是不是每个环境还要单独又创建一个Chart？最终，我们需要服务与环境两个维度进行排列组合个Chart。

如果不能很好解决这个问题。Chart的数量会爆炸式增长。Helm如何解决这个问题呢？

它通过模板技术解决。换句话说，就是将Chart中资源文件中的容易变化的部分配置抽离出来变成变量，不变的部分变成模板。

变量部分配置统一放在Chart包中的values.yaml文件中。所以，这部分配置，我们通常也称为values配置，或者values文件。

这样，我们的Chart包的结构就变成如下（实际还有一些别的文件，但是不是本文讨论范围）：

对于Chart中不变的部分，Helm使用gotemplate模板语言进行描述。就是说我们可以在deployments.yaml中直接写gotemplate模板语言了，如代码1：

apiVersion: apps/v1
kind: Deployment
metadata:
	name: {{ .Values.name }}
	labels:
	{{- include "demo.labels" . | nindent 4 }}
...篇幅有限，省略
		resources:
			{{- toYaml .Values.resources | nindent 12 }}

我们无意挑起模板语言的战争，我们对gotemplate没有好感。你需要小心翼翼地去维护模板文件中的空格数量。如代码1的最后一行，它的意思是指该YAML块缩进12个空格。

关键问题我们该如何确定它应该是12，而不是10呢？而且，如果重构这部分代码，我又要重新算一次空格的数量！

使用gotemplate作为它的模板语言是它的最大错误。我们可能需要另外写一篇文章介绍规避这个问题的方法。

在写Helm的gotemplate模板时，建议不要写太复杂的逻辑，代码宁可重复，甚至另创建一个新的Chart。

执行资源变更

当values与Chart都已经准备好之后，我们通过以下命令，即可将x-svc的所有的资源部署到指定的namespace中：

helm install x-svc ./svc-chart-1.0.tgz -f x-svc-value.yaml

注意，一个不存在的服务，首次部署时是要执行install子命令。将来更新时，就只能执行upgrade子命令了。

以此类推，y-svc的部署命令就是：

helm install y-svc ./svc-chart-1.0.tgz -f y-svc-value.yaml

在执行install成功后，如果你需要修改该release，你需要执行upgrade指令，如下：

helm upgrade y-svc ./svc-chart-2.0.tgz -f y-svc-value.yaml

但是，helm是如何知道是要执行创建/变更资源，还是要执行删除资源呢？svc-chart-2.0.tgz比1.0版本可能少了deployment资源。

这就涉及到资源变更的跟踪了。

资源变更跟踪

在介绍“资源变更跟踪”前，我们先介绍几个重要的相关子命令：

upgrade：更新已存在的release。如：helm upgrade y-svc ./svc-chart-1.0.tgz -f y-svc-value.yaml；
list：列出所有的已经安装的release；
rollback: 将指定的release进行回滚。甚至可以指定回滚到某个版本，命令：helm rollback <RELEASE> [REVISION] [flags]；
history: 列出release的发布记录。

有些同学可能发现问题了：执行helm命令时，即没有默认的，也没有显示指定的release持久化方式，这些release信息是记录在哪里的？

同时，这又与我们上文说的“资源变更跟踪”有什么关系？

它们是相关的。Helm的核心原理就在此：

当首次部署时，使用install，这时，Helm会直接在指定命名空间（默认是default）下，创建一个helm.sh/release类型的secret。secret的名称定义为：sh.helm.release.v1.release.v1。secret的内容是这次执行的所有的Kubernetes资源的YAML内容。
当使用upgrade更新时，Helm从sh.helm.release.v1.release.v1的secret取出所有的YAML资源内容与本次将要执行更新的YAML资源内容进行对比，计算出本次更新需要执行的操作，是删除，变更。源码：https://github.com/helm/helm/blob/main/pkg/action/upgrade.go#L286
当upgrade执行成功，Helm会创建名为sh.helm.release.v1.release.v2的secret。当你看到这个v2的时候，你就已经知道了。Helm是通过结合secret的名称约定和secret的内容来记录下每一次发布的。当下次upgrade时，Helm会取v2的secret，然后执行更新，并创建v3的secret。以此类推。

为了展示的更友好，Helm把这些底层都隐藏下来了，所以，当你执行history指令时，你看到的将是：

截图取自Helm官网

至此，整个Helm的本质，已经介绍完。剩下细节可以通过查文档学习了。

小结

虽然本文标题写的是Helm的本质，其实写的是Kubernetes的包管理器的本质：

自动化执行Kubenetes资源更新；
跟踪Kubenetes资源更新记录（本质还是版本化）。

你可以拿这两次去评估Kustomize或者另的包管理工具。

- https://showme.codes/zh-cn/2024-2-26-theory-of-helm/ - showme.codes

SRE-DevOps不得不懂的：Prometheus的配置工程化

Mon, 26 Feb 2024 00:00:00 +0000

翟志军 Jack Zhai https://showme.codes/zh-cn/2024-2-26-prometheus-engineering/ -

背景

Prometheus有两个最基本的组件：一个是Prometheus程序，一个是Alertmanager程序。

它们的职责分工很明确：

Prometheus程序负责：定时拉取监控指标数据、存储指标数据、根据告警规则发起告警通知；
Alertmanager程序负责：负责告警通知的路由，即当接收到Prometheus程序的通知后，该将通知以何种方式通知给谁。

Prometheus程序的配置最核心的配置是：

# ... 

# 当指标数据符合什么规则进行告警通知。
# 在其它文件定义，这里只是引用该文件的路径。
rule_files:
  [ - <filepath_glob> ... ]

# 从哪里，该如何拉取指标
scrape_configs:
  [ - <scrape_config> ... ]
  
# ...

Alertmanager程序的配置最核心的配置是：

# ...
# 告警通知路由规则
route:
	[- <route_config>-]
# 告警通知的接收者列表，部分监控告警平台也称之为channel
receivers:
	[- <receivers>-]
# ...

在实际工作中，Prometheus和Alertmanager的配置会非常大。

严谨的软件工程要求我们在真正部署这些配置前，对其进行有效性和正确性的检查。否则SRE/DevOps的工程效率就会很低，因为你需要手工调试庞大的配置。

所以，我们需要有一种高效率的方式来保证配置的有效性和正确性。

保证Prometheus程序配置的有效性和正确性

promtool

Prometheus程序提供了一个叫promtool的命令行程序。解压Prometheus的程序包后，你会发现它和Prometheus程序放在一个文件夹中。

promtool提供了一些子命令来保证Prometheus程序配置的有效性和正确性：

# 校验Prometheus配置的有效性，它支持--lint="duplicate-rules"参数，用于检查重复的rule配置
check config [<flags>] <config-files>...
# 校验rule配置的有效性
check rules [<flags>] <rule-files>...
# 执行rules单元测试用例
test rules <test-rule-file>...

至于有效性检查，只需要执行check子命令即可，不需要过多说明。

promtool的test rules子命令可以实现rule配置的单元测试，具体命令如下：

./promtool test rules test.yml

test.yaml是单元测试描述文件。promtool是支持同时指定多个单元测试文件的，如：./promtool test rules test.yml test1.yml test2.yml

单元测试描述文件内容的格式如下：

# Prometheus的rule配置文件路径
rule_files:
    - rule1.yml

# 评估的间隔时长
evaluation_interval: 1m

# 单元测试列表
tests:
- interval: 1m
  input_series:
  alert_rule_test:
  promql_expr_test:

tests下的每个用例由4个字段组成：

input_series：测试用例的测试数据，即指标的时序数据；
interval：代表每个时序数据之间的间隔时长；
alert_rule_test：告警规则的测试用例；
promql_expr_test：promql表达式的测试用例。我们可以使用它进行调试我们的promsql。

接下来将详细介绍它们。

测试用例数据

测试用例数据的定义格式如下：

  input_series:
  - series: 'up{job="prometheus", instance="localhost:9090"}'
	values: '0 0 0 0 0 0 0 0 0 0 0 0 0 0 0'
  - series: 'up{job="node_exporter", instance="localhost:9100"}'
	values: '1+0x6 0 0 0 0 0 0 0 0' 
  - series: 'go_goroutines{job="prometheus", instance="localhost:9090"}'
	values: '10+10x2 30+20x5' 
  - series: 'go_goroutines{job="node_exporter", instance="localhost:9100"}'
	values: '10+10x7 10+30x4'

每一条input_serie由两个字段组成：

series：指标时序数据的key
values：指标的value。其中的每一个值之间的间隔时长是interval的值

为了简化values的值的定义，你可以一种扩展符号来定义其值。语法如下：

a+bxc代表：a a+b a+(2*b) a+(3*b) … a+(c*b)；这一个a值是起始值的序列，然后a以b的(0..c)的倍数进行递增；
a-bxc表示：这一个a值是起始值的序列，然后a以b的(0..c)的倍数进行递减；
_下划线表示：序列中的某次指标值没有被抓取到；
stale表示：过期的样本数据。以下是一些来自官方文档的例子：
-2+4x3表示：-2 2 6 10
1-2x4表示：1 -1 -3 -5 -7
1x4表示：1 1 1 1 1
1 _x3 stale表示：1 _ _ _ stale
1+0x6 0 0 0 0 0 0 0 0表示： 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0
10+10x2 30+20x5表示：10 20 30 30 50 70 90 110 130

测试Promsql表达式

在写Prometheus告警规则时，一个很大的痛点就是无法简单的验证自己写的promsql的正确性。我们在告警规则的单元测试中验证后，再配置到真正的rule文件中。

promsql的测试用例的写法如下：

  promql_expr_test:
  - expr: go_goroutines > 5 
	# 要测试的promsql表达式，它将会从测试数据中查询数据
	eval_time: 4m
	# 评估时长。从测试数据的第0秒开始算。
	# 如果interval是1m，那么4m代表的是测试数据的第4个数值
	exp_samples: # 执行promsql表达式后，预期得到的数据结果
		- labels: 'go_goroutines{job="prometheus",instance="localhost:9090"}'
		  value: 50
		- labels: 'go_goroutines{job="node_exporter",instance="localhost:9100"}'
		  value: 50

告警规则的单元测试

在单元测试描述文件中，添加Promsql表达式的测试用例的同时，我们还可以添加告警规则的测试用例，代码样例如下：

alert_rule_test:
- eval_time: 10m
  alertname: InstanceDown
  exp_alerts:
  - exp_labels:
	  severity: page
	  instance: localhost:9090
	  job: prometheus
	exp_annotations:
	  summary: "Instance localhost:9090 down"
	  description: "localhost:9090 of job prometheus has been down for more than 5 minutes."

eval_time：规则评估时长；
alertname：告警名，要求与Prometheus的告警规则中的alertname一致；
exp_labels：预期收到的告警通知中的label值；
exp_annotations：预期收到的告警通知中的annotation值。

保证Alertmanager程序配置的有效性和正确性

amtool

与Prometheus程序类似，Alertmanager程序提供了一个叫amtool的命令行程序。

我们关注它的两个子命令：

config routes test：验证配置的正确性
check-config <config.yaml>：验证配置的有效性

config routes test子命令介绍

amtool不像promtool那样支持在YAML文件中定义测试用例，以下是它的命令样例： amtool config routes test --config.file=config.yaml --verify.receivers=team-X-pager service=database owner=team-X

--config.file参数指定了配置文件的路径。

除了支持指定配置的路径，还可以通过参数--alertmanager.url指定使用某个运行中的Alertmanager的配置。

--verify.receivers指定期望返回的receiver列表，使用逗号分隔。

该子命令的最后是标签集，由key=value的格式组成，并使用空格分隔。例子中service=database owner=team-X，代表的是{service="database",owner="team-X"}

为了更好的可视化，还可以加一个--tree的参数，效果如下：

% amtool config routes test --config.file=config.yaml --tree --verify.receivers=team-X-pager service=database owner=team-X

Matching routes:
.
└── default-route
    └── {service="database"}
        └── {owner="team-X"}  receiver: team-X-pager

如果验证失败，该命令返回非0结果。

check-config子命令介绍

它的运行效果如下：

% amtool check-config config.yaml
Checking 'config.yaml'  SUCCESS
Found:
 - global config
 - route
 - 1 inhibit rules
 - 5 receivers
 - 1 templates
  SUCCESS

如果验证失败，该命令返回非0结果。

可视化告警通知路由

Prometheus官网提供了一个告警通知路由的在线可视化编辑器。

将配置粘贴至编辑框中，然后在“Match Label Set”中输入告警的标签，最后下方会显示通知的路由路径。如下图，实心红点即是匹配了该label的receiver：

pro

可视化工具在路由配置调试阶段非常有用。减小了路由配置的难度。但是，需要注意：不要将任何敏感配置上传到公网。

如何集成到CI/CD Pipeline中

以上介绍的是两个命令最原始的使用方法，即手工运行。我们需要将其集成到CI/CD pipeline中，以实现工程化。

集成方式一般有两：

在Pipeline中增加一个执行promtool和amtool的阶段
集成构建工具中，比如集成到Bazel中。

当然有一些DevOps平台如果需要深度集成，可以将promtool的amtool的实现代码引入到自己的DevOps平台的代码中。

工程化的挑战

另一个工程化的挑战，就是以上的配置文件之间存在引用，如下prometheus的rule文件中的expr字段的值，实际上是被prometheus-unitesting.yml文件引用。

如果不对这个引用关系进行治理，这些配置的维护成本将会非常高。

由于YAML文件天生不具备变量定义的功能。可以采用类似Jsonnet、CUE这样的支持编程的配置语言代替YAML。

这个话题比较大，不在本文讨论范围。

- https://showme.codes/zh-cn/2024-2-26-prometheus-engineering/ - showme.codes