Tony Bai » Redhat

代码之外的必修课：顶级技术文档风格指南如何提升你的工程效率

bigwhite — Mon, 14 Jul 2025 12:30:40 +0000

本文永久链接 – https://tonybai.com/2025/07/14/writing-style-guide

大家好，我是Tony Bai。

作为一名开发者、架构师或运维专家，我们大部分时间都在与代码、系统和架构打交道。然而，我们同样在持续不断地进行另一种形式的“编码”——沟通编码。无论是撰写一个清晰的 README.md，提交一份详尽的 Pull Request 描述，编写项目内部的技术文档，还是在社区中回答一个问题，我们都在扮演着“技术作者”的角色。

代码的质量决定了软件能否运行，而沟通的质量则决定了项目能否高效协作、知识能否有效传承、社区能否健康发展。一份糟糕的文档，如同晦涩难懂的“面条代码”，会极大地消耗团队的精力和热情。

最近，Redhat公司发布了《Red Hat Technical Writing Style Guide》7.1版本。这份指南不仅仅是一系列规则的集合，它更像是一部由顶级开源软件公司沉淀下来的、关于如何通过清晰沟通来提升工程效率的哲学。

在这篇文章中，我将提炼其中的一些精髓，探讨那些能直接提升您和团队工程能力的写作原则，供大家参考。

写作的“第一性原理”：清晰、精确、用户至上

技术文档的首要目标是传递信息，任何模糊、冗长或模棱两可的表达都是工程效率的天敌。指南强调了几个核心原则：

1. 拥抱主动语态，指令明确无误

主动语态让指令更直接、更有力。在指导性文档中，这能显著降低读者的认知负荷。

不推荐 (被动语态)	推荐 (主动语态)
Linuxconf can be started by typing …	Type … to start Linuxconf.
新的配置可以被应用通过重启服务。	重启服务以应用新的配置。

对开发者的价值：当用户（或未来的你）阅读操作手册时，清晰的指令意味着更低的出错率和更快的解决问题速度。

2. 杜绝冗余，尊重读者的时间

避免使用不必要的填充词，让每一句话都言之有物。

冗余	精炼
Perform the installation of the product.	Install the product.
This problem is located on the /dev/sda1 partition.	This problem is on the /dev/sda1 partition.

3. 避免歧义：This 指的是什么？

在技术文档中，代词（如 this, that, it）是歧义的重灾区，尤其对于翻译和非母语阅读者。指南建议明确指出代词所指代的的名词。

- A site can use these to self-assign a private routable IP address space.
+ A site can use these unique local addresses to self-assign a private routable IP address space.

- This causes SSH to lose the recorded identities.
+ This action causes SSH to lose the recorded identities.

对开发者的价值：在复杂的配置说明或问题排查指南中，消除代词歧义可以防止因误解而导致的配置错误。

为全球化社区而写：包容性与可翻译性

开源项目和现代技术团队本质上是全球化的。我们的文档需要被不同文化背景的人阅读和翻译。

1. 使用包容性语言

这是现代技术社区的基石。避免使用可能带有偏见或冒犯性的术语，有助于建立一个更健康、更多元化的社区环境。

master/slave -> 推荐使用 primary/replica, controller/worker, leader/follower 等。
whitelist/blacklist -> 推荐使用 allowlist/denylist 或 blocklist。
性别代词 -> 避免使用 he/she，推荐使用中性的 they（可指代单数）或直接使用第二人称 you。

2. 为翻译而设计

糟糕的措辞会给机器翻译和人工翻译带来灾难。一些简单的规则可以极大地提升文档的可翻译性：

避免使用俚语和行话：eat your own dogfood (使用自己的产品), boil the ocean (范围过大) 等表达在其他文化中可能完全无法理解。
慎用 may 和 should：may 可能表示“可能性”或“许可”，should 可能表示“建议”或“期望”。使用 can (可以), might (可能), must (必须) 会更精确。
避免名词堆叠：Standard system log management configuration 这种连续名词的组合，在翻译时极易出错。可以调整为 Standard configuration of system log management。

工程师的文字“代码规范”：一致性与标准化

如同 eslint 或 gofmt 为代码提供规范一样，风格指南为我们的文字提供了“格式化”标准。这能确保整个项目文档风格统一，易于阅读和维护。

1. 统一命令语法文档

在展示命令行示例时，保持一致的格式至关重要。

# 一个清晰的命令语法示例
$ git clone [username@]hostname:/repository_filename [directory]

- 使用 $ 表示普通用户，# 表示 root 用户。
- 使用 [] 表示可选参数。
- 使用斜体或描述性词语（如 _filename_）表示 需替换的值。
- 在需要省略输出时，使用 ...output omitted... 标记，而不是随意删减。

2. 精确描述 UI 元素

当描述用户界面时，精确和简洁是关键。

直接了当：不说 Click the Save button，而说 Click Save。
名称匹配：文档中的 UI 元素名称（如按钮、菜单项）应与界面上显示的完全一致（包括大小写）。
导航路径：使用 -> 或 →清晰地表示导航路径，例如：Go to Monitoring → Metrics。

3. 避免产品名称的所有格

一个看似微小但能提升专业度的细节：

不推荐: Red Hat OpenShift’s Logging operator creates…
推荐: The Red Hat OpenShift Logging operator creates…

总结与展望：将沟通视为工程技艺

《红帽风格指南》带给我们的最大启示是：清晰、精确、专业的书面沟通不是一种“软技能”，而是工程技艺（Craftsmanship）不可或缺的一部分。它与编写高质量代码、设计健壮架构同等重要。

下一次，当你准备提交一个 Pull Request、更新一份 README，或撰写一篇技术博客时，不妨尝试运用其中的一两个原则：

将一个被动语态的句子改为主动语态。
检查是否有模糊的代词 it 或 this 可以被替换。
思考一下你使用的术语是否足够包容和全球通用。

投资于沟通，就是投资于整个团队的效率和项目的未来。正如一份优雅的代码令人赏心悦悦目，一份清晰的文档同样能带来极致的工程之美。

你的Go技能，是否也卡在了“熟练”到“精通”的瓶颈期？

想写出更地道、更健壮的Go代码，却总在细节上踩坑？
渴望提升软件设计能力，驾驭复杂Go项目却缺乏章法？
想打造生产级的Go服务，却在工程化实践中屡屡受挫？

继《Go语言第一课》后，我的《Go语言进阶课》终于在极客时间与大家见面了！

我的全新极客时间专栏《Tony Bai·Go语言进阶课》就是为这样的你量身打造！30+讲硬核内容，带你夯实语法认知，提升设计思维，锻造工程实践能力，更有实战项目串讲。

目标只有一个：助你完成从“Go熟练工”到“Go专家”的蜕变！现在就加入，让你的Go技能再上一个新台阶！

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。

使用Go开发Kubernetes Operator：基本结构

bigwhite — Mon, 15 Aug 2022 14:47:40 +0000

本文永久链接 – https://tonybai.com/2022/08/15/developing-kubernetes-operators-in-go-part1

注：文章首图基于《Kubernetes Operators Explained》修改

几年前，我还称Kubernetes为服务编排和容器调度领域的事实标准，如今K8s已经是这个领域的“霸主”，地位无可撼动。不过，虽然Kubernetes发展演化到今天已经变得非常复杂，但是Kubernetes最初的数据模型、应用模式与扩展方式却依然有效。并且像Operator这样的应用模式和扩展方式日益受到开发者与运维者的欢迎。

我们的平台内部存在有状态(stateful)的后端服务，对有状态的服务的部署和运维是k8s operator的拿手好戏，是时候来研究一下operator了。

一. Operator的优点

kubernetes operator的概念最初来自CoreOS – 一家被红帽(redhat)收购的容器技术公司。

CoreOS在引入Operator概念的同时，也给出了Operator的第一批参考实现：etcd operator和prometheus operator。

注：etcd于2013年由CoreOS以开源形式发布；prometheus作为首款面向云原生服务的时序数据存储与监控系统，由SoundCloud公司于2012年以开源的形式发布。

下面是CoreOS对Operator这一概念的诠释：Operator在软件中代表了人类的运维操作知识，通过它可以可靠地管理一个应用程序。

图：CoreOS对operator的诠释(截图来自CoreOS官方博客归档)

Operator出现的初衷就是用来解放运维人员的，如今Operator也越来越受到云原生运维开发人员的青睐。

那么operator好处究竟在哪里呢？下面示意图对使用Operator和不使用Operator进行了对比：

通过这张图，即便对operator不甚了解，你也能大致感受到operator的优点吧。

我们看到在使用operator的情况下，对有状态应用的伸缩操作(这里以伸缩操作为例，也可以是其他诸如版本升级等对于有状态应用来说的“复杂”操作)，运维人员仅需一个简单的命令即可，运维人员也无需知道k8s内部对有状态应用的伸缩操作的原理是什么。

在没有使用operator的情况下，运维人员需要对有状态应用的伸缩的操作步骤有深刻的认知，并按顺序逐个执行一个命令序列中的命令并检查命令响应，遇到失败的情况时还需要进行重试，直到伸缩成功。

我们看到operator就好比一个内置于k8s中的经验丰富运维人员，时刻监控目标对象的状态，把复杂性留给自己，给运维人员一个简洁的交互接口，同时operator也能降低运维人员因个人原因导致的操作失误的概率。

不过，operator虽好，但开发门槛却不低。开发门槛至少体现在如下几个方面：

对operator概念的理解是基于对k8s的理解的基础之上的，而k8s自从2014年开源以来，变的日益复杂，理解起来需要一定时间投入；
从头手撸operator很verbose，几乎无人这么做，大多数开发者都会去学习相应的开发框架与工具，比如：kubebuilder、operator framework sdk等；
operator的能力也有高低之分，operator framework就提出了一个包含五个等级的operator能力模型(CAPABILITY MODEL)，见下图。使用Go开发高能力等级的operator需要对client-go这个kubernetes官方go client库中的API有深入的了解。

图：operator能力模型(截图来自operator framework官网)

当然在这些门槛当中，对operator概念的理解既是基础也是前提，而理解operator的前提又是对kubernetes的诸多概念要有深入理解，尤其是resource、resource type、API、controller以及它们之间的关系。接下来我们就来快速介绍一下这些概念。

二. Kubernetes resource、resource type、API和controller介绍

Kubernetes发展到今天，其本质已经显现：

Kubernetes就是一个“数据库”(数据实际持久存储在etcd中)；
其API就是“sql语句”；
API设计采用基于resource的Restful风格, resource type是API的端点(endpoint)；
每一类resource(即Resource Type)是一张“表”，Resource Type的spec对应“表结构”信息(schema)；
每张“表”里的一行记录就是一个resource，即该表对应的Resource Type的一个实例(instance)；
Kubernetes这个“数据库”内置了很多“表”，比如Pod、Deployment、DaemonSet、ReplicaSet等；

下面是一个Kubernetes API与resource关系的示意图：

我们看到resource type有两类，一类的namespace相关的(namespace-scoped)，我们通过下面形式的API操作这类resource type的实例：

VERB /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE - 操作某特定namespace下面的resouce type中的resource实例集合
VERB /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME - 操作某特定namespace下面的resource type中的某个具体的resource实例

另外一类则是namespace无关，即cluster范围(cluster-scoped)的，我们通过下面形式的API对这类resource type的实例进行操作：

VERB /apis/GROUP/VERSION/RESOURCETYPE - 操作resouce type中的resource实例集合
VERB /apis/GROUP/VERSION/RESOURCETYPE/NAME - 操作resource type中的某个具体的resource实例

我们知道Kubernetes并非真的只是一个“数据库”，它是服务编排和容器调度的平台标准，它的基本调度单元是Pod(也是一个resource type)，即一组容器的集合。那么Pod又是如何被创建、更新和删除的呢？这就离不开控制器(controller)了。每一类resource type都有自己对应的控制器(controller)。以pod这个resource type为例，它的controller为ReplicasSet的实例。

控制器的运行逻辑如下图所示：

图：控制器运行逻辑(引自《Kubernetes Operators Explained》一文)

控制器一旦启动，将尝试获得resource的当前状态(current state)，并与存储在k8s中的resource的期望状态（desired state，即spec)做比对，如果不一致，controller就会调用相应API进行调整，尽力使得current state与期望状态达成一致。这个达成一致的过程被称为协调(reconciliation)，协调过程的伪代码逻辑如下：

for {
    desired := getDesiredState()
    current := getCurrentState()
    makeChanges(desired, current)
}

注：k8s中有一个object的概念？那么object是什么呢？它类似于Java Object基类或Ruby中的Object超类。不仅resource type的实例resource是一个(is-a)object，resource type本身也是一个object，它是kubernetes concept的实例。

有了上面对k8s这些概念的初步理解，我们下面就来理解一下Operator究竟是什么！

三. Operator模式 = 操作对象(CRD) + 控制逻辑(controller)

如果让运维人员直面这些内置的resource type(如deployment、pod等)，也就是前面“使用operator vs. 不使用operator”对比图中的第二种情况, 运维人员面临的情况将会很复杂，且操作易错。

那么如果不直面内置的resource type，那么我们如何自定义resource type呢, Kubernetes提供了Custom Resource Definition，CRD(在coreos刚提出operator概念的时候，crd的前身是Third Party Resource, TPR)可以用于自定义resource type。

根据前面我们对resource type理解，定义CRD相当于建立新“表”(resource type)，一旦CRD建立，k8s会为我们自动生成对应CRD的API endpoint，我们就可以通过yaml或API来操作这个“表”。我们可以向“表”中“插入”数据，即基于CRD创建Custom Resource(CR)，这就好比我们创建Deployment实例，向Deployment“表”中插入数据一样。

和原生内置的resource type一样，光有存储对象状态的CR还不够，原生resource type有对应controller负责协调(reconciliation)实例的创建、伸缩与删除，CR也需要这样的“协调者”，即我们也需要定义一个controller来负责监听CR状态并管理CR创建、伸缩、删除以及保持期望状态(spec)与当前状态(current state)的一致。这个controller不再是面向原生Resource type的实例，而是面向CRD的实例CR的controller。

有了自定义的操作对象类型(CRD)，有了面向操作对象类型实例的controller，我们将其打包为一个概念：“Operator模式”，operator模式中的controller也被称为operator，它是在集群中对CR进行维护操作的主体。

四. 使用kubebuilder开发webserver operator

假设：此时你的本地开发环境已经具备访问实验用k8s环境的一切配置，通过kubectl工具可以任意操作k8s。

再深入浅出的概念讲解都不如一次实战对理解概念更有帮助，下面我们就来开发一个简单的Operator。

前面提过operator开发非常verbose，因此社区提供了开发工具和框架来帮助开发人员简化开发过程，目前主流的包括operator framework sdk和kubebuilder，前者是redhat开源并维护的一套工具，支持使用go、ansible、helm进行operator开发(其中只有go可以开发到能力级别5的operator，其他两种则不行)；而kubebuilder则是kubernetes官方的一个sig(特别兴趣小组)维护的operator开发工具。目前基于operator framework sdk和go进行operator开发时，operator sdk底层使用的也是kubebuilder，所以这里我们就直接使用kubebuilder来开发operator。

按照operator能力模型，我们这个operator差不多处于2级这个层次，我们定义一个Webserver的resource type，它代表的是一个基于nginx的webserver集群，我们的operator支持创建webserver示例(一个nginx集群)，支持nginx集群伸缩，支持集群中nginx的版本升级。

下面我们就用kubebuilder来实现这个operator！

1. 安装kubebuilder

这里我们采用源码构建方式安装，步骤如下：

$git clone git@github.com:kubernetes-sigs/kubebuilder.git
$cd kubebuilder
$make
$cd bin
$./kubebuilder version
Version: main.version{KubeBuilderVersion:"v3.5.0-101-g5c949c2e",
KubernetesVendor:"unknown",
GitCommit:"5c949c2e50ca8eec80d64878b88e1b2ee30bf0bc",
BuildDate:"2022-08-06T09:12:50Z", GoOs:"linux", GoArch:"amd64"}

然后将bin/kubebuilder拷贝到你的PATH环境变量中的某个路径下即可。

2. 创建webserver-operator工程

接下来，我们就可以使用kubebuilder创建webserver-operator工程了：

$mkdir webserver-operator
$cd webserver-operator
$kubebuilder init  --repo github.com/bigwhite/webserver-operator --project-name webserver-operator

Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
Get controller runtime:
$ go get sigs.k8s.io/controller-runtime@v0.12.2
go: downloading k8s.io/client-go v0.24.2
go: downloading k8s.io/component-base v0.24.2
Update dependencies:
$ go mod tidy
Next: define a resource with:
kubebuilder create api

注：–repo指定go.mod中的module root path，你可以定义你自己的module root path。

3. 创建API，生成初始CRD

Operator包括CRD和controller，这里我们就来建立自己的CRD，即自定义的resource type，也就是API的endpoint，我们使用下面kubebuilder create命令来完成这个步骤：

$kubebuilder create api --version v1 --kind WebServer
Create Resource [y/n]
y
Create Controller [y/n]
y
Writing kustomize manifests for you to edit...
Writing scaffold for you to edit...
api/v1/webserver_types.go
controllers/webserver_controller.go
Update dependencies:
$ go mod tidy
Running make:
$ make generate
mkdir -p /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin
test -s /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen || GOBIN=/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests

之后，我们执行make manifests来生成最终CRD对应的yaml文件：

$make manifests
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases

此刻，整个工程的目录文件布局如下：

