ghcr.io/k8snetworkplumbingwg/whereabouts:v0.9.4

whereabouts

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

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

Whereabouts 可用于 IPv4 和 IPv6 地址分配。

Introduction

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

Whereabouts 采用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范围内分配IP地址，可以通过将某些范围添加到排除列表来排除其中的IP地址。例如，如果您决定排除192.168.2.0/28范围，则该范围内分配的第一个IP地址将是192.168.2.16。

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

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

Whereabouts的设计考虑了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 \
-f doc/crds/reconciler-deployment.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。

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

Fast 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密度集群中的网络性能。> [!NOTE] 请注意，要使此功能正常工作，必须运行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：从范围分配时使用的第一个IP。可选，若未设置则从range中推断。
• range_end：从范围分配时使用的最后一个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）。

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

重叠范围

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

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

[!NOTE] 请注意：此功能仅针对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

Helm将安装CRD和守护进程集。

IPAM配置示例

此处包含完整的CNI配置。Whereabouts仅关注CNI配置中的ipam部分。本示例特别使用了macvlan CNI插件。（如果您决定复制此块并尝试使用，请确保master设置为节点上存在的网络接口名称）。通常，集群中已有现有CNI插件的CNI配置，您只需复制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"
]
}
}

使用NetworkAttachmentDefinition的示例配置

在为Kubernetes使用额外网络接口的场景中，Whereabouts特别有用。NetworkAttachmentDefinition自定义资源可与CNI元插件（如https://github.com/intel/multus-cni%EF%BC%89%E9%85%8D%E5%90%88%E4%BD%BF%E7%94%A8%EF%BC%8C%E4%B8%BAKubernetes%E4%B8%AD%E7%9A%84Pod%E9%99%84%E5%8A%A0%E5%A4%9A%E4%B8%AA%E6%8E%A5%E5%8F%A3%E3%80%82

简而言之，NetworkAttachmentDefinition包含打包为自定义资源的CNI配置。以下是包含使用Whereabouts进行IPAM的CNI配置的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"
}
}'

IPv6配置示例

IPv6的使用方式相同：

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

分配多个IP地址的IPAM配置示例

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

{
"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字段结合使用，如下所示：

双栈（DualStack）配置示例

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

{
"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密度集群中的网络性能。

[!NOTE] 请注意，要使此功能正常工作，必须运行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前检查该IP是否已在另一个范围内分配（默认值为true）。

[!NOTE] 请注意：此功能仅针对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范围。