Prerequisites

• KubeSphere Extension Development Guide

Setting Up the Development Environment

A running KubeSphere cluster is required. You can either use the ks-dev environment provided by KubeSphere or set up you're own cluster.

Using ks-dev Environment

Register an account at https://kubesphere.cloud/sign-up and create a cluster via the console. KubeSphere offers 10 hours of free usage monthly for development and testing.

Local Environment Setup

Install Node.js via nvm:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 18

Install Yarn:

npm install --global yarn

Install Helm:

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Install kubectl:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo chmod +x kubectl 
sudo mv kubectl /usr/local/bin

Download the kubeconfig file from the KubeSphere dashboard and place it in ~/.kube/config.

Install ksbuilder:

wget https://github.com/kubesphere/ksbuilder/releases/download/v0.3.13/ksbuilder_0.3.13_linux_amd64.tar.gz
tar -zxf ksbuilder_0.3.13_linux_amd64.tar.gz
sudo mv ksbuilder /usr/local/bin

Verify installations:

$ ksbuilder --version
ksbuilder version 0.3.13
$ node --version
v18.20.2
$ yarn --version
1.22.22
$ helm version
version.BuildInfo{Version:"v3.14.4", GitCommit:"81c902a123462fd4052bc5e9aa9c513c4c8fc142", GitTreeState:"clean", GoVersion:"go1.21.9"}
$ kubectl version
Client Version: v1.30.0
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
$ kubectl get node
NAME   STATUS   ROLES                         AGE   VERSION
ks     Ready    control-plane,master,worker   15d   v1.23.10
$ kubectl -n kubesphere-system get po
NAME                                     READY   STATUS    RESTARTS        AGE
ks-apiserver-754d47ffcc-fx5fz            1/1     Running   2 (6d21h ago)   15d
ks-console-54958f4674-8s225              1/1     Running   2 (6d21h ago)   15d
ks-controller-manager-59d55bc77b-vgnl7   1/1     Running   2 (6d21h ago)   15d

Configuring Reverse Proxy for ks-apiserver

Refer to the official sample to configure a reverse proxy for ArgoCD.

apiVersion: extensions.kubesphere.io/v1alpha1
kind: ReverseProxy
metadata:
  name: argocd-proxy
  namespace: kubesphere-system
spec:
  matcher:
    method: '*'
    path: /proxy/argocd.ui/*
  upstream:
    url: http://argocd-server.argocd.svc/proxy/argocd.ui/
    # url: http://192.168.2.128:8080/proxy/argocd.ui/ # for local debugging
  directives:
    authProxy: true
    headerUp:
    - '-Authorization'
status:
  state: Available

The upstream.url should point to the internal service address: http://[service-name].[namespace].svc.

Deploying ArgoCD

Create a kustomization.yaml file to manage the deployment:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: argocd
resources:
- github.com/argoproj/argo-cd/manifests/cluster-install?ref=v2.10.0

patches:
- path: argo-config-patch.yaml
  target:
    kind: ConfigMap
    name: argocd-cmd-params-cm

Create argo-config-patch.yaml to set the UI base path:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cmd-params-cm
  namespace: argocd
data:
  server.basehref: "/proxy/argocd.ui/"
  server.insecure: "true"
  server.rootpath: "/proxy/argocd.ui"

Apply the configuration:

kubectl apply -k .

If changes do not apply immediately, restart the deployment:

kubectl rollout restart deployment argocd-server -n argocd

Frontend Configuration

Update ks-console/configs/webpack.config.js to prevent 404 errors when accessing the ArgoCD dashboard:

const { merge } = require('webpack-merge');
const baseConfig = require('@ks-console/bootstrap/webpack/webpack.dev.conf');

const devConfig = merge(baseConfig, {
  devServer: {
    proxy: {
      '/proxy': {
        target: 'http://192.168.2.128:30880',
        onProxyReq: (proxyReq, req, res) => {
            const user = 'admin';
            const pass = 'P@88w0rd';
            const token = Buffer.from(`${user}:${pass}`).toString("base64");
            proxyReq.setHeader('Authorization', `Basic ${token}`);
          },
      },
    },
  },
});

module.exports = devConfig;

Restart the frontend development server:

yarn dev

Debugging

After setup, access the dashboard to see the ArgoCD login enterface. If the session loops back to the login page with 401 errors, the issue often lies in missing authentication headers passed to the ArgoCD service.

To debug, run a local ArgoCD instance and point the ReverseProxy upstream URL to the local address.

VS Code Debug Configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch ArgoCD",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/argo-cd/cmd/main.go",
            "env": {
                "ARGOCD_BINARY_NAME": "argocd-server",
                "CGO_ENABLED": "0",
                "KUBECONATOR": "/home/dev/.kube/config"
            },
            "args": [
                "--insecure",
                "--rootpath",
                "/proxy/argocd.ui/",
                "--basehref",
                "/proxy/argocd.ui/"
            ]
        }
    ]
}

Add logging middleware in server/server.go to inspect incoming headers:

logMiddleware := func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        log.WithFields(log.Fields{
            "method":  r.Method,
            "path":    r.URL.Path,
            "headers": r.Header,
        }).Info("Received Request")
        next.ServeHTTP(w, r)
    })
}
handler = logMiddleware(handler)

If the logs show missing Cookie information compared to the browser dev tools, the issue is likely within the reverse proxy configuration. Hardcoding a cookie temporarily can help verify the API response.

If you encounter open dist/app/index.html: file does not exist, build the ArgoCD UI:

cd ui && yarn build

Then add the static assets path to the launch arguments:

"args": [
    "--staticassets",
    "/absolute/path/to/argo-cd/ui/dist"
]

Restart the service to access the ArgoCD panel. After resolving the cookie forwarding issue, proceed with OAuth integration.