$tree -F .
.
├── api/
│   └── v1/
│       ├── groupversion_info.go
│       ├── webserver_types.go
│       └── zz_generated.deepcopy.go
├── bin/
│   └── controller-gen*
├── config/
│   ├── crd/
│   │   ├── bases/
│   │   │   └── my.domain_webservers.yaml
│   │   ├── kustomization.yaml
│   │   ├── kustomizeconfig.yaml
│   │   └── patches/
│   │       ├── cainjection_in_webservers.yaml
│   │       └── webhook_in_webservers.yaml
│   ├── default/
│   │   ├── kustomization.yaml
│   │   ├── manager_auth_proxy_patch.yaml
│   │   └── manager_config_patch.yaml
│   ├── manager/
│   │   ├── controller_manager_config.yaml
│   │   ├── kustomization.yaml
│   │   └── manager.yaml
│   ├── prometheus/
│   │   ├── kustomization.yaml
│   │   └── monitor.yaml
│   ├── rbac/
│   │   ├── auth_proxy_client_clusterrole.yaml
│   │   ├── auth_proxy_role_binding.yaml
│   │   ├── auth_proxy_role.yaml
│   │   ├── auth_proxy_service.yaml
│   │   ├── kustomization.yaml
│   │   ├── leader_election_role_binding.yaml
│   │   ├── leader_election_role.yaml
│   │   ├── role_binding.yaml
│   │   ├── role.yaml
│   │   ├── service_account.yaml
│   │   ├── webserver_editor_role.yaml
│   │   └── webserver_viewer_role.yaml
│   └── samples/
│       └── _v1_webserver.yaml
├── controllers/
│   ├── suite_test.go
│   └── webserver_controller.go
├── Dockerfile
├── go.mod
├── go.sum
├── hack/
│   └── boilerplate.go.txt
├── main.go
├── Makefile
├── PROJECT
└── README.md

14 directories, 40 files

4. webserver-operator的基本结构

忽略我们此次不关心的诸如leader election、auth_proxy等，我将这个operator例子的主要部分整理到下面这张图中：

图中的各个部分就是使用kubebuilder生成的operator的基本结构。

webserver operator主要由CRD和controller组成：

图中的左下角的框框就是上面生成的CRD yaml文件：config/crd/bases/my.domain_webservers.yaml。CRD与api/v1/webserver_types.go密切相关。我们在api/v1/webserver_types.go中为CRD定义spec相关字段，之后make manifests命令可以解析webserver_types.go中的变化并更新CRD的yaml文件。

controller

从图的右侧部分可以看出，controller自身就是作为一个deployment部署在k8s集群中运行的，它监视CRD的实例CR的运行状态，并在Reconcile方法中检查预期状态与当前状态是否一致，如果不一致，则执行相关操作。

其它

图中左上角是有关controller的权限的设置，controller通过serviceaccount访问k8s API server，通过role.yaml和role_binding.yaml设置controller的角色和权限。

5. 为CRD spec添加字段(field)

为了实现Webserver operator的功能目标，我们需要为CRD spec添加一些状态字段。前面说过，CRD与api中的webserver_types.go文件是同步的，我们只需修改webserver_types.go文件即可。我们在WebServerSpec结构体中增加Replicas和Image两个字段，它们分别用于表示webserver实例的副本数量以及使用的容器镜像：

// api/v1/webserver_types.go

// WebServerSpec defines the desired state of WebServer
type WebServerSpec struct {
    // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
    // Important: Run "make" to regenerate code after modifying this file

    // The number of replicas that the webserver should have
    Replicas int `json:"replicas,omitempty"`

    // The container image of the webserver
    Image string `json:"image,omitempty"`

    // Foo is an example field of WebServer. Edit webserver_types.go to remove/update
    Foo string `json:"foo,omitempty"`
}

保存修改后，执行make manifests重新生成config/crd/bases/my.domain_webservers.yaml

$cat my.domain_webservers.yaml
---
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.9.2
  creationTimestamp: null
  name: webservers.my.domain
spec:
  group: my.domain
  names:
    kind: WebServer
    listKind: WebServerList
    plural: webservers
    singular: webserver
  scope: Namespaced
  versions:
  - name: v1
    schema:
      openAPIV3Schema:
        description: WebServer is the Schema for the webservers API
        properties:
          apiVersion:
            description: 'APIVersion defines the versioned schema of this representation
              of an object. Servers should convert recognized schemas to the latest
              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
            type: string
          kind:
            description: 'Kind is a string value representing the REST resource this
              object represents. Servers may infer this from the endpoint the client
              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
            type: string
          metadata:
            type: object
          spec:
            description: WebServerSpec defines the desired state of WebServer
            properties:
              foo:
                description: Foo is an example field of WebServer. Edit webserver_types.go
                  to remove/update
                type: string
              image:
                description: The container image of the webserver
                type: string
              replicas:
                description: The number of replicas that the webserver should have
                type: integer
            type: object
          status:
            description: WebServerStatus defines the observed state of WebServer
            type: object
        type: object
    served: true
    storage: true
    subresources:
      status: {}

一旦定义完CRD，我们就可以将其安装到k8s中：

$make install
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
test -s /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize || { curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -s -- 3.8.7 /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin; }
{Version:kustomize/v3.8.7 GitCommit:ad092cc7a91c07fdf63a2e4b7f13fa588a39af4f BuildDate:2020-11-11T23:14:14Z GoOs:linux GoArch:amd64}
kustomize installed to /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize build config/crd | kubectl apply -f -
customresourcedefinition.apiextensions.k8s.io/webservers.my.domain created

检查安装情况：

$kubectl get crd|grep webservers
webservers.my.domain                                             2022-08-06T21:55:45Z

6. 修改role.yaml

在开始controller开发之前，我们先来为controller后续的运行“铺平道路”，即设置好相应权限。

我们在controller中会为CRD实例创建对应deployment和service，这样就要求controller有操作deployments和services的权限，这样就需要我们修改role.yaml，增加service account: controller-manager 操作deployments和services的权限：

// config/rbac/role.yaml
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  creationTimestamp: null
  name: manager-role
rules:
- apiGroups:
  - my.domain
  resources:
  - webservers
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - my.domain
  resources:
  - webservers/finalizers
  verbs:
  - update
- apiGroups:
  - my.domain
  resources:
  - webservers/status
  verbs:
  - get
  - patch
  - update
- apiGroups:
  - apps
  resources:
  - deployments
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch
- apiGroups:
  - apps
  - ""
  resources:
  - services
  verbs:
  - create
  - delete
  - get
  - list
  - patch
  - update
  - watch

修改后的role.yaml先放在这里，后续与controller一并部署到k8s上。

7. 实现controller的Reconcile(协调)逻辑

kubebuilder为我们搭好了controller的代码架子，我们只需要在controllers/webserver_controller.go中实现WebServerReconciler的Reconcile方法即可。下面是Reconcile的一个简易流程图，结合这幅图理解代码就容易的多了：

下面是对应的Reconcile方法的代码：

// controllers/webserver_controller.go

func (r *WebServerReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    log := r.Log.WithValues("Webserver", req.NamespacedName)

    instance := &mydomainv1.WebServer{}
    err := r.Get(ctx, req.NamespacedName, instance)
    if err != nil {
        if errors.IsNotFound(err) {
            // Request object not found, could have been deleted after reconcile request.
            // Return and don't requeue
            log.Info("Webserver resource not found. Ignoring since object must be deleted")
            return ctrl.Result{}, nil
        }

        // Error reading the object - requeue the request.
        log.Error(err, "Failed to get Webserver")
        return ctrl.Result{RequeueAfter: time.Second * 5}, err
    }

    // Check if the webserver deployment already exists, if not, create a new one
    found := &appsv1.Deployment{}
    err = r.Get(ctx, types.NamespacedName{Name: instance.Name, Namespace: instance.Namespace}, found)
    if err != nil && errors.IsNotFound(err) {
        // Define a new deployment
        dep := r.deploymentForWebserver(instance)
        log.Info("Creating a new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
        err = r.Create(ctx, dep)
        if err != nil {
            log.Error(err, "Failed to create new Deployment", "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
            return ctrl.Result{RequeueAfter: time.Second * 5}, err
        }
        // Deployment created successfully - return and requeue
        return ctrl.Result{Requeue: true}, nil
    } else if err != nil {
        log.Error(err, "Failed to get Deployment")
        return ctrl.Result{RequeueAfter: time.Second * 5}, err
    }

    // Ensure the deployment replicas and image are the same as the spec
    var replicas int32 = int32(instance.Spec.Replicas)
    image := instance.Spec.Image

    var needUpd bool
    if *found.Spec.Replicas != replicas {
        log.Info("Deployment spec.replicas change", "from", *found.Spec.Replicas, "to", replicas)
        found.Spec.Replicas = &replicas
        needUpd = true
    }

    if (*found).Spec.Template.Spec.Containers[0].Image != image {
        log.Info("Deployment spec.template.spec.container[0].image change", "from", (*found).Spec.Template.Spec.Containers[0].Image, "to", image)
        found.Spec.Template.Spec.Containers[0].Image = image
        needUpd = true
    }

    if needUpd {
        err = r.Update(ctx, found)
        if err != nil {
            log.Error(err, "Failed to update Deployment", "Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)
            return ctrl.Result{RequeueAfter: time.Second * 5}, err
        }
        // Spec updated - return and requeue
        return ctrl.Result{Requeue: true}, nil
    }

    // Check if the webserver service already exists, if not, create a new one
    foundService := &corev1.Service{}
    err = r.Get(ctx, types.NamespacedName{Name: instance.Name + "-service", Namespace: instance.Namespace}, foundService)
    if err != nil && errors.IsNotFound(err) {
        // Define a new service
        srv := r.serviceForWebserver(instance)
        log.Info("Creating a new Service", "Service.Namespace", srv.Namespace, "Service.Name", srv.Name)
        err = r.Create(ctx, srv)
        if err != nil {
            log.Error(err, "Failed to create new Servie", "Service.Namespace", srv.Namespace, "Service.Name", srv.Name)
            return ctrl.Result{RequeueAfter: time.Second * 5}, err
        }
        // Service created successfully - return and requeue
        return ctrl.Result{Requeue: true}, nil
    } else if err != nil {
        log.Error(err, "Failed to get Service")
        return ctrl.Result{RequeueAfter: time.Second * 5}, err
    }

    // Tbd: Ensure the service state is the same as the spec, your homework

    // reconcile webserver operator in again 10 seconds
    return ctrl.Result{RequeueAfter: time.Second * 10}, nil
}

这里大家可能发现了：原来CRD的controller最终还是将CR翻译为k8s原生Resource，比如service、deployment等。CR的状态变化(比如这里的replicas、image等)最终都转换成了deployment等原生resource的update操作，这就是operator的精髓！理解到这一层，operator对大家来说就不再是什么密不可及的概念了。

有些朋友可能也会发现，上面流程图中似乎没有考虑CR实例被删除时对deployment、service的操作，的确如此。不过对于一个7×24小时运行于后台的服务来说，我们更多关注的是其变更、伸缩、升级等操作，删除是优先级最低的需求。

8. 构建controller image

controller代码写完后，我们就来构建controller的image。通过前文我们知道，这个controller其实就是运行在k8s中的一个deployment下的pod。我们需要构建其image并通过deployment部署到k8s中。

kubebuilder创建的operator工程中包含了Makefile，通过make docker-build即可构建controller image。docker-build使用golang builder image来构建controller源码，不过如果不对Dockerfile稍作修改，你很难编译过去，因为默认GOPROXY在国内无法访问。这里最简单的改造方式是使用vendor构建，下面是改造后的Dockerfile：

# Build the manager binary
FROM golang:1.18 as builder

ENV GOPROXY https://goproxy.cn
WORKDIR /workspace
# Copy the Go Modules manifests
COPY go.mod go.mod
COPY go.sum go.sum
COPY vendor/ vendor/
# cache deps before building and copying source so that we don't need to re-download as much
# and so that source changes don't invalidate our downloaded layer
#RUN go mod download

# Copy the go source
COPY main.go main.go
COPY api/ api/
COPY controllers/ controllers/

# Build
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod=vendor -a -o manager main.go

# Use distroless as minimal base image to package the manager binary
# Refer to https://github.com/GoogleContainerTools/distroless for more details
#FROM gcr.io/distroless/static:nonroot
FROM katanomi/distroless-static:nonroot
WORKDIR /
COPY --from=builder /workspace/manager .
USER 65532:65532

ENTRYPOINT ["/manager"]

下面是构建的步骤：

$go mod vendor
$make docker-build

test -s /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen || GOBIN=/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
go fmt ./...
go vet ./...
KUBEBUILDER_ASSETS="/home/tonybai/.local/share/kubebuilder-envtest/k8s/1.24.2-linux-amd64" go test ./... -coverprofile cover.out
?       github.com/bigwhite/webserver-operator    [no test files]
?       github.com/bigwhite/webserver-operator/api/v1    [no test files]
ok      github.com/bigwhite/webserver-operator/controllers    4.530s    coverage: 0.0% of statements
docker build -t bigwhite/webserver-controller:latest .
Sending build context to Docker daemon  47.51MB
Step 1/15 : FROM golang:1.18 as builder
 ---> 2d952adaec1e
Step 2/15 : ENV GOPROXY https://goproxy.cn
 ---> Using cache
 ---> db2b06a078e3
Step 3/15 : WORKDIR /workspace
 ---> Using cache
 ---> cc3c613c19c6
Step 4/15 : COPY go.mod go.mod
 ---> Using cache
 ---> 5fa5c0d89350
Step 5/15 : COPY go.sum go.sum
 ---> Using cache
 ---> 71669cd0fe8e
Step 6/15 : COPY vendor/ vendor/
 ---> Using cache
 ---> 502b280a0e67
Step 7/15 : COPY main.go main.go
 ---> Using cache
 ---> 0c59a69091bb
Step 8/15 : COPY api/ api/
 ---> Using cache
 ---> 2b81131c681f
Step 9/15 : COPY controllers/ controllers/
 ---> Using cache
 ---> e3fd48c88ccb
Step 10/15 : RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -mod=vendor -a -o manager main.go
 ---> Using cache
 ---> 548ac10321a2
Step 11/15 : FROM katanomi/distroless-static:nonroot
 ---> 421f180b71d8
Step 12/15 : WORKDIR /
 ---> Running in ea7cb03027c0
Removing intermediate container ea7cb03027c0
 ---> 9d3c0ea19c3b
Step 13/15 : COPY --from=builder /workspace/manager .
 ---> a4387fe33ab7
Step 14/15 : USER 65532:65532
 ---> Running in 739a32d251b6
Removing intermediate container 739a32d251b6
 ---> 52ae8742f9c5
Step 15/15 : ENTRYPOINT ["/manager"]
 ---> Running in 897893b0c9df
Removing intermediate container 897893b0c9df
 ---> e375cc2adb08
Successfully built e375cc2adb08
Successfully tagged bigwhite/webserver-controller:latest

注：执行make命令之前，先将Makefile中的IMG变量初值改为IMG ?= bigwhite/webserver-controller:latest

构建成功后，执行make docker-push将image推送到镜像仓库中(这里使用了docker公司提供的公共仓库)。

9. 部署controller

之前我们已经通过make install将CRD安装到k8s中了，接下来再把controller部署到k8s上，我们的operator就算部署完毕了。执行make deploy即可实现部署：

$make deploy
test -s /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen || GOBIN=/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin go install sigs.k8s.io/controller-tools/cmd/controller-gen@v0.9.2
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
test -s /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize || { curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -s -- 3.8.7 /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin; }
cd config/manager && /home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize edit set image controller=bigwhite/webserver-controller:latest
/home/tonybai/test/go/operator/kubebuilder/webserver-operator/bin/kustomize build config/default | kubectl apply -f -
namespace/webserver-operator-system created
customresourcedefinition.apiextensions.k8s.io/webservers.my.domain unchanged
serviceaccount/webserver-operator-controller-manager created
role.rbac.authorization.k8s.io/webserver-operator-leader-election-role created
clusterrole.rbac.authorization.k8s.io/webserver-operator-manager-role created
clusterrole.rbac.authorization.k8s.io/webserver-operator-metrics-reader created
clusterrole.rbac.authorization.k8s.io/webserver-operator-proxy-role created
rolebinding.rbac.authorization.k8s.io/webserver-operator-leader-election-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/webserver-operator-manager-rolebinding created
clusterrolebinding.rbac.authorization.k8s.io/webserver-operator-proxy-rolebinding created
configmap/webserver-operator-manager-config created
service/webserver-operator-controller-manager-metrics-service created
deployment.apps/webserver-operator-controller-manager created

我们看到deploy不仅会安装controller、serviceaccount、role、rolebinding，它还会创建namespace，也会将crd安装一遍。也就是说deploy是一个完整的operator安装命令。

注：使用make undeploy可以完整卸载operator相关resource。

我们用kubectl logs查看一下controller的运行日志：

$kubectl logs -f deployment.apps/webserver-operator-controller-manager -n webserver-operator-system
1.6600280818476188e+09    INFO    controller-runtime.metrics    Metrics server is starting to listen    {"addr": "127.0.0.1:8080"}
1.6600280818478029e+09    INFO    setup    starting manager
1.6600280818480284e+09    INFO    Starting server    {"path": "/metrics", "kind": "metrics", "addr": "127.0.0.1:8080"}
1.660028081848097e+09    INFO    Starting server    {"kind": "health probe", "addr": "[::]:8081"}
I0809 06:54:41.848093       1 leaderelection.go:248] attempting to acquire leader lease webserver-operator-system/63e5a746.my.domain...
I0809 06:54:57.072336       1 leaderelection.go:258] successfully acquired lease webserver-operator-system/63e5a746.my.domain
1.6600280970724037e+09    DEBUG    events    Normal    {"object": {"kind":"Lease","namespace":"webserver-operator-system","name":"63e5a746.my.domain","uid":"e05aaeb5-4a3a-4272-b036-80d61f0b6788","apiVersion":"coordination.k8s.io/v1","resourceVersion":"5238800"}, "reason": "LeaderElection", "message": "webserver-operator-controller-manager-6f45bc88f7-ptxlc_0e960015-9fbe-466d-a6b1-ff31af63a797 became leader"}
1.6600280970724993e+09    INFO    Starting EventSource    {"controller": "webserver", "controllerGroup": "my.domain", "controllerKind": "WebServer", "source": "kind source: *v1.WebServer"}
1.6600280970725305e+09    INFO    Starting Controller    {"controller": "webserver", "controllerGroup": "my.domain", "controllerKind": "WebServer"}
1.660028097173026e+09    INFO    Starting workers    {"controller": "webserver", "controllerGroup": "my.domain", "controllerKind": "WebServer", "worker count": 1}

可以看到，controller已经成功启动，正在等待一个WebServer CR的相关事件(比如创建)！下面我们就来创建一个WebServer CR!

10. 创建WebServer CR

webserver-operator项目中有一个CR sample，位于config/samples下面，我们对其进行改造，添加我们在spec中加入的字段：

// config/samples/_v1_webserver.yaml 

apiVersion: my.domain/v1
kind: WebServer
metadata:
  name: webserver-sample
spec:
  # TODO(user): Add fields here
  image: nginx:1.23.1
  replicas: 3

我们通过kubectl创建该WebServer CR：

$cd config/samples
$kubectl apply -f _v1_webserver.yaml
webserver.my.domain/webserver-sample created

观察controller的日志：

1.6602084232243123e+09  INFO    controllers.WebServer   Creating a new Deployment   {"Webserver": "default/webserver-sample", "Deployment.Namespace": "default", "Deployment.Name": "webserver-sample"}
1.6602084233446114e+09  INFO    controllers.WebServer   Creating a new Service  {"Webserver": "default/webserver-sample", "Service.Namespace": "default", "Service.Name": "webserver-sample-service"}

我们看到当CR被创建后，controller监听到相关事件，创建了对应的Deployment和service，我们查看一下为CR创建的Deployment、三个Pod以及service：

$kubectl get service
NAME                       TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
kubernetes                 ClusterIP   172.26.0.1             443/TCP        22d
webserver-sample-service   NodePort    172.26.173.0           80:30010/TCP   2m58s

$kubectl get deployment
NAME               READY   UP-TO-DATE   AVAILABLE   AGE
webserver-sample   3/3     3            3           4m44s

$kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
webserver-sample-bc698b9fb-8gq2h   1/1     Running   0          4m52s
webserver-sample-bc698b9fb-vk6gw   1/1     Running   0          4m52s
webserver-sample-bc698b9fb-xgrgb   1/1     Running   0          4m52s

我们访问一下该服务：

$curl http://192.168.10.182:30010



Welcome to nginx!



Welcome to nginx!
If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.

For online documentation and support please refer to
nginx.org.

Commercial support is available at
nginx.com.

Thank you for using nginx.

服务如预期返回响应！

11. 伸缩、变更版本和Service自愈

接下来我们来对CR做一些常见的运维操作。

副本数由3变为4

我们将CR的replicas由3改为4，对容器实例做一次扩展操作：

// config/samples/_v1_webserver.yaml 

apiVersion: my.domain/v1
kind: WebServer
metadata:
  name: webserver-sample
spec:
  # TODO(user): Add fields here
  image: nginx:1.23.1
  replicas: 4

然后通过kubectl apply使之生效：

$kubectl apply -f _v1_webserver.yaml
webserver.my.domain/webserver-sample configured

上述命令执行后，我们观察到operator的controller日志如下：

1.660208962767797e+09   INFO    controllers.WebServer   Deployment spec.replicas change {"Webserver": "default/webserver-sample", "from": 3, "to": 4}

稍后，查看pod数量：

$kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
webserver-sample-bc698b9fb-8gq2h   1/1     Running   0          9m41s
webserver-sample-bc698b9fb-v9gvg   1/1     Running   0          42s
webserver-sample-bc698b9fb-vk6gw   1/1     Running   0          9m41s
webserver-sample-bc698b9fb-xgrgb   1/1     Running   0          9m41s

webserver pod副本数量成功从3扩为4。

变更webserver image版本

我们将CR的image的版本从nginx:1.23.1改为nginx:1.23.0，然后执行kubectl apply使之生效。

我们查看controller的响应日志如下：

1.6602090494113188e+09  INFO    controllers.WebServer   Deployment spec.template.spec.container[0].image change {"Webserver": "default/webserver-sample", "from": "nginx:1.23.1", "to": "nginx:1.23.0"}

controller会更新deployment，导致所辖pod进行滚动升级：

$kubectl get pods
NAME                               READY   STATUS              RESTARTS   AGE
webserver-sample-bc698b9fb-8gq2h   1/1     Running             0          10m
webserver-sample-bc698b9fb-vk6gw   1/1     Running             0          10m
webserver-sample-bc698b9fb-xgrgb   1/1     Running             0          10m
webserver-sample-ffcf549ff-g6whk   0/1     ContainerCreating   0          12s
webserver-sample-ffcf549ff-ngjz6   0/1     ContainerCreating   0          12s

耐心等一小会儿，最终的pod列表为：

$kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
webserver-sample-ffcf549ff-g6whk   1/1     Running   0          6m22s
webserver-sample-ffcf549ff-m6z24   1/1     Running   0          3m12s
webserver-sample-ffcf549ff-ngjz6   1/1     Running   0          6m22s
webserver-sample-ffcf549ff-t7gvc   1/1     Running   0          4m16s

service自愈：恢复被无删除的Service

我们来一次“误操作”，将webserver-sample-service删除，看看controller能否帮助service自愈：

$kubectl delete service/webserver-sample-service
service "webserver-sample-service" deleted

查看controller日志：

1.6602096994710526e+09  INFO    controllers.WebServer   Creating a new Service  {"Webserver": "default/webserver-sample", "Service.Namespace": "default", "Service.Name": "webserver-sample-service"}

我们看到controller检测到了service被删除的状态，并重建了一个新service！

访问新建的service：

$curl http://192.168.10.182:30010



Welcome to nginx!



Welcome to nginx!
If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.

For online documentation and support please refer to
nginx.org.

Commercial support is available at
nginx.com.

Thank you for using nginx.

可以看到service在controller的帮助下完成了自愈！

五. 小结

本文对Kubernetes Operator的概念以及优点做了初步的介绍，并基于kubebuilder这个工具开发了一个具有2级能力的operator。当然这个operator离完善还有很远的距离，其主要目的还是帮助大家理解operator的概念以及实现套路。

相信你阅读完本文后，对operator，尤其是其基本结构会有一个较为清晰的了解，并具备开发简单operator的能力！

文中涉及的源码可以在这里下载 – https://github.com/bigwhite/experiments/tree/master/webserver-operator。

六. 参考资料

kubernetes operator 101, Part 1: Overview and key features – https://developers.redhat.com/articles/2021/06/11/kubernetes-operators-101-part-1-overview-and-key-features
Kubernetes Operators 101, Part 2: How operators work – https://developers.redhat.com/articles/2021/06/22/kubernetes-operators-101-part-2-how-operators-work
Operator SDK: Build Kubernetes Operators – https://developers.redhat.com/blog/2020/04/28/operator-sdk-build-kubernetes-operators-and-deploy-them-on-openshift
kubernetes doc: Custom Resources – https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/
kubernetes doc: Operator pattern – https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
kubernetes doc: API concepts – https://kubernetes.io/docs/reference/using-api/api-concepts/
Introducing Operators: Putting Operational Knowledge into Software 第一篇有关operator的文章 by coreos – https://web.archive.org/web/20170129131616/https://coreos.com/blog/introducing-operators.html
CNCF Operator白皮书v1.0 – https://github.com/cncf/tag-app-delivery/blob/main/operator-whitepaper/v1/Operator-WhitePaper_v1-0.md
Best practices for building Kubernetes Operators and stateful apps – https://cloud.google.com/blog/products/containers-kubernetes/best-practices-for-building-kubernetes-operators-and-stateful-apps
A deep dive into Kubernetes controllers – https://docs.bitnami.com/tutorials/a-deep-dive-into-kubernetes-controllers
Kubernetes Operators Explained – https://blog.container-solutions.com/kubernetes-operators-explained
书籍《Kubernetes Operator》 – https://book.douban.com/subject/34796009/
书籍《Programming Kubernetes》 – https://book.douban.com/subject/35498478/
Operator SDK Reaches v1.0 – https://cloud.redhat.com/blog/operator-sdk-reaches-v1.0
What is the difference between kubebuilder and operator-sdk – https://github.com/operator-framework/operator-sdk/issues/1758
Kubernetes Operators in Depth – https://www.infoq.com/articles/kubernetes-operators-in-depth/
Get started using Kubernetes Operators – https://developer.ibm.com/learningpaths/kubernetes-operators/
Use Kubernetes operators to extend Kubernetes’ functionality – https://developer.ibm.com/learningpaths/kubernetes-operators/operators-extend-kubernetes/
memcached operator – https://github.com/operator-framework/operator-sdk-samples/tree/master/go/memcached-operator

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2022年，Gopher部落全面改版，将持续分享Go语言与Go应用领域的知识、技巧与实践，并增加诸多互动形式。欢迎大家加入！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/。smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展；短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。2020年4月8日，中国三大电信运营商联合发布《5G消息白皮书》，51短信平台也会全新升级到“51商用消息平台”，全面支持5G RCS消息。

著名云主机服务厂商DigitalOcean发布最新的主机计划，入门级Droplet配置升级为：1 core CPU、1G内存、25G高速SSD，价格5$/月。有使用DigitalOcean需求的朋友，可以打开这个链接地址：https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻)归档仓库 – https://github.com/bigwhite/gopherdaily

