ghcr.io/k8snetworkplumbingwg/whereabouts:v0.9.1

whereabouts

一种集群范围的IP地址管理（IPAM）CNI插件，用于分配IP地址。

如果您需要一种在集群中动态分配IP地址的方法，Whereabouts正是您所需的工具。如果您喜欢host-local CNI插件的工作方式，但需要一种能在集群所有节点上工作的工具（host-local仅能为同一节点上的Pod分配IP）——Whereabouts正是您要找的。

host-localWhereabouts可用于IPv4和IPv6地址分配。

Introduction

CNI（容器网络接口）插件通常有一个名为ipam的配置元素。CNI IPAM插件可分配IP地址，而Whereabouts在一个范围内分配IP地址，无需使用DHCP服务器。

ipamWhereabouts采用CIDR表示法的地址范围（如192.168.2.0/24），并在该范围内分配IP地址。在这种情况下，它将分配192.168.2.1至192.168.2.254之间的IP地址。当IP地址分配给Pod后，Whereabouts会在数据存储中跟踪该IP地址，直至Pod生命周期结束。当Pod被删除时，Whereabouts会释放该地址，使其可用于后续请求分配。Whereabouts始终分配范围内可用的最低值地址。

192.168.2.0/24``192.168.2.1``192.168.2.254您还可以指定要排除在分配之外的范围，例如，如果您希望在192.168.2.0/24范围内分配IP地址，可以通过将某些地址添加到排除列表来排除其中的IP地址。例如，如果您决定排除192.168.2.0/28范围，则该范围内分配的第一个IP地址将是192.168.2.16。

192.168.2.0/24``192.168.2.0/28``192.168.2.16考虑到某些旧设备认为以.0结尾的IP地址无效，Whereabouts不会分配以.0结尾的地址。

.0``.0Whereabouts的最初灵感来源于用户尝试使用Multus CNI（一种为Pod附加多个网络接口的CNI插件）示例时的场景，这些示例使用host-local插件，用户发现它……几乎是理想的工具。有时人们甚至假设它能跨节点工作，结果却导致IP地址冲突。

host-localWhereabouts专为Kubernetes设计，但不仅限于在Kubernetes中使用。

为了跟踪节点之间正在使用的IP地址，Whereabouts使用etcd或Kubernetes自定义资源作为后端。我们的目标是使Whereabouts更加灵活，并支持更多存储后端，欢迎为此目标做出任何贡献。

欢迎提交问题和PR！README底部列出了一些已知限制。

Installation

安装Whereabouts分为两个步骤：

• 安装Whereabouts本身（它只是磁盘上的一个二进制文件）。
• 创建IPAM CNI配置。

更多安装选项（包括etcd使用）和配置参数可在扩展配置文档中找到。

Installing Whereabouts.

您可以通过DaemonSet安装此插件，命令如下：

git clone https://github.com/k8snetworkplumbingwg/whereabouts && cd whereabouts
kubectl apply \
-f doc/crds/daemonset-install.yaml \
-f doc/crds/whereabouts.cni.cncf.io_ippools.yaml \
-f doc/crds/whereabouts.cni.cncf.io_overlappingrangeipreservations.yaml

DaemonSet安装要求Kubernetes版本1.16或更高。

Installing with helm 3

您也可以使用helm 3安装Whereabouts：

helm template whereabouts oci://ghcr.io/k8snetworkplumbingwg/whereabouts-chart --version

Helm将安装CRD和DaemonSet。

Example IPAM Config

这里包含完整的CNI配置。Whereabouts仅关注CNI配置中的ipam部分。本示例特别使用macvlan CNI插件。（如果您决定复制此块并尝试使用，请确保master设置为节点上存在的网络接口名称。）通常，您的集群中已有现有CNI插件的CNI配置，只需复制ipam部分并修改其中的值即可。

ipam``macvlan``master``ipam

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"range": "192.168.2.225/28",
"exclude": [
"192.168.2.229/30",
"192.168.2.236/32"
]
}
}

An example configuration using a NetworkAttachmentDefinition

NetworkAttachmentDefinitionWhereabouts在为Kubernetes使用额外网络接口的场景中特别有用。NetworkAttachmentDefinition自定义资源可与Multus CNI等CNI元插件一起使用，为Kubernetes中的Pod附加多个接口。

