been/provider-gitlab

Crossplanes GitLab Provider 文档

概述

Crossplanes GitLab Provider是基于Crossplanes框架构建的云服务提供商（Provider）组件，旨在将GitLab资源纳入Kubernetes控制平面。通过该Provider，用户可使用Kubernetes API以声明式方式定义、部署和管理GitLab资源（如项目、用户、组、CI/CD变量等），实现GitLab资源与Kubernetes生态的无缝集成。

核心功能与特性

核心功能

• 多类型GitLab资源支持：覆盖GitLab核心实体，包括项目（Project）、用户（User）、组（Group）、CI/CD变量（Variable）、分支保护规则（BranchProtection）等。
• 声明式配置：通过Kubernetes自定义资源（CR）定义GitLab资源期望状态，Provider自动协调实际状态与期望状态。
• 实时状态同步：持续监控GitLab API，将资源状态同步至Kubernetes CR状态字段，支持状态查询与故障排查。
• 细粒度权限控制：结合Kubernetes RBAC实现GitLab资源的权限隔离，支持多团队资源管理。

关键特性

• 版本兼容性：兼容GitLab API v4及主流GitLab版本（GitLab CE/EE 14.0+）。
• 错误自愈：当GitLab资源状态偏离期望状态时，自动触发修复逻辑。
• 可扩展架构：支持通过Crossplanes Composition构建复合资源（XR），实现GitLab资源与其他云资源的联动编排。

使用场景

适用范围

• 企业级GitLab资源标准化：统一多团队GitLab项目/组的配置规范（如可见性、权限模板、CI/CD流程）。
• GitOps工作流集成：在GitOps流水线中通过Kubernetes资源定义GitLab环境，实现"配置即代码"。
• 多云/混合云GitLab管理：跨多个GitLab实例（如自托管与GitLab.com）统一资源管理。
• 合规与审计：通过Kubernetes审计日志记录GitLab资源变更，满足合规要求。

使用方法与配置说明

前置条件

• 运行中的Kubernetes集群（v1.21+）。
• 已安装Crossplanes（v1.10+），参考Crossplanes安装文档。
• 具备GitLab API访问权限的令牌（Personal Access Token），需包含必要权限（如api、read_user、write_repository等，具体权限取决于管理的资源类型）。

部署Provider

1. 安装Provider CRD

通过Crossplanes CLI或直接应用Provider清单部署：

bash
# 使用Crossplanes CLI安装（推荐）
kubectl crossplane install provider crossplane/provider-gitlab:v0.1.0

# 或直接应用Provider YAML
kubectl apply -f - <<EOF
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-gitlab
spec:
  package: crossplane/provider-gitlab:v0.1.0
EOF

2. 验证Provider部署

确认Provider Pod运行正常：

bash
kubectl get pods -n crossplane-system | grep provider-gitlab

配置Provider

1. 创建ProviderConfig

ProviderConfig用于配置GitLab API连接信息，需包含GitLab地址及认证令牌：

yaml
apiVersion: gitlab.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  baseUrl: https://gitlab.com/api/v4  # 自托管GitLab需替换为实际地址（如https://gitlab.example.com/api/v4）
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: gitlab-creds
      key: token

2. 创建认证密钥

创建包含GitLab API令牌的Kubernetes Secret：

bash
kubectl create secret generic gitlab-creds -n crossplane-system --from-literal=token=your-gitlab-pat-token

管理GitLab资源

以管理GitLab项目为例，创建Kubernetes CR定义项目期望状态：

示例：创建GitLab项目

yaml
apiVersion: project.gitlab.crossplane.io/v1alpha1
kind: Project
metadata:
  name: demo-project
spec:
  forProvider:
    name: demo-project  # GitLab项目名称
    path: demo-project  # GitLab项目路径（URL中的路径部分）
    visibility: public  # 可见性：public/private/internal
    description: "Created via Crossplanes GitLab Provider"
    initializeWithReadme: true  # 初始化README文件
    mergeRequestsEnabled: true  # 启用合并请求
  providerConfigRef:
    name: default  # 关联前述ProviderConfig

应用上述CR后，Provider将调用GitLab API创建项目，并同步状态至CR的status.atProvider字段：

bash
kubectl get projects.project.gitlab.crossplane.io demo-project -o yaml

配置参数说明

ProviderConfig 参数

资源CR通用参数

所有GitLab资源CR均包含以下通用配置：

• spec.forProvider：资源的具体配置字段（因资源类型而异，详见资源API文档）。
• spec.providerConfigRef：关联的ProviderConfig名称。
• spec.writeConnectionSecretToRef（可选）：将资源连接信息（如项目ID）写入Secret。
• status.atProvider：资源实际状态字段，由Provider同步自GitLab API。

版本兼容性