我的联系方式：

微博：https://weibo.com/bigwhite20xx
博客：tonybai.com
github: https://github.com/bigwhite

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

TB一周萃选[第10期]

bigwhite — Sat, 03 Mar 2018 06:43:11 +0000

本文是首发于个人微信公众号的文章“TB一周萃选[第10期]”的归档。

这个世界上最危险的毒药，就是成就感。而解药就是每晚都想一想，明天如何做得更好。 – 英格瓦坎普拉德，宜家创始人

2018年元宵节已过，这个传统意义上的年就算真的过完了，我们的那颗有些闲散、有些懈怠的心需要收一收，是时候为2018年的“事业”做些规划，从2018的起跑线上起跑出去了。就连现在的孩子，在开学第一课时都要对自己的寒假生活做生动的回顾并且对新学期给予展望了。

春节假期匆忙且短暂，不过在这段时间里还是有很多值得关注的文章、资料、书籍以及项目的。

一、一周文章精粹

1. Go官方提出新的包依赖管理工具：vgo

就在上周，Go社区里发生了一件“大事”：Go大神Russ Cox一周内连发了七篇文章，并宣布Go很可能在下一个版本：Go 1.11中加入可选的、“实验性”的新模型： vgo(versioned Go)，以试图解决长期以来Go被广泛诟病的包依赖管理问题。

Russ Cox在设计vgo时参考了当今比较流行的cargo、npm等工具，也从之前Go官方实验dep中吸取了足够的实验结论，另辟蹊径，提出了很多很有创新的观点和方法，在社区里引起了广泛的关注和讨论。

vgo的一些主要设计考量如下：

接受语义版本(semver)规则
使用semantic import versioning规则替代原有的import rule
引入module概念（go.mod)
使用minimal version selection(最小版本选择)，而不是业界事实标准的maximal version selected（最新版本选择）的方案；
去除vendor机制
去除GOPATH

Russ Cox还提供了一个vgo的初步实现，供广大Gopher体验。

vgo的公开意味着Go team已经将包依赖管理问题列为高优先级待解决的问题，vgo虽然只是原型，其设计思路也可能不会全部进入到最终的解决方法中，但这毕竟迈出了坚实的一步。

文章链接：Go & Verisioning

2. Go官方2017用户调查结果

本周Go官方在Blog上公布了2017用户调查结果，几个结论值得大家关注：

越来越多用户在工作中正式使用Go (67%)
Web开发、系统编程、Devops、网络编程依旧是Go使用的主要领域，但在移动端、桌面端GUI编程的比例下滑明显
在API/RPC服务领域的使用占据榜首，CLI、WebService(返回html)排名2、3
包依赖管理以及缺少泛型依然是Gopher最希望Go team解决的两个问题
Linux、MacOS依然是Gopher主力开发平台
vscode在Go编辑器市场份额升至No.1
最喜欢的关键字：go、defer、func、select和interface排名top5

文章链接：“Go 2017用户调查结果”

3. 容器术语介绍入门

著名开源公司Redhat近两年拥抱容器的态度十分坚决，近期来收购了coreos。近期Redhat在官博上发表了一篇文章，对容器领域的相关术语概念做了详尽的介绍，强烈推荐。

文章链接：“容器术语介绍入门”

4. Go语言实现的微服务系列

Go语言已经被证明了是当前应用云化、面向微服务的服务端编程的头部语言之一。关于Go与Microservice的文章也有不少。Ewan Valentine的Go语言实现微服务系列（10篇）就是这类文章中难得的全面、细致讲述Go如何实现微服务应用的文章资料。在这一系列文章中，作者谈到的了mongodb, grpc, docker, Google Cloud, Kubernetes, NATS, CircleCI, Terraform、go-micro框架等诸多在编写、部署、运维微服务过程中所能用到的框架、协议、工具等。.

文章链接：microservice in golang series

5. Brian Ketelsen专访：Go取得快速增长的原因

Brian Ketelsen是知名Gopher，GopherCon大会、GopherAcademy的联合发起人、《Go in action》一书的联合作者。在Microsoft对其的一篇专访中，Brian Ketelsen谈了对Go语言这些年取得快速成长的看法。

文章链接：Brian Ketelsen专访：Go取得快速增长的原因

6. 在Linux上使用Go作为脚本语言

Cloudflare公司的很多产品采用的是Go技术栈，公司内部支撑系统亦是。Go的简单特质以及Go tools的使用模式让Go十分适合在Linux系统上被当做“脚本语言”使用（结合shebang行），它的强类型特性又是真正的脚本语言所不具备的。cloudflare的这篇文章讲解了该公司使用go作为脚本语言在Linux上的实践方法，值得借鉴。

文章链接：《在Linux使用Go作为脚本语言》

二、一周资料分享

1. Google机器学习速成教程

Google公司本周正式推出面向普通开发者、机器学习爱好者的机器学习速成教程资料。粗略浏览了一遍，感觉该教程是目前传统程序员向机器学习、AI领域转型的最优秀资料之一。教程提供了教程中实验的全部资料和实验环境，并给出了前提条件中给出了预备知识的学习教程，包括数学知识、Python编程等。更为可贵的是该教程提供完整的中文版，国内程序员学习起来曲线也降低了不少。唯一不便的可能就是需要科学上网才能打开教程。

资料分享链接：“Google机器学习速成教程”

三、一周项目推荐

1. vitess

之所以推荐vitess这个项目，是因为它在不久前成为了CNCF基金会的第16个孵化级别项目，并且是cncf第二个存储项目。Vitess最初是作为YouTube的一个内部解决方案来处理大量存储的扩展，它是一个数据库编排系统，通过广义分片来对MySQL进行水平缩放。通过封装分片路由逻辑，Vitess允许应用程序代码和数据库查询对于将数据分布到多个分片上保持不变。借助Vitess，组织甚至可以根据需求的增长来分割和合并碎片，原子切割步骤只需要几秒钟。

同时该项目还是Go语言的早期“尝鲜者”：在2011年就开始使用Go语言开发了。随着vitess用户的增多（包括slack、flipkart等），vitess似乎又进入一个黄金开发的阶段，将较为成熟的、业界广为使用的数据库分片技术继续延续和优化下去，并且vitess与容器、kubernetes的结合使用也日益成熟，为云原生应用在k8s上提供一个可扩展的存储层。

项目链接：“vitess”

四、一周图书推荐

1.《Master Ethereum》

随着2017年比特币市场的异常繁荣，2018的区块链技术有迎来爆发的趋势。作为第二代区块链技术代表的以太坊(Ethereum)，它试图实现一个总体上完全无需信任基础的智能合约平台和庞大的生态圈，受到了区块链业界最为广泛的关注，有关以太坊的技术书籍亦是如此。

《Master Ethereum》，中文名可译为“精通以太坊”，这是一本尚未完成的书，但在编写的过程中就受到了广泛的关注。除了是因为大家对以太坊技术关注之外，该书在github的开源也是其吸引眼球的重要原因。该书的两位作者是bitcoin专家，本书的目标是为开发者提供有关以太坊概念、使用、智能合约(smart contract)、经典以太坊网络、以太坊标准等全面的内容。

图书链接：《Master Ethereum》

我的联系方式：

微博：https://weibo.com/bigwhite20xx
微信公众号：iamtonybai
博客：tonybai.com
github: https://github.com/bigwhite

微信赞赏：

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

TB一周萃选[第9期]

bigwhite — Sun, 11 Feb 2018 05:41:08 +0000

本文是首发于个人微信公众号的文章“TB一周萃选[第9期]”的归档。

