Tony Bai » yum

Go编译的几个细节，连专家也要停下来想想

bigwhite — Sun, 10 Nov 2024 22:13:45 +0000

本文永久链接 – https://tonybai.com/2024/11/11/some-details-about-go-compilation

在Go开发中，编译相关的问题看似简单，但实则蕴含许多细节。有时，即使是Go专家也需要停下来，花时间思考答案或亲自验证。本文将通过几个具体问题，和大家一起探讨Go编译过程中的一些你可能之前未曾关注的细节。

注：本文示例使用的环境为Go 1.23.0、Linux Kernel 3.10.0和CentOS 7.9。

1. Go编译默认采用静态链接还是动态链接？

我们来看第一个问题：Go编译默认采用静态链接还是动态链接呢？

很多人脱口而出：动态链接，因为CGO_ENABLED默认值为1，即开启Cgo。也有些人会说：“其实Go编译器默认是静态链接的，只有在使用C语言库时才会动态链接”。那么到底哪个是正确的呢？

我们来看一个具体的示例。但在这之前，我们要承认一个事实，那就是CGO_ENABLED默认值为1，你可以通过下面命令来验证这一点：

$go env|grep CGO_ENABLED
CGO_ENABLED='1'

验证Go默认究竟是哪种链接，我们写一个hello, world的Go程序即可：

// go-compilation/main.go

package main

import "fmt"

func main() {
    fmt.Println("hello, world")
}

构建该程序：

$go build -o helloworld-default main.go

之后，我们查看一下生成的可执行文件helloworld-default的文件属性：

$file helloworld-default
helloworld-default: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
$ldd helloworld-default
   不是动态可执行文件

我们看到，虽然CGO_ENABLED=1，但默认情况下，Go构建出的helloworld程序是静态链接的(statically linked)。

那么默认情况下，Go编译器是否都会采用静态链接的方式来构建Go程序呢？我们给上面的main.go添加一行代码：

// go-compilation/main-with-os-user.go

package main

import (
    "fmt"
    _ "os/user"
)

func main() {
    fmt.Println("hello, world")
}

和之前的hello, world不同的是，这段代码多了一行包的空导入，导入的是os/user这个包。

编译这段代码，我们得到helloworld-with-os-user可执行文件。

$go build -o helloworld-with-os-user main-with-os-user.go

使用file和ldd检视文件helloworld-with-os-user：

$file helloworld-with-os-user
helloworld-with-os-user: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), not stripped

$ldd helloworld-with-os-user
    linux-vdso.so.1 =>  (0x00007ffcb8fd4000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007fb5d6fce000)
    libc.so.6 => /lib64/libc.so.6 (0x00007fb5d6c00000)
    /lib64/ld-linux-x86-64.so.2 (0x00007fb5d71ea000)

我们看到：一行新代码居然让helloworld从静态链接变为了动态链接，同时这也是如何编译出一个hello world版的动态链接Go程序的答案。

通过nm命令我们还可以查看Go程序依赖了哪些C库的符号：

$nm -a helloworld-with-os-user |grep " U "
                 U abort
                 U __errno_location
                 U fprintf
                 U fputc
                 U free
                 U fwrite
                 U malloc
                 U mmap
                 U munmap
                 U nanosleep
                 U pthread_attr_destroy
                 U pthread_attr_getstack
                 U pthread_attr_getstacksize
                 U pthread_attr_init
                 U pthread_cond_broadcast
                 U pthread_cond_wait
                 U pthread_create
                 U pthread_detach
                 U pthread_getattr_np
                 U pthread_key_create
                 U pthread_mutex_lock
                 U pthread_mutex_unlock
                 U pthread_self
                 U pthread_setspecific
                 U pthread_sigmask
                 U setenv
                 U sigaction
                 U sigaddset
                 U sigemptyset
                 U sigfillset
                 U sigismember
                 U stderr
                 U strerror
                 U unsetenv
                 U vfprintf

由此，我们可以得到一个结论，在默认情况下(CGO_ENABLED=1)，Go会尽力使用静态链接的方式，但在某些情况下，会采用动态链接。那么究竟在哪些情况下会默认生成动态链接的程序呢？我们继续往下看。

2. 在何种情况下默认会生成动态链接的Go程序？

在以下几种情况下，Go编译器会默认(CGO_ENABLED=1)生成动态链接的可执行文件，我们逐一来看一下。

2.1 一些使用C实现的标准库包

根据上述示例，我们可以看到，在某些情况下，即使只依赖标准库，Go 仍会在CGO_ENABLED=1的情况下采用动态链接。这是因为代码依赖的标准库包使用了C版本的实现。虽然这种情况并不常见，但os/user包和net包是两个典型的例子。

os/user包的示例在前面我们已经见识过了。user包允许开发者通过名称或ID查找用户账户。对于大多数Unix系统(包括linux)，该包内部有两种版本的实现，用于解析用户和组ID到名称，并列出附加组ID。一种是用纯Go编写，解析/etc/passwd和/etc/group文件。另一种是基于cgo的，依赖于标准C库（libc）中的例程，如getpwuid_r、getgrnam_r和getgrouplist。当cgo可用(CGO_ENABLED=1)，并且特定平台的libc实现了所需的例程时，将使用基于cgo的（libc支持的）代码，即采用动态链接方式。

同样，net包在名称解析(Name Resolution，即域名或主机名对应IP查找)上针对大多数Unix系统也有两个版本的实现：一个是纯Go版本，另一个是基于C的版本。C版本会在cgo可用且特定平台实现了相关C函数(比如getaddrinfo和getnameinfo等)时使用。

下面是一个简单的使用net包并采用动态链接的示例：

// go-compilation/main-with-net.go

package main

import (
    "fmt"
    _ "net"
)

func main() {
    fmt.Println("hello, world")
}

编译后，我们查看一下文件属性：

$go build -o helloworld-with-net main-with-net.go 

$file helloworld-with-net
helloworld-with-net: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), not stripped

$ldd helloworld-with-net
    linux-vdso.so.1 =>  (0x00007ffd75dfd000)
    libresolv.so.2 => /lib64/libresolv.so.2 (0x00007fdda2cf9000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007fdda2add000)
    libc.so.6 => /lib64/libc.so.6 (0x00007fdda270f000)
    /lib64/ld-linux-x86-64.so.2 (0x00007fdda2f13000)

我们看到C版本实现依赖了libresolv.so这个用于名称解析的C库。

由此可得，当Go在默认cgo开启时，一旦依赖了标准库中拥有C版本实现的包，比如os/user、net等，Go编译器会采用动态链接的方式编译Go可执行程序。

2.2 显式使用cgo调用外部C程序

如果使用cgo与外部C代码交互，那么生成的可执行文件必然会包含动态链接。下面我们来看一个调用cgo的简单示例。

首先，建立一个简单的C lib：

// go-compilation/my-c-lib

$tree my-c-lib
my-c-lib
├── Makefile
├── mylib.c
└── mylib.h

// go-compilation/my-c-lib/Makefile

.PHONY:  all static

all:
        gcc -c -fPIC -o mylib.o mylib.c
        gcc -shared -o libmylib.so mylib.o
static:
        gcc -c -fPIC -o mylib.o mylib.c
        ar rcs libmylib.a mylib.o

// go-compilation/my-c-lib/mylib.h

#ifndef MYLIB_H
#define MYLIB_H

void hello();
int add(int a, int b);

#endif // MYLIB_H

// go-compilation/my-c-lib/mylib.c

#include 

void hello() {
    printf("Hello from C!\n");
}

int add(int a, int b) {
    return a + b;
}

执行make all构建出动态链接库libmylib.so！接下来，我们编写一个Go程序通过cgo调用libmylib.so中：

// go-compilation/main-with-call-myclib.go 

package main

/*
#cgo CFLAGS: -I ./my-c-lib
#cgo LDFLAGS: -L ./my-c-lib -lmylib
#include "mylib.h"
*/
import "C"
import "fmt"

func main() {
    // 调用 C 函数
    C.hello()

    // 调用 C 中的加法函数
    result := C.add(3, 4)
    fmt.Printf("Result of addition: %d\n", result)
}

编译该源码：

$go build -o helloworld-with-call-myclib main-with-call-myclib.go

通过ldd可以看到，可执行文件helloworld-with-call-myclib是动态链接的，并依赖libmylib.so：

$ldd helloworld-with-call-myclib
    linux-vdso.so.1 =>  (0x00007ffcc39d8000)
    libmylib.so => not found
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f7166df5000)
    libc.so.6 => /lib64/libc.so.6 (0x00007f7166a27000)
    /lib64/ld-linux-x86-64.so.2 (0x00007f7167011000)

设置LD_LIBRARY_PATH(为了让程序找到libmylib.so)并运行可执行文件helloworld-with-call-myclib：

$ LD_LIBRARY_PATH=./my-c-lib:$LD_LIBRARY_PATH ./helloworld-with-call-myclib
Hello from C!
Result of addition: 7

2.3 使用了依赖cgo的第三方包

在日常开发中，我们经常依赖一些第三方包，有些时候这些第三方包依赖cgo，比如mattn/go-sqlite3。下面就是一个依赖go-sqlite3包的示例：

// go-compilation/go-sqlite3/main.go
package main

import (
    "database/sql"
    "fmt"
    "log"

    _ "github.com/mattn/go-sqlite3"
)

func main() {
    // 打开数据库（如果不存在，则创建）
    db, err := sql.Open("sqlite3", "./test.db")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 创建表
    sqlStmt := `CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);`
    _, err = db.Exec(sqlStmt)
    if err != nil {
        log.Fatalf("%q: %s\n", err, sqlStmt)
    }

    // 插入数据
    _, err = db.Exec(`INSERT INTO user (name) VALUES (?)`, "Alice")
    if err != nil {
        log.Fatal(err)
    }

    // 查询数据
    rows, err := db.Query(`SELECT id, name FROM user;`)
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var id int
        var name string
        err = rows.Scan(&id, &name)
        if err != nil {
            log.Fatal(err)
        }
        fmt.Printf("%d: %s\n", id, name)
    }

    // 检查查询中的错误
    if err = rows.Err(); err != nil {
        log.Fatal(err)
    }
}

编译和运行该源码：

$go build demo
$ldd demo
    linux-vdso.so.1 =>  (0x00007ffe23d8e000)
    libdl.so.2 => /lib64/libdl.so.2 (0x00007faf0ddef000)
    libpthread.so.0 => /lib64/libpthread.so.0 (0x00007faf0dbd3000)
    libc.so.6 => /lib64/libc.so.6 (0x00007faf0d805000)
    /lib64/ld-linux-x86-64.so.2 (0x00007faf0dff3000)
$./demo
1: Alice

到这里，有些读者可能会问一个问题：如果需要在上述依赖场景中生成静态链接的Go程序，该怎么做呢？接下来，我们就来看看这个问题的解决细节。

3. 如何在上述情况下实现静态链接？

到这里是不是有些烧脑了啊！我们针对上一节的三种情况，分别对应来看一下静态编译的方案。

3.1 仅依赖标准包

在前面我们说过，之所以在使用os/user、net包时会在默认情况下采用动态链接，是因为Go使用了这两个包对应功能的C版实现，如果要做静态编译，让Go编译器选择它们的纯Go版实现即可。那我们仅需要关闭CGO即可，以依赖标准库os/user为例：

$CGO_ENABLED=0 go build -o helloworld-with-os-user-static main-with-os-user.go
$file helloworld-with-os-user-static
helloworld-with-os-user-static: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped
$ldd helloworld-with-os-user-static
    不是动态可执行文件

3.2 使用cgo调用外部c程序（静态链接）

对于依赖cgo调用外部c的程序，我们要使用静态链接就必须要求外部c库提供静态库，因此，我们需要my-c-lib提供一份libmylib.a，这通过下面命令可以实现(或执行make static)：

$gcc -c -fPIC -o mylib.o mylib.c
$ar rcs libmylib.a mylib.o

有了libmylib.a后，我们还要让Go程序静态链接该.a文件，于是我们需要修改一下Go源码中cgo链接的flag，加上静态链接的选项：

// go-compilation/main-with-call-myclib-static.go
... ...
#cgo LDFLAGS: -static -L my-c-lib -lmylib
... ...

编译链接并查看一下文件属性：

$go build -o helloworld-with-call-myclib-static main-with-call-myclib-static.go

