Calico API：Kubernetes容器网络与安全的核心API定义库

原创

qife122

发布于 2026-02-08 17:44:09

930

🐾 Calico API

Calico API是Project Calico项目的权威源代码，包含了该项目的API定义。它为Kubernetes容器网络和安全策略提供了一套标准化的类型定义和客户端工具，使开发者能够方便地构建、管理和自动化Calico网络和安全策略。

🌟 功能特性

丰富的API类型：包含BGPConfiguration、BGPFilter、BGPPeer、GlobalNetworkPolicy、NetworkPolicy、IPPool、IPReservation、Tier等核心资源类型，覆盖网络配置、安全策略、IP地址管理等各个方面。
自动生成的客户端：提供自动生成的Go语言客户端（clientset）、listers和informers，支持Kubernetes风格的资源操作（Create、Update、Delete、Get、List、Watch、Patch）和事件监听。
多架构支持：构建系统支持跨平台编译（如amd64, arm64, s390x等），可生成针对不同CPU架构的二进制文件和Docker镜像。
开发者友好：包含完整的开发者指南，详细说明了如何设置开发环境、构建代码、运行测试以及贡献代码的流程。
安全策略支持：定义了精细的网络策略规则（Rule），支持基于标签选择器、命名空间、服务账户、CIDR、端口和协议等多维度的流量控制。
BGP网络集成：提供了完整的BGP配置API，支持节点对等、路由过滤和BGP策略管理，便于集成到现有网络基础设施中。
分阶段策略（Staged Policy）：支持StagedGlobalNetworkPolicy、StagedNetworkPolicy等资源，允许策略分阶段部署和验证，提高变更安全性。
分层安全模型（Tier）：通过Tier资源实现安全策略的分层管理，允许管理员定义策略的应用顺序和默认行为。

🛠️ 安装指南

前提条件

Linux构建环境
Docker
Git
Make

构建Calico API

克隆仓库git clone https://github.com/projectcalico/api.git cd api
构建所有组件make image此命令将生成多个容器镜像。要进行干净的构建，可使用：make clean image
为特定架构构建make image ARCH=arm64
更新生成的代码（在添加新的API类型后）make build此命令会重新生成客户端、listers、informers等代码。

📖 使用说明

导入客户端

你可以直接导入生成的客户端库来操作Calico API资源。

import (
    "context"
    "fmt"
    calicoclientset "github.com/projectcalico/api/pkg/client/clientset_generated/clientset"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/tools/clientcmd"
)

func main() {
    // 加载kubeconfig
    config, err := clientcmd.BuildConfigFromFlags("", "/path/to/kubeconfig")
    if err != nil {
        panic(err)
    }
    
    // 创建Calico客户端
    clientset, err := calicoclientset.NewForConfig(config)
    if err != nil {
        panic(err)
    }
    
    // 示例：列出所有GlobalNetworkPolicy
    policies, err := clientset.ProjectcalicoV3().GlobalNetworkPolicies().List(context.TODO(), metav1.ListOptions{})
    if err != nil {
        panic(err)
    }
    
    for _, policy := range policies.Items {
        fmt.Printf("Policy: %s\n", policy.Name)
    }
}

定义自定义资源示例

以下是一个GlobalNetworkPolicy的YAML示例，展示了如何定义一条允许特定命名空间内Pod间通信的入口规则。

apiVersion: projectcalico.org/v3
kind: GlobalNetworkPolicy
metadata:
  name: allow-frontend-to-backend
spec:
  tier: "default"
  order: 100
  selector: app == 'backend'
  ingress:
    - action: Allow
      source:
        selector: app == 'frontend'
        namespaceSelector: name == 'production'
      protocol: TCP
      destination:
        ports: [6379]
  egress:
    - action: Allow

使用Informers监听资源变化

import (
    informers "github.com/projectcalico/api/pkg/client/informers_generated/externalversions"
    "k8s.io/apimachinery/pkg/util/wait"
    "k8s.io/client-go/tools/cache"
)

// 创建SharedInformerFactory
factory := informers.NewSharedInformerFactory(clientset, time.Minute*5)

// 获取特定资源的Informer
policyInformer := factory.Projectcalico().V3().GlobalNetworkPolicies().Informer()

// 添加事件处理函数
policyInformer.AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc: func(obj interface{}) {
        fmt.Printf("Policy added: %s\n", obj.(*v3.GlobalNetworkPolicy).Name)
    },
    UpdateFunc: func(oldObj, newObj interface{}) {
        fmt.Printf("Policy updated: %s\n", newObj.(*v3.GlobalNetworkPolicy).Name)
    },
    DeleteFunc: func(obj interface{}) {
        fmt.Printf("Policy deleted: %s\n", obj.(*v3.GlobalNetworkPolicy).Name)
    },
})

// 启动Informer
factory.Start(wait.NeverStop)
factory.WaitForCacheSync(wait.NeverStop)

// 保持程序运行
select {}

💻 核心代码

1. BGPConfiguration API 定义 (`pkg/apis/projectcalico/v3/bgpconfiguration.go`)

