Last updated:

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.4.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.

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
Domain requirements: For HTTP-01 challenge, your domain must be publicly accessible and port 80 must be open. Let’s Encrypt limitations: Certificate validity is fixed at 90 days There are limits on the number of certificates that can be issued per domain per week For testing, it’s recommended to use Let’s Encrypt’s staging environment: https://acme-staging-v02.api.letsencrypt.org/directoryStaging

Attention

Domain requirements: For HTTP-01 challenge, your domain must be publicly accessible and port 80 must be open.
Let’s Encrypt limitations:
- Certificate validity is fixed at 90 days
- There are limits on the number of certificates that can be issued per domain per week
- For testing, it’s recommended to use Let’s Encrypt’s staging environment:
  https://acme-staging-v02.api.letsencrypt.org/directoryStaging

# 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

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

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

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

Attention
Replace `kubesphere.my.org` with your custom domain.

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.

Set Service to use NodePort mode.

kubectl -n ingress-nginx patch svc ingress-nginx-controller -p '{"spec": {"type": "NodePort"}}'

View Service information.

kubectl -n ingress-nginx get svc ingress-nginx-controller

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

Attention
Replace `kubesphere.my.org` with your custom domain.

Replace kubesphere.my.org with your custom domain.

Example output (your address may differ):

https://kubesphere.my.org:31655

Get node IP.

kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'

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.
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.

Attention
Replace `kubesphere.my.org` with your custom domain.

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

Feedback

Was this page Helpful?

Receive the latest news, articles and updates from KubeSphere

Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

Previous : Install KubeSphere on Kubernetes Next : Install and Use Extensions

What’s on this Page