$file helloworld-with-call-myclib-static
helloworld-with-call-myclib-static: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 2.6.32, BuildID[sha1]=b3da3ed817d0d04230460069b048cab5f5bfc3b9, not stripped

我们得到了预期的结果！

3.3 依赖使用cgo的外部go包（静态链接）

最麻烦的是这类情况，要想实现静态链接，我们需要找出外部go依赖的所有c库的.a文件(静态共享库)。以我们的go-sqlite3示例为例，go-sqlite3是sqlite库的go binding，它依赖sqlite库，同时所有第三方c库都依赖libc，我们还要准备一份libc的.a文件，下面我们就先安装这些：

$yum install -y gcc glibc-static sqlite-devel
... ...

已安装:
  sqlite-devel.x86_64 0:3.7.17-8.el7_7.1                                                                                          

更新完毕:
  glibc-static.x86_64 0:2.17-326.el7_9.3

接下来，我们就来以静态链接的方式在go-compilation/go-sqlite3-static下编译一下：

$go build -tags 'sqlite_omit_load_extension' -ldflags '-linkmode external -extldflags "-static"' demo

$file ./demo
./demo: ELF 64-bit LSB executable, x86-64, version 1 (GNU/Linux), statically linked, for GNU/Linux 2.6.32, BuildID[sha1]=c779f5c3eaa945d916de059b56d94c23974ce61c, not stripped

这里命令行中的-tags ‘sqlite_omit_load_extension’用于禁用SQLite3的动态加载功能，确保更好的静态链接兼容性。而-ldflags ‘-linkmode external -extldflags “-static”‘的含义是使用外部链接器(比如gcc linker)，并强制静态链接所有库。

我们再看完略烧脑的几个细节后，再来看一个略轻松的话题。

4. Go编译出的可执行文件过大，能优化吗？

Go编译出的二进制文件一般较大，一个简单的“Hello World”程序通常在2MB左右：

$ls -lh helloworld-default
-rwxr-xr-x 1 root root 2.1M 11月  3 10:39 helloworld-default

这一方面是因为Go将整个runtime都编译到可执行文件中了，另一方面也是因为Go静态编译所致。那么在默认情况下，Go二进制文件的大小还有优化空间么？方法不多，有两种可以尝试：

去除符号表和调试信息

在编译时使用-ldflags=”-s -w”标志可以去除符号表和调试符号，其中-s用于去掉符号表和调试信息，-w用于去掉DWARF调试信息，这样能显著减小文件体积。以helloworld为例，可执行文件的size减少了近四成：

$go build -ldflags="-s -w" -o helloworld-default-nosym main.go
$ls -l
-rwxr-xr-x 1 root root 2124504 11月  3 10:39 helloworld-default
-rwxr-xr-x 1 root root 1384600 11月  3 13:34 helloworld-default-nosym

使用tinygo

TinyGo是一个Go语言的编译器，它专为资源受限的环境而设计，例如微控制器、WebAssembly和其他嵌入式设备。TinyGo的目标是提供一个轻量级的、能在小型设备上运行的Go运行时，同时尽可能支持Go语言的特性。tinygo的一大优点就是生成的二进制文件通常比标准Go编译器生成的文件小得多：

$tinygo build -o helloworld-tinygo main.go
$ls -l
总用量 2728
-rwxr-xr-x  1 root root 2128909 11月  5 05:43 helloworld-default*
-rwxr-xr-x  1 root root  647600 11月  5 05:45 helloworld-tinygo*

我们看到：tinygo生成的可执行文件的size仅是原来的30%。

注：虽然TinyGo在特定场景（如IoT和嵌入式开发）中非常有用，但在常规服务器环境中，由于生态系统兼容性、性能、调试支持等方面的限制，可能并不是最佳选择。对于需要高并发、复杂功能和良好调试支持的应用，标准Go仍然是更合适的选择。

注：这里使用的tinygo为0.34.0版本。

5. 未使用的符号是否会被编译到Go二进制文件中？

到这里，相信读者心中也都会萦绕一些问题：到底哪些符号被编译到最终的Go二进制文件中了呢？未使用的符号是否会被编译到Go二进制文件中吗？在这一小节中，我们就来探索一下。

出于对Go的了解，我们已经知道无论是GOPATH时代，还是Go module时代，Go的编译单元始终是包(package)，一个包（无论包中包含多少个Go源文件）都会作为一个编译单元被编译为一个目标文件(.a)，然后Go链接器会将多个目标文件链接在一起生成可执行文件，因此如果一个包被依赖，那么它就会进入到Go二进制文件中，它内部的符号也会进入到Go二进制文件中。

那么问题来了！是否被依赖包中的所有符号都会被放到最终的可执行文件中呢？我们以最简单的helloworld-default为例，它依赖fmt包，并调用了fmt包的Println函数，我们看看Println这个符号是否会出现在最终的可执行文件中：

$nm -a helloworld-default | grep "Println"
000000000048eba0 T fmt.(*pp).doPrintln

居然没有！我们初步怀疑是inline优化在作祟。接下来，关闭优化再来试试：

$go build -o helloworld-default-noinline -gcflags='-l -N' main.go

$nm -a helloworld-default-noinline | grep "Println"
000000000048ec00 T fmt.(*pp).doPrintln
0000000000489ee0 T fmt.Println

看来的确如此！不过当使用”fmt.”去过滤helloworld-default-noinline的所有符号时，我们发现fmt包的一些常见的符号并未包含在其中，比如Printf、Fprintf、Scanf等。

这是因为Go编译器的一个重要特性：死码消除(dead code elimination)，即编译器会将未使用的代码和数据从最终的二进制文件中剔除。

我们再来继续探讨一个衍生问题：如果Go源码使用空导入方式导入了一个包，那么这个包是否会被编译到Go二进制文件中呢？其实道理是一样的，如果用到了里面的符号，就会存在，否则不会。

以空导入os/user为例，即便在CGO_ENABLED=0的情况下，因为没有使用os/user中的任何符号，在最终的二进制文件中也不会包含user包：

$CGO_ENABLED=0 go build -o helloworld-with-os-user-noinline -gcflags='-l -N' main-with-os-user.go
[root@iZ2ze18rmx2avqb5xgb4omZ helloworld]# nm -a helloworld-with-os-user-noinline |grep user
0000000000551ac0 B runtime.userArenaState

但是如果是带有init函数的包，且init函数中调用了同包其他符号的情况呢？我们以expvar包为例看一下：

// go-compilation/main-with-expvar.go

package main

import (
    _ "expvar"
    "fmt"
)

func main() {
    fmt.Println("hello, world")
}

编译并查看一下其中的符号：

$go build -o helloworld-with-expvar-noinline -gcflags='-l -N' main-with-expvar.go
$nm -a helloworld-with-expvar-noinline|grep expvar
0000000000556480 T expvar.appendJSONQuote
00000000005562e0 T expvar.cmdline
00000000005561c0 T expvar.expvarHandler
00000000005568e0 T expvar.(*Func).String
0000000000555ee0 T expvar.Func.String
00000000005563a0 T expvar.init.0
00000000006e0560 D expvar..inittask
0000000000704550 d expvar..interfaceSwitch.0
... ...

除此之外，如果一个包即便没有init函数，但有需要初始化的全局变量，比如crypto包的hashes：

// $GOROOT/src/crypto/crypto.go
var hashes = make([]func() hash.Hash, maxHash)

crypto包的相关如何也会进入最终的可执行文件中，大家自己动手不妨试试。下面是我得到的一些输出：

$go build -o helloworld-with-crypto-noinline -gcflags='-l -N' main-with-crypto.go
$nm -a helloworld-with-crypto-noinline|grep crypto
00000000005517b0 B crypto.hashes
000000000048ee60 T crypto.init
0000000000547280 D crypto..inittask

有人会问：os/user包也有一些全局变量啊，为什么这些符号没有被包含在可执行文件中呢？比如：

// $GOROOT/src/os/user/user.go
var (
    userImplemented      = true
    groupImplemented     = true
    groupListImplemented = true
)

这就要涉及Go包初始化的逻辑了。我们看到crypto包包含在可执行文件中的符号中有crypto.init和crypto..inittask这两个符号，显然这不是crypto包代码中的符号，而是Go编译器为crypto包自动生成的init函数和inittask结构。

Go编译器会为每个包生成一个init函数，即使包中没有显式定义init函数，同时每个包都会有一个inittask结构，用于运行时的包初始化系统。当然这么说也不足够精确，如果一个包没有init函数、需要初始化的全局变量或其他需要运行时初始化的内容，则编译器不会为其生成init函数和inittask。比如上面的os/user包。

os/user包确实有上述全局变量的定义，但是这些变量是在编译期就可以确定值的常量布尔值，而且未被包外引用或在包内用于影响控制流。Go编译器足够智能，能够判断出这些初始化是”无副作用的”，不需要在运行时进行初始化。只有真正需要运行时初始化的包才会生成init和inittask。这也解释了为什么空导入os/user包时没有相关的init和inittask符号，而crypto、expvar包有的init.0和inittask符号。

6. 如何快速判断Go项目是否依赖cgo？

在使用开源Go项目时，我们经常会遇到项目文档中没有明确说明是否依赖Cgo的情况。这种情况下，如果我们需要在特定环境（比如CGO_ENABLED=0）下使用该项目，就需要事先判断项目是否依赖Cgo，有些时候还要快速地给出判断。

那究竟是否可以做到这种快速判断呢？我们先来看看一些常见的作法。

第一类作法是源码层面的静态分析。最直接的方式是检查源码中是否存在import “C”语句，这种引入方式是CGO使用的显著标志。

// 在项目根目录中执行
$grep -rn 'import "C"' .

这个命令会递归搜索当前目录下所有文件，显示包含import “C”的行号和文件路径，帮助快速定位CGO的使用位置。

此外，CGO项目通常包含特殊的编译指令，这些指令以注释形式出现在源码中，比如前面见识过的#cgo CFLAGS、#cgo LDFLAGS等，通过对这些编译指令的检测，同样可以来判断项目是否依赖CGO。

不过第一类作法并不能查找出Go项目的依赖包是否依赖cgo。而找出直接依赖或间接依赖是否依赖cgo，我们需要工具帮忙，比如使用Go工具链提供的命令分析项目依赖：

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}' ./...  | grep -v '\[\]'

其中ImportPath是依赖包的导入路径，而CgoFiles则是依赖中包含import “C”的Go源文件。我们以go-sqlite3那个依赖cgo的示例来验证一下：

// cd go-compilation/go-sqlite3

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}' ./...  | grep -v '\[\]'
runtime/cgo: [cgo.go]
github.com/mattn/go-sqlite3: [backup.go callback.go error.go sqlite3.go sqlite3_context.go sqlite3_load_extension.go sqlite3_opt_serialize.go sqlite3_opt_userauth_omit.go sqlite3_other.go sqlite3_type.go]

用空导入os/user的示例再来看一下：

$go list -deps -f '{{.ImportPath}}: {{.CgoFiles}}'  main-with-os-user.go | grep -v '\[\]'
runtime/cgo: [cgo.go]
os/user: [cgo_lookup_cgo.go getgrouplist_unix.go]

我们知道os/user有纯go和C版本两个实现，因此上述判断只能说“对了一半”，当我关闭CGO_ENABLED时，Go编译器不会使用基于cgo的C版实现。

那是否在禁用cgo的前提下对源码进行一次编译便能验证项目是否对cgo有依赖呢？这样做显然谈不上是一种“快速”的方法，那是否有效呢？我们来对上面的go-sqlite3项目做一个测试，我们在关闭CGO_ENABLED时，编译一下该示例：

// cd go-compilation/go-sqlite3
$ CGO_ENABLED=0 go build demo

我们看到，Go编译器并未报错！似乎该项目不需要cgo! 但真的是这样吗？我们运行一下编译后的demo可执行文件：

$ ./demo
2024/11/03 22:10:36 "Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub": CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);

我们看到成功编译出来的程序居然出现运行时错误，提示需要cgo！

到这里，没有一种方法可以快速、精确的给出项目是否依赖cgo的判断。也许判断Go项目是否依赖CGO并没有捷径，需要从源码分析、依赖检查和构建测试等多个维度进行。

7. 小结

