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