亲情犹如一江剪不断的春水，流动的是游子心中永远的思念；亲情犹如一丘数不尽的细沙，沉淀的是长年堆积的牵挂；亲情犹如夜空中那颗北斗，指引的是那迷路的羔羊回家的方向。忙碌了一年，该回家了，给心放个假，带上媳妇带上你的娃，回家看看那年迈的爸妈，出发！ — 改编自网络

此时此刻，很多人刚刚踏上了春节回家的旅途，有些人更是已经叩开了家的大门。每逢中国传统佳节-春节，令世界瞩目并为之瞠目结舌的中国式人口大迁移就会发生一次：几亿人熬夜刷票并不辞辛劳地携着夫/妻儿女，经由多种交通工具，跨越高山大河，不远千百里，战胜种种“囧况”，只为一个目的：在春节前回到那个充满熟悉味道的家乡。

这种在一个文明延续5000多年未中断的民族中发生的全民行为让西方社会感到十分不解，甚至指责这是对资源的一种浪费；并且也有国内的人发出类似不和谐的声音。但是它依然在发生着，每年都在发生，形式有些许变化，但剧情大体雷同。

曾经有国内外学者对中国特有的春节大迁徙的原因进行研究和分析，并给出了各种专业化的理由。但在我看来，对现代人来说，回家过年，是一种心灵的相互充电! 而且是充电7天，“通话”一整年。

对于一年到头在外奔波劳碌的人们来说，只有回家，才能真实地触摸到自己的“根”，才能切切实实地体会这种归属感，才能在一定程度上纾解那些在工作的城市中涵盖不了的人生寄托。在这种归属感中，哪怕只是获得片刻的身心安宁，也是一种极为重要的精神能量的充电；而对于守候在家乡的父母或者孩童儿，你的回家，让他们将近一年的期盼终于有了一个圆满的结果，这同样为下一个365天的期盼周期提供了强大的动力和希望。

如果非要给这种行为找个理由，那我要说这就是由一个体内延绵数千年的中华民族血脉的中国人的基因所决定的。

一、一周文章精粹

1. Go 1.10发布Party

自从Go 1.6开始，每逢偶数版本（一般在每年2、3月发布），Gopher社区都会举办庆祝Release的全球Party。在中国农历春节到来之际，也恰逢Go最新版本Go 1.10即将发布之时，Go wiki发布了Go 1.10 Release Party的Schedule和相关资料。截至目前，已经有15个Party已经list到页面上，活动从2月15号一直延续到3月份。

2. 避免或减少对Go context Value的使用

context包最初诞生于Google公司内部，并在Google内部项目大量使用。context在golang/x中孵化了多年，并得到了很多开源项目的使用，尤其是一些使用了”middleware”模式的项目中，于是在Go 1.7发布时，context包正式加入Go标准库。context加入后，可谓既带来魔力，亦带来了争议，甚至有人将其视为具有“病毒”属性，一旦使用，便可轻易传染到项目中代码的各个角落。

Go开发者、培训师Jon Calhoun也在个人网站上撰写了一篇文章，来告诫大家Go context value的一些缺陷，建议大家避免或减少对Go context Value的使用，并给出自己的替代方案。其主要理由是：context.WithValue和Context.Value的使用让我们失去了编译器对类型安全性的检查。

文章链接：“Pitfalls of context values and how to avoid or mitigate them in Go”

3. 来自Google Cloud Platform的12条有关用户账号、授权和密码管理的最佳实践

对于许多开发者来说，账户管理是一个黑暗的角落，没有得到足够的重视。来自Google Cloud Platform的解决方案专家Ian Maddox给我们带来了12条有关此方面的最佳实践，包括：区分用户标识与用户账号、允许用户更改用户名、用户ID大小写敏感、两步验证等。

文章链接：“12 best practices for user account, authorization and password management”

4. AI界网红-深度学习之父Geoffrey Hinton的传奇学术生涯

这几年最火爆的人工智能技术就是深度学习，可以说当下的主流人工智能就是深度学习，而深度学习的理论基石就是反向传播。和当代物理学类似，最新的计算机应用实际上也是在消化几十年前就已经建立的理论，这不：反向传播就是Geoffrey Hinton与同事David Rumelhart、Ronald Williams在1986年发布的成果，Geoffrey Hinton也因此被誉为深度学习之父。Geoffrey Hinton花了30年在AI前沿的研究，在今天终于开花结果。不过这位现在AI奠基人并没有就此停歇，去年他还提出了“胶囊理论”，不过要彻底理解他的理论，不知道AI应用界还要花多久。下面这篇文章是“多伦多生活”上发表的一篇有关Geoffrey Hinton的传奇学术生涯的新闻稿，我们可以通过它一瞥AI超级明星的学术人生。

图：Geoffrey Hinton

文章链接：“深度学习之父Geoffrey Hinton的传奇学术生涯”

5. Go项目在github上接受PR了

go语言自身的开发一直是在google内部的平台上，github上的golang项目仅仅是其一个mirror。在这之前，golang项目在github上是拒绝pr的，contributor必须注册google的开发账号才能为go语言本身做贡献，这种门槛显然有些高。近期Go项目作出了对社区更为友好的举动：允许在github上直接提交PR。不过代码的review依旧是在google原平台上，github上提交的pr将被GerritBot自动同步到Go team的Gerrit上进行code review。不过这已经是一个不错的开端了。估计会吸引更多开发者为Go做contribution。

文章链接：
* “doc: remove Pull Request note in README.md”
* “pr流程”

二、一周资料分享

1. istio微服务教程 by Redhat

下一代微服务平台日益火爆，比如：istio、conduit等。近期Redhat开源了一套istio微服务教程，主要是for java microservice，但感觉对其他语言开发的微服务也适用。教程使用的是istio最新发布的0.5.0版本，底层使用的是redhat自身的oc平台(openshift)，但替换成kubernetes应该很容易。教程包含的内容还是很全面的，针对包括metrics、tracing、routerule管理、fault injection、retry&timeout、mirroring traffic、access control、rate limiting、circuit breaker、egress等常见的微服务框架治理机制都提供了demo实例。

资料分享链接：Istio Tutorial for Java Microservices

三、一周项目推荐

1. rook：致力于让存储服务成为云原生平台上的“头等”服务

2018年1月30日，云原生cncf组织下又增加了一位新成员:rook项目，由于刚入行，其与linkerd、coredns同样处于Inception级别。rook是什么？它解决了哪些问题呢？

如今在Kubernetes上部署的应用在使用存储服务时，多使用k8s集群外提供的外部存储服务。在公有云上，使用较多的是诸如EBS、S3等；在定制云/私有云中，使用的则是NFS、Ceph或更为传统的存储解决方案，如下图所示：

图：使用rook前

Rook存在的意义就是将存储服务移入集群内部，让那些依赖存储服务的应用可以无缝地使用这些服务，这样一来，整个云原生集群环境就可以脱离厂商依赖（比如对amazon、google cloud platform的依赖），实现整体的可移植了，无论是公有云还是私有云。

图：使用rook后

可以说，Rook让存储服务成为云原生平台上的“头等”服务，与其他应用服务一样。

那Rook究竟是什么呢？Rook不是一个像ceph那样的分布式共享存储系统。rook的考虑是：与其花费几年甚至十几年实现一个成熟的、久经考验的分布式存储系统，到不如帮助现有的已经十分成熟的、久经沙场的存储系统更方便的被云原生环境中的应用所使用，比如：ceph。于是rook通过将那些专有存储服务管理员的日常操作自动化：包括引导启动、配置、伸缩、升级、迁移、灾难恢复、监控、资源管理，将存储服务包装为云原生应用，无缝运行在云原生环境上，目前主要是在Kubernetes上。

图：rook架构

Rook的出现，迅速得到了来自Redhat、ceph开发者的支持，社区也在日益壮大。目前其最新版本为v0.6.2，按计划在2018年中旬发布第一个production-ready的正式版。

项目地址：Rook

四、一周图书推荐

1.《High Performance Browser Networking》

Ilya Grigorik是Google性能优化工程师，他在2013出版的这本《High Performance Browser Networking》堪称当代Web性能调优的圣经。该书以调优为核心，从网络基础(101)讲起，然后深入探讨了无线和移动网络的工作机制。最后，揭示了HTTP 协议的底层细节，同时详细介绍了HTTP 2.0、 XHR、SSE、WebSocket、WebRTC 和DataChannel 等现代浏览器新增的具有革命性的新能力。该书无论是对前端开发，还是后端网络服务开发设计人员都是大有裨益的。

更重要的是该书当时所讲述的诸多浏览器协议技术，比如：HTTP2.0、WebSocket、SSE在如今已经成为标准，并广泛应用于生产实践中。

图书链接：
英文版：《High Performance Browser Networking》
中文版：《Web性能权威指南》
免费版：《High Performance Browser Networking》

我的联系方式：

微博：http://weibo.com/bigwhite20xx
微信公众号：iamtonybai
博客：tonybai.com
github: https://github.com/bigwhite

微信赞赏：

商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作

使用core-vagrant方式安装CoreOS

bigwhite — Mon, 20 Jul 2015 11:34:24 +0000

CoreOS是一种专门为运行类docker容器而生的linux发行版。与其他通用linux发行版（ubuntu、debian、redhat)相比，它具有体型最小，消耗最小，支持滚动更新等特点。除此之外CoreOS内置的分布式系统服务组件也给开发者和运维者组建分布式集群、部署分布式服务应用带来了极大便利。

CoreOS与知名容器Docker脚前脚后诞生，到目前为止已经较为成熟，国外主流云平台提供商如Amazon EC2、Google Compute Engine、Microsoft Azure、Digtial Ocean等均提供了CoreOS image，通过这些服务，你可以一键建立一个CoreOS实例，这似乎也是CoreOS官方推荐的主流install方式（最Easy）。

CoreOS当然支持其他方式的安装，比如支持虚拟机安装(vagrant+virtualbox)、PXE(preboot execute environment)安装以及iso install to 物理disk方式。如果仅仅是做一些实验，虚拟机安装是最简单也是最安全的方式。不过由于CoreOS的官方下载站在大陆无法直接访问（大陆程序员们好悲催啊），因此这一最简单的虚拟机安装CoreOS的过程也就不那么简单了。

通过core-vagrant安装的直接结果是CoreOS被安装到一个VirtualBox虚拟机中，之后我们利用Vagrant命令来进行 CoreOS虚拟机的启停。CoreOS以及Vagrant都在持续演进，尤其是CoreOS目前在active dev中，版本号变化很快，这也是CoreOS滚动升级的必然结果。因此在安装操作演示前，我们有必要明确一下这个安装过程使用的软件版本：

    物理机OS:
        Ubuntu 12.04 3.8.0-42-generic x86_64
    VirtualBox:
        Oracle VM VirtualBox Manager 4.2.10
    Vagrant:
        Vagrant 1.7.3
    CoreOS:
        stable 717.3.0
    coreos-vagrant source:
        commit b9ed7e2182ff08b72419ab3e89f4a5652bc75082

一、原理

如果没有Wall，CoreOS的coreos-vagrant安装将非常简单：

1、git clone https://github.com/coreos/coreos-vagrant
2、编辑配置文件
3、vagrant up
4、vagrant ssh

但是现在有了Wall，步骤3：vagrant up会报错：无法连接到http://stable.release.core-os.net/amd64-usr/717.3.0/xx这个url，导致安装失败。

我大致分析了一下vagrant up的执行过程：

1、设置配置默认值

    $num_instances = 1
    $instance_name_prefix = "core"
    $update_channel = "alpha"
    $image_version = "current"
    $enable_serial_logging = false
    $share_home = false
    $vm_gui = false
    $vm_memory = 1024
    $vm_cpus = 1
    $shared_folders = {}
    $forwarded_ports = {}

2、判断是否存在config.rb这个配置，如果有，则加载。
3、设置config.vm.url，并获取对应的json文件：

{
"name": "coreos-stable",
"description": "CoreOS stable",
"versions": [{
    "version": "717.3.0",
    "providers": [{
      "name": "virtualbox",
      "url": "http://stable.release.core-os.net/amd64-usr/717.3.0/coreos_production_vagrant.box",
      "checksum_type": "sha256",
      "checksum": "99dcd74c7cae8b1d90f108f8819f92b17bfbd34f4f141325bd0400fe4def55b6"
    }]
}]
}

4、根据config.vm.provider（是virtualbox还是vmvare等）来决定采用哪种虚拟机创建逻辑。

这里我们看到，整个过程只需要从core-os.net下载两个文件：coreos_production_vagrant.box和coreos_production_vagrant.json。如果我们提前将这两个文件下载到本地，并放在一个临时的http server下，修改Vagrantfile和coreos_production_vagrant.json这两个文件，就应该可以通过coreos-vagrant安装了。

二、coreos-vagrant安装single instance CoreOS

好了，根据上述原理，我们首先要下载coreos_production_vagrant.box和coreos_production_vagrant.json这两个文件，根据我们的channel和版本选择，两个文件的下载地址分别为：

http://stable.release.core-os.net/amd64-usr/717.3.0/coreos_production_vagrant.box
http://stable.release.core-os.net/amd64-usr/717.3.0/coreos_production_vagrant.json

接下来就是不管你用什么梯子，只要把这两个文件下载到本地，并放到一个目录下就好了。

我们需要修改一下coreos_production_vagrant.json，将其中的url改为：

"url": "http://localhost:8080/coreos_production_vagrant.box"

我们要将这两个文件放到一个local file server中，后续供core-vagrant访问。最简单的方法就是使用:

python -m SimpleHTTPServer 8080

当然使用Go实现一个简单的http file server也是非常简单的：

//fileserver.go
package main

import "net/http"
import "log"

func main() {
log.Fatal(http.ListenAndServe(":8080", http.FileServer(http.Dir("./"))))
}

接下来我们就可以按照正常步骤，下载coreos-vagrant并up了：

$git clone https://github.com/coreos/coreos-vagrant

修改Vagrantfile：

$ diff Vagrantfile Vagrantfile.bak
14,15c14,15
< $update_channel = "stable"
< $image_version = "717.3.0"
—
> $update_channel = "alpha"
> $image_version = "current"
55c55
< config.vm.box_url = "http://localhost:8080/coreos_production_vagrant.json"
—
> config.vm.box_url = "http://%s.release.core-os.net/amd64-usr/%s/coreos_production_vagrant.json" % [$update_channel, $image_version]

将user-data.sample改名为user-data，并编辑user-data，在etcd2下面增加一行：

etcd2:
name: core-01

将units:下面对于etcd2的注释去掉，以enable etcd2服务。（将etcd服务注释掉）

万事俱备，只需vagrant up。

$ vagrant up
Bringing machine 'core-01' up with 'virtualbox' provider…
==> core-01: Box 'coreos-stable' could not be found. Attempting to find and install…
    core-01: Box Provider: virtualbox
    core-01: Box Version: 717.3.0
==> core-01: Loading metadata for box 'http://localhost:8080/coreos_production_vagrant.json'
    core-01: URL: http://localhost:8080/coreos_production_vagrant.json
==> core-01: Adding box 'coreos-stable' (v717.3.0) for provider: virtualbox
    core-01: Downloading: http://localhost:8080/coreos_production_vagrant.box
    core-01: Calculating and comparing box checksum…
==> core-01: Successfully added box 'coreos-stable' (v717.3.0) for 'virtualbox'!
==> core-01: Importing base box 'coreos-stable'…
==> core-01: Matching MAC address for NAT networking…
==> core-01: Checking if box 'coreos-stable' is up to date…
==> core-01: Setting the name of the VM: coreos-vagrant_core-01_1437121834188_89503
==> core-01: Clearing any previously set network interfaces…
==> core-01: Preparing network interfaces based on configuration…
    core-01: Adapter 1: nat
    core-01: Adapter 2: hostonly
==> core-01: Forwarding ports…
    core-01: 22 => 2222 (adapter 1)
==> core-01: Running 'pre-boot' VM customizations…
==> core-01: Booting VM…
==> core-01: Waiting for machine to boot. This may take a few minutes…
    core-01: SSH address: 127.0.0.1:2222
    core-01: SSH username: core
    core-01: SSH auth method: private key
    core-01: Warning: Connection timeout. Retrying…
==> core-01: Machine booted and ready!
==> core-01: Setting hostname…
==> core-01: Configuring and enabling network interfaces…
==> core-01: Running provisioner: file…
==> core-01: Running provisioner: shell…
    core-01: Running: inline script

登入你的coreos实例：
$ vagrant ssh
CoreOS stable (717.3.0)
core@core-01 ~ $

在vagrant up时，你可能会遇到如下两个错误：

错误1：

Progress state: VBOX_E_FILE_ERROR
VBoxManage: error: Could not open the medium storage unit '/home1/tonybai/.vagrant.d/boxes/coreos-stable/717.3.0/virtualbox/coreos_production_vagrant_image.vmdk'.
VBoxManage: error: VMDK: inconsistent references to grain directory in '/home1/tonybai/.vagrant.d/boxes/coreos-stable/717.3.0/virtualbox/coreos_production_vagrant_image.vmdk' (VERR_VD_VMDK_INVALID_HEADER).

这个问题的原因很可能是你的Virtualbox版本不对，比如版本太低，与coreos_production_vagrant.box格式不兼容。可尝试安装一下高版本virtualbox来解决。

错误2：

core-01: SSH address: 127.0.0.1:2222
core-01: SSH username: core
core-01: SSH auth method: private key
core-01: Warning: Connection timeout. Retrying…
core-01: Warning: Connection timeout. Retrying…
core-01: Warning: Connection timeout. Retrying…