在本文中，我们深入探讨了Go语言编译过程中的几个重要细节，尤其是在静态链接和动态链接的选择上。通过具体示例，我们了解到：

默认链接方式：尽管CGO_ENABLED默认值为1，Go编译器在大多数情况下会采用静态链接，只有在依赖特定的C库或标准库包时，才会切换到动态链接。
动态链接的条件：我们讨论了几种情况下Go会默认生成动态链接的可执行文件，包括依赖使用C实现的标准库包、显式使用cgo调用外部C程序，以及使用依赖cgo的第三方包。
实现静态链接：对于需要动态链接的场景，我们也提供了将其转为静态链接的解决方案，包括关闭CGO、使用静态库，以及处理依赖cgo的外部包的静态链接问题。
二进制文件优化：我们还介绍了如何通过去除符号表和使用TinyGo等方法来优化生成的Go二进制文件的大小，以满足不同场景下的需求。
符号编译与死码消除：最后，我们探讨了未使用的符号是否会被编译到最终的二进制文件中，并解释了Go编译器的死码消除机制。

通过这些细节探讨，我希望能够帮助大家更好地理解Go编译的复杂性，并在实际开发中做出更明智的选择，亦能在面对Go编译相关问题时，提供有效的解决方案。

本文涉及的源码可以在这里下载。

Gopher部落知识星球在2024年将继续致力于打造一个高品质的Go语言学习和交流平台。我们将继续提供优质的Go技术文章首发和阅读体验。同时，我们也会加强代码质量和最佳实践的分享，包括如何编写简洁、可读、可测试的Go代码。此外，我们还会加强星友之间的交流和互动。欢迎大家踊跃提问，分享心得，讨论技术。我会在第一时间进行解答和交流。我衷心希望Gopher部落可以成为大家学习、进步、交流的港湾。让我相聚在Gopher部落，享受coding的快乐! 欢迎大家踊跃加入！

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

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite
Gopher Daily归档 – https://github.com/bigwhite/gopherdaily
Gopher Daily Feed订阅 – https://gopherdaily.tonybai.com/feed

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

通过实例理解API网关的主要功能特性

bigwhite — Sun, 03 Dec 2023 09:35:56 +0000

本文永久链接 – https://tonybai.com/2023/12/03/understand-api-gateway-main-functional-features-by-example

在当今的技术领域中，“下云”的概念正逐渐抬头，像David Heinemeier Hansson(37signals公司的联合创始人, Ruby on Rails的Creator)就直接将公司所有的业务都从公有云搬迁到了自建的数据中心中。虽说大多数企业不会这么“极端”，但随着企业对云原生架构采用的广泛与深入，不可避免地面临着对云服务的依赖。云服务在过去的几年中被广泛应用于构建灵活、可扩展的应用程序和基础设施，为企业提供了许多便利和创新机会。然而，随着业务规模的增长和数据量的增加，云服务的成本也随之上升。企业开始意识到，对云服务的依赖已经成为一个值得重新评估的议题。云服务的开销可能占据了企业可用的预算的相当大部分。为了保持竞争力并更好地控制成本，企业需要寻找方法来减少对云服务的依赖，寻找更经济的解决方案，同时确保仍能获得所需的性能、安全性和可扩展性。

在这样的背景下，我们的关注点是选择一款适宜的API网关，从主流功能特性的角度来评估候选者的支持。API网关作为现代云原生应用架构中的关键组件，扮演着连接前端应用和后端服务的中间层，负责管理、控制和保护API的访问。它的功能特性对于确保API的安全性、可靠性和可扩展性至关重要。

尽管API网关并不是一个新鲜事物了，但对于那些长期依赖于云供应商的服务的人来说，它似乎变得有些“陌生”。因此，本文旨在帮助我们重新理解API网关的主要特性，并获得对API网关选型的能力，以便在停止使用云供应商服务之前，找到一个合适的替代品^_^。

1. API网关回顾

API网关是现代应用架构中的关键组件之一，它的存在简化了应用程序的架构，并为客户端提供一个单一的访问入口，并进行相关的控制、优化和管理。API网关可以帮助企业实现微服务架构、提高系统的可扩展性和安全性，并提供更好的开发者体验和用户体验。

1.1 API网关的演化

随着互联网的快速发展和企业对API的需求不断增长，API网关作为一种关键的中间层技术逐渐崭露头角并经历了一系列的演进和发展。这里将API网关的演进历史粗略分为以下几个阶段:

API网关之前的早期阶段

在互联网发展的早期阶段，大多数应用程序都是以单体应用的形式存在。后来随着应用规模的扩大和业务复杂性的增加，单体应用的架构变得不够灵活和可扩展，面向服务架构（Service-Oriented Architecture，SOA）逐渐兴起，企业开始将应用程序拆分成一组独立的服务。这个时期，每个服务都是独立对外暴露API，客户端也是通过这些API直接访问服务，但这会导致一些安全性、运维和扩展性的问题。之后，企业也开始意识到需要一种中间层来管理和控制这种客户端到服务的通信行为，并确保服务的可靠性和安全性，于是开始有了API网关的概念。

API网关的兴起

早期的API网关，其主要功能就是单纯的路由和转发。API网关将请求从客户端转发到后端服务，并将后端服务的响应返回给客户端。在这个阶段，API网关的功能非常简单，主要用于解决客户端和后端服务之间的通信问题。

API网关的成熟

随着微服务架构的兴起和API应用的不断发展，企业开始将应用程序进一步拆分成更小的、独立部署的微服务。每个对外暴露的微服务都有自己的API，并通过API网关进行统一管理和访问。API网关在微服务架构中的作用变得更加重要，它的功能也逐渐丰富起来了。

在这一阶段，它不仅负责路由和转发请求，API网关还增加了安全和治理的功能，可以满足几个不同领域的微服务需求。比如：API网关可以通过身份认证、授权、访问控制等功能来保护API的安全；通过基于重试、超时、熔断的容错机制等来对API的访问进行治理；通过日志记录、基于指标收集以及Tracing等对API的访问进行观测与监控；支持实时的服务发现等。

API网关(图来自网络)

API网关的云原生化

随着云原生技术的发展，如容器化和服务网格（Service Mesh）等，API网关也在不断演进和适应新的环境。在云原生环境中，API网关实现了与容器编排系统（如Kubernetes）和服务网格集成，其自身也可以作为一个云原生服务来部署，以实现更高的可伸缩性、弹性和自动化。同时，新的技术和标准也不断涌现，如GraphQL和gRPC等，API网关也增加了对这些新技术的集成和支持。

1.2 API网关的主要功能特性

从上面的演化历史我们看到：API网关的演进使其从最初简单的请求转发角色，逐渐成为整个API管理和微服务架构中的关键组件。它不仅扮演着API管理层与后端服务层之间的适配器，也是云原生架构中不可或缺的基础设施，使微服务管理更加智能化和自动化。下面是现代API网关承担的主要功能特性，我们后续也会基于这些特性进行示例说明：

请求转发和路由
身份认证和授权
流量控制和限速
高可用与容错处理
监控和可观测性

2. 那些主流的API网关

下面是来自CNCF Landscape中的主流API网关集合(截至2023.11月)，图中展示了关于各个网关的一些细节，包括star数量和背后开发的公司或组织：

主流的API网关还有各大公有云提供商的实现，比如：Amazon的API Gateway、Google Cloud的API Gateway以及上图中的Azure API Management等，但它们不在我们选择范围之内；虽然被CNCF收录，但多数API网关受到的关注并不高，超过1k star的不到30%，这些不是很受关注或dev不是那么active的项目也无法在生产环境担当关键角色；而像APISIX、Kong这两个受关注很高的网关，它们是建构在Nginx之上实现的，技术栈与我们不契合；而像EMISSARY INGRESS、Gloo等则是完全云原生化或者说是Kubernetes Native的，无法在无Kubernetes的基于VM或裸金属的环境下部署和运行。

好吧，剩下的只有几个Go实现的API Gateway了，在它们之中，我们选择用Tyk API网关来作为后续API功能演示的示例。

注：这并不代表Tyk API网关就要比其他Go实现的API Gateway优秀，只是它的资料比较齐全，适合在本文中作演示罢了。

3. API网关主要功能特性示例(Tyk API网关版本)

3.1 Tyk API网关简介

记得在至少5年前就知道Tyk API网关的存在，印象中它是使用Go语言开发的早期的那批API网关之一。Tyk从最初的纯开源项目，到如今由背后商业公司支持，以Open Core模式开源的网关，一直保持了active dev的状态。经过多年的演进，它已经一款功能强大的开源兼商业API管理和网关解决方案，提供了全面的功能和工具，帮助开发者有效地管理、保护和监控API。同时，Tyk API网关支持多种安装部署方式，即可以单一程序的方式放在物理机或VM上运行，也可以支持容器部署，通过docker-compose拉起，亦可以通过Kubernetes Operator将其部署在Kubernetes中，这也让Tyk API网关具备了在各大公有云上平滑迁移的能力。

关于Tyk API网关开源版本的功能详情，可以点击左边超链接到其官网查阅，这里不赘述。

3.2 安装Tyk API网关

下面我们就来安装一下Tyk API网关，我们直接在VM上安装，VM上的环境是CentOS 7.9。Tyk API提供了很多中安装方法，这里使用CentOS的yum包管理工具安装Tyk API网关，大体步骤如下(演示均以root权限操作)。

3.2.1 创建tyk gateway软件源

默认的yum repo中是不包含tyk gateway的，我们需要在/etc/yum.repos.d下面创建一个新的源，即新建一个tyk_tyk-gateway.repo文件，其内容如下：

[tyk_tyk-gateway]
name=tyk_tyk-gateway
baseurl=https://packagecloud.io/tyk/tyk-gateway/el/7/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/tyk/tyk-gateway/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

[tyk_tyk-gateway-source]
name=tyk_tyk-gateway-source
baseurl=https://packagecloud.io/tyk/tyk-gateway/el/7/SRPMS
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/tyk/tyk-gateway/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

接下来我们执行下面命令来创建tyk_tyk-gateway这个repo的YUM缓存：

$yum -q makecache -y --disablerepo='*' --enablerepo='tyk_tyk-gateway'
导入 GPG key 0x5FB83118:
 用户ID     : "https://packagecloud.io/tyk/tyk-gateway (https://packagecloud.io/docs#gpg_signing) "
 指纹       : 9179 6215 a875 8c40 ab57 5f03 87be 71bd 5fb8 3118
 来自       : https://packagecloud.io/tyk/tyk-gateway/gpgkey

repo配置和缓存完毕后，我们就可以安装Tyk API Gateway了：

$yum install -y tyk-gateway

安装后的tky-gateway将以一个systemd daemon服务的形式存在于主机上，程序意外退出或虚机重启后，该服务也会被systemd自动拉起。通过systemctl status命令可以查看服务的运行状态：

# systemctl status tyk-gateway
● tyk-gateway.service - Tyk API Gateway
   Loaded: loaded (/usr/lib/systemd/system/tyk-gateway.service; enabled; vendor preset: disabled)
   Active: active (running) since 日 2023-11-19 20:22:44 CST; 12min ago
 Main PID: 29306 (tyk)
    Tasks: 13
   Memory: 19.6M
   CGroup: /system.slice/tyk-gateway.service
           └─29306 /opt/tyk-gateway/tyk --conf /opt/tyk-gateway/tyk.conf

11月 19 20:34:54 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:34:54" level=error msg="Connection to Redis faile...b-sub
11月 19 20:35:04 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:35:04" level=error msg="cannot set key in pollerC...ured"
11月 19 20:35:04 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:35:04" level=error msg="Redis health check failed...=main
Hint: Some lines were ellipsized, use -l to show in full.

3.2.2 安装redis

我们看到tyk-gateway已经成功启动，但从其服务日志来看，它在连接redis时报错了！tyk gateway默认将数据存储在redis中，为了让tyk gateway正常运行，我们还需要安装redis！这里我们使用容器的方式安装和运行一个redis服务：

$docker pull redis:6.2.14-alpine3.18
$docker run -d --name my-redis -p 6379:6379 redis:6.2.14-alpine3.18
e5d1ec8d5f5c09023d1a4dd7d31d293b2d7147f1d9a01cff8eff077c93a9dab7

拉取并运行redis后，我们通过redis-cli验证一下与redis server的连接：

