/kubesphere-devops-overview

name: kubesphere-devops-overview
description: Use when working with KubeSphere DevOps extension, CI/CD pipelines, Jenkins integration, or pipeline troubleshooting

KubeSphere DevOps Overview

Overview

KubeSphere DevOps provides CI/CD capabilities through Jenkins integration, supporting both graphical pipeline editing and Jenkinsfile-based pipelines. It enables automated builds, testing, and deployments across multi-cluster environments with **ArgoCD integration** for GitOps continuous deployment.

When to Use

• Setting up CI/CD pipelines in KubeSphere
• Configuring Jenkins integration
• Managing DevOps projects and pipelines
• Troubleshooting pipeline execution issues
• Integrating with GitHub, GitLab, or SVN repositories
• Configuring SonarQube for code quality

Core Concepts

Resource Mapping

KubeSphere DevOps maps resources across three layers:

KubeSphere          Kubernetes                    Jenkins
─────────────────────────────────────────────────────────────
Workspace           Workspace CR                  (authorization)
└── DevOpsProject   ├── DevOpsProject CR          └── Folder
    (Namespace)     └── Namespace (with label)
    └── Pipeline    ├── Pipeline CR               └── WorkflowJob
        └── Run     ├── PipelineRun CR            └── Build #N

**Key Concept:** A "DevOps Project" in KubeSphere is fundamentally a **Kubernetes namespace** with the `devops.kubesphere.io/managed=true` label. The DevOpsProject CR exists as a wrapper resource, but when querying for accessible DevOps projects, you interact with **namespaces**, not the DevOpsProject CRs directly.

**For tenants:** Use the `/kapis/devops.kubesphere.io/v1alpha3/workspaces/{workspace}/namespaces` endpoint to list accessible DevOps projects (returns namespace resources). The `/apis/devops.kubesphere.io/v1alpha3/devopsprojects` endpoint requires cluster-scoped permissions and returns 403 for tenants.

DevOps Project Naming Convention

DevOps projects have two forms of names:

| Name Type | Example | Source | Usage | |-----------|---------|--------|-------| | **Shortname** | `devopstest` | `.metadata.generateName` in DevOpsProject CR | Display/user-friendly name | | **Fullname** | `devopstestc2nj7` | `.metadata.name` in DevOpsProject CR and Namespace | Actual resource identifier |

**Important:**

• The **fullname** is the actual Kubernetes namespace name (e.g., `devopstestc2nj7`)
• When creating a DevOps project with shortname `devopstest`, KubeSphere generates a unique fullname by appending random characters
• All API operations use the **fullname** (namespace name), not the shortname
• When a user refers to a project by shortname and multiple projects match, **ask for confirmation** before proceeding

Workspace Association

DevOpsProjects belong to a Workspace via label:

apiVersion: devops.kubesphere.io/v1alpha3
kind: DevOpsProject
metadata:
  name: my-project
  labels:
    kubesphere.io/workspace: demo   # Associates with Workspace 'demo'

To create and associate:

# 1. Create Workspace
kubectl apply -f - <<EOF
apiVersion: tenant.kubesphere.io/v1beta1
kind: Workspace
metadata:
  name: demo
EOF

# 2. Create DevOpsProject with label
kubectl apply -f - <<EOF
apiVersion: devops.kubesphere.io/v1alpha3
kind: DevOpsProject
metadata:
  name: my-project
  labels:
    kubesphere.io/workspace: demo
EOF

Project Components

┌──────────────────────────────────────────────────────────────┐
│                     DevOps Project                            │
│  (Namespace with devops.kubesphere.io/managed=true label)    │
└──────────────────────┬───────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
│  Pipelines   │ │Credentials│ │   Webhooks  │
│              │ │           │ │             │
│ - Graphical  │ │ - SSH     │ │ - GitHub    │
│ - Jenkinsfile│ │ - Basic   │ │ - GitLab    │
│ - Multi-branch│ │ - Token  │ │ - Generic   │
└──────────────┘ └───────────┘ └─────────────┘

Installation

Using InstallPlan (Recommended for Production)

**Minimal Installation (Default Config) - RECOMMENDED:**

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: devops
  namespace: kubesphere-system
spec:
  extension:
    name: devops
    version: 1.2.4
  enabled: true
  upgradeStrategy: Manual   # Required for production
  # Note: spec.config is omitted to use extension default values

**When to use minimal installation:**

• First-time installation to test default configuration
• Standard deployments without special resource requirements
• When you want to use the extension's tested defaults

**Custom Configuration (Only When Needed):**

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: devops
  namespace: kubesphere-system
spec:
  extension:
    name: devops
    version: 1.2.4
  enabled: true
  upgradeStrategy: Manual   # Required for production
  # config: leave empty to use default values

**Custom Configuration (Override Defaults):**

apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: devops
  namespace: kubesphere-system
spec:
  extension:
    name: devops
    version: 1.2.4
  enabled: true
  upgradeStrategy: Manual   # Required for production
  config: |
    # Overrides values from DevOps chart's values.yaml
    agent:
      jenkins:
        Master:
          NodeSelector: {}
          resources:
            requests:
              cpu: "500m"
              memory: "4Gi"
            limits:
              cpu: "2000m"
              memory: "8Gi"
        Agent:
          Image: "jenkins/inbound-agent"
          Tag: "3309.v27b_9314fd1a_4-1-jdk21"
          Privileged: false

**Important:**

• Always use `upgradeStrategy: Manual` for production
• `config` is optional - omit or leave empty to use extension defaults
• Config values