Skip to content
Skills Library
DevOps & cloud · Tool integration

kubesphere-devops-overview

/kubesphere-devops-overview

Use when working with KubeSphere DevOps extension, CI/CD pipelines, Jenkins integration, or pipeline troubleshooting

Repository
kubesphere ↗
Licence
Apache-2.0
Last repository change
15.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 15.07.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when working with KubeSphere DevOps extension, CI/CD pipelines, Jenkins integration, or pipeline troubleshooting

Original author description

Use when working with KubeSphere DevOps extension, CI/CD pipelines, Jenkins integration, or pipeline troubleshooting

How it works

  1. Overview
  2. When to Use
  3. Core Concepts
  4. Installation
  5. Architecture
  6. Key Resources
  7. Quick Commands
  8. Pipeline Types
  9. Common Mistakes
  10. Version Compatibility
Original SKILL.md headings · 396 lines, 1,437 words
SKILL.md preview
---
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:

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

To create and associate:

```bash
# 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:**

```yaml
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):**

```yaml
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):**

```yaml
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 override the extension's `values.yaml` settings
- DevOps is a critical infrastructure component - plan upgrades carefully

### Multi-Cluster Installation

To install DevOps agent on member clusters, add `clusterScheduling`:

```yaml
apiVersion: kubesphere.io/v1alpha1
kind: InstallPlan
metadata:
  name: devops
  namespace: kubesphere-system
spec:
  extension:
    name: devops
    version: 1.2.4
  enabled: true
  upgradeStrategy: Manual
  config: |
    # Base config for all clusters
    agent:
      jenkins:
        Master:
          resources:
            requests:
              cpu: "500m"
              memory: "4Gi"
  clusterScheduling:
    placement:
      clusters:
        - host      # Install on host cluster
        - member1   # Install on member1
        - member2   # Install on member2
    # Optional: per-cluster overrides
    overrides:
      member1: |
        agent:
          jenkins:
            Master:
              resources:
                limits:
                  memory: "8Gi"   # Larger master for member1
      member2: |
        agent:
          jenkins:
            Agent:
              NodeSelector:
                zone: west
```

**Key Points:**
- `clusterScheduling.placement.clusters`: List clusters where DevOps agent runs
- `clusterScheduling.overrides`: Cluster-specific config overrides
- Without `clusterScheduling`, DevOps only runs on the host cluster
- Overrides merge with base config, override values take precedence

### Using Helm (Alternative)

```bash
helm upgrade --install devops kse-extensions/devops \
  -n kubesphere-devops-system \
  --create-namespace
```

### Post-Installation Verification

Verify the DevOps installation:

```bash
# Check DevOps pods
kubectl get pods -n kubesphere-devops-system

# Check InstallPlan status
kubectl get installplan devops -n kubesphere-system

# For multi-cluster: check agent status on each cluster
kubectl get installplan devops -n kubesphere-system -o jsonpath='{.status.clusterSchedulingStatuses}'
```

## Architecture

| Component | Purpose | Namespace |
|-----------|---------|-----------|
| devops-jenkins | Jenkins master | kubesphere-devops-system |
| devops-apiserver | DevOps API service | kubesphere-devops-system |
| devops-controller | Resource controllers | kubesphere-devops-system |
| devops-argocd-* | ArgoCD (GitOps) | argocd |
| Jenkins Agent | Pipeline executors | Dynamic (per pipeline) |
|-----------|---------|-----------|
| devops-jenkins | Jenkins master | kubesphere-devops-system |
| devops-apiserver | DevOps API service | kubesphere-devops-system |
| devops-controller | Resource controllers | kubesphere-devops-system |
| Jenkins Agent | Pipeline executors | Dynamic (per pipeline) |
### Jenkins Integration

KubeSphere DevOps integrates with Jenkins for CI/CD execution. The secret `devops-jenkins` contains the admin token for direct Jenkins access:

```bash
# Get Jenkins admin token
TOKEN=$(kubectl -n kubesphere-devops-system get secret devops-jenkins -o jsonpath='{.data.jenkins-admin-token}' | base64 -d)

# Access Jenkins API
kubectl run curl-jenkins --rm -i --restart=Never --image=curlimages/curl \
  -- "http://admin:${TOKEN}@devops-jenkins.kubesphere-devops-system:80/api/json"
```

**Jenkins NodePort:**
```bash
kubectl get svc devops-jenkins -n kubesphere-devops-system
# Default: 30180
```

**Access Jenkins Console:**
- URL: `http://<node-ip>:30180`
- Username: `admin`
- Password: Get from secret above

### ArgoCD Integration

KubeSphere DevOps includes **ArgoCD v2.11.7** for GitOps continuous deployment:

**ArgoCD Components:**
| Component | Purpose |
|-----------|---------|
| application-controller | Manages Application state |
| applicationset-controller | Manages ApplicationSet resources |
| dex-server | SSO authentication |
| notifications-controller | Event notifications |
| repo-server | Repository operations |
| argocd-server | API/UI server |
| redis | Cache layer |

**Access ArgoCD:**
```bash
# Get ArgoCD server URL
kubectl get svc devops-agent-argocd-server -n argocd

# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d
```

**Key Features:**
- Declarative GitOps deployment
- Multi-source application support
- Automated sync policies
- SSO integration via Dex
- Notification webhooks

## Key Resources
## Key Resources

| Resource | API Version | Purpose |
|----------|-------------|---------|
| Pipeline | devops.kubesphere.io/v1alpha3 | CI/CD pipeline definition |
| DevOpsProject | devops.kubesphere.io/v1alpha3 | DevOps project (namespace wrapper) |
| Credential | v1/Secret | Repository and deployment credentials |

## Quick Commands

```bash
# List DevOps projects
kubectl get devopsprojects

# List pipelines in a project
kubectl get pipelines -n <devops-project-namespace>

# Get pipeline runs
kubectl get pipelineruns -n <devops-project-namespace>

# Check Jenkins status
kubectl -n kubesphere-devops-system get pods -l app=devops-jenkins

# View Jenkins logs
kubectl -n kubesphere-devops-system logs -l app=devops-jenkins

# Get Jenkins admin password
kubectl -n kubesphere-devops-system get secret devops-jenkins -o jsonpath='{.data.jenkins-admin-password}' | base64 -d
```

## Pipeline Types

| Type | Description | Use Case |
|------|-------------|----------|
| **Graphical** | Visual pipeline editor | Simple pipelines, no code |
| **Jenkinsfile (SCM)** | Pipeline defined in repository | Version-controlled pipelines |
| **Jenkinsfile (Inline)** | Pipeline defined in KubeSphere | Quick testing |
| **Multi-branch** | Auto-discovers branches | GitFlow, feature branches |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Pipeline fails with "No agent" | Check Jenkins agent configuration |
| Cannot access Git repository | Verify credentials and webhook setup |
| kubeconfig credentials fail | Use `string` type instead of `kubeconfigContent` (v1.2+) |
| Jenkins out of memory | Increase Jenkins master resources |
| Pipeline hangs | Check agent pod status and resource limits |

## Version Compatibility

| DevOps | Jenkins | Notes |
|--------|---------|-------|
| v1.2.x | 2.504.1 LTS | kubernetes-cd plugin removed |
| v1.1.x | 2.346.3 LTS | Legacy kubeconfigContent supported |

## References

- [DevOps Documentation](https://docs.kubesphere.io/v4.1/11-use-extensions/02-devops/)
- [Pipeline Syntax](https://www.jenkins.io/doc/book/pipeline/syntax/)
- [Extension README](/root/go/src/github.com/kubesphere/kse-extensions/devops/README.md)

Versions

The database has no other skills named kubesphere-devops-overview.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version c2a096aa101a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100kubesphere-devops-jenkins
    Use when configuring Jenkins in KubeSphere DevOps, including agent customization, LDAP/OIDC integration, build artifact retrieval, or troubleshooting Jenkins issues
  • 91kubesphere-devops-pipeline
    Use when creating, running, or managing CI/CD pipelines in KubeSphere DevOps, including pipeline API operations and run monitoring
  • 100jenkins-pipeline-intro
    Manage jenkins pipeline intro operations. Auto-activating skill for DevOps Basics. Triggers on: jenkins pipeline intro, jenkins pipeline intro Part of the DevOps Basics skill category. Use when working with jenkins pipeline intro functionality. Trigger with phrases like "jenkins…
  • 100cicd-pipeline-skill
    Generates CI/CD pipeline configurations for test automation with GitHub Actions, Jenkins, GitLab CI, and Azure DevOps. Includes TestMu AI cloud integration. Use when user mentions "CI/CD", "pipeline", "GitHub Actions", "Jenkins", "GitLab CI". Triggers on: "CI/CD", "pipeline",…
  • 100jenkins
    Create and manage Jenkins CI/CD pipelines, configure agents, manage plugins, and automate builds. Use when working with Jenkins servers, creating Jenkinsfiles, or setting up build automation for enterprise environments.
  • 100azure-devops
    Set up Azure Pipelines for CI/CD, configure build and release pipelines, manage Azure DevOps projects, and integrate with Azure services. Use when working with Azure DevOps Services or Server for enterprise DevOps workflows.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.