# docker run -it --rm redis:6.2.14-alpine3.18  redis-cli -h 192.168.0.24
192.168.0.24:6379>

我们看到可以正常连接！但此时Tyk Gateway仍然无法与redis正常连接，我们还需要对Tyk Gateway做一些配置调整！

3.2.3 配置Tyk Gateway

yum默认将Tyk Gateway安装到/opt/tyk-gateway下面，这个路径下的文件布局如下：

$tree -F -L 2 .
.
├── apps/
│   └── app_sample.json
├── coprocess/
│   ├── api.h
│   ├── bindings/
│   ├── coprocess_common.pb.go
│   ├── coprocess_mini_request_object.pb.go
│   ├── coprocess_object_grpc.pb.go
│   ├── coprocess_object.pb.go
│   ├── coprocess_response_object.pb.go
│   ├── coprocess_return_overrides.pb.go
│   ├── coprocess_session_state.pb.go
│   ├── coprocess_test.go
│   ├── dispatcher.go
│   ├── grpc/
│   ├── lua/
│   ├── proto/
│   ├── python/
│   └── README.md
├── event_handlers/
│   └── sample/
├── install/
│   ├── before_install.sh*
│   ├── data/
│   ├── init_local.sh
│   ├── inits/
│   ├── post_install.sh*
│   ├── post_remove.sh*
│   ├── post_trans.sh
│   └── setup.sh*
├── middleware/
│   ├── ottoAuthExample.js
│   ├── sampleMiddleware.js
│   ├── samplePostProcessMiddleware.js
│   ├── samplePreProcessMiddleware.js
│   ├── testPostVirtual.js
│   ├── testVirtual.js
│   └── waf.js
├── policies/
│   └── policies.json
├── templates/
│   ├── breaker_webhook.json
│   ├── default_webhook.json
│   ├── error.json
│   ├── monitor_template.json
│   └── playground/
├── tyk*
└── tyk.conf

其中tyk.conf就是tyk gateway的配置文件，我们先看看其默认的内容：

$cat /opt/tyk-gateway/tyk.conf
{
  "listen_address": "",
  "listen_port": 8080,
  "secret": "xxxxxx",
  "template_path": "/opt/tyk-gateway/templates",
  "use_db_app_configs": false,
  "app_path": "/opt/tyk-gateway/apps",
  "middleware_path": "/opt/tyk-gateway/middleware",
  "storage": {
    "type": "redis",
    "host": "redis",
    "port": 6379,
    "username": "",
    "password": "",
    "database": 0,
    "optimisation_max_idle": 2000,
    "optimisation_max_active": 4000
  },
  "enable_analytics": false,
  "analytics_config": {
    "type": "",
    "ignored_ips": []
  },
  "dns_cache": {
    "enabled": false,
    "ttl": 3600,
    "check_interval": 60
  },
  "allow_master_keys": false,
  "policies": {
    "policy_source": "file"
  },
  "hash_keys": true,
  "hash_key_function": "murmur64",
  "suppress_redis_signal_reload": false,
  "force_global_session_lifetime": false,
  "max_idle_connections_per_host": 500
}

我们看到：storage下面存储了redis的配置信息，我们需要将redis的host配置修改为我们的VM地址：

    "host": "192.168.0.24",

然后重启Tyk Gateway服务：

$systemctl daemon-reload
$systemctl restart tyk-gateway

之后，我们再查看tyk gateway的运行状态：

systemctl status tyk-gateway
● tyk-gateway.service - Tyk API Gateway
   Loaded: loaded (/usr/lib/systemd/system/tyk-gateway.service; enabled; vendor preset: disabled)
   Active: active (running) since 一 2023-11-20 06:54:07 CST; 41s ago
 Main PID: 20827 (tyk)
    Tasks: 15
   Memory: 24.8M
   CGroup: /system.slice/tyk-gateway.service
           └─20827 /opt/tyk-gateway/tyk --conf /opt/tyk-gateway/tyk.conf

11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Loading API configurations...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Tracking hostname" api_nam...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Initialising Tyk REST API ...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API bind on custom port:0"...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Checking security policy: ...fault
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API Loaded" api_id=1 api_n...ip=--
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Loading uptime tests..." p...k-mgr
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Initialised API Definition...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=warning msg="All APIs are protected ...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API reload complete" prefix=main
Hint: Some lines were ellipsized, use -l to show in full.

从服务日志来看，现在Tyk Gateway可以正常连接redis并提供服务了！我们也可以通过下面的命令验证网关的运行状态：

$curl localhost:8080/hello
{"status":"pass","version":"5.2.1","description":"Tyk GW","details":{"redis":{"status":"pass","componentType":"datastore","time":"2023-11-20T06:58:57+08:00"}}}

“/hello”是Tyk Gateway的内置路由，由Tyk网关自己提供服务。

到这里Tyk Gateway的安装和简单配置就结束了，接下来，我们就来看看API Gateway的主要功能特性，并借助Tyk Gateway来展示一下这些功能特性。

注：查看Tyk Gateway的运行日志，可以使用journalctl -u tyk-gateway -f命令实时follow最新日志输出。

3.3 功能特性：请求转发与路由

请求转发和路由是API Gateway的主要功能特性之一，API Gateway可以根据请求的路径、方法、查询参数等信息将请求转发到相应的后端服务，其内核与反向代理类似，不同之处在于API Gateway增加了“API”这层抽象，更加专注于构建、管理和增强API。

下面我们来看看Tyk如何配置API路由，我们首先创建一个新API。

3.3.1 创建一个新API

Tyk开源版支持两种创建API的方式，一种是通过调用Tyk的控制类API，一种则是通过传统的配置文件，放入特定目录下。无论哪种方式添加完API，最终都要通过Tyk Gateway热加载(hot reload)或重启才能生效。

注：Tyk Gateway的商业版本提供Dashboard，可以以图形化的方式管理API，并且商业版本的API定义会放在Postgres或MongoDB中，我们这里用开源版本，只能手工管理了，并且API定义只能放在文件中。

下面，我们就来在Tyk上创建一个新的API路由，该路由示例的示意图如下：

在未添加新API之前，我们使用curl访问一下该API路径：

$curl localhost:8080/api/v1/no-authn
Not Found

Tyk Gateway由于找不到API路由，返回Not Found。接下来，我们采用调用tyk gateway API的方式来添加路由：

$curl -v -H "x-tyk-authorization: {tyk gateway secret}" \
  -s \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "name": "no-authn-v1",
    "slug": "no-authn-v1",
    "api_id": "no-authn-v1",
    "org_id": "1",
    "use_keyless": true,
    "auth": {
      "auth_header_name": "Authorization"
    },
    "definition": {
      "location": "header",
      "key": "x-api-version"
    },
    "version_data": {
      "not_versioned": true,
      "versions": {
        "Default": {
          "name": "Default",
          "use_extended_paths": true
        }
      }
    },
    "proxy": {
      "listen_path": "/api/v1/no-authn",
      "target_url": "http://localhost:18081/",
      "strip_listen_path": true
    },
    "active": true
}' http://localhost:8080/tyk/apis | python -mjson.tool 

