/kubesphere-devops-credentials

name: kubesphere-devops-credentials
description: Use when managing credentials in KubeSphere DevOps, including repository credentials, kubeconfig, and API tokens

KubeSphere DevOps Credentials

Overview

Credentials in KubeSphere DevOps are Kubernetes Secrets with specific labels and annotations. They are synced to Jenkins for use in pipelines. Supported types include SSH keys, username/password, and secret tokens.

When to Use

• Creating credentials for Git repositories
• Setting up deployment credentials (kubeconfig, registry)
• Managing API tokens for external services
• Troubleshooting credential access issues
• Migrating credentials between DevOps projects

Credential Types

| Type | Use Case | Secret Key | |------|----------|------------| | **SSH** | Git repositories | `username`, `privatekey` | | **Basic** | Username/password | `username`, `password` | | **Secret** | API tokens, secrets | `secret` | | **Kubeconfig** | Kubernetes clusters | `kubeconfig` (v1.1.x only) | | **SSH Username/Pass** | Git with user/pass | `username`, `password` | | **String** | Generic text/tokens | `secret` |

Resource Structure

Credentials are stored as Kubernetes Secrets with DevOps labels:

apiVersion: v1
kind: Secret
metadata:
  name: my-credential
  namespace: project-xxx  # DevOps project namespace
  labels:
    devops.kubesphere.io/credential: "true"
  annotations:
    credential.devops.kubesphere.io/syncstatus: successful
    credential.devops.kubesphere.io/type: ssh|basic-auth|secret-text
stringData:
  username: git-user
  privatekey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----
type: credential.devops.kubesphere.io/ssh  # CRITICAL: Must use credential.devops.kubesphere.io/* type, NOT Opaque!

**⚠️ CRITICAL: Secret Type Must Be `credential.devops.kubesphere.io/*`**

The `type` field must be one of:

• `credential.devops.kubesphere.io/basic-auth`
• `credential.devops.kubesphere.io/ssh-auth`
• `credential.devops.kubesphere.io/secret-text`
• `credential.devops.kubesphere.io/kubeconfig`

**Using `type: Opaque` will result in:**

• Credential sync status stuck at "pending"
• Jenkins cannot find the credential
• Pipeline builds fail with "CredentialId could not be found"

**Controller Logic:** The credential controller only watches secrets with types starting with `credential.devops.kubesphere.io/` (see `devopscredential_controller.go` line 102). Secrets with `type: Opaque` are completely ignored.

API Endpoints

| Operation | Method | Endpoint | |-----------|--------|----------| | List Credentials | GET | `/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials` | | Create Credential | POST | `/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials` | | Get Credential | GET | `/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials/{credential}` | | Update Credential | PUT | `/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials/{credential}` | | Delete Credential | DELETE | `/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials/{credential}` | | Get Usage | GET | `/kapis/devops.kubesphere.io/v1alpha2/namespaces/{devops}/credentials/{credential}/usage` |

Common Operations

List Credentials

curl "https://kubesphere-api/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials" \
  -H "Authorization: Bearer $TOKEN"

Create SSH Credential

curl -X POST "https://kubesphere-api/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "kind": "Secret",
    "metadata": {
      "name": "github-ssh-key",
      "annotations": {
        "credential.devops.kubesphere.io/type": "ssh"
      }
    },
    "stringData": {
      "username": "git",
      "privatekey": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----"
    },
    "type": "credential.devops.kubesphere.io/ssh-auth"
  }'

Create Basic Auth Credential

curl -X POST "https://kubesphere-api/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "kind": "Secret",
    "metadata": {
      "name": "docker-registry",
      "annotations": {
        "credential.devops.kubesphere.io/type": "basic-auth"
      }
    },
    "stringData": {
      "username": "docker-user",
      "password": "docker-password"
    },
    "type": "credential.devops.kubesphere.io/basic-auth"
  }'

Create Basic Auth for Git Access Token (GitHub/GitLab)

**Best Practice:** Use `basic-auth` type for Git access tokens:

# For GitHub/GitLab access tokens
curl -X POST "https://kubesphere-api/kapis/devops.kubesphere.io/v1alpha3/namespaces/{devops}/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "kind": "Secret",
    "metadata": {
      "name": "github-token",
      "annotations": {
        "credential.devops.kubesphere.io/type": "basic-auth"
      }
    },
    "stringData": {
      "username": "git",           # Can be any value for token auth
      "password": "ghp_xxxxxxxxxx"  # Your GitHub/GitLab access token
    },
    "type": "credential.devops.kubesphere.io/basic-auth"
  }'

**Why basic-auth for tokens?**

• Git access tokens are used like passwords in HTTPS Git URLs
• ArgoCD and Jenkins both support basic-auth for Git authentication
• Username can be any value (often 'git' or your username)
• Password field holds the actual token

**Supported Git Providers:**

• GitHub Personal Access Token: `ghp_xxxxxxxxxxxx`
• GitLab Personal Access Token: `glpat-xxxxxxxxxx`
• Bitbucket App Password
• Gitea/Forgejo Access Token

Create Secret Text Credential

curl -X POST "https://kubesphere-api/kapis/devops.kub