coreos虚拟机创建后，似乎一直无法连接上。在coreos的github issue中，有人遇到了这个问题，目前给出的原因是因为cpu的支持虚拟化技术的vt开关没有打开，需要在bios中将其开启。这主要在安装64bit box时才会发生。

到这里，我们已经完成了一个single instance coreos虚拟机的安装。vagrant halt可以帮助你将启动的coreos虚拟机停下来。

$ vagrant halt
==> core-01: Attempting graceful shutdown of VM…

三、 CoreOS cluster

上面虽然成功的安装了coreos，然并卵。在实际应用中，CoreOS多以Cluster形式呈现，也就是说我们要启动多个CoreOS实例。

使用vagrant启动多个coreos实例很简单，只需将配置中的$num_instances从1改为n。

这里我们启用config.rb这个配置文件(将config.rb.sample改名为config.rb)，并将其中的$num_instances修改为3：

# Size of the CoreOS cluster created by Vagrant
$num_instances=3

该配置文件中的数据会覆盖Vagrantfile中的默认配置。

三个instance中的etcd2要想组成集群还需要一个配置修改，那就是在etcd.io上申请一个token：

$curl https://discovery.etcd.io/new

https://discovery.etcd.io/fe81755687323aae273dc5f111eb059a

将这个token配置到user-data中的etcd2下：

etcd2:

    #generate a new token for each unique cluster from https://discovery.etcd.io/new
    #discovery: https://discovery.etcd.io/
    discovery: https://discovery.etcd.io/fe81755687323aae273dc5f111eb059a

我们再来up看看：

$ vagrant up
Bringing machine 'core-01' up with 'virtualbox' provider…
Bringing machine 'core-02' up with 'virtualbox' provider…
Bringing machine 'core-03' up with 'virtualbox' provider…
==> core-01: Checking if box 'coreos-stable' is up to date…
==> core-01: VirtualBox VM is already running.
==> core-02: Importing base box 'coreos-stable'…
==> core-02: Matching MAC address for NAT networking…
==> core-02: Checking if box 'coreos-stable' is up to date…
==> core-02: Setting the name of the VM: coreos-vagrant_core-02_1437388468647_96550
==> core-02: Fixed port collision for 22 => 2222. Now on port 2200.
==> core-02: Clearing any previously set network interfaces…
==> core-02: Preparing network interfaces based on configuration…
    core-02: Adapter 1: nat
    core-02: Adapter 2: hostonly
==> core-02: Forwarding ports…
    core-02: 22 => 2200 (adapter 1)
==> core-02: Running 'pre-boot' VM customizations…
==> core-02: Booting VM…
==> core-02: Waiting for machine to boot. This may take a few minutes…
    core-02: SSH address: 127.0.0.1:2200
    core-02: SSH username: core
    core-02: SSH auth method: private key
    core-02: Warning: Connection timeout. Retrying…
==> core-02: Machine booted and ready!
==> core-02: Setting hostname…
==> core-02: Configuring and enabling network interfaces…
==> core-02: Running provisioner: file…
==> core-02: Running provisioner: shell…
    core-02: Running: inline script
==> core-03: Importing base box 'coreos-stable'…
==> core-03: Matching MAC address for NAT networking…
==> core-03: Checking if box 'coreos-stable' is up to date…
==> core-03: Setting the name of the VM: coreos-vagrant_core-03_1437388512743_68112
==> core-03: Fixed port collision for 22 => 2222. Now on port 2201.
==> core-03: Clearing any previously set network interfaces…
==> core-03: Preparing network interfaces based on configuration…
    core-03: Adapter 1: nat
    core-03: Adapter 2: hostonly
==> core-03: Forwarding ports…
    core-03: 22 => 2201 (adapter 1)
==> core-03: Running 'pre-boot' VM customizations…
==> core-03: Booting VM…
==> core-03: Waiting for machine to boot. This may take a few minutes…
    core-03: SSH address: 127.0.0.1:2201
    core-03: SSH username: core
    core-03: SSH auth method: private key
    core-03: Warning: Connection timeout. Retrying…
==> core-03: Machine booted and ready!
==> core-03: Setting hostname…
==> core-03: Configuring and enabling network interfaces…
==> core-03: Running provisioner: file…
==> core-03: Running provisioner: shell…
    core-03: Running: inline script

$vagrant ssh core-02
CoreOS stable (717.3.0)
core@core-02 ~ $

可以看到Vagrant启动了三个coreos instance。关闭这些instance，同样用halt：

$ vagrant halt
==> core-03: Attempting graceful shutdown of VM…
==> core-02: Attempting graceful shutdown of VM…
==> core-01: Attempting graceful shutdown of VM…

四、小结

以上仅仅是CoreOS最基本的入门，虽然现在安装ok了，但CoreOS的各种服务组件的功用、配置；如何与Docker配合形成分布式服务系统；如何用Google Kubernetes管理容器集群等还需更进一步深入学习，这个后续会慢慢道来。

探讨Docker容器中修改系统变量的方法

bigwhite — Tue, 14 Oct 2014 13:56:12 +0000

探讨完Docker对共享内存状态持久化的支持状况后，我将遗留产品build到一个pre-production image中，测试启动是否OK。很显然，我过于乐观了，Docker之路并不平坦。我收到了shmget报出的EINVAL错误码，提示参数非法。 shmget的manual对EINVAL错误码的说明如下：

EINVAL：
A new segment was to be created and size < SHMMIN or size > SHMMAX, or no new segment was to be created, a segment with given key existed, but size is greater than the size of that segment.

显然我们要创建的shared memory的size很可能大于SHMMAX这个系统变量了。那么一个从base image创建出的容器中的系统变量到底是什么值呢？我们来查看一下，我们基于"centos:centos6"启动一个Docker容器，并检查其中的系统变量值设置：

$ sudo docker run -it "centos:centos6" /bin/bash
bash-4.1# cat /proc/sys/kernel/shmmax
33554432
bash-4.1# sysctl -a|grep shmmax
kernel.shmmax = 33554432

可以看出默认情况下，当前容器中root账号看到的shmmax值我33554432，我的程序要创建的shm size的确要大于这个值，报出EINVAL错误也就无可厚非了。我尝试按照物理机上的方法临时修改一下该值：

bash-4.1# echo 68719476736 > /proc/sys/kernel/shmmax
bash: /proc/sys/kernel/shmmax: Read-only file system

/proc/sys/kernel/shmmax居然是只读的，无法修改。

我又尝试修改/etc/sysctl.conf这个持久化系统变量的地方，但打开/etc/sysctl.conf文件，我发现我又错了，这个文件中shmmax的值如下：

# Controls the maximum shared segment size, in bytes
kernel.shmmax = 68719476736

/etc/sysctl.conf文件中的系统变量shmmax的值是68719476736，而系统当前的实际值则是33554432，难道是/etc /sysctl.conf中的值没有生效，于是我手工重新加载一次该文件：

-bash-4.1# sysctl -p
error: "Read-only file system" setting key "net.ipv4.ip_forward"
error: "Read-only file system" setting key "net.ipv4.conf.default.rp_filter"
error: "Read-only file system" setting key "net.ipv4.conf.default.accept_source_route"
error: "Read-only file system" setting key "kernel.sysrq"
error: "Read-only file system" setting key "kernel.core_uses_pid"
error: "net.ipv4.tcp_syncookies" is an unknown key
error: "net.bridge.bridge-nf-call-ip6tables" is an unknown key
error: "net.bridge.bridge-nf-call-iptables" is an unknown key
error: "net.bridge.bridge-nf-call-arptables" is an unknown key
error: "Read-only file system" setting key "kernel.msgmnb"
error: "Read-only file system" setting key "kernel.msgmax"
error: "Read-only file system" setting key "kernel.shmmax"
error: "Read-only file system" setting key "kernel.shmall"

我得到了和之前类似的错误结果：只读文件系统，无法修改。于是乎两个问题萦绕在我的面前：
1、为什么容器内当前系统变量值与sysctl.conf中的不一致？
2、为什么无法修改当前系统变量值?

在翻阅了Stackoverflow, github docker issues后，我得到了的答案如下：

1、Docker的base image做的很精简，甚至都没有init进程，原本在OS启动时执行生效系统变量的过程(sysctl -p)也给省略了，导致这些系统变量依旧保留着kernel默认值。以CentOs为例，在linux kernel boot后，init都会执行/etc/rc.d/rc.sysinit，后者会加载/etc/sysctl.conf中的系统变量值。下面是 CentOs5.6中的rc.sysinit代码摘录：

… …
# Configure kernel parameters
update_boot_stage RCkernelparam
sysctl -e -p /etc/sysctl.conf >/dev/null 2>&1
… …

2、Docker容器中的系统变量在non-priviledged模式下目前(我使用的时docker 1.2.0版本)就无法修改，这和resolv.conf、hosts等文件映射到宿主机对应的文件有不同。

$ mount -l
…. ….
/dev/mapper/ubuntu–Server–14–vg-root on /etc/resolv.conf type ext4 (rw,relatime,errors=remount-ro,data=ordered)
/dev/mapper/ubuntu–Server–14–vg-root on /etc/hostname type ext4 (rw,relatime,errors=remount-ro,data=ordered)
/dev/mapper/ubuntu–Server–14–vg-root on /etc/hosts type ext4 (rw,relatime,errors=remount-ro,data=ordered)
… …

那么我们该如何修改系统变量值来满足遗留产品的需求呢？

一、使用–privileged选项

我们使用–privileged这个特权选项来启动一个基于centos:centos6的新容器，看看是否能对shmmax这样的系统变量值进行修改：

$ sudo docker run -it –privileged "centos:centos6" /bin/bash
bash-4.1# cat /proc/sys/kernel/shmmax
33554432
bash-4.1# echo 68719476736 > /proc/sys/kernel/shmmax
bash-4.1# cat /proc/sys/kernel/shmmax
68719476736
bash-4.1# sysctl -p
net.ipv4.ip_forward = 0
net.ipv4.conf.default.rp_filter = 1
net.ipv4.conf.default.accept_source_route = 0
kernel.sysrq = 0
kernel.core_uses_pid = 1
… …
kernel.msgmnb = 65536
kernel.msgmax = 65536
kernel.shmmax = 68719476736
kernel.shmall = 4294967296

可以看出，通过–privileged选项，容器获得了额外的特权，并且可以对系统变量的值进行修改了。不过这样的修改是不能保存在容器里的，我们stop 容器，再重启该容器就能看出来：

$ sudo docker start 3e22d65a7845
$ sudo docker attach 3e22d65a7845
bash-4.1# cat /proc/sys/kernel/shmmax
33554432

shmmax的值在容器重启后又变回了原先的那个默认值。不过重启后的容器依旧具有privileged的特权，我们还可以重新手工执行命令对系统变量进行修改：

bash-4.1# echo 68719476736 > /proc/sys/kernel/shmmax
bash-4.1# cat /proc/sys/kernel/shmmax
68719476736

但即便这样，也无法满足我们的需求，我们总不能每次都在容器中手工执行系统变量值修改的操作吧。privileged选项的能力能否带到 image中呢？答案是目前还不能，我们无法在build image时通过privileged选项修改系统变量值。

这样一来，我们能做的只有把产品启动与系统变量值修改放在一个脚本中了，并将该脚本作为docker 容器的cmd命令来执行，比如我们构建一个Dockerfile：

