mirror of
https://github.com/kubesphere/website.git
synced 2025-12-26 00:12:48 +00:00
467 lines
10 KiB
Plaintext
467 lines
10 KiB
Plaintext
---
|
|
title: "Access KubeSphere Console via Domain Name"
|
|
keywords: "Kubernetes, {ks_product-en}, Domain Access, TLS"
|
|
description: "Learn how to access KubeSphere console via custom domain name."
|
|
weight: 02
|
|
---
|
|
|
|
This section explains how to access the {ks_product-en} web console using a custom domain name. To achieve this, you need to configure TLS access using cert-manager.
|
|
|
|
== Prerequisites
|
|
|
|
- Kubernetes is installed.
|
|
- link:https://helm.sh/docs/intro/install/[Helm] is installed (for installing cert-manager and ingress-nginx).
|
|
- {ks_product-en} is installed or ready to be installed.
|
|
|
|
== Step 1: Install NGINX Ingress Controller
|
|
|
|
If you haven't installed link:https://kubernetes.github.io/ingress-nginx/[NGINX Ingress Controller], follow these steps.
|
|
|
|
[source,bash]
|
|
----
|
|
# 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
|
|
|
|
link:https://cert-manager.io/docs/[cert-manager] is a Kubernetes native certificate management controller that helps automate the management and issuance of TLS certificates.
|
|
|
|
[source,bash]
|
|
----
|
|
# 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.
|
|
|
|
[source,bash]
|
|
----
|
|
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
|
|
----
|
|
|
|
[.admon.note,cols="a"]
|
|
|===
|
|
|Note
|
|
|
|
|
|
|
For more information about these parameters, please refer to link:../../03-installation-and-upgrade/02-install-kubesphere/05-appendix/[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.
|
|
|
|
[source,bash]
|
|
----
|
|
# Create Issuer
|
|
cat <<EOF | kubectl apply -f -
|
|
apiVersion: cert-manager.io/v1
|
|
kind: Issuer
|
|
metadata:
|
|
name: self-signed
|
|
namespace: kubesphere-system
|
|
spec:
|
|
selfSigned: {}
|
|
EOF
|
|
----
|
|
|
|
[source,bash]
|
|
----
|
|
# 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
|
|
----
|
|
|
|
[source,bash]
|
|
----
|
|
# 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.
|
|
|
|
[.admon.attention,cols="a"]
|
|
|===
|
|
|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
|
|
|===
|
|
|
|
[source,bash]
|
|
----
|
|
# 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
|
|
----
|
|
|
|
[source,bash]
|
|
----
|
|
# 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
|
|
----
|
|
|
|
[source,bash]
|
|
----
|
|
# 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:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl describe certificate kubesphere-tls-certs -n kubesphere-system
|
|
----
|
|
|
|
View certificate issuance process:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl get challenges,orders,certificaterequests -n kubesphere-system
|
|
----
|
|
|
|
== Step 4: Verify TLS Configuration
|
|
|
|
. Check if certificate is successfully issued.
|
|
+
|
|
--
|
|
[source,bash]
|
|
----
|
|
kubectl get certificate -n kubesphere-system
|
|
----
|
|
|
|
Example output:
|
|
|
|
[source,bash]
|
|
----
|
|
NAME READY SECRET AGE
|
|
kubesphere-tls-certs True kubesphere-tls-certs 110s
|
|
----
|
|
--
|
|
|
|
. Check Ingress configuration.
|
|
+
|
|
--
|
|
[source,bash]
|
|
----
|
|
kubectl get ingress -n kubesphere-system
|
|
----
|
|
|
|
Example output:
|
|
|
|
[source,bash]
|
|
----
|
|
NAME CLASS HOSTS ADDRESS PORTS AGE
|
|
ks-console nginx kubesphere.my.org 80, 443 1m30s
|
|
----
|
|
--
|
|
|
|
. Test HTTPS access using curl.
|
|
+
|
|
--
|
|
[source,bash]
|
|
----
|
|
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
|
|
----
|
|
|
|
[.admon.attention,cols="a"]
|
|
|===
|
|
|Attention
|
|
|
|
|
|
|
Replace `kubesphere.my.org` with your custom domain.
|
|
|===
|
|
|
|
Example output:
|
|
|
|
[source,bash]
|
|
----
|
|
Redirecting to <a href="/login">/login</a>.
|
|
----
|
|
--
|
|
|
|
== Step 5: Access {ks_product-en} Web Console
|
|
|
|
When using custom DNS, if you want to access the {ks_product-en} web console from other machines using the domain name, you need to perform the following additional steps.
|
|
|
|
. Set Service to use NodePort mode.
|
|
+
|
|
[source,bash]
|
|
----
|
|
kubectl -n ingress-nginx patch svc ingress-nginx-controller -p '{"spec": {"type": "NodePort"}}'
|
|
----
|
|
|
|
. View Service information.
|
|
+
|
|
[source,bash]
|
|
----
|
|
kubectl -n ingress-nginx get svc ingress-nginx-controller
|
|
----
|
|
|
|
. Get HTTPS access address.
|
|
+
|
|
--
|
|
[source,bash]
|
|
----
|
|
echo https://kubesphere.my.org:$(kubectl -n ingress-nginx get svc ingress-nginx-controller -o jsonpath='{.spec.ports[?(@.port==443)].nodePort}')
|
|
----
|
|
|
|
[.admon.attention,cols="a"]
|
|
|===
|
|
|Attention
|
|
|
|
|
|
|
Replace `kubesphere.my.org` with your custom domain.
|
|
|===
|
|
|
|
Example output (your address may differ):
|
|
|
|
[source,bash]
|
|
----
|
|
https://kubesphere.my.org:31655
|
|
----
|
|
--
|
|
|
|
. Get node IP.
|
|
+
|
|
[source,bash]
|
|
----
|
|
kubectl get nodes -o jsonpath='{.items[0].status.addresses[?(@.type=="InternalIP")].address}'
|
|
----
|
|
|
|
. On the machine accessing the {ks_product-en} web console, add DNS for node IP.
|
|
+
|
|
--
|
|
[source,bash]
|
|
----
|
|
vim /etc/hosts
|
|
----
|
|
|
|
Add node IP and domain.
|
|
|
|
[source,bash]
|
|
----
|
|
<Node IP> kubesphere.my.org
|
|
----
|
|
|
|
[.admon.attention,cols="a"]
|
|
|===
|
|
|Attention
|
|
|
|
|
|
|
Replace `kubesphere.my.org` with your custom domain.
|
|
|===
|
|
|
|
--
|
|
|
|
. If everything is configured correctly, you should be able to access the {ks_product-en} web console using the HTTPS address obtained above, such as https://kubesphere.my.org:31655.
|
|
|
|
|
|
== Troubleshooting
|
|
|
|
=== Certificate Not Issued Successfully
|
|
|
|
Check certificate status:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl describe certificate -n kubesphere-system
|
|
----
|
|
|
|
Check cert-manager logs:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl logs -n cert-manager -l app=cert-manager
|
|
----
|
|
|
|
=== Ingress Configuration Issues
|
|
|
|
Check Ingress configuration:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl describe ingress -n kubesphere-system
|
|
----
|
|
|
|
Check Ingress controller logs:
|
|
|
|
[source,bash]
|
|
----
|
|
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
|
|
----
|
|
|
|
== Uninstallation
|
|
|
|
Uninstall cert-manager
|
|
|
|
[source,bash]
|
|
----
|
|
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
|
|
|
|
[source,bash]
|
|
----
|
|
helm uninstall ingress-nginx -n ingress-nginx
|
|
----
|