< img height="1" width="1" style="display:none;" alt="" src="https://px.ads.linkedin.com/collect/?pid=3131724&fmt=gif" />
Last updated: 2025-03-04 07:41:16
  • avatar

Access KubeSphere Console via Domain Name

This section explains how to access the KubeSphere web console using a custom domain name. To achieve this, you need to configure TLS access using cert-manager.

Prerequisites

  • Kubernetes is installed.

  • Helm is installed (for installing cert-manager and ingress-nginx).

  • KubeSphere is installed or ready to be installed.

Step 1: Install NGINX Ingress Controller

If you haven’t installed NGINX Ingress Controller, follow these steps.

# Add ingress-nginx repository helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx # Update repository helm repo update # Install ingress-nginx helm install ingress-nginx ingress-nginx/ingress-nginx \ --namespace ingress-nginx \ --create-namespace \ --version 4.2.5 # Verify installation kubectl -n ingress-nginx get svc ingress-nginx-controller # Check IngressClass kubectl get ingressclass

Step 2: Install cert-manager

cert-manager is a Kubernetes native certificate management controller that helps automate the management and issuance of TLS certificates.

# Add cert-manager repository helm repo add jetstack https://charts.jetstack.io # Update repository helm repo update # Install cert-manager helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ --version v1.12.0 \ --set installCRDs=true # Verify installation kubectl get pods -n cert-manager

Step 3: Configure TLS for KubeSphere

Method 1: Configure TLS during KubeSphere installation

If you haven’t installed KubeSphere yet, you can configure TLS during installation. The following command uses cert-manager to generate a self-signed certificate.

helm upgrade --install -n kubesphere-system --create-namespace ks-core https://charts.kubesphere.io/main/ks-core-1.1.3.tgz \ --set portal.hostname=kubesphere.my.org \ # Replace kubesphere.my.org with your custom domain --set portal.https.port=30880 \ --set ingress.enabled=true \ --set ingress.tls.source=generation \ --set ingress.ingressClassName=nginx
Note

For more information about these parameters, please refer to Advanced Configuration of KubeSphere Core.

Method 2: Manually configure self-signed TLS after KubeSphere installation

If KubeSphere is already installed, you need to manually configure TLS.

# Create Issuer cat <<EOF | kubectl apply -f - apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: self-signed namespace: kubesphere-system spec: selfSigned: {} EOF
# Create Certificate cat <<EOF | kubectl apply -f - apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: kubesphere-tls-certs namespace: kubesphere-system spec: duration: 2160h # 90 days # Start renewal 15 days before expiration renewBefore: 360h # 15 days (15 * 24 hours) dnsNames: - kubesphere.my.org # Replace with your custom domain issuerRef: group: cert-manager.io kind: Issuer name: self-signed secretName: kubesphere-tls-certs usages: - digital signature - key encipherment EOF
# Create Ingress cat <<EOF | kubectl apply -f - apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: cert-manager.io/issuer: self-signed cert-manager.io/issuer-kind: Issuer name: ks-console namespace: kubesphere-system spec: ingressClassName: nginx rules: - host: kubesphere.my.org # Replace with your custom domain http: paths: - backend: service: name: ks-console port: number: 80 pathType: ImplementationSpecific tls: - hosts: - kubesphere.my.org # Replace with your custom domain secretName: kubesphere-tls-certs EOF

Method 3: Manually configure Let’s Encrypt certificate after KubeSphere installation

If KubeSphere is already installed, you can also manually configure Let’s Encrypt to issue certificates.

Attention
  1. Domain requirements: For HTTP-01 challenge, your domain must be publicly accessible and port 80 must be open.

  2. Let’s Encrypt limitations:

# Create Let's Encrypt Issuer (HTTP-01 challenge) cat <<EOF | kubectl apply -f - apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-prod spec: acme: # Let's Encrypt production API server: https://acme-v02.api.letsencrypt.org/directory # Your email for receiving certificate expiration notices email: your-email@example.com privateKeySecretRef: name: letsencrypt-prod-account-key solvers: - http01: ingress: class: nginx EOF
# Create certificate to issue certificate using Let's Encrypt: cat <<EOF | kubectl apply -f - apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: kubesphere-tls-certs namespace: kubesphere-system spec: # Let's Encrypt certificate validity is fixed at 90 days and cannot be modified through this field # Start renewal 30 days before expiration renewBefore: 720h # 30 days dnsNames: - kubesphere.my.org # Replace with your custom domain issuerRef: group: cert-manager.io kind: ClusterIssuer # Use ClusterIssuer name: letsencrypt-prod secretName: kubesphere-tls-certs usages: - digital signature - key encipherment EOF
# Create Ingress cat <<EOF | kubectl apply -f - apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: cert-manager.io/cluster-issuer: letsencrypt-prod cert-manager.io/issuer-kind: ClusterIssuer name: ks-console namespace: kubesphere-system spec: ingressClassName: nginx rules: - host: kubesphere.my.org # Replace with your custom domain http: paths: - backend: service: name: ks-console port: number: 80 pathType: ImplementationSpecific tls: - hosts: - kubesphere.my.org # Replace with your custom domain secretName: kubesphere-tls-certs EOF

Verify Configuration

Check certificate issuance status:

kubectl describe certificate kubesphere-tls-certs -n kubesphere-system

View certificate issuance process:

kubectl get challenges,orders,certificaterequests -n kubesphere-system

Step 4: Verify TLS Configuration

  1. Check if certificate is successfully issued.

    kubectl get certificate -n kubesphere-system

    Example output:

    NAME READY SECRET AGE kubesphere-tls-certs True kubesphere-tls-certs 110s
  2. Check Ingress configuration.

    kubectl get ingress -n kubesphere-system

    Example output:

    NAME CLASS HOSTS ADDRESS PORTS AGE ks-console nginx kubesphere.my.org 80, 443 1m30s
  3. Test HTTPS access using curl.

    INGRESS_IP=$(kubectl -n ingress-nginx get svc ingress-nginx-controller -o jsonpath={.spec.clusterIP}) curl --resolve kubesphere.my.org:443:$INGRESS_IP https://kubesphere.my.org -k
    Attention

    Replace kubesphere.my.org with your custom domain.

    Example output:

    Redirecting to <a href="/login">/login</a>.

Step 5: Access KubeSphere Web Console

When using custom DNS, if you want to access the KubeSphere web console from other machines using the domain name, you need to perform the following additional steps.

  1. Set Service to use NodePort mode.

    kubectl -n ingress-nginx patch svc ingress-nginx-controller -p '{"spec": {"type": "NodePort"}}'
  2. View Service information.

    kubectl -n ingress-nginx get svc ingress-nginx-controller
  3. Get HTTPS access address.

    echo https://kubesphere.my.org:$(kubectl -n ingress-nginx get svc ingress-nginx-controller -o jsonpath='{.spec.ports[?(@.port==443)].nodePort}')
    Attention

    Replace kubesphere.my.org with your custom domain.

    Example output (your address may differ):

    https://kubesphere.my.org:31655
  4. Get node IP.

    kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'
  5. On the machine accessing the KubeSphere web console, add DNS for node IP.

    vim /etc/hosts

    Add node IP and domain.

    <Node IP> kubesphere.my.org
    Attention

    Replace kubesphere.my.org with your custom domain.

  6. If everything is configured correctly, you should be able to access the KubeSphere web console using the HTTPS address obtained above, such as https://kubesphere.my.org:31655.

Troubleshooting

Certificate Not Issued Successfully

Check certificate status:

kubectl describe certificate -n kubesphere-system

Check cert-manager logs:

kubectl logs -n cert-manager -l app=cert-manager

Ingress Configuration Issues

Check Ingress configuration:

kubectl describe ingress -n kubesphere-system

Check Ingress controller logs:

kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

Uninstallation

Uninstall cert-manager

helm uninstall cert-manager -n cert-manager kubectl delete crd certificaterequests.cert-manager.io certificates.cert-manager.io challenges.acme.cert-manager.io clusterissuers.cert-manager.io issuers.cert-manager.io orders.acme.cert-manager.io

Uninstall NGINX Ingress Controller

helm uninstall ingress-nginx -n ingress-nginx

Receive the latest news, articles and updates from KubeSphere