crossplane/xfn

crossplane-function-runner 镜像文档

1. 镜像概述和主要用途

1.1 概述

crossplane-function-runner 是一个用于 Crossplane 的参考 Composition Function 运行器镜像，旨在为 Kubernetes 集群中的 Crossplane 控制平面提供标准化的 Composition Function 执行环境。该镜像作为 Crossplane 合成逻辑扩展的基础组件，负责加载、执行用户定义的 Composition Function，并与 Crossplane API 进行交互，实现自定义资源合成逻辑的落地。

1.2 主要用途

• 作为 Crossplane Composition Function 的运行时载体，执行用户编写的自定义合成逻辑（如资源生成、策略校验、动态配置调整等）
• 桥接 Crossplane 控制平面与外部函数逻辑，标准化函数输入输出格式
• 提供轻量级、可配置的运行环境，支持多种类型的 Composition Function（如 Go 编译函数、WebAssembly 模块等）

2. 核心功能和特性

2.1 核心功能

• Crossplane API 原生集成：遵循 Crossplane Composition Function 规范（v1beta1），支持与 Crossplane 控制平面的双向通信，包括函数输入（FunctionIO）接收与输出响应
• 多函数类型支持：兼容 Crossplane 标准函数类型，包括：
  • 编译型函数（如 Go 语言实现的二进制函数）
  • WebAssembly (Wasm) 函数模块
  • 外部 HTTP 函数（通过网络调用外部服务）
• 轻量级运行时：基于 Alpine 基础镜像构建，资源占用低（默认内存 < 50MB，CPU < 100m），适合 Kubernetes 环境部署
• 可观测性配置：支持分级日志（DEBUG/INFO/WARN/ERROR）、结构化日志输出，以及调试模式开关
• 灵活的函数加载：支持本地目录挂载、远程 HTTP 拉取、ConfigMap/Secret 注入等多种函数加载方式

3. 使用场景和适用范围

3.1 典型使用场景

• Crossplane 合成逻辑扩展：当 Crossplane 内置合成逻辑无法满足需求时，通过自定义 Composition Function 实现资源生成、修改或校验（如动态调整资源规格、添加强制标签）
• 多云资源策略实施：在跨云厂商（AWS/Azure/GCP）资源管理中，通过函数统一实施策略（如根据云厂商类型自动配置网络 ACL、存储加密）
• 企业级资源规范落地：强制资源命名规范、成本中心标签、合规性校验（如 PCI-DSS 环境禁止公网暴露）
• 开发测试环境快速迭代：本地或 CI 环境中测试 Composition Function 逻辑，无需完整部署 Crossplane 控制平面

4. 使用方法和配置说明

4.1 前置条件

• 运行环境：Kubernetes 集群（v1.24+）或 Docker 环境（v20.10+）
• 依赖：Crossplane 控制平面（v1.12+）已部署，且可通过网络访问其 API（crossplane-api 服务或外部暴露地址）
• 函数代码：需准备符合 Crossplane Composition Function 规范的函数代码（如编译后的二进制文件、Wasm 模块）

4.2 基础使用流程

4.2.1 拉取镜像

bash
docker pull docker.xuanyuan.run/crossplane-function-runner:latest  # 或指定版本，如 v0.1.0

4.2.2 本地 Docker 运行

通过 docker run 启动运行器，挂载函数代码目录并配置 Crossplane API 地址：

bash
docker run -d \
  --name crossplane-function-runner \
  -v /path/to/local/functions:/functions  # 挂载本地函数目录（含函数二进制/Wasm模块） \
  -e CROSSPLANE_API_URL=https://crossplane-api.default.svc.cluster.local:443 \  # Crossplane API 地址（必填） \
  -e LOG_LEVEL=info \  # 日志级别（默认 info） \
  -e FUNCTIONS_DIR=/functions \  # 函数代码存放目录（默认 /functions） \
  -p 8080:8080 \  # 暴露运行器监听端口（默认 8080） \
  crossplane-function-runner:latest

4.3 Kubernetes 环境部署（通过 Deployment）

在 Kubernetes 集群中部署时，建议通过 Deployment 管理，并挂载包含函数代码的 ConfigMap/Secret：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: crossplane-function-runner
  namespace: crossplane-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: function-runner
  template:
    metadata:
      labels:
        app: function-runner
    spec:
      containers:
      - name: runner
        image: docker.xuanyuan.run/crossplane-function-runner:latest
        args: ["--log-level", "info"]
        ports:
        - containerPort: 8080
        env:
        - name: CROSSPLANE_API_URL
          value: "https://crossplane-api.crossplane-system.svc.cluster.local:443"  # Crossplane API 内部服务地址
        - name: LOG_LEVEL
          value: "info"
        - name: FUNCTIONS_DIR
          value: "/functions"
        volumeMounts:
        - name: functions-volume
          mountPath: /functions  # 挂载函数代码目录
      volumes:
      - name: functions-volume
        configMap:
          name: crossplane-functions  # 包含函数代码的 ConfigMap（需提前创建）

4.4 函数加载方式

运行器支持以下函数加载方式，通过 FUNCTION_LOAD_MODE 环境变量指定（默认 local）：

• local：加载本地目录（FUNCTIONS_DIR）中的函数文件（二进制/Wasm）
• http：从远程 HTTP 服务拉取函数（需配置 FUNCTION_HTTP_URL 环境变量）
• secret：从 Kubernetes Secret 中加载（需挂载 Secret 到 FUNCTIONS_DIR）

5. 配置参数

5.1 命令行参数

5.2 环境变量

6. 部署示例（docker-compose）

通过 docker-compose 快速搭建本地测试环境（含 Crossplane 控制平面模拟，实际场景需对接真实 Crossplane）：

yaml
version: "3.8"
services:
  function-runner:
    image: docker.xuanyuan.run/crossplane-function-runner:latest
    container_name: crossplane-function-runner
    ports:
      - "8080:8080"
    volumes:
      - ./local-functions:/functions  # 本地函数代码目录（存放 test-function.wasm 或二进制）
    environment:
      - CROSSPLANE_API_URL=https://crossplane-api:443  # 对接模拟的 Crossplane API 服务
      - LOG_LEVEL=debug  # 开启调试日志
      - DEBUG_MODE=true
      - FUNCTION_LOAD_MODE=local
    depends_on:
      - crossplane-api-mock  # 模拟 Crossplane API 的服务（实际环境移除）

  crossplane-api-mock:
    image: docker.xuanyuan.run/nginx:alpine  # 仅用于模拟 API 服务，实际环境替换为真实 Crossplane API
    container_name: crossplane-api-mock
    ports:
      - "443:443"
    volumes:
      - ./mock-api-cert:/etc/nginx/certs  # 模拟 HTTPS 证书
      - ./mock-api-config:/etc/nginx/conf.d  # 模拟 API 响应配置

7. 注意事项

• 函数代码需符合 Crossplane Composition Function 规范（参考 https://docs.crossplane.io/latest/concepts/composition-functions/）
• 生产环境中建议通过 Kubernetes Deployment 部署，并启用健康检查（livenessProbe/readinessProbe，检查 http://localhost:8080/health 端点）
• 函数代码更新后需重启运行器或通过 FUNCTION_LOAD_MODE=http 动态拉取（需函数支持热加载）