* About to connect() to localhost port 8080 (#0)
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> POST /tyk/apis HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8080
> Accept: */*
> x-tyk-authorization: {tyk gateway secret}
> Content-Type: application/json
> Content-Length: 797
>
} [data not shown]
* upload completely sent off: 797 out of 797 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 22 Nov 2023 05:38:40 GMT
< Content-Length: 53
<
{ [data not shown]
* Connection #0 to host localhost left intact
{
    "action": "added",
    "key": "no-authn-v1",
    "status": "ok"
}

从curl返回结果我们看到：API已经被成功添加。这时tyk gateway的安装目录/opt/tyk-gateway的子目录apps下会新增一个名为no-authn-v1.json的配置文件，这个文件内容较多，有300行，这里就不贴出来了，这个文件就是新增的no-authn API的定义文件。

不过此刻，Tyk Gateway还需热加载后才能为新的API提供服务，调用下面API可以触发Tyk Gateway的热加载：

$curl -H "x-tyk-authorization: {tyk gateway secret}" -s http://localhost:8080/tyk/reload/group | python -mjson.tool
{
    "message": "",
    "status": "ok"
}

注：即便触发热加载成功，但如果body中的json格式错，比如多了一个结尾逗号，Tyk Gateway是不会报错的！

API路由创建完毕并生效后，我们再来访问一下API：

$ curl localhost:8080/api/v1/no-authn
{
    "error": "There was a problem proxying the request"
}

我们看到：Tyk Gateway返回的已经不是“Not Found”了！现在我们创建一下no-authn这个API服务，考虑到适配更多后续示例，这里建立这样一个http server：

// api-gateway-examples/httpserver

func main() {
    // 解析命令行参数
    port := flag.Int("p", 8080, "Port number")
    apiVersion := flag.String("v", "v1", "API version")
    apiName := flag.String("n", "example", "API name")
    flag.Parse()                                         

    // 注册处理程序
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Println(*r)
        fmt.Fprintf(w, "Welcome api: localhost:%d/%s/%s\n", *port, *apiVersion, *apiName)
    })                                                                                     

    // 启动HTTP服务器
    addr := fmt.Sprintf(":%d", *port)
    log.Printf("Server listening on port %d\n", *port)
    log.Fatal(http.ListenAndServe(addr, nil))
}

我们启动一个该http server的实例：

$go run main.go -p 18081 -v v1 -n no-authn
2023/11/22 22:02:42 Server listening on port 18081

现在我们再通过tyk gateway调用一下no-authn这个API：

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

我们看到这次路由通了！no-authn API返回了期望的结果！

3.3.2 负载均衡

如果no-authn API存在多个服务实例，Tyk Gateway也可以将请求流量负载均衡到多个no-authn服务实例上去，下图是Tyk Gateway进行请求流量负载均衡的示意图：

要实现负责均衡，我们需要调整no-authn API的定义，这次我们直接修改/opt/tyk-gateway/apps/no-authn-v1.json，变更的配置主要有三项：

// /opt/tyk-gateway/apps/no-authn-v1.json

  "proxy": {
    "preserve_host_header": false,
    "listen_path": "/api/v1/no-authn",
    "target_url": "",                  // (1) 改为""
    "disable_strip_slash": false,
    "strip_listen_path": true,
    "enable_load_balancing": true,     // (2) 改为true
    "target_list": [                   // (3) 填写no-authn服务实例列表
      "http://localhost:18081/",
      "http://localhost:18082/",
      "http://localhost:18083/"
    ],

修改完配置后，调用Tyk的控制类API使之生效，然后我们启动三个no-authn的API实例：

$go run main.go -p 18081 -v v1 -n no-authn
$go run main.go -p 18082 -v v1 -n no-authn
$go run main.go -p 18083 -v v1 -n no-authn

接下来，我们多次调用curl访问no-authn API：

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18083/v1/no-authn

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18083/v1/no-authn

我们看到：Tyk Gateway在no-authn API的各个实例之间做了等权重的轮询。如果我们停掉实例3，再来访问该API，我们将得到下面结果：

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Bad Request

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Bad Request

注：Tyk Gateway商业版通过Dashboard支持配置带权重的RR负载均衡算法。

我们看到：实例3已经下线，但Tyk Gateway并不会跳过该已经下线的实例，这在生产环境会给客户端带来不一致的响应。

3.3.3 服务实例存活检测(uptime test)

Tyk Gateway在开启负载均衡的时候，也提供了对后端服务实例的存活检测机制，当某个服务实例down了后，负载均衡机制会绕过该实例将请求发到下一个处于存活状态的实例；而当down机实例恢复后，Tyk Gateway也能及时检测到服务实例上线，并将其加入流量负载调度。

支持存活检测(uptime test)的API定义配置如下：

// /opt/tyk-gateway/apps/no-authn-v1.json

"uptime_tests": {
    "disable": false,
    "poller_group":"",
    "check_list": [
      {
        "url": "http://localhost:18081/"
      },
      {
        "url": "http://localhost:18082/"
      },
      {
        "url": "http://localhost:18083/"
      }
    ],
    "config": {
      "enable_uptime_analytics": true,
      "failure_trigger_sample_size": 3,
      "time_wait": 300,
      "checker_pool_size": 50,
      "expire_utime_after": 0,
      "service_discovery": {
        "use_discovery_service": false,
        "query_endpoint": "",
        "use_nested_query": false,
        "parent_data_path": "",
        "data_path": "",
        "port_data_path": "",
        "target_path": "",
        "use_target_list": false,
        "cache_disabled": false,
        "cache_timeout": 0,
        "endpoint_returns_list": false
      },
      "recheck_wait": 0
    }
}

"proxy": {
    ... ...
    "enable_load_balancing": true,
    "target_list": [
      "http://localhost:18081/",
      "http://localhost:18082/",
      "http://localhost:18083/"
    ],
    "check_host_against_uptime_tests": true,
    ... ...
}

我们新增了uptime_tests的配置，uptime_tests的check_list中的url的值要与proxy中target_list中的值完全一样，这样Tyk Gateway才能将二者对应上。另外proxy的check_host_against_uptime_tests要设置为true。

这样配置并生效后，等我们将服务实例3停掉后，后续到no-authn的请求就只会转发到实例1和实例2了。而当恢复实例3运行后，Tyk Gateway又会将流量分担到实例3上。

3.3.4 动态负载均衡

上面负载均衡示例中target_list中的目标实例的IP和端口的手工配置的，而在云原生时代，我们经常会基于容器承载API服务实例，当容器因故退出，并重新启动一个新容器时，IP可能会发生变化，这样上述的手工配置就无法满足要求，这就对API Gateway提出了与服务发现组件集成的要求：通过服务发现组件动态获取服务实例的访问列表，进而实现动态负载均衡。

Tyk Gateway内置了主流服务发现组件(比如Etcd、Consul、ZooKeeper等)的对接能力，鉴于环境所限，这里就不举例了，大家可以在Tyk Gateway的服务发现示例文档页面找到与不同服务发现组件对接时的配置示例。

3.3.5 IP访问限制

针对每个API，API网关还提供IP访问限制的特性，比如Tyk Gateway就提供了IP白名单和IP黑名单功能，通常二选一开启一种限制即可。

以白名单为例，即凡是在白名单中的IP才被允许访问该API。下面是白名单配置样例：

// /opt/tyk-gateway/apps/no-authn-v1.json

  "enable_ip_whitelisting": true,
  "allowed_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14"],

生效后，当我们访问no-authn API时，会得到下面错误：

$curl localhost:8080/api/v1/no-authn
{
    "error": "access from this IP has been disallowed"
}

如果开启的是黑名单，那么凡是在黑名单中的IP都被禁止访问该API，下面是黑名单配置样例：

// /opt/tyk-gateway/apps/no-authn-v1.json

  "enable_ip_blacklisting": true,
  "blacklisted_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14", "127.0.0.1"],

生效后，当我们访问no-authn API时，会得到如下结果：

$curl 127.0.0.1:8080/api/v1/no-authn
{
    "error": "access from this IP has been disallowed"
}

到目前为止，我们的API网关和定义的API都处于“裸奔”状态，因为没有对客户端进行身份认证，任何客户端都可以访问到我们的API，显然这不是我们期望的，接下来，我们就来看看API网关的一个重要功能特性：身份认证与授权。

3.4 功能特性：身份认证和授权

在《通过实例理解Go Web身份认证的几种方式》一文中，我们提到过：建立全局的安全通道是任何身份认证方式的前提。

3.4.1 建立安全通道，卸载TLS证书

Tyk Gateway支持在Gateway层面统一配置TLS证书，同时也起到在Gateway卸载TLS证书的作用：

这次我们要在tyk.conf中进行配置，才能在Gateway层面生效。这里我们借用《通过实例理解Go Web身份认证的几种方式》一文中生成的几个证书(大家可以在https://github.com/bigwhite/experiments/tree/master/authn-examples/tls-authn/make_certs下载)，并将它们放到/opt/tyk-gateway/certs/下面：

$ls /opt/tyk-gateway/certs/
server-cert.pem  server-key.pem

然后，我们在/opt/tyk-gateway/tyk.conf文件中增加下面配置：

// /opt/tyk-gateway/tyk.conf 

  "http_server_options": {
    "use_ssl": true,
    "certificates": [
      {
        "domain_name": "server.com",
        "cert_file": "./certs/server-cert.pem",
        "key_file": "./certs/server-key.pem"
      }
    ]
  }

之后，重启tyk gateway服务，使得tyk.conf的配置修改生效。

注：在/etc/hosts中设置server.com为127.0.0.1。

现在我们用之前的http方式访问一下no-authn的API：

$curl server.com:8080/api/v1/no-authn
Client sent an HTTP request to an HTTPS server.

由于全局启用了HTTPS，采用http方式的请求将被拒绝。我们换成https方式访问：

// 不验证服务端证书
$curl -k https://server.com:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

// 验证服务端的自签证书
$curl --cacert ./inter-cert.pem https://server.com:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

3.4.2 Mutual TLS双向认证

在《通过实例理解Go Web身份认证的几种方式》一文中，我们介绍的第一种身份认证方式就是TLS双向认证，那么Tyk Gateway对MTLS的支持如何呢？Tyk官方文档提到它既支持client mTLS，也支持upstream mTLS。

我们更关心的是client mTLS，即客户端在与Gateway建连后，Gateway会使用Client CA验证客户端的证书！我最初认为这个Client CA的配置是在tyk.conf中，但找了许久，也没有发现配置Client CA的地方。

在no-authn API的定义文件(no-authn-v1.json)中，我们做如下配置改动：

  "use_mutual_tls_auth": true,
  "client_certificates": [
      "/opt/tyk-gateway/certs/inter-cert.pem"
  ],

但使用下面命令访问API时报错：

$curl --key ./client-key.pem --cert ./client-cert.pem --cacert ./inter-cert.pem https://server.com:8080/api/v1/no-authn
{
    "error": "Certificate with SHA256 bc8717c0f2ea5a0b81813abb3ec42ef8f9bf60da251b87243627d65fb0e3887b not allowed"
}

如果将”client_certificates”的配置中的inter-cert.pem改为client-cert.pem，则是可以的，但个人感觉这很奇怪，不符合逻辑，将tyk gateway的文档、issue甚至代码翻了又翻，也没找到合理的配置client CA的位置。

Tyk Gateway支持多种身份认证方式，下面我们来看一种使用较为广泛的方式：JWT Auth。

主要JWT身份认证方式的原理和详情，可以参考我之前的文章《通过实例理解Go Web身份认证的几种方式》。

3.4.3 JWT Token Auth

下面是我为这个示例做的一个示意图：

这是我们日常开发中经常遇到的场景，即通过portal用用户名和密码登录后便可以拿到一个jwt token，然后后续的访问功能API的请求仅携带该jwt token即可。API Gateway对于portal/login API不做任何身份认证；而对后续的功能API请求，通过共享的secret(也称为static secret)对请求中携带的jwt token进行签名验证。

portal/login API由于不进行authn，这样其配置与前面的no-authn API几乎一致，只是API名称、路径和target_list有不同：

// apps/portal-login-v1.json

{
  "name": "portal-login-v1",
  "slug": "portal-login-v1",
  "listen_port": 0,
  "protocol": "",
  "enable_proxy_protocol": false,
  "api_id": "portal-login-v1",
  "org_id": "1",
  "use_keyless": true,
  ... ...
  "proxy": {
    "preserve_host_header": false,
    "listen_path": "/api/v1/portal/login",
    "target_url": "",
    "disable_strip_slash": false,
    "strip_listen_path": true,
    "enable_load_balancing": true,
    "target_list": [
      "http://localhost:28084"
    ],
    "check_host_against_uptime_tests": true,
  ... ...
}

对应的portal login API也不复杂：

// api-gateway-examples/portal-login/main.go

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/golang-jwt/jwt/v5"
)

func main() {
    // 创建一个基本的HTTP服务器
    mux := http.NewServeMux()

    username := "admin"
    password := "123456"
    key := "iamtonybai"

    // for uptime test
    mux.HandleFunc("/health", func(w http.ResponseWriter, req *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    // login handler
    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        // 从请求头中获取Basic Auth认证信息
        user, pass, ok := req.BasicAuth()
        if !ok {
            // 认证失败
            w.WriteHeader(http.StatusUnauthorized)
            return
        }

        // 验证用户名密码
        if user == username && pass == password {
            // 认证成功，生成token
            token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
                "username": username,
                "iat":      jwt.NewNumericDate(time.Now()),
            })
            signedToken, _ := token.SignedString([]byte(key))
            w.Write([]byte(signedToken))
        } else {
            // 认证失败
            http.Error(w, "Invalid username or password", http.StatusUnauthorized)
        }
    })

    // 监听28084端口
    err := http.ListenAndServe(":28084", mux)
    if err != nil {
        log.Fatal(err)
    }
}

运行该login API服务后，我们用curl命令获取一下jwt token：

$curl -u 'admin:123456' -k https://server.com:8080/api/v1/portal/login
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA

现在我们再来建立protected API：

// apps/protected-v1.json

{
  "name": "protected-v1",
  "slug": "protected-v1",
  "listen_port": 0,
  "protocol": "",
  "enable_proxy_protocol": false,
  "api_id": "protected-v1",
  "org_id": "1",
  "use_keyless": false,    // 设置为false, gateway才会进行jwt的验证
  ... ...
  "enable_jwt": true,      // 开启jwt
  "use_standard_auth": false,
  "use_go_plugin_auth": false,
  "enable_coprocess_auth": false,
  "custom_plugin_auth_enabled": false,
  "jwt_signing_method": "hmac",        // 设置alg为hs256
  "jwt_source": "aWFtdG9ueWJhaQ==",    // 设置共享secret: base64("iamtonybai")
  "jwt_identity_base_field": "username", // 设置代表请求中的用户身份的字段，这里我们用username
  "jwt_client_base_field": "",
  "jwt_policy_field_name": "",
  "jwt_default_policies": [
     "5e189590801287e42a6cf5ce"        // 设置security policy，这个似乎是jwt auth必须的
  ],
  "jwt_issued_at_validation_skew": 0,
  "jwt_expires_at_validation_skew": 0,
  "jwt_not_before_validation_skew": 0,
  "jwt_skip_kid": false,
  ... ...
  "version_data": {
    "not_versioned": true,
    "default_version": "",
    "versions": {
      "Default": {
        "name": "Default",
        "expires": "",
        "paths": {
          "ignored": null,
          "white_list": null,
          "black_list": null
        },
        "use_extended_paths": true,
        "extended_paths": {
          "persist_graphql": null
        },
        "global_headers": {
          "username": "$tyk_context.jwt_claims_username" // 设置转发到upstream的请求中的header字段username
        },
        "global_headers_remove": null,
        "global_response_headers": null,
        "global_response_headers_remove": null,
        "ignore_endpoint_case": false,
        "global_size_limit": 0,
        "override_target": ""
      }
    }
  },
  ... ...
  "enable_context_vars": true, // 开启上下文变量
  "config_data": null,
  "config_data_disabled": false,
  "tag_headers": ["username"], // 设置header
  ... ...
}

这个配置就相对复杂许多，也是翻阅了很长时间资料才验证通过的配置。JWT Auth必须有关联的policy设置，我们在tyk gateway开源版中要想设置policy，需要现在tyk.conf中做如下设置：

// /opt/tyk-gateway/tyk.conf

  "policies": {
    "policy_source": "file",
    "policy_record_name": "./policies/policies.json"
  },

而policies/policies.json的内容如下：

// /opt/tyk-gateway/policies/policies.json
{
    "5e189590801287e42a6cf5ce": {
        "rate": 1000,
        "per": 1,
        "quota_max": 100,
        "quota_renewal_rate": 60,
        "access_rights": {
            "protected-v1": {
                "api_name": "protected-v1",
                "api_id": "protected-v1",
                "versions": [
                    "Default"
                ]
            }
        },
        "org_id": "1",
        "hmac_enabled": false
    }
}

上述设置完毕并重启tyk gateway生效后，且protected api服务也已经启动时，我们访问一下该API服务：

$curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA" -k https://server.com:8080/api/v1/protected
invoke protected api ok

我们看到curl发出的请求成功通过了Gateway的验证！并且通过protected API输出的请求信息来看，Gateway成功解析出username，并将其作为Header中的字段传递给了protected API服务实例：

http.Request{Method:"GET", URL:(*url.URL)(0xc0002f6240), Proto:"HTTP/1.1", ProtoMajor:1, ProtoMinor:1, Header:http.Header{"Accept":[]string{"*/*"}, "Accept-Encoding":[]string{"gzip"}, "Authorization":[]string{"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA"}, "User-Agent":[]string{"curl/7.29.0"}, "Username":[]string{"admin"}, "X-Forwarded-For":[]string{"127.0.0.1"}}, Body:http.noBody{}, GetBody:(func() (io.ReadCloser, error))(nil), ContentLength:0, TransferEncoding:[]string(nil), Close:false, Host:"localhost:28085", Form:url.Values(nil), PostForm:url.Values(nil), MultipartForm:(*multipart.Form)(nil), Trailer:http.Header(nil), RemoteAddr:"[::1]:55583", RequestURI:"/", TLS:(*tls.ConnectionState)(nil), Cancel:(<-chan struct {})(nil), Response:(*http.Response)(nil), ctx:(*context.cancelCtx)(0xc0002e34f0)}

如果不携带Authorization头字段或jwt的token是错误的，那么结果将如下所示：

$ curl -k https://server.com:8080/api/v1/protected
{
    "error": "Authorization field missing"
}

$ curl -k -H "Authorization: Bearer xxx" https://server.com:8080/api/v1/protected
{
    "error": "Key not authorized"
}

一旦通过API Gateway的身份认证，上游的API服务就会拿到客户端身份，有了唯一身份后，就可以进行授权操作了，其实policy设置本身也是一种授权访问控制。Tyk Gateway自身也支持RBAC等模型，也支持与OPA(open policy agent)等的集成，但更多是在商业版的tyk dashboard下完成的，这里也就不重点说明了。

下面的Gateway的几个主要功能特性由于试验环境受限以及文章篇幅考量，我不会像上述例子这么细致的说明了，只会简单说明一下。

3.5 功能特性：流量控制与限速

Tyk Gateway内置提供了强大的流量控制功能，可以通过全局级别和API级别的限速来管理请求流量。此外，Tyk Gateway 还支持请求配额（request quota）来限制每个用户或应用程序在一个时间周期内的请求次数。

流量不仅和请求速度和数量有关系，与请求的大小也有关系，Tyk Gateway还支持在全局层面和API层面设置Request的size limit，以避免超大包对网关运行造成不良影响。

3.6 功能特性：高可用与容错处理

在许多情况下，我们要为客户确保服务水平(service level)，比如：最大往返时间、最大响应时延等。Tyk Gateway提供了一系列功能，可帮助我们确保网关的高可用运行和SLA服务水平。

Tyk支持健康检查，这对于确定Tyk Gateway的状态极为重要，没有健康检查，就很难知道网关的实际运行状态如何。

Tyk Gateway还内置了断路器(circuit breaker)，这个断路器是基于比例的，因此如果y个请求中的x请求都失败了，断路器就会跳闸，例如，如果x = 10，y = 100，则阈值百分比为10%。当失败比例到达10%时，断路器就会切断流量，同时跳闸还会触发一个事件，我们可以记录和处理该事件。

当upstream的服务响应迟迟不归时，Tyk Gateway还可以设置强制超时，可以确保服务始终在给定时间内响应。这在高可用性系统中非常重要，因为在这种系统中，响应性能至关重要，这样才能干净利落地处理错误。

3.7 功能特性：监控与可观测性

微服务时代，可观测性对运维以及系统高可用的重要性不言而喻。Tyk Gateway在多年的演化过程中，也逐渐增加了对可观测的支持，

可观测主要分三大块：

Tyk Gateway支持设置输出日志的级别(log level)，默认是info级别。Tyk输出的是结构化日志，这使得它可以很好的与其他日志收集查询系统集成，Tyk支持与主流的日志收集工具对接，包括：logstash、sentry、Graylog、Syslog等。

metrics

度量数据是反映网关系统健康状况、错误计数和类型、IT基础设施（服务器、虚拟机、容器、数据库和其他后端组件）及其他流程的硬件资源数据的重要参考。运维团队可以通过使用监控工具来利用实时度量的数据，识别运行趋势、在系统故障时设置警报、确定问题的根本原因并缓解问题。

Tyk Gateway内置了对主流metrics采集方案Prometheus+Grafana的支持，可以在网关层面以及对API进行实时度量数据采集和展示。

tracing

Tyk Gateway从5.2版本开始支持了与服务Tracing界的标准：OpenTelemetry的集成，这样你可以使用多种支持OpenTelemetry的Tracing后端，比如Jaeger、Datadog等。Tracing可在Gateway层面开启，也可以延展到API层面。

4. 小结

本文对已经相对成熟的API网关技术做了回顾，对API网关的演进阶段、主流特性以及当前市面上的主流API网关进行了简要说明，并以Go实现的Tyk Gateway社区开源版为例，以示例方式对API网关的主要功能做了介绍。

总体而言，Tyk Gateway是一款功能强大，社区相对活跃并有商业公司支持的产品，文档很丰富，但从实际使用层面，这些文档对Tyk社区版本的使用者来说并不友好，指导性不足(更多用商业版的Dashboard说明，与配置文件难于对应)，就像本文例子中那样，为了搞定JWT认证，笔者着实花了不少时间查阅资料，甚至阅读源码。

Tyk Gateway的配置设计平坦，没有层次和逻辑，感觉是随着时间随意“堆砌”上去的。并且配置文件更新时，如果出现格式问题，Tyk Gateway并不报错，让人难于确定配置是否真正生效了，只能用Tyk Gateway的控制API去查询结果来验证，非常繁琐低效。

本文涉及的源码可以在这里下载，文中涉及的一些tyk gateway api和security policy的配置也可以在其中查看。

5. 参考资料

Leaving the Cloud – https://37signals.com/podcast/leaving-the-cloud/
The Past, Present, and Future of API Gateways – https://www.infoq.com/articles/past-present-future-api-gateways/
How moving from AWS to Bare-Metal saved us 230,000/yr – https://blog.oneuptime.com/moving-from-aws-to-bare-metal/
A Comprehensive Guide to API Gateways, Kubernetes Gateways, and Service Meshes – https://navendu.me/posts/gateway-and-mesh/
Use API gateways in microservices – https://learn.microsoft.com/en-us/azure/architecture/microservices/design/gateway
The Tyk API Gateway and Postman – https://blog.postman.com/the-tyk-api-gateway-and-postman/
Getting Started with Tyk API Gateway with Keycloak – https://javascript.plainenglish.io/getting-started-to-tyk-api-gateway-with-keycloak-16307435584a
Observing your API traffic with Tyk, Elasticsearch & Kibana – https://medium.com/@asoorm/observing-your-api-metrics-with-tyk-elasticsearch-kibana-74e8fd946c39
Set up JWT token in tyk gateway – https://community.tyk.io/t/set-up-jwt-token-in-tyk-gateway/6572/9

“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群！高品质首发Go技术文章，“三天”首发阅读权，每年两期Go语言发展现状分析，每天提前1小时阅读到新鲜的Gopher日报，网课、技术专栏、图书内容前瞻，六小时内必答保证等满足你关于Go语言生态的所有需求！2023年，Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码，关注代码质量并深入理解Go核心技术，并继续加强与星友的互动。欢迎大家加入！

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式：

微博(暂不可用)：https://weibo.com/bigwhite20xx
微博2：https://weibo.com/u/6484441286
博客：tonybai.com
github: https://github.com/bigwhite
Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

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

提高您的kubectl生产力（第三部分）：集群上下文切换、使用别名减少输入和插件扩展

bigwhite — Sat, 31 Aug 2019 05:01:43 +0000

本文翻译自《Boosting your kubectl productivity》。

第一部分：什么是kubectl？
第二部分：命令完成、资源规范快速查看和自定义列输出格式什么是kubectl？

4. 轻松切换集群和名称空间

当kubectl必须向Kubernetes API发出请求时，它会读取系统上所谓的kubeconfig文件，以获取它需要访问的所有连接参数并向API服务器发出请求。

默认的kubeconfig文件是~/.kube/config。此文件通常由某个命令自动创建或更新（例如，aws eks update-kubeconfig或者gcloud container clusters get-credentials，如果您使用托管Kubernetes服务）。

使用多个集群时，您的kubeconfig文件中配置了多个集群的连接参数。这意味着，您需要一种方法来告诉kubectl 您希望它连接到哪个集群。

在集群中，您可以设置多个名称空间（名称空间是物理集群中的一种“虚拟”集群）。Kubectl也会从kubeconfig文件确定用于请求的命名空间。因此，您需要一种方法来告诉kubectl 您希望它使用哪个命名空间。

本节将介绍kubectl切换集群上下文的原理以及它是如何轻松完成的。

请注意，您还可以在KUBECONFIG环境变量中列出多个kubeconfig文件。在这种情况下，所有这些文件将在执行时合并为单个有效配置。您还可以使用–kubeconfig指定kubectl命令的选项以覆盖默认的kubeconfig文件。请参阅官方文档。

Kubeconfig文件

让我们看看kubeconfig文件实际包含的内容：

如您所见，kubeconfig文件由一组上下文组成。上下文包含以下三个元素：

集群(cluster)：集群的API服务器的URL
用户(user)：集群的特定用户的身份验证凭据
命名空间(namespace)：连接到集群时使用的命名空间

实际上，人们经常在他们的kubeconfig文件中为每个集群的配置一个上下文。但是，你也可以为每个集群配置多个上下文，其用户或命名空间不同。但这似乎不太常见，因此通常在集群和上下文之间存在一对一的映射。

在任何给定时间，其中一个上下文被设置为当前上下文（通过kubeconfig文件中的专用字段）：

当kubectl读取kubeconfig文件时，它总是使用当前上下文中的信息。因此，在上面的例子中，kubectl将连接到Hare集群。

因此，要切换到另一个集群，您只需更改kubeconfig文件中的当前上下文：

在上面的示例中，kubectl现在将连接到Fox集群。

要切换到同一集群中的另一个命名空间，您可以更改当前上下文的命名空间元素的值：

在上面的示例中，kubectl现在将使用Fox群集中的Prod命名空间（而不是之前设置的Test命名空间）。

请注意，kubectl还提供了–cluster，–user和–namespace，以及–context允许您覆盖单个元素和当前上下文本身的选项，无论kubeconfig文件中设置了什么。见kubectl options。

理论上，您可以通过手动编辑kubeconfig文件来执行这些更改。但当然这很乏味。以下部分介绍了允许您自动执行这些更改的各种工具。

使用kubectx

kubectx是一种非常流行的用于在集群和命名空间之间切换的工具。

此工具提供允许您分别更改当前上下文和命名空间的命令kubectx和kubens命令。

如上所述，如果每个集群只有一个上下文，则更改当前上下文意味着更改集群。

在这里，您可以看到这两个命令：

在表象之下，这些命令只是编辑kubeconfig文件，如上一节中所述。

要安装kubectx，只需按照GitHub页面上的说明操作即可。

kubectx和kubens都通过完成交办提供命令完成(command completion)。这允许您自动完成上下文名称和名称空间，这样您就不必完全键入它们。您也可以在GitHub页面上找到设置完成的说明。

kubectx的另一个有用功能是交互模式。这与fzf工具结合使用，您必须单独安装（事实上，安装fzf，将自动启用kubectx交互模式）。交互模式允许您通过交互式模糊搜索界面（由fzf提供）选择目标上下文或命名空间。

使用shell别名

实际上，您并不需要单独的工具来更改当前上下文和命名空间，因为kubectl也提供了执行此操作的命令。特别是，该kubectl config命令提供了用于编辑kubeconfig文件的子命令。这里是其中的一些：

kubectl config get-contexts：列出所有上下文
kubectl config current-context：获取当前上下文
kubectl config use-context：更改当前上下文
kubectl config set-context：更改上下文的元素

但是，直接使用这些命令并不是很方便，因为它们很难输入。但是你可以做的是将它们包装成可以更容易执行的shell别名。

我基于这些命令创建了一组别名，这些命令提供了与kubectx类似的功能。在这里你可以看到他们的行动：

请注意，别名使用fzf来提供交互式模糊搜索界面（如kubectx的交互模式）。这意味着，您需要安装fzf才能使用这些别名。

以下是别名的定义：

# Get current context
alias krc='kubectl config current-context'
# List all contexts
alias klc='kubectl config get-contexts -o name | sed "s/^/  /;\|^  $(krc)$|s/ /*/"'
# Change current context
alias kcc='kubectl config use-context "$(klc | fzf -e | sed "s/^..//")"'

# Get current namespace
alias krn='kubectl config get-contexts --no-headers "$(krc)" | awk "{print \$5}" | sed "s/^$/default/"'
# List all namespaces
alias kln='kubectl get -o name ns | sed "s|^.*/|  |;\|^  $(krn)$|s/ /*/"'
# Change current namespace
alias kcn='kubectl config set-context --current --namespace "$(kln | fzf -e | sed "s/^..//")"'

要安装这些别名，你只需要在上面定义添加到您的~/.bashrc或~/.zshrc文件，并重新加载你的shell(source ~/.bashrc or source ~/.zshrc)！

使用插件

Kubectl允许安装可以像本机命令一样调用的插件。例如，您可以安装名为kubectl-foo的插件，然后将其调用为kubectl foo。

Kubectl插件将在本文的后续部分中详细介绍。

能够像这样更改当前上下文和命名空间不是很好吗？例如，运行kubectl ctx以更改上下文，kubectl ns更改名称空间？

我创建了两个允许这样做的插件：

在内部，插件构建在上一节的别名之上。

在这里你可以看到插件的实际效果：

请注意，插件使用fzf来提供交互式模糊搜索界面。这意味着，您需要安装fzf才能使用这些插件。

要安装插件，你只需要将名为的shell脚本kubectl-ctx和kubectl-ns的脚本下载以到PATH下的任何目录中，并使他们具备可执行权限（例如，使用chmod +x）。紧接着，你就应该能够使用kubectl ctx和kubectl ns！

5. 使用自动生成的别名减少输入

Shell别名通常是减少手工输入的好方法。该kubectl-aliases项目就是以这个想法为核心，并提供800多个kubectl命令别名。

您可能想知道如何记住800个别名？实际上，您不需要记住它们，因为它们都是根据一个简单的方案生成的，下面将显示一些示例别名：

如您所见，别名由组件(component)组成，每个组件代表kubectl命令的特定元素。每个别名可以有一个用于基本命令，操作和资源的组件，以及用于选项的多个组件，您只需根据上述方案从左到右“填充”这些组件。

请注意，目前完全详细的方案在GitHub页面上。在那里，您还可以找到别名的完整列表。

例如，别名kgpooyamlall代表命令kubectl get pods -o yaml –all-namespaces：

请注意，大多数选项组件的相对顺序无关紧要。所以，kgpooyamlall相当于kgpoalloyaml。

您不需要将所有组件用于别名。例如k，kg，klo，ksys，或者kgpo是有效的别名也。此外，您可以在命令行中将别名与其他单词组合使用。

例如，您可以k proxy用于运行kubectl proxy：

或者您可以kg roles用于运行kubectl get roles（目前不存在Roles资源的别名组件）：

要获取特定Pod，您可以使用kgpo my-pod以运行kubectl get pod my-pod：

请注意，某些别名甚至需要在命令行上的进一步参数。例如，kgpol别名代表kubectl get pods -l。该-l选项需要一个参数（标签规范）。所以，你必须使用这个别名，例如，像这样:

出于这个原因，你可以使用a，f以及l只在一个别名的结尾部分。

一般来说，一旦你掌握了这个方案，就可以直观地从你想要执行的命令中推断出别名，并节省大量的输入！

安装

要安装kubectl-别名，你只需要下载.kubectl-aliasesGitHub文件，并在你的~/.bashrc或~/.zshrc文件生效它：

source ~/.kubectl_aliases

重新加载shell后，您应该能够使用所有800个kubectl别名！

命令完成

如您所见，您经常在命令行上向别名添加更多单词。例如：

$kgpooyaml test-pod-d4b77b989

如果你使用kubectl命令完成，那么你可能习惯于自动完成资源名称之类的事情。但是当你使用别名时，你还可以这样做吗？

这是一个重要的问题，因为如果它不起作用，那将消除这些别名的一些好处！

答案取决于您使用的shell。

对于Zsh，完成对于别名是开箱即用的。

不幸的是，对于Bash，默认情况下，对于别名，完成功能不起作用。好消息是它可以通过一些额外的步骤来完成。下一节将介绍如何执行此操作。

在Bash中启用别名的完成

Bash的问题在于它尝试在别名上尝试完成（每当你按Tab键），而不是在别名命令（如Zsh）上。由于您没有所有800个别名的完成脚本，因此不起作用。

complete-alias项目提供了解决这个问题的通用解决方案。它使用别名的完成机制，在内部将别名扩展到别名命令，并返回扩展命令的完成建议。这意味着，它使别名的完成行为与别名命令完全相同。

在下文中，我将首先解释如何安装complete-alias，然后如何配置它以启用所有kubectl别名的完成。

安装complete-alias

首先，complete-alias依赖于bash-completion。因此，您需要确保在安装complete-alias之前安装了bash-completion。早先已经为Linux和macOS提供了相关说明。

对于macOS用户的重要注意事项：与kubectl完成脚本一样，complete-alias不适用于Bash 3.2，这是macOS上Bash的默认版本。特别是，complete-alias依赖于bash-completion v2（brew install bash-completion@2），它至少需要Bash 4.1。这意味着，要在macOS上使用complete-alias，您需要安装较新版本的Bash。

要安装complete-alias，您只需bash_completion.sh从GitHub存储库下载脚本，并将其在您的~/.bashrc文件中source：

source ~/bash_completion.sh

重新加载shell后，应正确安装complete-alias。

启用kubectl别名的完成

从技术上讲，complete-alias提供了_complete_aliasshell函数。此函数检查别名并返回别名命令的完成建议。

要将其与特定别名挂钩，您必须使用completeBash内置来设置别名_complete_alias的完成功能。

举个例子，我们k来看一下代表kubectl命令的别名。要设置_complete_alias此别名的完成功能，您必须执行以下命令：

$complete -F _complete_alias k

这样做的结果是，无论何时在k别名上自动完成，_complete_alias都会调用该函数，该函数检查别名并返回kubectl命令的完成建议。

作为另一个例子，让我们采用kg代表的别名kubectl get：

$complete -F _complete_alias kg

同样，这样做的结果是，当您自动完成时kg，您将获得与之相同的完成建议kubectl get。

请注意，可以以这种方式对系统上的任何别名使用complete-alias。

因此，要启用所有 kubectl别名的完成，您只需为每个别名运行上述命令。以下代码片段完全相同（假设您安装了kubectl-aliases ~/.kubectl-aliases）：

for _a in $(sed '/^alias /!d;s/^alias //;s/=.*$//' ~/.kubectl_aliases); do
  complete -F _complete_alias "$_a"
done

只需将此片段添加到您的~/.bashrc文件中，重新加载您的shell，现在您应该可以使用所有800 kubectl别名的完成！

6. 使用插件扩展kubectl

从版本1.12开始，kubectl包含一个插件机制，允许您使用自定义命令扩展kubectl。

以下是kubectl插件的示例，可以调用为kubectl hello：

$ kubectl hello
Hello, I'm a kubectl plugin!

kubectl插件机制将严格遵循Git插件机制的设计。

本节将向您展示如何安装插件，您可以在哪里找到现有的插件，以及如何创建自己的插件。

安装插件

Kubectl插件作为简单的可执行文件分发，其名称的形式为kubectl-x。前缀kubectl-是必需的，接下来是允许调用插件的新kubectl子命令。

例如，上面显示的hello插件将作为名为的文件分发kubectl-hello。

要安装插件，您只需将kubectl-x文件复制到您的任何目录中PATH并使其可执行（例如，使用chmod +x）。之后，您可以立即调用该插件kubectl x。

您可以使用以下命令列出系统上当前安装的所有插件：

$kubectl plugin list

如果您有多个具有相同名称的插件，或者存在不可执行的插件文件，则此命令还会显示警告。

使用krew查找和安装插件

Kubectl插件可以像软件包一样共享和重用。但是在哪里可以找到其他人共享的插件？

该krew项目旨在提供一个统一的解决方案，共享，查找，安装和管理kubectl插件。该项目将自己称为“kubectl插件的包管理器”（名称krew是brew的提示）。

Krew 以kubectl插件索引为中心，您可以从中选择和安装。

$ kubectl krew search | less
$ kubectl krew search view
$ kubectl krew info view-utilization
$ kubectl krew install view-utilization
$ kubectl krew list

如您所见，krew本身是一个kubectl插件。这意味着，安装krew本质上就像安装任何其他kubectl插件一样。您可以在GitHub页面上找到krew的详细安装说明。

最重要的krew命令如下：

# Search the krew index (with an optional search query)
$ kubectl krew search []
# Display information about a plugin
$ kubectl krew info 
# Install a plugin
$ kubectl krew install 
# Upgrade all plugins to the newest versions
$ kubectl krew upgrade
# List all plugins that have been installed with krew
$ kubectl krew list
# Uninstall a plugin
$ kubectl krew remove

请注意，使用krew安装插件并不妨碍以传统方式安装插件。即使你使用krew，你仍然可以通过其他方式安装你在其他地方找到的插件（或自己创建）。

请注意，该kubectl krew list命令仅列出已使用krew安装的插件，而该kubectl plugin list命令列出了所有插件，即使用krew安装的插件和以其他方式安装的插件。

在其他地方寻找插件

Krew仍然是一个年轻的项目，目前krew索引中只有大约30个插件。如果你在那里找不到你需要的东西，你可以在其他地方寻找插件，例如，在GitHub上。

我建议查看kubectl-plugins GitHub主题。你会发现有几十个可用的插件值得一看。

创建自己的插件

当然，您可以创建自己的kubectl插件，这很容易实现。

您只需创建一个可执行文件，执行您想要的操作，为其命名kubectl-x，然后按上述方法安装它。

可执行文件可以是任何类型，Bash脚本，编译的Go程序，Python脚本，它确实无关紧要。唯一的要求是它可以由操作系统直接执行。

我们现在创建一个示例插件。在上部分中，您使用kubectl命令列出每个pod的容器镜像。您可以轻松地将此命令转换为可以调用的插件，比如说kubectl img。

为此，只需创建一个名为kubectl-img以下内容的文件：

#!/bin/bash
kubectl get pods -o custom-columns='NAME:metadata.name,IMAGES:spec.containers[*].image'

现在使文件可执行，chmod +x kubectl-img并将其移动到您的任何PATH中的目录。之后，您可以立即开始使用该插件kubectl img！

如上所述，kubectl插件可以用任何编程语言或脚本语言编写。如果使用shell脚本，则可以从插件轻松调用kubectl。但是，您可以使用实际编程语言编写更复杂的插件，例如，使用Kubernetes客户端库。如果使用Go，您还可以使用cli-runtime库，它专门用于编写kubectl插件。

分享你的插件

如果您认为其中一个插件可能对其他人有用，请随时在GitHub上分享。确保将其添加到kubectl-plugins主题中，以便其他人可以找到它。

您还可以请求将您的插件添加到krew索引中。您可以在krew GitHub存储库中找到有关如何执行此操作的说明。

命令完成

目前，插件机制遗憾的是还不支持命令完成。这意味着您需要完全键入插件名称以及插件的任何参数。

但是，在kubectl GitHub存储库中有一个处于open状态的功能请求issue。因此，此功能有可能在将来的某个时间得到实现。

以上就是有关kubectl高效使用的所有内容了！

我的网课“Kubernetes实战：高可用集群搭建、配置、运维与应用”在慕课网上线了，感谢小伙伴们学习支持！

我爱发短信：企业级短信平台定制开发专家 https://tonybai.com/
smspush : 可部署在企业内部的定制化短信平台，三网覆盖，不惧大并发接入，可定制扩展；短信内容你来定，不再受约束, 接口丰富，支持长短信，签名可选。

我的联系方式：

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

微信赞赏：

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

提高您的kubectl生产力（第二部分）：命令完成、资源规范快速查看和自定义列输出格式

bigwhite — Fri, 30 Aug 2019 06:39:45 +0000

本文翻译自《Boosting your kubectl productivity》。

第一部分：什么是kubectl？

1. 通过命令完成(command completion)减少输入

命令完成是提高你的kubectl生产力的最有用但经常被忽视的技巧之一。

命令完成允许您使用Tab键自动完成kubectl命令的各个部分。这适用于子命令，选项和参数，包括资源名称等难以输入的内容。

在这里你可以看到kubectl命令完成的动作：

命令完成在Bash和Zsh shell下均可用。

在官方文档中包含有关设置命令完成的详细说明，下面的章节我们再带着大家回顾一下。

命令完成的工作原理

通常，命令完成是一个shell功能，它通过completion script(完成脚本)的方式工作。完成脚本是一个shell脚本，用于定义特定命令的完成行为。获取完成脚本可以完成相应的命令。

Kubectl可以使用以下命令自动生成并打印出Bash和Zsh的完成脚本：

$kubectl completion bash
# or
$kubectl completion zsh

理论上，在适当的shell中获取此命令的输出可以完成kubectl命令。

但是，在实践中，Bash（包括Linux和macOS之间的差异）和Zsh的细节不同。以下部分解释了所有这些情况：

在Linux上为Bash设置命令完成
在macOS上设置Bash的命令完成
设置Zsh的命令完成

在Linux上的Bash

Bash的完成脚本取决于bash-completion项目，因此您必须先安装它。

您可以使用各种包管理器安装bash-completion 。例如：

$sudo apt-get install bash-completion
# or
$yum install bash-completion

您可以使用以下命令测试是否正确安装了bash-completion：

$type _init_completion

如果这输出shell函数的代码，则已正确安装bash-completion。如果该命令输出not found错误，则必须将以下行添加到您的~/.bashrc文件中：

$source /usr/share/bash-completion/bash_completion

是否必须将此行添加到您的~/.bashrc文件中，取决于您用于安装bash-completion的包管理器。对于APT来说，这是必要的，对于yum，则无需。

安装bash-completion后，您必须进行设置，以便在所有shell会话中获取kubectl 完成脚本。

一种方法是将以下行添加到您的~/.bashrc文件中：

source <(kubectl completion bash)

另一种可能性是将kubectl完成脚本添加到/etc/bash_completion.d目录中（如果它不存在则创建它）：

$kubectl completion bash >/etc/bash_completion.d/kubectl

/etc/bash_completion.d目录中的所有完成脚本都是由bash-completion自动获取的。

两种方法都是等价的。

重新加载shell后，kubectl命令完成应该正常工作！

在MacOS上的Bash

有了macOS，就会出现轻微的复杂情况。原因是macOS上的Bash默认版本是3.2，这已经过时了。遗憾的是，kubectl完成脚本至少需要Bash 4.1，因此不适用于Bash 3.2。

Apple在macOS中包含过时版本的Bash的原因是较新版本使用Apple不支持的GPLv3许可证。

这意味着，要在macOS上使用kubectl命令完成，您必须安装较新版本的Bash。您甚至可以将它设为新的默认shell，这将为您节省很多此类麻烦。这实际上并不困难，您可以在我之前编写的macOS文章中的升级Bash中找到说明。

在继续之前，请确保您现在确实使用的是Bash 4.1或更新版本（请查看bash –version）。

Bash的完成脚本取决于bash-completion项目，因此您必须先安装它。

您可以使用Homebrew安装bash-completion ：

$brew install bash-completion@2

bash-completion v2的@2代表。kubectl完成脚本需要bash-completion v2，而bash-completion v2至少需要Bash 4.1。这就是您不能在低于4.1的Bash版本上使用kubectl完成脚本的原因。

该brew install命令的输出包含一个“警告”部分，其中包含将以下行添加到您的~/.bash_profile文件的说明：

export BASH_COMPLETION_COMPAT_DIR=/usr/local/etc/bash_completion.d
[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"

您必须这样做才能完成bash-completion的安装。但是，我建议将这些行添加到您~/.bashrc文件中而不是~/.bash_profile文件中。这能确保子shell中也可以使用bash-completion。

重新加载shell后，可以使用以下命令测试是否正确安装了bash-completion：

$type _init_completion

如果这输出shell函数的代码，那么你就完成了。

现在，您必须进行设置以便kubectl 完成脚本在所有shell会话中获取。

一种方法是将以下行添加到您的~/.bashrc文件中：

source <(kubectl completion bash)

另一种可能性是将kubectl完成脚本添加到/usr/local/etc/bash_completion.d目录：

$kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl

这仅在您使用Homebrew安装bash-completion时才有效。在这种情况下，bash-completion会在此目录中提供所有完成脚本。

如果您还使用Homebrew安装了kubectl，您甚至不必执行上述步骤，因为完成脚本应该已经通过kubectl howbrew formula放在/usr/local/etc/bash_completion.d目录中了。在这种情况下，kubectl完成应该在安装bash-completion后自动开始工作。

最后，所有这些方法都是等效的。

重新加载shell后，kubectl完成应该正常工作！

Zsh

Zsh的完成脚本没有任何依赖项。因此，您所要做的就是设置所有内容，以便在所有shell会话中获取源代码。

您可以通过在~/.zshrc文件中添加以下行来完成此操作：

source <(kubectl completion zsh)

如果在重新加载shell后出现错误:command not found: compdef，则必须启用compdef内置功能，您可以通过将以下内容添加到~/.zshrc文件的开头来执行此操作：

autoload -Uz compinit
compinit

2. 快速查找资源规范

创建YAML资源定义时，您需要知道这些资源的字段及其含义。一个可以查找到此类信息的位置是在API参考文档中，那里包含了所有资源的完整规范。

但是，每次需要查找某些内容时都要切换到Web浏览器很乏味。因此，kubectl提供了kubectl explain命令，可以打印出终端中所有资源的资源规范。

kubectl explain用法如下：

$kubectl explain resource[.field]...

该命令输出所请求资源或字段的规范。kubectl explain显示的信息与API参考中的信息相同。

默认情况下，kubectl explain仅显示单个级别的字段。您可以使用显示整个字段树的标志:–recursive：

$kubectl explain deployment.spec --recursive

如果您不确定可以使用哪些资源名称，可以使用kubectl explain以下命令显示所有这些名称：

$kubectl api-resources

此命令以复数形式显示资源名称（例如，deployments而不是deployment）。对于拥有短名称的资源，它还显示该资源的短名称（例如：deploy）。不要担心这些差异，对于kubectl来说，所有这些名称变体都是等同的。也就是说，你可以在kubectl explain中使用它们中的任何一个。

例如，以下所有命令都是等效的：

$kubectl explain deployments.spec
# or
$kubectl explain deployment.spec
# or
$kubectl explain deploy.spec

3. 使用自定义列输出格式

kubectl get命令的默认输出格式（用于读取资源）如下：

$kubectl get pods
NAME                      READY   STATUS    RESTARTS   AGE
engine-544b6b6467-22qr6   1/1     Running   0          78d
engine-544b6b6467-lw5t8   1/1     Running   0          78d
engine-544b6b6467-tvgmg   1/1     Running   0          78d
web-ui-6db964458-8pdw4    1/1     Running   0          78d

这对于人类而言，是一种很好的可读格式，但它只包含有限的信息。如您所见，每个资源只显示一些字段（与完整资源定义相比）。

这就是自定义列输出格式的用武之地。它允许您自由定义要显示在其中的列和数据。您可以选择要在输出中显示为单独列的资源的任何字段

自定义列输出选项的用法如下：

-o custom-columns=:[,:]...

您必须将每个输出列定义为一

header>:对：

header> 是列的名称，您可以选择任何您想要的。
* 是一个选择资源字段的表达式（在下面更详细地说明）。

我们来看一个简单的例子：

$ kubectl get pods -o custom-columns='NAME:metadata.name'
NAME
engine-544b6b6467-22qr6
engine-544b6b6467-lw5t8
engine-544b6b6467-tvgmg
web-ui-6db964458-8pdw4

这里，输出包含一个显示所有Pod名称的列。

选择Pod名称的表达式是metadata.name。这样做的原因是Pod的名称在Pod资源字段的metadata的name字段中定义（您可以在API参考中查找或使用kubectl explain pod.metadata.name）。

现在，假设您要在输出中添加一个附加列，例如，显示每个Pod正在运行的节点。为此，您只需向自定义列选项添加适当的列规范：

$kubectl get pods \
  -o custom-columns='NAME:metadata.name,NODE:spec.nodeName'
NAME                      NODE
engine-544b6b6467-22qr6   ip-10-0-80-67.ec2.internal
engine-544b6b6467-lw5t8   ip-10-0-36-80.ec2.internal
engine-544b6b6467-tvgmg   ip-10-0-118-34.ec2.internal
web-ui-6db964458-8pdw4    ip-10-0-118-34.ec2.internal

选择节点名称的表达式是spec.nodeName。这是因为已调度Pod的节点保存在Pod的spec.nodeName字段中（请参阅参考资料kubectl explain pod.spec.nodeName）。

请注意，Kubernetes资源字段区分大小写。

您可以通过这种方式将资源的任何字段设置为输出列。只需浏览资源规范并尝试使用您喜欢的任何字段！

但首先，让我们仔细看看这些字段选择表达式。

JSONPath表达式

选择资源字段的表达式基于JSONPath。

JSONPath是一种从JSON文档中提取数据的语言（类似于XPath for XML）。选择单个字段只是JSONPath的最基本用法。它有很多功能，如列表选择器，过滤器等。

但是，kubectl explain仅支持JSONPath功能的一部分。以下通过示例用法总结了这些支持的功能：

# Select all elements of a list
$kubectl get pods -o custom-columns='DATA:spec.containers[*].image'

# Select a specific element of a list
$kubectl get pods -o custom-columns='DATA:spec.containers[0].image'

# Select those elements of a list that match a filter expression
$kubectl get pods -o custom-columns='DATA:spec.containers[?(@.image!="nginx")].image'

# Select all fields under a specific location, regardless of their name
$kubectl get pods -o custom-columns='DATA:metadata.*'

# Select all fields with a specific name, regardless of their location
$kubectl get pods -o custom-columns='DATA:..image'

特别重要的是[]操作符。Kubernetes资源的许多字段都是列表，此运算符允许您选择这些列表中的项目。它通常与通配符一起使用，[*]以选择列表中的所有项目。

您将在下面找到一些使用此表示法的示例。

示例应用程序

使用自定义列输出格式的可能性是无穷无尽的，因为您可以在输出中显示资源的任何字段或字段组合。以下是一些示例应用程序，但您可以自己探索并找到对您有用的应用程序！

提示：如果您经常使用其中一个命令，则可以为其创建shell别名。

显示Pods的容器镜像

$kubectl get pods \
  -o custom-columns='NAME:metadata.name,IMAGES:spec.containers[*].image'
NAME                       IMAGES
engine-544b6b6467-22qr6    rabbitmq:3.7.8-management,nginx
engine-544b6b6467-lw5t8    rabbitmq:3.7.8-management,nginx
engine-544b6b6467-tvgmg    rabbitmq:3.7.8-management,nginx
web-ui-6db964458-8pdw4     wordpress

此命令显示每个Pod的所有容器镜像的名称。

请记住，Pod可能包含多个容器。在这种情况下，单个Pod的容器镜像在同一列中显示为逗号分隔列表。

显示节点的可用区域

$kubectl get nodes \
  -o custom-columns='NAME:metadata.name,ZONE:metadata.labels.failure-domain\.beta\.kubernetes\.io/zone'
NAME                          ZONE
ip-10-0-118-34.ec2.internal   us-east-1b
ip-10-0-36-80.ec2.internal    us-east-1a
ip-10-0-80-67.ec2.internal    us-east-1b

如果您的Kubernetes群集部署在公共云基础架构（例如AWS，Azure或GCP）上，则此命令非常有用。它显示每个节点所在的可用区域。

可用区域是云的概念，表示地理区域内的一个可复制点。

每个节点的可用区域通过特殊标签failure-domain.beta.kubernetes.io/zone获得。如果集群在公共云基础结构上运行，则会自动创建此标签，并将其值设置为节点的可用区域的名称。

标签不是Kubernetes资源规范的一部分，因此您无法在API参考中找到上述标签。但是，如果将节点输出为YAML或JSON，则可以看到它（以及所有其他标签）：

$kubectl get nodes -o yaml
# or
$kubectl get nodes -o json

除了探索资源规范之外，这通常是发现有关资源的更多信息的好方法。

我的网课“Kubernetes实战：高可用集群搭建、配置、运维与应用”在慕课网上线了，感谢小伙伴们学习支持！

我的联系方式：

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

微信赞赏：

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

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