此文件定义了BGP配置资源，用于全局BGP设置。

// Copyright (c) 2020-2021 Tigera, Inc. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
package v3

import (
    "github.com/projectcalico/api/pkg/lib/numorstring"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

const (
    KindBGPConfiguration     = "BGPConfiguration"
    KindBGPConfigurationList = "BGPConfigurationList"
)

type BindMode string

const (
    BindModeNone   BindMode = "None"
    BindModeNodeIP BindMode = "NodeIP"
)

// +genclient:nonNamespaced
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// BGPConfigurationList是BGPConfiguration资源的列表。
type BGPConfigurationList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    Items []BGPConfiguration `json:"items" protobuf:"bytes,2,rep,name=items"`
}

// +genclient
// +genclient:nonNamespaced
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// BGPConfiguration定义了BGP的全局配置。
type BGPConfiguration struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    Spec BGPConfigurationSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
}

// BGPConfigurationSpec包含了BGP配置的值。
type BGPConfigurationSpec struct {
    // LogSeverityScreen是发送到stdout的日志严重级别。[默认: INFO]
    LogSeverityScreen string `json:"logSeverityScreen,omitempty" validate:"omitempty,logLevel"`
    // 其他字段...
}

2. NetworkPolicy API 定义 (`pkg/apis/projectcalico/v3/networkpolicy.go`)

此文件定义了命名空间作用域的网络策略资源。

// Copyright (c) 2017-2024 Tigera, Inc. All rights reserved.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
package v3

import (
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

const (
    KindNetworkPolicy     = "NetworkPolicy"
    KindNetworkPolicyList = "NetworkPolicyList"
)

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// NetworkPolicyList是Policy对象的列表。
type NetworkPolicyList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    Items []NetworkPolicy `json:"items" protobuf:"bytes,2,rep,name=items"`
}

// +genclient
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// NetworkPolicy定义了命名空间级别的网络安全策略。
type NetworkPolicy struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    Spec NetworkPolicySpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
}

// NetworkPolicySpec包含了网络策略的规范。
type NetworkPolicySpec struct {
    // Tier指定此策略所属的层级名称。如果省略，则假定为默认层级（名称为"default"）。
    Tier string `json:"tier,omitempty" validate:"omitempty,name"`
    // Order是可选的字段，指定同一层级内策略的应用顺序。
    Order *float64 `json:"order,omitempty"`
    // Selector选择此策略应用的工作负载端点。
    Selector string `json:"selector" validate:"selector"`
    // Ingress定义入站流量规则的有序集合。
    Ingress []Rule `json:"ingress,omitempty" validate:"omitempty,dive"`
    // Egress定义出站流量规则的有序集合。
    Egress []Rule `json:"egress,omitempty" validate:"omitempty,dive"`
    // Types指定此策略适用的流量方向（Ingress, Egress, 或两者）。
    Types []PolicyType `json:"types,omitempty" validate:"omitempty,dive,policyType"`
}

3. 客户端生成脚本 (`hack/update-codegen.sh`)

此脚本用于生成客户端、listers和informers代码。

#!/bin/bash
# Copyright 2015 The Kubernetes Authors.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
set -o errexit
set -o nounset
set -o pipefail

REPO_ROOT=$(realpath $(dirname "${BASH_SOURCE}")/..)
BINDIR=${REPO_ROOT}/bin

# 生成版本化客户端 (pkg/client/clientset_generated/clientset)
client-gen "$@" \
    --go-header-file "${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt" \
    --input-base "github.com/projectcalico/api/pkg/apis/" \
    --input "projectcalico/v3" \
    --output-dir "${REPO_ROOT}/pkg/client/clientset_generated" \
    --clientset-path "github.com/projectcalico/api/pkg/client/clientset_generated/" \
    --clientset-name "clientset"

# 生成lister
lister-gen "$@" \
    --go-header-file "${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt" \
    --output-dir "${REPO_ROOT}/pkg/client/listers_generated" \
    --output-pkg "github.com/projectcalico/api/pkg/client/listers_generated" \
    "github.com/projectcalico/api/pkg/apis/projectcalico/v3"

# 生成informer
informer-gen "$@" \
    --go-header-file "${REPO_ROOT}/hack/boilerplate/boilerplate.go.txt" \
    --versioned-clientset-package "github.com/projectcalico/api/pkg/client/clientset_generated/clientset" \
    --listers-package "github.com/projectcalico/api/pkg/client/listers_generated" \
    --output-dir "${REPO_ROOT}/pkg/client/informers_generated" \
    --output-pkg "github.com/projectcalico/api/pkg/client/informers_generated" \
    "github.com/projectcalico/api/pkg/apis/projectcalico/v3"

这些核心代码展示了Calico API库的主要结构和功能，包括API类型定义、客户端代码生成以及构建系统的关键组成部分。通过使用这些API，开发者可以构建强大的网络和安全自动化工具，充分利用Calico在Kubernetes环境中的高级网络功能。FINISHED

QEHhY4oFma5gLUWjolaPoJ798aL6NOEUm82cMVLULfA=

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

kubernetes