FROM centos:centos6
MAINTAINER Tony Bai
RUN yum install python-setuptools -y
RUN easy_install supervisor
RUN mkdir -p /var/log/supervisor
COPY ./supervisord.conf /etc/supervisord.conf
COPY ./start.sh /bin/start.sh
RUN chmod +x /bin/start.sh
CMD ["/bin/start.sh]

//start.sh
sysctl -p
/usr/bin/supervisord

这样，start.sh在supervisord启动前将系统变量值重新加载，而supervisord后续启动的程序就可以看到这些新系统变量的值了。不过别忘了利用这个image启动容器时要加上–priviledged选项，否则容器启动就会失败。

二、使用phusion/baseimage

前面说过/etc/sysctl.conf中的值没有生效是因为docker官方提供的centos:centos6把init进程的初始化过程给精简掉了。phusion/baseimage是目前docker registery上仅次于ubuntu和centos两个之后的base image，其提供了/sbin/my_init这个init进程，用于在container充当init进程的角色。那么my_init是否可以用于执行sysctl -p呢？我们试验一下：

我们先pull这个base image下来：sudo docker pull phusion/baseimage。pull成功后，我们先基于“phusion/baseimage”启动一个容器做一些explore工作：

$ sudo docker run -i -t "phusion/baseimage"
*** Running /etc/my_init.d/00_regen_ssh_host_keys.sh…
No SSH host key available. Generating one…
Creating SSH2 RSA key; this may take some time …
Creating SSH2 DSA key; this may take some time …
Creating SSH2 ECDSA key; this may take some time …
Creating SSH2 ED25519 key; this may take some time …
invoke-rc.d: policy-rc.d denied execution of restart.
*** Running /etc/rc.local…
*** Booting runit daemon…
*** Runit started as PID 100

通过nsenter进去，查看一下/sbin/my_init的源码，我们发现这是一个python脚本，不过从头到尾浏览一遍，没有发现sysctl加载/etc/sysctl.conf系统变量的操作。

不过，phusion文档中说my_init可以在初始化过程中执行/etc/my_init.d下的脚本。那是不是我们将一个执行sysctl -p的脚本放入/etc/my_init.d下就可以实现我们的目的了呢？试试。

我们编写一个脚本：load_sys_varibles.sh

#!/bin/sh
sysctl -p > init.txt

下面是制作image的Dockerfile:

FROM phusion/baseimage:latest
MAINTAINER Tony Bai
RUN echo "kernel.shmmax = 68719476736" >> /etc/sysctl.conf
RUN mkdir -p /etc/my_init.d
ADD load_sys_varibles.sh /etc/my_init.d/load_sys_varibles.sh
RUN chmod +x /etc/my_init.d/load_sys_varibles.sh
CMD ["/sbin/my_init"]

phusion/baseimage是基于ubuntu的OS，其sysctl.conf默认情况下没啥内容，所以我们在Dockerfile中向这个文件写入我们需要的系统变量值。构建image并启动容器：

$ sudo docker build -t "myphusion:v1" ./
Sending build context to Docker daemon 13.12 MB
Sending build context to Docker daemon
Step 0 : FROM phusion/baseimage:latest
—> cf39b476aeec
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> d0e9b51a3e4f
Step 2 : RUN echo "kernel.shmmax = 68719476736" >> /etc/sysctl.conf
—> Using cache
—> 2c800687cc83
Step 3 : RUN mkdir -p /etc/my_init.d
—> Using cache
—> fe366eea5eb4
Step 4 : ADD load_sys_varibles.sh /etc/my_init.d/load_sys_varibles.sh
—> a641bb595fb9
Removing intermediate container c381b9f001c2
Step 5 : RUN chmod +x /etc/my_init.d/load_sys_varibles.sh
—> Running in 764866552f25
—> eae3d7f1eac5
Removing intermediate container 764866552f25
Step 6 : CMD ["/sbin/my_init"]
—> Running in 9ab8d0b717a7
—> 8be4e7b6b174
Removing intermediate container 9ab8d0b717a7
Successfully built 8be4e7b6b174

$ sudo docker run -it "myphusion:v1"
*** Running /etc/my_init.d/00_regen_ssh_host_keys.sh…
No SSH host key available. Generating one…
Creating SSH2 RSA key; this may take some time …
Creating SSH2 DSA key; this may take some time …
Creating SSH2 ECDSA key; this may take some time …
Creating SSH2 ED25519 key; this may take some time …
invoke-rc.d: policy-rc.d denied execution of restart.
*** Running /etc/my_init.d/load_sys_varibles.sh…
sysctl: setting key "kernel.shmmax": Read-only file system
*** /etc/my_init.d/load_sys_varibles.sh failed with status 255

*** Killing all processes…

唉，还是老问题！即便是在my_init中执行，依旧无法逾越Read-only file system，查看Phusion/baseimage的Dockerfile才知道，它也是From ubuntu:14.04的，根不变，上层再怎么折腾也没用。

换一种容器run方法吧，加上–privileged：

$ sudo docker run -it –privileged "myphusion:v1"
*** Running /etc/my_init.d/00_regen_ssh_host_keys.sh…
No SSH host key available. Generating one…
Creating SSH2 RSA key; this may take some time …
Creating SSH2 DSA key; this may take some time …
Creating SSH2 ECDSA key; this may take some time …
Creating SSH2 ED25519 key; this may take some time …
invoke-rc.d: policy-rc.d denied execution of restart.
*** Running /etc/my_init.d/load_sys_varibles.sh…
*** Running /etc/rc.local…
*** Booting runit daemon…
*** Runit started as PID 102

这回灵光了。enter到容器里看看设置的值是否生效了：

root@9e399f46372a:~#cat /proc/sys/kernel/shmmax
68719476736

结果如预期。这样来看phusion/baseimage算是为sysctl -p加载系统变量值提供了一个便利，但依旧无法脱离–privileged，且依旧无法在image中持久化这个设置。

在Docker github的issue中有人提出建议在Dockerfile中加入类似RUNP这样的带有特权的指令语法，但不知何时才能在Docker中加入这一功能。

总而言之，基于目前docker官网提供的base image，我们很难找到特别理想的修改系统变量值的方法，除非自己制作base image，这个还没尝试过，待后续继续研究。

docker容器内服务程序的优雅退出

bigwhite — Thu, 09 Oct 2014 13:58:49 +0000

近期在试验如何将我们的产品部署到docker容器中去，这其中涉及到一个技术环节，那就是如何让docker容器退出时其内部运行的服务程序也可以优雅的退出。所谓优雅退出，指的就是程序在退出前有清理资源（比如关闭文件描述符、关闭socket），保存必要中间状态，持久化内存数据（比如将内存中的数据flush到文件中）的机会。docker作为目前最火的轻量级虚拟化技术，其在后台服务领域的应用是极其广泛的，其设计者在程序优雅退出方面是有考虑的。下面我们由简单到复杂逐一考量一下。

一、优雅退出的原理

对于服务程序而言，一般都是以daemon形式运行在后台的。通知这些服务程序退出需要使用到系统的signal机制。一般服务程序都会监听某个特定的退出signal，比如SIGINT、SIGTERM等（通过kill -l命令你可以查看到几十种signal）。当我们使用kill + 进程号时，系统会默认发送一个SIGTERM给相应的进程。该进程通过signal handler响应这一信号，并在这个handler中完成相应的“优雅退出”操作。

与“优雅退出”对立的是“暴力退出”，也就是我们常说的使用kill -9，也就是kill -s SIGKILL + 进程号，这个行为不会给目标进程任何时间空隙，而是直接将进程杀死，无论进程当前在做何种操作。这种操作常常导致“不一致”状态的出现。SIGKILL这个信号比较特殊，进程无法有效监听该信号，无法有效针对该信号设置handler，无法改变其信号的默认处理行为。

二、测试用“服务程序”

为了测试docker容器对优雅退出的支持，我们编写如下“服务程序”用于放在docker容器中运行：

//dockerapp1.go

package main

import "fmt"
import "time"
import "os"
import "os/signal"
import "syscall"

type signalHandler func(s os.Signal, arg interface{})

type signalSet struct {
m map[os.Signal]signalHandler
}

func signalSetNew() *signalSet {
        ss := new(signalSet)
        ss.m = make(map[os.Signal]signalHandler)
        return ss
}

func (set *signalSet) register(s os.Signal, handler signalHandler) {
        if _, found := set.m[s]; !found {
                set.m[s] = handler
        }
}

func (set *signalSet) handle(sig os.Signal, arg interface{}) (err error) {
        if _, found := set.m[sig]; found {
                set.m[sig](sig, arg)
                return nil
        } else {
                return fmt.Errorf("No handler available for signal %v", sig)
        }

panic("won't reach here")
}

func main() {
go sysSignalHandleDemo()
time.Sleep(time.Hour) // make the main goroutine wait!
}

func sysSignalHandleDemo() {
        ss := signalSetNew()
        handler := func(s os.Signal, arg interface{}) {
                fmt.Printf("handle signal: %v\n", s)
                if s == syscall.SIGTERM {
                        fmt.Printf("signal termiate received, app exit normally\n")
                        os.Exit(0)
                }
        }

        ss.register(syscall.SIGINT, handler)
        ss.register(syscall.SIGUSR1, handler)
        ss.register(syscall.SIGUSR2, handler)
        ss.register(syscall.SIGTERM, handler)

        for {
                c := make(chan os.Signal)
                var sigs []os.Signal
                for sig := range ss.m {
                        sigs = append(sigs, sig)
                }
                signal.Notify(c)
                sig := <-c

                err := ss.handle(sig, nil)
                if err != nil {
                        fmt.Printf("unknown signal received: %v, app exit unexpectedly\n", sig)
                        os.Exit(1)
                }
        }
}

关于Go语言对系统Signal的处理，可以参考《Go中的系统Signal处理》一文。

三、制作测试用docker image

在《 Ubuntu Server 14.04安装docker》一文中，我们完成了在ubuntu 14.04上安装docker的步骤。要制作测试用docker image，我们首先需要pull一个base image。我们以CentOS6.5为例：

在Ubuntu 14.04上执行：
sudo docker pull centos:centos6

docker会自动从官方仓库下载一个制作好的docker image。下载成功后，我们可以run一下试试，像这样：

$> sudo docker run -t -i centos:centos6 /bin/bash

我们查看一下CentOS6的小版本：
$> cat /etc/centos-release
CentOS release 6.5 (Final)

这是一个极其精简的CentOS，各种工具均未安装：
bash-4.1# telnet
bash: telnet: command not found
bash-4.1# ssh
bash: ssh: command not found
bash-4.1# ftp
bash: ftp: command not found
bash-4.1# echo $PATH
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

如果你要安装一些必要的工具，可以直接使用yum install，默认的base image已经将yum配置好了，可以直接使用。如果通过公司代理访问外部网络，别忘了先export http_proxy。另外docker直接使用宿主机的/etc/resolv.conf作为容器的DNS，我们也无需额外设置DNS。

接下来，我们就制作我们的第一个测试用image。安装官方推荐的Best Practice，我们使用Dockerfile来bulid一个测试用image。步骤如下：

- 建立~/ImagesFactory目录
- 将构建好的dockerapp1拷贝到~/ImagesFactory目录下
- 进入~/ImagesFactory目录，创建Dockerfile文件，Dockerfile内容如下：

FROM centos:centos6
MAINTAINER Tony Bai
COPY ./dockerapp1 /bin
CMD /bin/dockerapp1

- 执行docker build，结果如下：

$ sudo docker build -t="test:v1" ./
Sending build context to Docker daemon 7.496 MB
Sending build context to Docker daemon
Step 0 : FROM centos:centos6
—> 68edf809afe7
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> c617b456934a
Step 2 : COPY ./dockerapp1 /bin
2014/10/09 16:05:25 lchown /var/lib/docker/aufs/mnt/fb0e864d3f07ca17ef8b6b69f034728e1f1158fd3f9c83fa48243054b2f26958/bin/dockerapp1: not a directory

居然build失败，提示什么not a directory。于是各种Search，终于发现问题所在，原来是“COPY ./dockerapp1 /bin”这条命令错了，少了个“/”，将" /bin"改为“/bin/”就OK了，Docker真是奇怪啊，这块明显应该做得更兼容些。新的Dockerfile如下：

FROM centos:centos6
MAINTAINER Tony Bai
COPY ./dockerapp1 /bin/
CMD /bin/dockerapp1

构建结果如下：

$ sudo docker build -t="test:v1" ./
Sending build context to Docker daemon 7.496 MB
Sending build context to Docker daemon
Step 0 : FROM centos:centos6
—> 68edf809afe7
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> c617b456934a
Step 2 : COPY ./dockerapp1 /bin/
—> 20c3783c42ab
Removing intermediate container cab639ab4321
Step 3 : CMD /bin/dockerapp1
—> Running in 31875d3c37f9
—> 21a720a808a7
Removing intermediate container 31875d3c37f9
Successfully built 21a720a808a7

$ sudo docker images
REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE
test v1 21a720a808a7 59 seconds ago 214.6 MB

四、第一个测试容器

我们基于image "test:v1"启动一个测试容器：

$ sudo docker run -d "test:v1"
daf3ae88fec23a31cde9f6b9a3f40057953c87b56cca982143616f738a84dcba

$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
daf3ae88fec2 test:v1 "/bin/sh -c /bin/doc 17 seconds ago Up 16 seconds condescending_sammet

通过docker run命令，我们基于image"test:v1"启动了一个容器。通过docker ps命令可以看到容器成功启动，容器id：daf3ae88fec2，别名为：condescending_sammet。

根据Dockerfile我们知道，容器启动后将执行"/bin/dockerapp1"这个程序，dockerapp1退出，容器即退出。 run命令的"-d"选项表示容器将以daemon的形式运行，我们在前台无法看到容器的输出。那么我们怎么查看容器的输出呢？我们可以通过 docker logs + 容器id的方式查看容器内应用的标准输出或标准错误。我们也可以进入容器来查看。

进入容器有多种方法，比如用sudo docker attach daf3ae88fec2。attach后，就好比将daemon方式运行的容器拿到了前台，你可以Ctrl + C一下，可以看到如下dockerapp1的输出:

^Chandle signal: interrupt

另外一种方式是利用nsenter工具进入我们容器的namespace空间。ubuntu 14.04下可以通过如下方式安装该工具：

$ wget https://www.kernel.org/pub/linux/utils/util-linux/v2.24/util-linux-2.24.tar.gz; tar xzvf util-linux-2.24.tar.gz
$ cd util-linux-2.24
$ ./configure –without-ncurses && make nsenter
$ sudo cp nsenter /usr/local/bin

安装后，我们通过如下方式即可进入上面的容器：

$ echo $(sudo docker inspect –format "{{ .State.Pid }}" daf3ae88fec2)
5494
$ sudo nsenter –target 5494 –mount –uts –ipc –net –pid
-bash-4.1# ps -ef
UID        PID PPID C STIME TTY          TIME CMD
root         1     0 0 09:20 ?        00:00:00 /bin/dockerapp1
root        16     0 0 09:32 ?        00:00:00 -bash
root        27    16 0 09:32 ?        00:00:00 ps -ef
-bash-4.1#

进入容器后通过ps命令可以看到正在运行的dockerapp1程序。在容器内，我们可以通过kill来测试dockerapp1的运行情况：

-bash-4.1# kill -s SIGINT 1

通过前面的attach窗口，我们可以看到dockerapp1输出:

handle signal: interrupt

如果你发送SIGTERM信号，那么dockerapp1将终止运行，容器也就停止了。

-bash-4.1# kill 1

attach窗口显示：

signal termiate received, app exit normally

我们可以看到容器启动后默认执行的时Dockerfile中的CMD命令，如果Dockerfile中有多行CMD命令，Docker在启动容器时只会执行最后一条CMD命令。如果在docker run中指定了命令，docker则会执行命令行中的命令而不会执行dockerapp1，比如：

$ sudo docker run -t -i "test:v1" /bin/bash
bash-4.1#

这里我们看到直接执行的时bash，dockerapp1并未执行。

五、docker stop的行为

我们先来看看docker stop的manual：

$ sudo docker stop –help
Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
Stop a running container by sending SIGTERM and then SIGKILL after a grace period
-t, –time=10 Number of seconds to wait for the container to stop before killing it. Default is 10 seconds.

可以看出当我们执行docker stop时，docker会首先向容器内的当前主程序发送一个SIGTERM信号，用于容器内程序的退出。如果容器在收到SIGTERM后没有马上退出，那么stop命令会在等待一段时间（默认是10s）后，再向容器发送SIGKILL信号，将容器杀死，变为退出状态。

我们来验证一下docker stop的行为。启动刚才那个容器：

$ sudo docker start daf3ae88fec2
daf3ae88fec2

attach到容器daf3ae88fec2
$ sudo docker attach daf3ae88fec2

新打开一个窗口，执行docker stop命令：
$ sudo docker stop daf3ae88fec2
daf3ae88fec2

可以看到attach窗口输出：
handle signal: terminated
signal termiate received, app exit normally

通过docker ps查看，发现容器已经退出。

也许通过上面的例子还不能直观的展示stop命令的两阶段行为，因为dockerapp1收到SIGTERM后直接就退出了，stop命令无需等待容器慢慢退出，也无需发送SIGKILL。我们改造一下dockerapp1这个程序。

我们复制一下dockerapp1.go为dockerapp2.go，编辑dockerapp2.go，将handler中对SIGTERM的处理注释掉，其他不变：

handler := func(s os.Signal, arg interface{}) {
                fmt.Printf("handle signal: %v\n", s)
                /*
                if s == syscall.SIGTERM {
                        fmt.Printf("signal termiate received, app exit normally\n")
                        os.Exit(0)
                }
                */
        }

我们使用dockerapp2来构建一个新image：test:v2，将Dockerfile中得dockerapp1换成 dockerapp2即可。

$ sudo docker build -t="test:v2" ./
Sending build context to Docker daemon 9.369 MB
Sending build context to Docker daemon
Step 0 : FROM centos:centos6
—> 68edf809afe7
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> c617b456934a
Step 2 : COPY ./dockerapp2 /bin/
—> 27cd613a9bd7
Removing intermediate container 07c760b6223b
Step 3 : CMD /bin/dockerapp2
—> Running in 1aac086452a7
—> 82eb876fefd2
Removing intermediate container 1aac086452a7
Successfully built 82eb876fefd2

利用image "test:v2"创建一个容器来测试stop。

$ sudo docker run -d "test:v2"
29f3ec1af3c355458cbbd802a5e8a53da28e9f51a56ce822c7bba2a772edceac

$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
29f3ec1af3c3 test:v2 "/bin/sh -c /bin/doc 7 seconds ago Up 6 seconds romantic_feynman

Attach到这个容器并观察，在另外一个窗口stop该container。我们在attach窗口只看到如下输出：

handle signal: terminated

stop命令的执行没有立即返回，而是等待容器退出。等待10s后，容器退出，stop命令执行结束。从这个例子我们可以明显看出stop的两阶段行为。

如果我们以sudo docker run -i -t "test:v1" /bin/bash形式启动容器，那stop命令会将SIGTERM发送给bash这个程序，即使你通过nsenter进入容器，启动了dockerapp1，dockerapp1也不会收到SIGTERM，dockerapp1会随着容器的退出而被强行终止，就像被 kill -9了一样。

六、多进程容器服务程序

上面无论是dockerapp1还是dockerapp2，都是一个单进程服务程序。如果我们在容器内执行一个多进程程序，我们该如何优雅退出呢？我们先来编写一个多进程的服务程序dockerapp3：

在dockerapp1.go的基础上对main和sysSignalHandleDemo进行修改形成dockerapp3.go，修改后这两个函数的代码如下：

//dockerapp3.go
… …

func main() {
go sysSignalHandleDemo()

        pid, _, err := syscall.RawSyscall(syscall.SYS_FORK, 0, 0, 0)
        if err != 0 {
                fmt.Printf("err fork process, err: %v\n", err)
                return
        }

        if pid == 0 {
                fmt.Printf("i am in child process, pid = %v\n", syscall.Getpid())
                time.Sleep(time.Hour) // make the child process wait
        }
        fmt.Printf("i am parent process, pid = %v\n", syscall.Getpid())
        fmt.Printf("fork ok, childpid = %v\n", pid)
        time.Sleep(time.Hour) // make the main goroutine wait!
}

func sysSignalHandleDemo() {
        ss := signalSetNew()
        handler := func(s os.Signal, arg interface{}) {
                fmt.Printf("%v: handle signal: %v\n", syscall.Getpid(), s)
                if s == syscall.SIGTERM {
                        fmt.Printf("%v: signal termiate received, app exit normally\n", syscall.Getpid())
                        os.Exit(0)
                }
        }

        ss.register(syscall.SIGINT, handler)
        ss.register(syscall.SIGUSR1, handler)
        ss.register(syscall.SIGUSR2, handler)
        ss.register(syscall.SIGTERM, handler)

                err := ss.handle(sig, nil)
                if err != nil {
                        fmt.Printf("%v: unknown signal received: %v, app exit unexpectedly\n", syscall.Getpid(), sig)
                        os.Exit(1)
                }
        }
}

dockerapp3利用fork创建了一个子进程，这样dockerapp3实际上是两个进程在运行，各自有自己的signal监听 goroutine，goroutine的处理逻辑是相同的。注意：由于Windows和Mac OS X不具备fork语义，因此在这两个平台上运行dockerapp3不会得到预期结果。

利用dockerapp3，我们创建image "test:v3":

$ sudo docker build -t="test:v3" ./
[sudo] password for tonybai:
Sending build context to Docker daemon 11.24 MB
Sending build context to Docker daemon
Step 0 : FROM centos:centos6
—> 68edf809afe7
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> c617b456934a
Step 2 : COPY ./dockerapp3 /bin/
—> 6ccf97065853
Removing intermediate container 6d85fe241939
Step 3 : CMD /bin/dockerapp3
—> Running in 75d76380992a
—> c9e7bf361ed7
Removing intermediate container 75d76380992a
Successfully built c9e7bf361ed7

启动基于test:v3 image的容器：

$ sudo docker run -d "test:v3"
781cecb4b3628cb33e1b104ea57e506ad5cb4a44243256ebd1192af86834bae6
$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
781cecb4b362 test:v3 "/bin/sh -c /bin/doc 5 seconds ago Up 4 seconds insane_bohr

通过docker logs查看dockerapp3的输出：

$ sudo docker logs 781cecb4b362
i am parent process, pid = 1
fork ok, childpid = 13
i am in child process, pid = 13

可以看出主进程pid为1，子进程pid为13。我们通过stop停止该容器：

$ sudo docker stop 781cecb4b362
781cecb4b362

再次通过docker logs查看：

$ sudo docker logs 781cecb4b362
i am parent process, pid = 1
fork ok, childpid = 13
i am in child process, pid = 13
1: handle signal: terminated
1: signal termiate received, app exit normally

我们可以看到主进程收到了stop发来的SIGTERM并退出，主进程的退出导致容器退出，导致子进程13也无法生存，并且没有优雅退出。而在非容器状态下，子进程是可以被init进程接管的。

因此对于docker容器内运行的多进程程序，stop命令只会将SIGTERM发送给容器主进程，要想让其他进程也能优雅退出，需要在主进程与其他进程间建立一种通信机制。在主进程退出前，等待其他子进程退出。待所有其他进程退出后，主进程再退出，容器停止。这样才能保证服务程序的优雅退出。

七、容器内启动多个服务程序

虽说docker best practice建议一个container内只放置一个服务程序，但对已有的一些遗留系统，在架构没有做出重构之前，很可能会有在一个 container中部署两个以上服务程序的情况和需求。而docker Dockerfile只允许执行一个CMD，这种情况下，我们就需要借助类似supervisor这样的进程监控管理程序来启动和管理container 内的多个程序了。

