K8s Operator中序列化Authentik蓝图时保留自定义YAML标签方案咨询

针对你遇到的authentik blueprint序列化/反序列化到K8s CRD的问题，核心解决思路是用go-yaml v3的yaml.Node保留原始YAML结构和自定义标签，同时手动实现controller-runtime要求的DeepCopy方法，具体步骤如下：

1. 用yaml.Node定义结构多变的字段 #

在CRD结构体中，把.entries.attrs这类结构不确定的字段定义为yaml.Node类型，这样能完整保留原始YAML的所有信息（包括自定义标签、注释、层级结构）。

示例结构体：

import (
    "gopkg.in/yaml.v3"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// AuthentikBlueprintSpec defines the desired state of AuthentikBlueprint
type AuthentikBlueprintSpec struct {
    Entries []BlueprintEntry `json:"entries" yaml:"entries"`
    // 其他固定字段...
}

// BlueprintEntry represents a single entry in the authentik blueprint
type BlueprintEntry struct {
    ID   string    `json:"id" yaml:"id"`
    Type string    `json:"type" yaml:"type"`
    // 用yaml.Node存储结构多变的attrs字段，保留自定义标签
    // +kubebuilder:validation:Schemaless
    // +kubebuilder:pruning:PreserveUnknownFields
    Attrs yaml.Node `json:"attrs" yaml:"attrs"`
    // 其他固定字段...
}

// AuthentikBlueprint is the Schema for the authentikblueprints API
type AuthentikBlueprint struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`

    Spec   AuthentikBlueprintSpec   `json:"spec,omitempty"`
    Status AuthentikBlueprintStatus `json:"status,omitempty"`
}

// AuthentikBlueprintList contains a list of AuthentikBlueprint
type AuthentikBlueprintList struct {
    metav1.TypeMeta `json:",inline"`
    metav1.ListMeta `json:"metadata,omitempty"`
    Items           []AuthentikBlueprint `json:"items"`
}

2. 手动实现DeepCopy方法 #

controller-gen无法为yaml.Node自动生成正确的DeepCopy逻辑，需要手动为包含yaml.Node的结构体实现DeepCopyInto和DeepCopy方法：

// DeepCopyInto implements deepcopy logic for BlueprintEntry
func (in *BlueprintEntry) DeepCopyInto(out *BlueprintEntry) {
    *out = *in
    // 通过序列化+反序列化完成yaml.Node的深拷贝，避免浅拷贝导致的并发问题
    buf, _ := yaml.Marshal(in.Attrs)
    _ = yaml.Unmarshal(buf, &out.Attrs)
    // 其他引用类型字段（如切片、指针）也需手动处理深拷贝
}

// DeepCopy implements deepcopy for BlueprintEntry
func (in *BlueprintEntry) DeepCopy() *BlueprintEntry {
    if in == nil {
        return nil
    }
    out := new(BlueprintEntry)
    in.DeepCopyInto(out)
    return out
}

// 为AuthentikBlueprintSpec、AuthentikBlueprint等上层结构体实现对应的DeepCopy方法
// 注意：给包含yaml.Node的结构体加上// +kubebuilder:skip注解，避免controller-gen自动生成的代码覆盖手动实现

3. 用go-yaml v3处理序列化/反序列化 #

在Operator逻辑中，全程用go-yaml v3处理蓝图相关的序列化/反序列化，确保!KeyOf、!Find这类自定义标签不丢失：

// 从CRD Spec序列化回原始Blueprint YAML
func SerializeBlueprint(spec AuthentikBlueprintSpec) ([]byte, error) {
    return yaml.Marshal(spec)
}

// 从原始Blueprint YAML反序列化为CRD Spec
func DeserializeBlueprint(data []byte) (AuthentikBlueprintSpec, error) {
    var spec AuthentikBlueprintSpec
    err := yaml.Unmarshal(data, &spec)
    return spec, err
}

关键注意事项 #

• 禁止混用encoding/json和go-yaml v3：JSON序列化会丢失YAML自定义标签、注释等信息，所有蓝图相关的序列化操作都要用go-yaml v3。
• 手动实现DeepCopy时要覆盖所有引用类型字段，避免浅拷贝引发的资源竞争或数据不一致问题。
• CRD字段上的// +kubebuilder:validation:Schemaless和// +kubebuilder:pruning:PreserveUnknownFields注解必须加，让K8s API服务器接受任意结构的YAML数据。

内容的提问来源于stack exchange，提问作者GeorgeRaven