# 插件系统

## 概述

SPIRE 的功能主要通过插件提供。插件系统允许自定义和扩展 SPIRE 的行为。

## 插件架构

```{mermaid}
flowchart TB
    subgraph "SPIRE Server/Agent"
        Catalog[插件目录]
        Loader[插件加载器]
    end
    
    subgraph "内置插件"
        B1[DataStore]
        B2[NodeAttestor]
        B3[KeyManager]
    end
    
    subgraph "外部插件"
        E1[自定义插件]
    end
    
    Catalog --> Loader
    Loader --> B1
    Loader --> B2
    Loader --> B3
    Loader -.->|gRPC| E1
```

## Server 插件

### DataStore

存储注册条目、已证明节点和信任包。

| 插件 | 描述 |
|------|------|
| `sql` | SQL 数据库（PostgreSQL, MySQL, SQLite）|

**配置示例：**

```hcl
plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "postgres"
            connection_string = "host=localhost dbname=spire"
        }
    }
}
```

### KeyManager

管理 Server 的签名密钥。

| 插件 | 描述 |
|------|------|
| `disk` | 磁盘存储 |
| `memory` | 内存存储（不持久化）|
| `aws_kms` | AWS KMS |
| `gcp_kms` | GCP Cloud KMS |

### NodeAttestor

验证 Agent 的身份。

| 插件 | 描述 |
|------|------|
| `aws_iid` | AWS 实例身份文档 |
| `azure_msi` | Azure 托管服务身份 |
| `gcp_iit` | GCP 实例身份令牌 |
| `k8s_psat` | Kubernetes PSAT |
| `k8s_sat` | Kubernetes SAT |
| `join_token` | 一次性令牌 |
| `x509pop` | X.509 证书持有证明 |

### UpstreamAuthority

与上游 PKI 集成。

| 插件 | 描述 |
|------|------|
| `disk` | 磁盘上的 CA 证书 |
| `aws_pca` | AWS Private CA |
| `vault` | HashiCorp Vault |
| `spire` | 嵌套 SPIRE |
| `cert-manager` | Kubernetes cert-manager |

### BundlePublisher

发布信任包到外部系统。

| 插件 | 描述 |
|------|------|
| `aws_s3` | AWS S3 |
| `gcp_cloudstorage` | GCP Cloud Storage |

### Notifier

事件通知。

| 插件 | 描述 |
|------|------|
| `k8sbundle` | Kubernetes ConfigMap/Secret |

## Agent 插件

### KeyManager

管理 Agent 的密钥。

| 插件 | 描述 |
|------|------|
| `disk` | 磁盘存储 |
| `memory` | 内存存储 |

### NodeAttestor

生成节点证明数据。

| 插件 | 描述 |
|------|------|
| `aws_iid` | AWS 实例身份文档 |
| `azure_msi` | Azure MSI |
| `gcp_iit` | GCP IIT |
| `k8s_psat` | Kubernetes PSAT |
| `k8s_sat` | Kubernetes SAT |
| `join_token` | 一次性令牌 |
| `x509pop` | X.509 POP |
| `sshpop` | SSH 证书 POP |

### WorkloadAttestor

识别工作负载。

| 插件 | 描述 |
|------|------|
| `unix` | Unix 进程属性 |
| `k8s` | Kubernetes Pod 属性 |
| `docker` | Docker 容器属性 |
| `systemd` | Systemd 单元属性 |

**选择器示例：**

```
# Unix
unix:uid:1000
unix:gid:1000
unix:user:appuser

# Kubernetes
k8s:ns:default
k8s:sa:myapp
k8s:pod-label:app:web

# Docker
docker:label:com.example.app:web
docker:image_id:sha256:abc123
```

### SVIDStore

将 SVID 存储到外部系统。

| 插件 | 描述 |
|------|------|
| `aws_secretsmanager` | AWS Secrets Manager |
| `gcp_secretmanager` | GCP Secret Manager |

## 插件配置

### 基本结构

```hcl
plugins {
    <类型> "<名称>" {
        plugin_cmd = "/path/to/plugin"  # 外部插件
        plugin_checksum = "sha256:..."  # 可选校验和
        plugin_data {
            # 插件特定配置
        }
    }
}
```

### 多实例配置

```hcl
plugins {
    NodeAttestor "k8s_psat" {
        plugin_data {
            clusters = {
                "cluster1" = {
                    service_account_allow_list = ["spire:spire-agent"]
                }
            }
        }
    }
    
    NodeAttestor "join_token" {
        # 同时启用 join_token
    }
}
```

## 开发自定义插件

### gRPC 接口

每种插件类型都定义了 gRPC 接口：

```protobuf
service NodeAttestor {
    rpc AidAttestation(stream AidAttestationRequest) 
        returns (stream AidAttestationResponse);
}
```

### 插件开发步骤

1. 实现对应的 gRPC 接口
2. 编译为独立可执行文件
3. 在配置中指定 `plugin_cmd`
4. 可选：添加 `plugin_checksum` 校验

### 示例框架

```go
package main

import (
    "github.com/spiffe/spire-plugin-sdk/pluginmain"
    nodeattestorv1 "github.com/spiffe/spire-plugin-sdk/proto/spire/plugin/agent/nodeattestor/v1"
)

type MyAttestor struct {
    nodeattestorv1.UnimplementedNodeAttestorServer
}

func main() {
    pluginmain.Serve(
        nodeattestorv1.NodeAttestorPluginServer(&MyAttestor{}),
    )
}
```

## 最佳实践

:::{admonition} 插件配置建议
:class: tip

1. **生产环境使用持久化 KeyManager**: 避免使用 `memory`
2. **启用多种 NodeAttestor**: 提供备用证明方式
3. **验证插件校验和**: 确保插件完整性
4. **监控插件健康状态**: 设置告警
:::