下面我们来自制作一个基于centos:centos6的安装了supervisord以及两个服务程序的image。我们将dockerapp1拷贝一份，并将拷贝命名为dockerapp1-brother。下面是我们的Dockerfile：

FROM centos:centos6
MAINTAINER Tony Bai
RUN yum install python-setuptools -y
RUN easy_install supervisor
RUN mkdir -p /var/log/supervisor
COPY ./supervisord.conf /etc/supervisord.conf
COPY ./dockerapp1 /bin/
COPY ./dockerapp1-brother /bin/
CMD ["/usr/bin/supervisord"]

supervisord的配置文件supervisord.conf内容如下：

; supervisor config file

[unix_http_server]
file=/var/run/supervisor.sock ; (the path to the socket file)
chmod=0700 ; sockef file mode (default 0700)

[supervisord]
logfile=/var/log/supervisor/supervisord.log ; (main log file;default $CWD/supervisord.log)
pidfile=/var/run/supervisord.pid ; (supervisord pidfile;default supervisord.pid)
childlogdir=/var/log/supervisor ; ('AUTO' child log dir, default $TEMP)

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

[supervisorctl]
serverurl=unix:///var/run/supervisor.sock ; use a unix:// URL for a unix socket

[supervisord]
nodaemon=false

[program:dockerapp1]
command=/bin/dockerapp1
stdout_logfile=/tmp/dockerapp1.log
stopsignal=TERM
stopwaitsecs=10

[program:dockerapp1-brother]
command=/bin/dockerapp1-brother
stdout_logfile=/tmp/dockerapp1-brother.log
stopsignal=QUIT
stopwaitsecs=10

开始build镜像：
    $> sudo docker build -t="test:supervisor-v1" ./
    … …
    Successfully built d006b9ad10eb

基于该镜像，启动一个容器：
$> sudo docker run -d "test:supervisor-v1"
05ded2b898c90059d4c9b5c6ccc8603b6848ae767360c42bd9b36ff87fb4b9df

执行ps命令查看镜像id：
$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

怎么回事？Container没有启动起来？

$ sudo docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
05ded2b898c9 test:supervisor-v1 "/usr/bin/supervisor 22 seconds ago Exited (0) 21 seconds ago hungry_engelbart

通过ps -a查看，container启动是成功了，但是成功退出了。于是尝试查看一下log：

sudo docker logs 05ded2b898c9
/usr/lib/python2.6/site-packages/supervisor-3.1.2-py2.6.egg/supervisor/options.py:296: UserWarning: Supervisord is running as root and it is searching for its configuration file in default locations (including its current working directory); you probably want to specify a "-c" argument specifying an absolute path to a configuration file for improved security.
'Supervisord is running as root and it is searching '

似乎是supervisord转为daemon程序，容器主进程退出了，容器随之终止了。

看来容器内的supervisord不能以daemon形式运行，应该以前台形式run。修改一下supervisord.conf中得配置：

将
[supervisord]
nodaemon=false

改为

[supervisord]
nodaemon=true

重新制作镜像:

$ sudo docker build -t="test:supervisor-v2" ./
Sending build context to Docker daemon 13.12 MB
Sending build context to Docker daemon
Step 0 : FROM centos:centos6
—> 68edf809afe7
Step 1 : MAINTAINER Tony Bai
—> Using cache
—> c617b456934a
Step 2 : RUN yum install python-setuptools -y
—> Using cache
—> e09c66a1ea8c
Step 3 : RUN easy_install supervisor
—> Using cache
—> 9c8797e8c27e
Step 4 : RUN mkdir -p /var/log/supervisor
—> Using cache
—> 9bfc67f8517d
Step 5 : COPY ./supervisord.conf /etc/supervisord.conf
—> 8c514f998363
Removing intermediate container 4a185856e6ed
Step 6 : COPY ./dockerapp1 /bin/
—> 0317bd4914d3
Removing intermediate container ac5738380854
Step 7 : COPY ./dockerapp1-brother /bin/
—> d89711888bdf
Removing intermediate container eadc9444e716
Step 8 : CMD ["/usr/bin/supervisord"]
—> Running in aaa042ac3914
—> 9655256bbfed
Removing intermediate container aaa042ac3914
Successfully built 9655256bbfed

有了前面的铺垫，这次build image瞬间完成。启动容器，查看容器启动状态，查看容器内supervisord的运行日志如下：

$ sudo docker run -d "test:supervisor-v2"
61916f1c82338b28ced101b6bde119e4afb7c7fa349b4332ed51a43a4586b1b9

$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
61916f1c8233 test:supervisor-v2 "/usr/bin/supervisor 16 seconds ago Up 16 seconds prickly_einstein

$ sudo docker logs 8eb3e9892e66

/usr/lib/python2.6/site-packages/supervisor-3.1.2-py2.6.egg/supervisor/options.py:296: UserWarning: Supervisord is running as root and it is searching for its configuration file in default locations (including its current working directory); you probably want to specify a "-c" argument specifying an absolute path to a configuration file for improved security.
'Supervisord is running as root and it is searching '
2014-10-09 14:36:02,334 CRIT Supervisor running as root (no user in config file)
2014-10-09 14:36:02,349 INFO RPC interface 'supervisor' initialized
2014-10-09 14:36:02,349 CRIT Server 'unix_http_server' running without any HTTP authentication checking
2014-10-09 14:36:02,349 INFO supervisord started with pid 1
2014-10-09 14:36:03,354 INFO spawned: 'dockerapp1' with pid 14
2014-10-09 14:36:03,363 INFO spawned: 'dockerapp1-brother' with pid 15
2014-10-09 14:36:04,368 INFO success: dockerapp1 entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2014-10-09 14:36:04,369 INFO success: dockerapp1-brother entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

可以看到supervisord已经将dockerapp1和dockerapp1-brother启动起来了。

现在我们尝试停止容器，我们预期是supervisord在退出前通知dockerapp1和dockerapp1-brother先退出，我们可以通过查看容器内的/tmp/dockerapp1.log和/tmp/dockerapp1-brother.log来确认supervisord是否做了通知。

$ sudo docker stop 61916f1c8233
61916f1c8233

$ sudo docker logs 61916f1c8233
… …
2014-10-09 14:37:52,253 WARN received SIGTERM indicating exit request
2014-10-09 14:37:52,254 INFO waiting for dockerapp1, dockerapp1-brother to die
2014-10-09 14:37:52,254 INFO stopped: dockerapp1-brother (exit status 0)
2014-10-09 14:37:52,256 INFO stopped: dockerapp1 (exit status 0)

通过容器的log，我们看出supervisord是等待两个程序退出后才退出的，不过我们还是要看看两个程序的输出日志以最终确认。重新启动容器，通过nsenter进入到容器中。

-bash-4.1# vi /tmp/dockerapp1.log

handle signal: terminated
signal termiate received, app exit normally

-bash-4.1# vi /tmp/dockerapp1-brother.log

handle signal: terminated
signal termiate received, app exit normally

两个程序的标准输出日志证实了我们的预期。

BTW，在物理机上测试supervisord以daemon形式运行，当kill掉supervisord时，supervisord是不会通知其监控和管理的程序退出的。只有在以non-daemon形式运行时，supervisord才会在退出前先通知下面的程序退出。如果在一段时间内下面程序没有退出，supervisord在退出前会kill -9强制杀死这些程序的进程。

最后要说的时，在验证一些想法时，没有必要build image，我们可以直接将本地文件copy到容器中，下面是一个例子，我们将dockerapp1和dockerapp1-brother拷贝到镜像中：
$ sudo docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4d8982bfccc7 centos:centos6 "/bin/bash" 26 minutes ago Up 26 minutes sharp_thompson
$ sudo docker inspect -f '{{.Id}}' 4d8982bfccc7
4d8982bfccc79dea762b41f8a6f669bda1ec73c8881b6ca76e7a7917c62972c4
$ sudo cp dockerapp1 /var/lib/docker/aufs/mnt/4d8982bfccc79dea762b41f8a6f669bda1ec73c8881b6ca76e7a7917c62972c4/bin/dockerapp1
$ sudo cp dockerapp1-brother /var/lib/docker/aufs/mnt/4d8982bfccc79dea762b41f8a6f669bda1ec73c8881b6ca76e7a7917c62972c4/bin/dockerapp1-brother

libiconv库链接问题一则

bigwhite — Thu, 25 Apr 2013 10:04:34 +0000

与在Solaris系统上不同，Linux的libc库中包含了libiconv库中函数的定义，因此在Linux上使用libiconv库相关函数，编译时是不需要显式-liconv的。但最近我的一位同事在某redhat enterprise server 5.6机器上编译程序时却遇到了找不到iconv库函数符号的链接问题，到底是怎样一回事呢？这里分享一下问题查找过程。

一、现场重现

这里借用一下这位同事的测试程序以及那台机器，重现一下问题过程：
/*test.c */

…
#include

int main(void)
{
    int r;
    char *sin, *sout;
    size_t lenin, lenout;
    char *src = "你好!";
    char dst[256] = {0};
    iconv_t c_pt;

sin = src;
lenin = strlen(src)+1;

sout = dst;
lenout = 256;

    if ((c_pt = iconv_open("UTF-8", "GB2312")) == (iconv_t)(-1)){
        printf("iconv_open error!. errno[%d].\n", errno);
        return -1;
    }

    if ((r = iconv(c_pt, (char **)&sin, &lenin, &sout, &lenout)) != 0){
        printf("iconv error!. errno[%d].\n", r);
        return -1;
    }

iconv_close(c_pt);

printf("SRC[%s], DST[%s].\n", src, dst);

return 0;
}

根据之前的经验，我们按如下命令编译该程序：

$> gcc -g -o test test.c

/tmp/ccyQ5blC.o: In function `main':
/home/tonybai/tmp/test.c:28: undefined reference to `libiconv_open'
/home/tonybai/tmp/test.c:33: undefined reference to `libiconv'
/home/tonybai/tmp/test.c:38: undefined reference to `libiconv_close'

咦，这是咋搞的呢？怎么找不到iconv库的符号！！！显式加上iconv的链接指示再试试。

$> gcc -g -o test test.c -liconv

这回编译OK了。的确如那位同事所说出现了怪异的情况。

二、现场取证

惯性思维让我首先提出疑问：难道是这台机器上的libc版本有差异，检查一下libc中是否定义了iconv相关符号。

$ nm /lib64/libc.so.6 |grep iconv
000000397141e040 T iconv
000000397141e1e0 T iconv_close
000000397141ddc0 T iconv_open

iconv的函数都定义了呀！怎么会链接不到？

我们再来看看已经编译成功的那个test到底连接到哪个iconv库了。

$ ldd test
    linux-vdso.so.1 => (0x00007fff77d6b000)
    libiconv.so.2 => /usr/local/lib/libiconv.so.2 (0x00002abbeb09e000)
    libc.so.6 => /lib64/libc.so.6 (0×0000003971400000)
    /lib64/ld-linux-x86-64.so.2 (0×0000003971000000)

哦，系统里居然在/usr/local/lib下面单独安装了一份libiconv。gcc显然是链接到这里的libiconv了，但gcc怎么会链接到这里了呢？

三、大侦探的分析^_^

Gcc到底做了什么呢？我们看看其verbose的输出结果。

$ gcc -g -o test test.c -liconv -v
使用内建 specs。
目标：x86_64-redhat-linux
配置为：../configure –prefix=/usr –mandir=/usr/share/man –infodir=/usr/share/info –enable-shared –enable-threads=posix –enable-          checking=release –with-system-zlib –enable-__cxa_atexit –disable-libunwind-exceptions –enable-libgcj-multifile –enable-languages=c,c++,   objc,obj-c++,java,fortran,ada –enable-java-awt=gtk –disable-dssi –disable-plugin –with-java-home=/usr/lib/jvm/java-1.4.2-gcj-1.4.2.0/jre –with-cpu=generic –host=x86_64-redhat-linux
线程模型：posix
gcc 版本 4.1.2 20080704 (Red Hat 4.1.2-50)
/usr/libexec/gcc/x86_64-redhat-linux/4.1.2/cc1 -quiet -v test.c -quiet -dumpbase test.c -mtune=generic -auxbase test -g -version -o /tmp/     ccypZm0v.s
忽略不存在的目录“/usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../x86_64-redhat-linux/include”
#include "…" 搜索从这里开始：
#include <…> 搜索从这里开始：
/usr/local/include
/usr/lib/gcc/x86_64-redhat-linux/4.1.2/include
/usr/include
搜索列表结束。
GNU C 版本 4.1.2 20080704 (Red Hat 4.1.2-50) (x86_64-redhat-linux)
    由 GNU C 版本 4.1.2 20080704 (Red Hat 4.1.2-50) 编译。
GGC 准则：–param ggc-min-expand=100 –param ggc-min-heapsize=131072
Compiler executable checksum: ef754737661c9c384f73674bd4e06594
as -V -Qy -o /tmp/ccaqvDgX.o /tmp/ccypZm0v.s
GNU assembler version 2.17.50.0.6-14.el5 (x86_64-redhat-linux) using BFD version 2.17.50.0.6-14.el5 20061020
/usr/libexec/gcc/x86_64-redhat-linux/4.1.2/collect2 –eh-frame-hdr -m elf_x86_64 –hash-style=gnu -dynamic-linker /lib64/ld-linux-x86-64.so. 2 -o test /usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../lib64/crt1.o /usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../lib64/crti.o /usr/   lib/gcc/x86_64-redhat-linux/4.1.2/crtbegin.o -L/usr/lib/gcc/x86_64-redhat-linux/4.1.2 -L/usr/lib/gcc/x86_64-redhat-linux/4.1.2 -L/usr/lib/gcc/ x86_64-redhat-linux/4.1.2/../../../../lib64 -L/lib/../lib64
-L/usr/lib/../lib64 /tmp/ccaqvDgX.o -liconv -lgcc –as-needed -lgcc_s –no-as-needed -lc -lgcc –as-needed -lgcc_s –no-as-needed /usr/lib/gcc/x86_64-redhat-linux/4.1.2/crtend.o /usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../lib64/crtn.o

从这个结果来看，gcc在search iconv.h这个头文件时，首先找到的是/usr/local/include/iconv.h，而不是/usr/include/iconv.h。这两个文件有啥不同么？

在/usr/local/include/iconv.h中，我找到如下代码：

…
#ifndef LIBICONV_PLUG
#define iconv_open libiconv_open
#endif
extern iconv_t iconv_open (const char* tocode, const char* fromcode);
…

libiconv_open vs iconv_open，卧槽！！！再对比一下前面编译时输出的错误信息：

大侦探醒悟了！大侦探带你还原一下真实情况。

我们在执行gcc -g -o test test.c时，根据gcc -v中include search dir的顺序，gcc首先search到的是/usr/local/include/iconv.h，而这里iconv_open等函数被预编译器替换成了libiconv_open等加上了lib前缀的函数，而这些函数符号显然在libc中是无法找到的，libc中只有不带lib前缀的 iconv_open等函数的定义。大侦探也是一时眼拙了，没有细致查看gcc的编译错误信息中的内容，这就是问题所在！

而gcc -g -o test test.c -liconv为何可以顺利编译通过呢？gcc是如何找到/usr/local/lib下的libiconv的呢？大侦探再次为大家还原一下真相。

我们在执行gcc -g -o test test.c -liconv时，gcc同样首先search到的是/usr/local/include/iconv.h，然后编译test.c源码，ok；接下来启动ld程序进行链接；ld找到了libiconv，ld是怎么找到iconv的呢，libiconv在/usr/local/lib下，ld显然是到这个目录下search了。我们通过执行下面命令可以知晓ld的默认搜索路径：

$> ld -verbose|grep SEARCH
SEARCH_DIR("/usr/x86_64-redhat-linux/lib64"); SEARCH_DIR("/usr/local/lib64"); SEARCH_DIR("/lib64"); SEARCH_DIR("/usr/lib64"); SEARCH_DIR("/usr/x86_64-redhat-linux/lib"); SEARCH_DIR("/usr/lib64"); SEARCH_DIR("/usr/local/lib"); SEARCH_DIR("/lib"); SEARCH_DIR("/usr/lib");

ld的默认search路径中有/usr/local/lib(我之前一直是以为/usr/local/lib不是gcc/ld的默认搜索路径的)，因此找到libiconv就不足为奇了。

四、问题解决

我们不想显式的加上-liconv，那如何解决这个问题呢？我们是否可以强制gcc先找到/usr/include/iconv.h呢？我们先来做个试验。

$ gcc -g -o test test.c -liconv -I ~/include -v
…
忽略不存在的目录“/usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../x86_64-redhat-linux/include”
#include "…" 搜索从这里开始：
#include <…> 搜索从这里开始：
/home/tonybai/include
/usr/local/include
/usr/lib/gcc/x86_64-redhat-linux/4.1.2/include
/usr/include
搜索列表结束。

…

试验结果似乎让我们觉得可行，我们通过-I指定的路径被放在了第一的位置进行search。我们来尝试一下强制gcc先search /usr/include。

$ gcc -g -o test test.c -I ~/include -v
…
忽略不存在的目录“/usr/lib/gcc/x86_64-redhat-linux/4.1.2/../../../../x86_64-redhat-linux/include”
忽略重复的目录“/usr/include”
因为它是一个重复了系统目录的非系统目录
#include "…" 搜索从这里开始：
#include <…> 搜索从这里开始：
/usr/local/include
/usr/lib/gcc/x86_64-redhat-linux/4.1.2/include
/usr/include
搜索列表结束。
…