NetworkAttachmentDefinition简而言之，NetworkAttachmentDefinition包含打包为自定义资源的CNI配置。以下是包含使用Whereabouts进行IPAM的CNI配置的NetworkAttachmentDefinition示例：

NetworkAttachmentDefinition``NetworkAttachmentDefinition

apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: whereabouts-conf
spec:
config: '{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"range": "192.168.2.225/28"
}
}'

Example IPv6 Config

IPv6的使用方式相同：

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"range": "2001::0/116",
"gateway": "2001::f:1"
}
}

Example IPAM config for assigning multiple IP addresses

ipRanges字段可用于提供一系列范围配置，以分配多个IP地址。

ipRanges

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"ipRanges": [{
"range": "192.168.10.1/24"
}, {
"range": "176.168.10.1/16"
}]
}
}

上述配置也可与基本range字段结合使用，如下所示：

range

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"ipRanges": [{
"range": "192.168.10.1/24"
}, {
"range": "176.168.10.1/16"
}],
"range": "abcd::1/64"
}
}

Example DualStack config

与上述类似，ipRanges可用于配置双栈（DualStack）：

ipRanges

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"ipRanges": [{
"range": "192.168.10.1/24"
}, {
"range": "abcd::1/64"
}]
}
}

Fast IPAM by Using Preallocated Node Slices [Experimental]

通过基于节点的IP切片减少IP分配竞争，提升大规模Kubernetes环境中的IPAM性能。

核心参数

必填参数

以下参数为必填项：

• type：应设置为whereabouts。
  type 必须设置为 whereabouts。

• range：指定将分配IP地址的范围。
  range 例如，如果范围设置为192.168.2.225/28，将在该范围内分配IP地址（不包括第一个网络地址和最后一个广播地址）。

[!NOTE] 如果需要工具计算给定CIDR地址的范围，可尝试在线工具subnet-calculator.com或IPv6子网计算器。

范围结束语法

此外，range参数支持包含最后使用IP的CIDR表示法。例如：range: "192.168.2.225-192.168.2.230/28"。

可选参数

以下参数为可选项：

• range_start：从范围分配时使用的第一个IP。可选，如果未设置则从range推断。

• range_end：从范围分配时使用的最后一个IP。可选，如果未设置则确定范围内的最后一个IP。

• exclude：要排除分配的CIDR列表。
  exclude 在示例中，我们排除范围192.168.2.229/30中的IP地址被分配（在这种情况下是3个地址：.229、.230、.231），以及192.168.2.236/32（仅单个地址）。

[!NOTE] 注意1：您需要正确设置子网内的排除范围，系统不会为您进行双重检查（除了验证CIDR表示法是否可解析）。

[!NOTE] 注意2：对于大IPv6 CIDR（range≤/64），仅第一个/65范围可寻址（例如从x:x:x:x::0到x:x:x:x:7fff:ffff:ffff:ffff）。

此外，您可以使用静态IPAM插件配置中的任何内容来设置路由、网关和DNS（以及其他静态IP地址）。

示例双栈配置

与上述类似，ipRanges可用于配置双栈

{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"ipRanges": [{
"range": "192.168.10.1/24"
}, {
"range": "abcd::1/64"
}]
}
}

使用预分配节点切片的快速IPAM [实验性]

通过基于节点的IP切片减少IP分配竞争，增强大规模Kubernetes环境中的IPAM性能。

快速IPAM配置

apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: whereabouts-fast-ipam
spec:
config: '{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"range": "192.168.2.0/24",
"node_slice_size": "/22"
}
}'

此设置启用快速IPAM功能以优化节点的IP分配，提高高Pod密度集群中的网络性能。 请注意，要使其工作，您必须运行whereabouts控制器。清单可在doc/crds/node-slice-controller.yaml中找到。 您必须在与network-attachment-definitions相同的命名空间中运行whereabouts守护进程集和whereabouts控制器。 示例中的node_slice_size字段决定了每个节点分配的CIDR大小，该字段的存在会触发Fast IPAM模式。

核心参数

必填参数

以下参数为必填项：

• type：应设置为whereabouts。
• range：指定将分配IP地址的范围。

例如，如果range设置为192.168.2.225/28，则将在该范围内分配IP地址，不包括第一个网络地址和最后一个广播地址。

如果您需要工具来计算给定CIDR地址的范围，可尝试在线工具subnet-calculator.com或IPv6子网计算器。