糟糕！/usr/include被忽略了！还是从/usr/local/include开始，方案失败。

似乎剩下的唯一方案就是将/usr/local/lib下的那份libiconv卸载掉！那就这么做吧^_^！

Go中的系统Signal处理

bigwhite — Fri, 21 Sep 2012 08:56:41 +0000

我们在生产环境下运行的系统要求优雅退出，即程序接收退出通知后，会有机会先执行一段清理代码，将收尾工作做完后再真正退出。我们采用系统Signal来通知系统退出，即kill pragram-pid。我们在程序中针对一些系统信号设置了处理函数，当收到信号后，会执行相关清理程序或通知各个子进程做自清理。kill -9强制杀掉程序是不能被接受的，那样会导致某些处理过程被强制中断，留下无法恢复的现场，导致消息被破坏，影响下次系统启动运行。

最近用Golang实现的一个代理程序也需要优雅退出，因此我尝试了解了一下Golang中对系统Signal的处理方式，这里和大家分享。Golang 的系统信号处理主要涉及os包、os.signal包以及syscall包。其中最主要的函数是signal包中的Notify函数：

func Notify(c chan<- os.Signal, sig …os.Signal)

该函数会将进程收到的系统Signal转发给channel c。转发哪些信号由该函数的可变参数决定，如果你没有传入sig参数，那么Notify会将系统收到的所有信号转发给c。如果你像下面这样调用Notify：

signal.Notify(c, syscall.SIGINT, syscall.SIGUSR1, syscall.SIGUSR2)

则Go只会关注你传入的Signal类型，其他Signal将会按照默认方式处理，大多都是进程退出。因此你需要在Notify中传入你要关注和处理的Signal类型，也就是拦截它们，提供自定义处理函数来改变它们的行为。

下面是一个较为完整的例子：

//signal.go

package main

import "fmt"
import "time"
import "os"
import "os/signal"
import "syscall"

type signalHandler func(s os.Signal, arg interface{})

type signalSet struct {
m map[os.Signal]signalHandler
}

func signalSetNew()(*signalSet){
    ss := new(signalSet)
    ss.m = make(map[os.Signal]signalHandler)
    return ss
}

func (set *signalSet) register(s os.Signal, handler signalHandler) {
    if _, found := set.m[s]; !found {
        set.m[s] = handler
    }
}

func (set *signalSet) handle(sig os.Signal, arg interface{})(err error) {
    if _, found := set.m[sig]; found {
        set.m[sig](sig, arg)
        return nil
    } else {
        return fmt.Errorf("No handler available for signal %v", sig)
    }

panic("won't reach here")
}

func main() {
go sysSignalHandleDemo()
time.Sleep(time.Hour) // make the main goroutine wait!
}

func sysSignalHandleDemo() {
    ss := signalSetNew()
    handler := func(s os.Signal, arg interface{}) {
        fmt.Printf("handle signal: %v\n", s)
    }

    ss.register(syscall.SIGINT, handler)
    ss.register(syscall.SIGUSR1, handler)
    ss.register(syscall.SIGUSR2, handler)

    for {
        c := make(chan os.Signal)
        var sigs []os.Signal
        for sig := range ss.m {
            sigs = append(sigs, sig)
        }
        signal.Notify(c)
        sig := <-c

        err := ss.handle(sig, nil)
        if (err != nil) {
            fmt.Printf("unknown signal received: %v\n", sig)
            os.Exit(1)
        }
    }
}

上例中Notify函数只有一个参数，没有传入要关注的sig，因此程序会将收到的所有类型Signal都转发到channel c中。build该源文件并执行程序：

$> go build signal.go
$> signal

在另外一个窗口下执行如下命令：
$> ps -ef|grep signal
tonybai 25271 1087 0 16:27 pts/1 00:00:00 signal
$> kill -n 2 25271
$> kill -n 12 25271
$> kill 25271

我们在第一个窗口会看到如下输出：
$> signal
handle signal: interrupt
handle signal: user defined signal 2
unknown signal received: terminated

在sysSignalHandleDemo中我们也可以为Notify传入我们所关注的Signal集合：

signal.Notify(c, sigs…)

这样只有在该集合中的信号我们才能捕获，收到未在集合中的信号时，程序多直接退出。上面只是一个Demo，只是说明了我们可以捕捉到我们所关注的信号，并未体现程序如何优雅退出，不同程序的退出方式不同，这里没有通用方法，就不细说了，你的程序需要你专门的设计。

另外我们生产环境下的程序多是以Daemon守护进程的形式运行的。我们用C实现的程序多参考“Unix高级编程”中的方法将程序转为Daemon Process，但在Go中目前尚提供相关方式，网上有一些实现，但据说都不理想。更多的Go开发者建议不要在代码中实现Daemon转换，建议直接利用第三方工具。比如在Ubuntu下我们可以使用start-stop-daemon这个小程序轻松将你的程序转换为Daemon：

$> start-stop-daemon –start –pidfile ./signal.pid –startas /home/tonybai/test/go/signal –background -m
$> start-stop-daemon –stop –pidfile ./signal.pid –startas /home/tonybai/test/go/signal

这里注意：只有加上-m选项，pidfile才能成功创建。

start-stop-daemon在Debian系的Linux发行版中都是默认自带的。但在Redhat系Linux发行版中却没有该工具，我们可以自行安装：

wget -c http://developer.axis.com/download/distribution/apps-sys-utils-start-stop-daemon-IR1_9_18-2.tar.gz
tar -xzf apps-sys-utils-start-stop-daemon-IR1_9_18-2.tar.gz
cd apps/sys-utils/start-stop-daemon-IR1_9_18-2
gcc start-stop-daemon.c -o start-stop-daemon

切换到root下
cp start-stop-daemon /sbin/
chmod +x /sbin/start-stop-daemon

另外Go 1.0.2提供的二进制安装包直接在Redhat 5.6(Linux tonybai 2.6.18-238.el5 #1 SMP Sun Dec 19 14:22:44 EST 2010 x86_64 x86_64 x86_64 GNU/Linux)下面运行出错，提示无法找到GLIBC 2.7版本。目前解决这一问题的方法似乎只有从源码编译安装。进入到$GOROOT/src下，执行./all.bash即可。重现编译链接后的go可执行程序则运行一切正常。

如何加入Linux内核开发社区(7)

bigwhite — Mon, 09 Apr 2012 05:25:34 +0000

本文翻译自The Linux Foundation的《How to Participate in the Linux Community》(基于2012-03-21最新版本)，原作者为Jonathan Corbet(corbet@lwn.net)。下面是该文章第七章、第八章以及第九章节的中译文。

7、高级主题

但愿此时此刻，你已经理解了内核开发过程是如何进行的。但仍然还有很多东西要学习！这一节将涵盖几个主题，这些主题对于那些致力于成为Linux 内核开发过程中固定一员的开发者来说是很有帮助的。

7.1、使用Git管理补丁

早在2002年，内核就开始使用分布式版本管理工具了，当时Linus首先使用的是一款名为BitKeeper的专有(proprietary) 应用。虽然BitKeeper是有争议的，但它所代表的软件版本管理方法几乎是没有任何争议的。分布式版本控制使得内核开发项目的开发效率获得了加速地提升。如今，有很多种可以替代BitKeeper的工具。不管结果如何，内核项目已经决定了将git作为其版本管理工具的选择。

使用git管理补丁可以使开发者的工作更加轻松，特别是当补丁的数量越来越多的情况下。Git也有其不完善的地方并且可能产生某种危险；它是一个年轻而强大的工具，目前其开发者仍然在对其进行改进。本文不会尝试教授读者们如何使用git；其自带的长文档提供了足够的资料。相反，这里着重关注git是如何融入到内核开发过程中去的。那些期望快速学会使用git的开发者可以在下面网址中找到更多信息：

http://git-scm.com/

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

并且可以在互联网上找到各种不同的教程。

第一件事就是阅读上述站点所提供的内容，在尝试使用git制作补丁之前充分理解git的工作原理。一个使用git的开发者应该能够从内核主线库获得代码拷贝、查看修改历史记录、向代码树提交改变以及使用分支等。对git重写历史的工具(例如rebase)的理解也是很有用的。Git尤其自己的术语与概念；一个git的新用户应该知道引用(refs)、远程分支(remote branches)、暂存区(index，译注：现在更多称之为stage)、快进合并(fast-forward merge)、推(push)和拉(pull)以及detached heads等。一开始这些可能会让人感到有些望而生畏，但通过一点点学习这些概念掌握起来也不是那么难。

使用git生成通过email提交的补丁是一种用来加快git学习速度的非常好的练习。

如果你准备创建一个供其他人查看的git源码树，你自然会需要一个服务器，其他人可以从该服务器上拉(pull)代码。如果你拥有一个可以访问互联网的系统，使用git-daemon搭建这个服务器将会相对简单一些。否则，一些出现在互联网上的免费的公共托管站点(例如，Github)可供使用。已被社区认可的开发者可以从kernel.org获得一个帐户，但这些可是来之不易的；更多内容请参见http://kernel.org/faq/ 。

正常的git工作流程涉及到许多分支使用。每行代码都可能被分离到一个独立的"主题分支"中并且独立维护。在Git中使用分支的代价非常小，我们没有理由不自由使用它们。并且，无论如何你都不应该在一个你想要其他人从中拉取(pull)代码的分支上进行开发。对公众开放的分支应该谨慎创建；只有当开发分支上的代码完成并具备发布条件时再将代码合并到补丁中，不要在完成之前就合并。

Git提供了一些功能强大的工具，它们可以让你重写开发历史。一个令人为难的补丁(可能是破坏了bisection的补丁，又或是有其他明显bug的补丁)可能在适当地方被修复或整体从开发历史中消失。一个补丁序列可以被重写，重写后就好似今天主线上最新的修改似的，即便你已经在这个补丁序列上工作几个月了。改变可以透明地从一个分支转移到另一个分支，等等。明智地的使用git所提供的能力对代码库历史进行修订可以有助于创建出问题更少的整洁的补丁集合。

然而，除了着迷于创建一个完美的项目历史之外，过度地使用git提供的能力可能会导致其他问题。重写历史将重写历史所对应的改变，将一个测试过(希望是)的内核树转化为一个未测试过的内核。但是，除此之外，如果没有有关项目历史的共享视图，开发者间的合作将不会那么容易；如果你重写了一段代码历史，并且其他开发者已经将这段代码拉入其个人代码库，你会让这些开发者的工作变得更为困难。因此，这里可以应用一条简单的经验法则：已经被导出到其他库中的历史记录此后一般应被视作不可改变的。

这样，一旦你向你的公共代码库服务器推送了一组变更，这些变更就不应该被重写了。如果你尝试推送无法进行快进合并(例如，那些没有共享同一变更历史的改变)的变更，Git会试图强制执行这条规则。对这种检查进行重写是可能的，并且有时重写一个导出源码树可能是必须的。在linux-next中通过在树间移动变更集(changesets)来避免冲突就是一个例子。不过这种行为应该是不常发生的。这也是开发工作要在私有分支上(必要时可以进行历史重写)完成并只是在其处于开发后期时才移到公共分支的原因之一。

随着主线版本(或即将到来的其他基于一组变更的源码树)的推进，人们总愿意合并那些树以保持走在开发的最前沿。对于一个私有分支来说，换基(rebasing)可以作为一种跟上另外一棵源码树开发进度的简单方法，但一旦源码树已经对外发布，换基这种方法就不再适合。一旦如此，就必须进行全量合并(full merge)。偶尔的合并很有意义，但过于频繁的合并可能会导致修订历史不必要得混乱。针对这种情况的建议是不要频繁地合并，通常只在特定发布点(例如，一个主线的-rc版本发布时)进行合并操作。如果你对特定的变更感到紧张不安，那么你可以一直在私有分支上进行测试合并。git的"rerere"工具在这种情况下十分有用；它会记住合并时的冲突是如何被解决的，这样你就无需再做一遍这个工作了。

关于类似git这样的工具的一个最大的抱怨是：补丁从一棵树到另一棵树的大量的迁移使得许多欠考虑的变更很容易通过评审雷达的盲区而进入内核主线。当内核开发者看到这种事情发生时都会十分不满；搭建一棵包含了未评审或离题补丁的源码树很可能会对以后你的源码树被内核主线合并的资格产生影响。这里引述Linus的一段话：

你可以给我发送补丁，不过对我来说是从你那里拉出一个git补丁。我需要知道你十分清楚你自己正在做什么，并且我需要有能力在无需手工逐个检查每个变更的情况下信任你所做的这些工作。(http://lwn.net/Articles/224135/).

为了避免这类情况，请确保一个特定分支里面的所有补丁都紧扣相关主题；一个"驱动程序修复"分支不应该对核心内存管理代码进行修改。并且，更为重要的是，不要使用git树绕过评审过程。不时地将源码树的概要发到相关的邮件列表中，并且当时机合适时，请求将你的源码树中的变更包含到linux-next中。

如果当其他人开始向你的源码树发送补丁时，不要忘记评审这些补丁代码。同时，也要保证你维护着正确的作者身份信息；在这方面git的"am"工具做得最好，不过对于那些通过第三方转发给你的补丁，你需要为补丁增加一个"From:"行。

当提出"拉出"请求时，请确保提供了所有相关信息：你的源码树的位置，从哪个分支拉出，以及此次拉出将导致哪些改变。在这方面，git的"request-pull"命令很有帮助；这个命令会将请求按照其他开发者所期望的那样进行格式化，并且还会执行检查以确保你记得已经将那些改变提交到公共代码树服务器上了。

7.2、评审补丁

很多读者肯定会反对将本章标题命名为"高级主题"，因为即便是刚入门的内核开发者也应当评审补丁。的确，没有比审查其他人发布的代码更好的方式去学习在内核环境下如何编程了。此外，评审者永远供不应求；通过审查代码，你可以对整个开发过程作出重要的贡献。

评审代码可能是一件令人胆怯的事情，特别是对于内核开发新手们，他们对于那些经验丰富的开发者所公开提出的代码质疑很可能会感到紧张不安。不过，即使是经验最为丰富的开发者所编写到的代码也可能有改进的余地。也许对评审者(所有评审者)最好的建议是：用询问而不是批评来表达评审意见。问"在这条路径上这个锁是如何被释放的？"总是会比"这里的锁用错了"收到更好的效果。

不同的开发者会从不同的角度去评审代码。一些人主要关注代码风格以及是否代码行伴有结尾空白。其他人会主要关注这个补丁所实现的改变对与内核整体来说是好事还是坏事。然而，还有其他一些人将检查有问题的锁、过度使用栈、潜在的安全问题、在其他地方发现重复代码、是否有充足的文档、对内核性能的不利影响、用户空间ABI变化等。如果能够促使更好的代码进入内核，那么所有类型的评审都是受欢迎的并且是值得花时间做的。

8、更多信息

Linux内核开发以及相关主题的信息来源有很多。这里面首当其冲的应该是可以在发布的内核源码包中找到的Documentation目录。顶层的HOWTO文件是一个重要的起点；SubmittingPatches和SubmittingDrivers同样是所有内核开发者都应该阅读的重要文档。许多内核内部API都使用kerneldoc机制进行了文档化；"make htmldocs"或"make pdfdocs"可用于生成HTML或PDF格式(但很多Linux发行版中包含的TeX版本运行时遇到内部限制，因此也无法正确地处理这里的文档)的内核文档。

各种讨论内核开发细节的网络站点。作者这里将http://lwn.net作为一个内核开发信息来源推荐给大家；许多关于特定内核主题的信息都可以通过LWN内核索引找到：

http://lwn.net/Kernel/Index/

除此之外，一个对内核开发者有价值的资源是：

http://kernelnewbies.org/

有关linux-next源码树的资料汇集在：

http://linux.f-seidel.de/linux-next/pmwiki/

当然，大家不应该忘记http://kernel.org，这里可是内核发布版本信息的最终位置。

下面是一些关于内核开发的书籍：

* Linux Device Drivers(译注：其中译版为《Linux设备驱动程序》), 3rd Edition (Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman). 在线版本在http://lwn.net/Kernel/LDD3/。

* Linux Kernel Development (Robert Love)(译注：其中译版为《Linux内核设计与实现》)。

* Understanding the Linux Kernel (Danial Bovet and Marco Cesati)(译注：其中译版为《深入理解Linux内核》)。

但所有这些书籍都有一个共同的不足：在它们上架时往往有些过时，并且它们上架已经有一段时间了。不过，在这些书中我们仍然可以找到很多有价值的资料。

Git的文档可以在下面网址上找到：

http://www.kernel.org/pub/software/scm/git/docs/

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html

9、结论

恭喜每一个读完这篇冗长文档的人。希望本文可以为你对Linux内核的开发过程以及如何加入此过程的理解提供有用的帮助。

最后，最重要的是参与。任何开源软件项目只不过是其所有贡献者所做事情的总和。Linux内核项目进展如此迅速，质量如此之好，都是因为有数量可观的开发者的帮助，他们的工作都是为了创建一个更好的内核。Linux内核就是一个由成千上万人为了一个共同的目标而一起奋斗而完成的一个最好的例子。

虽然内核项目总是能受益于一个更为庞大的开发者基础，但那里也总是有更多的工作要去做。但同样重要的是，在Linux生态系统中的其他大多数参与者也能从对内核的贡献中受益。让代码进入主线是更高代码质量、更低的维护和发行成本、对内核开发方向的更高层次的影响以及更多其他事情的关键。这是一个所有参与者共赢的局面。发动你的编辑器并加入我们吧；你会受到热烈欢迎。

(全文翻译结束)