范围结束语法

此外，range参数支持包含最后使用IP的CIDR表示法。例如：range: "192.168.2.225-192.168.2.230/28"。

可选参数

以下参数为可选项：

• range_start：从range分配时使用的第一个IP。可选，若未设置则从range推断。
• range_end：从range分配时使用的最后一个IP。可选，若未设置则确定范围内的最后一个IP。
• exclude：要排除在分配之外的CIDR列表。

在示例中，我们排除范围192.168.2.229/30内的IP地址（此处包含3个地址：.229、.230、.231）以及192.168.2.236/32（单个地址）。

[!NOTE] 1：您需要自行正确设置子网内的排除范围，系统不会为您进行双重检查（除了解析CIDR表示法外）。 [!NOTE] 2：对于宽IPv6 CIDR（range≤/64），仅第一个/65范围可寻址（例如从x:x:x:x::0到x:x:x:x:7fff:ffff:ffff:ffff）。

此外，您可以使用https://github.com/containernetworking/plugins/tree/master/plugins/ipam/static%E9%85%8D%E7%BD%AE%E4%B8%AD%E7%9A%84%E4%BB%BB%E4%BD%95%E5%86%85%E5%AE%B9%E6%9D%A5%E8%AE%BE%E7%BD%AE%E8%B7%AF%E7%94%B1%E3%80%81%E7%BD%91%E5%85%B3%E5%92%8CDNS%EF%BC%88%E4%BB%A5%E5%8F%8A%E5%85%B6%E4%BB%96%E9%9D%99%E6%80%81IP%E5%9C%B0%E5%9D%80%EF%BC%89%E3%80%82

重叠范围

重叠范围功能默认启用，不允许IP地址在两个重叠的不同范围之间重新分配。但此功能可禁用。

• enable_overlapping_ranges：（布尔值）分配前检查IP是否已在另一个范围内分配（默认值为true）。

请注意：此功能仅在Kubernetes存储后端实现。

网络名称

默认情况下，无法两次配置相同的CIDR范围并让whereabouts独立从这些范围分配IP。但在多租户场景中，当多个组负责选择CIDR范围时，此功能非常有用。

通过使用参数network_name（字符串），管理员可以让whereabouts对相同的CIDR范围多次分配IP地址。

参数enable_overlapping_ranges（见上文）按网络名称作用域。

(...)
"network_name": "network-with-independent-allocation",
"enable_overlapping_ranges": true,
(...)

构建

从./hack目录运行构建命令：

./hack/build-go.sh

在本地kind集群中运行whereabouts CNI

您可以启动kind集群以运行本地更改：

make kind
# 或 make kind COMPUTE_NODES=

然后可以创建NetworkAttachmentDefinition：

cat <<'EOF' | kubectl apply -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: whereabouts-conf
spec:
config: '{
"cniVersion": "0.3.0",
"name": "whereaboutsexample",
"type": "macvlan",
"master": "eth0",
"mode": "bridge",
"ipam": {
"type": "whereabouts",
"range": "192.168.2.225/28"
}
}'
EOF

创建使用NetworkAttachmentDefinition的部署，例如：

cat <<'EOF' | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
name: netshoot-deployment
labels:
app: netshoot-deployment
spec:
replicas: 1
selector:
matchLabels:
app: netshoot-pod
template:
metadata:
annotations:
k8s.v1.cni.cncf.io/networks: whereabouts-conf
labels:
app: netshoot-pod
spec:
containers:
- name: netshoot
image: nicolaka/netshoot
command:
- sleep
- "3600"
imagePullPolicy: IfNotPresent
EOF

致谢

徽标中使用的字体是AZONIX，由MixoFX设计。

已知限制

• 节点上的系统崩溃可能会留下孤立的IP分配，因此如果系统不稳定，可能会耗尽IP。

• 可能需要一个操作员来确保数据干净，即使只是在某个时间间隔（例如通过 cron 作业）

• 可能有很多IP地址比较可以优化，存在大量字符串转换。
• etcd方法有一些限制，它使用全ASCII方法。如果采用二进制方式，可能可以存储更多数据并实现更高效的IP地址比较。
• 在加拿大可能无法使用，显然要让加拿大人能操作，得叫“where aboots?”。
• 对于宽IPv6 CIDR（range≤/64），由于uint64偏移计算，Whereabouts仅可寻址第一个/65范围。