diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 4a166e69f8..4de8ca094b 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -15,6 +15,7 @@ *** xref:user-workspaces.adoc[] ** xref:calculating-che-resource-requirements.adoc[] * xref:installing-che.adoc[] +* xref:installing-che-on-the-virtual-kubernetes-cluster.adoc[] ** xref:installing-che-in-the-cloud.adoc[] *** xref:installing-che-on-openshift-using-cli.adoc[] *** xref:installing-che-on-openshift-using-the-web-console.adoc[] diff --git a/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc b/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc index cdf599e3a1..3cb3ea5aa4 100644 --- a/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc +++ b/modules/administration-guide/pages/installing-che-on-minikube-keycloak-oidc.adoc @@ -15,6 +15,8 @@ WARNING: Single-node {kubernetes} clusters are suited only for testing or develo * Minikube stable release. See link:https://kubernetes.io/docs/tasks/tools/install-minikube/[Installing Minikube]. +* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. + * `{orch-cli}` stable release. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing `{orch-cli}`]. * `{prod-cli}`. See xref:installing-the-chectl-management-tool.adoc[]. @@ -23,26 +25,30 @@ WARNING: Single-node {kubernetes} clusters are suited only for testing or develo . Start Minikube. Allocate at least 8GB of RAM and 4 CPU cores: + +[source,shell,subs="+attributes"] ---- -$ minikube start --addons=ingress --vm=true --memory=8192 --cpus=4 +minikube start --addons=ingress --vm=true --memory=8192 --cpus=4 ---- -. Deploy `cert-manager`. See link:https://cert-manager.io/docs/installation[Installing cert-manager]. - -. Wait until all `cert-manager` pods are ready: +. Install link:https://cert-manager.io[cert-manager] + -[subs="+attributes"] +[source,shell,subs="attributes+"] ---- -$ {orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component=controller -n cert-manager --timeout=60s && \ -{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component=cainjector -n cert-manager --timeout=60s && \ -{orch-cli} wait --for=condition=ready pod -l app.kubernetes.io/component=webhook -n cert-manager --timeout=60s +helm repo add jetstack https://charts.jetstack.io +helm repo update + +helm install cert-manager jetstack/cert-manager \ + --wait \ + --create-namespace \ + --namespace cert-manager \ + --set installCRDs=true ---- -. Deploy https://www.keycloak.org/[Keycloak]: +. Install https://www.keycloak.org/[Keycloak]: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ {orch-cli} apply -f - < keycloak-ca.crt +{orch-cli} get secret ca.crt -o "jsonpath={.data['ca\.crt']}" -n keycloak | base64 -d > keycloak-ca.crt ---- . Copy Keycloak CA certificate into Minikube: + +[source,shell,subs="+attributes"] ---- -$ minikube ssh sudo "mkdir -p /etc/ca-certificates" && \ - minikube cp keycloak-ca.crt /etc/ca-certificates/keycloak-ca.crt +minikube ssh sudo "mkdir -p /etc/ca-certificates" && \ +minikube cp keycloak-ca.crt /etc/ca-certificates/keycloak-ca.crt ---- . Configure Minikube to use Keycloak as the OIDC provider: + +[source,shell,subs="+attributes"] ---- -$ minikube start \ +minikube start \ --extra-config=apiserver.oidc-issuer-url=https://keycloak.$(minikube ip).nip.io/realms/che \ --extra-config=apiserver.oidc-username-claim=email \ --extra-config=apiserver.oidc-client-id=k8s-client \ @@ -227,18 +235,18 @@ $ minikube start \ . Wait until the Keycloak pod is ready: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ {orch-cli} wait --for=condition=ready pod -l app=keycloak -n keycloak --timeout=120s +{orch-cli} wait --for=condition=ready pod -l app=keycloak -n keycloak --timeout=120s ---- . Configure Keycloak to create the realm, client, and user: + IMPORTANT: You must do this each time you start the Minikube cluster. + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ {orch-cli} exec deploy/keycloak -n keycloak -- bash -c \ +{orch-cli} exec deploy/keycloak -n keycloak -- bash -c \ "/opt/keycloak/bin/kcadm.sh config credentials \ --server http://localhost:8080 \ --realm master \ @@ -271,9 +279,9 @@ $ {orch-cli} exec deploy/keycloak -n keycloak -- bash -c \ . Copy Keycloak CA certificate into the `{prod-namespace}` namespace: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ {orch-cli} create namespace {prod-namespace} && \ +{orch-cli} create namespace {prod-namespace} && \ {orch-cli} create configmap keycloak-certs \ --from-file=keycloak-ca.crt=keycloak-ca.crt \ -n {prod-namespace} && \ @@ -285,9 +293,9 @@ $ {orch-cli} create namespace {prod-namespace} && \ . Prepare the `CheCluster` patch: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ cat > che-patch.yaml << EOF +cat > che-patch.yaml << EOF kind: CheCluster apiVersion: org.eclipse.che/v2 spec: @@ -296,6 +304,9 @@ spec: oAuthClientName: k8s-client oAuthSecret: eclipse-che identityProviderURL: "https://keycloak.$(minikube ip).nip.io/realms/che" + gateway: + oAuthProxy: + cookieExpireSeconds: 300 components: cheServer: extraProperties: @@ -305,39 +316,39 @@ EOF . Create the {prod-short} instance with `{prod-cli}`: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ {prod-cli} server:deploy --platform k8s --domain $(minikube ip).nip.io --che-operator-cr-patch-yaml che-patch.yaml --skip-cert-manager +{prod-cli} server:deploy --platform k8s --domain $(minikube ip).nip.io --che-operator-cr-patch-yaml che-patch.yaml --skip-cert-manager ---- + Alternatively, use the link:https://artifacthub.io/packages/helm/eclipse-che/eclipse-che[{prod}] Helm Charts: + -[subs="+attributes"] +[source,shell,subs="+attributes"] ---- -$ helm install che \ +helm install che \ --namespace eclipse-che \ --set networking.domain=$(minikube ip).nip.io \ --set networking.auth.oAuthSecret=eclipse-che \ --set networking.auth.oAuthClientName=k8s-client \ --set networking.auth.identityProviderURL=https://keycloak.$(minikube ip).nip.io/realms/che . && \ - sleep 5s && \ - {orch-cli} patch checluster/eclipse-che --patch '{"spec": {"components": {"cheServer": {"extraProperties": {"CHE_OIDC_USERNAME__CLAIM": "email"}}}}}' --type=merge -n eclipse-che +sleep 5s && \ +{orch-cli} patch checluster/eclipse-che --patch '{"spec": {"components": {"cheServer": {"extraProperties": {"CHE_OIDC_USERNAME__CLAIM": "email"}}}}}' --type=merge -n eclipse-che ---- .Verification steps . Verify the {prod-short} instance status: + -[subs="+attributes,+quotes"] +[source,shell,subs="+attributes"] ---- -$ {prod-cli} server:status +{prod-cli} server:status ---- . Navigate to the {prod-short} cluster instance: + -[subs="+attributes,+quotes"] +[source,shell,subs="+attributes"] ---- -$ {prod-cli} dashboard:open +{prod-cli} dashboard:open ---- . Log in to the {prod-short} instance with *Username:* `test` and *Password:* `test`. diff --git a/modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc b/modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc new file mode 100644 index 0000000000..feb88e2846 --- /dev/null +++ b/modules/administration-guide/pages/installing-che-on-the-virtual-kubernetes-cluster.adoc @@ -0,0 +1,683 @@ +:_content-type: PROCEDURE +:navtitle: Installing {prod-short} on the virtual {kubernetes} cluster +:description: Installing {prod-short} on the virtual {kubernetes} cluster +:keywords: installing-{prod-short}-on-the-virtual-kubernetes-cluster +:page-aliases: + +[id="installing-{prod-short}-on-the-virtual-kubernetes-cluster.adoc"] += Installing {prod-short} on the virtual {kubernetes} cluster + + +Virtual clusters are fully working {kubernetes} clusters that run on top of other {kubernetes} clusters. Compared to fully separate "real" clusters, virtual clusters reuse worker nodes and networking of the host cluster. They have their own control plane and schedule all workloads into a single {namespace} of the host cluster. Similar to virtual machines, virtual clusters partition a single physical cluster into multiple separate ones. + +`vCluster` offers a solution for deploying {prod-short} in scenarios where it normally would be impossible. This includes situations where the {kubernetes} cluster version is incompatible with {prod-short}, or when the Cloud Service Provider lacks support for external OIDC. Utilizing `vClusters` allows bypassing these constraints and enables {prod-short} to function as needed. + +.Prerequisites + +* `helm`: The package manager for {kubernetes}. See: link:https://helm.sh/docs/intro/install/[Installing Helm]. + +* `vcluster`: The command line tool for managing virtual {kubernetes} clusters. See link:https://www.vcluster.com/docs/getting-started/setup[Installing vCluster CLI]. + +* `{orch-cli}`: The Kubernetes command-line tool. See link:https://kubernetes.io/docs/tasks/tools/#kubectl[Installing {orch-cli}]. + +* `kubelogin`: The plugin for `kubectl` also known as `kubectl oidc-login`. See https://github.com/int128/kubelogin[Installing kubelogin]. + +* `{prod-cli}`: The command line tool for {prod}. See: xref:installing-the-chectl-management-tool.adoc[]. + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. + +.Procedure + +. Define the cluster domain name. ++ +[source,shell] +---- +DOMAIN_NAME= +---- + +. Install link:https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/[Ingress Controller]. +Check your {kubernetes} provider documentation how to install it. ++ +[TIP] +==== +Use the following command to install link:https://docs.nginx.com/nginx-ingress-controller/[NGINX Ingress Controller] +on Azure Kubernetes Service cluster: +[source,shell,subs="attributes+"] +---- +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update + +helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --create-namespace \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"=/healthz \ + --set controller.service.externalTrafficPolicy=Cluster +---- +==== + +. Install the link:https://cert-manager.io[cert-manager]: ++ +[source,shell,subs="attributes+"] +---- +helm repo add jetstack https://charts.jetstack.io +helm repo update + +helm install cert-manager jetstack/cert-manager \ + --wait \ + --create-namespace \ + --namespace cert-manager \ + --set installCRDs=true +---- + +. Define the `Keycloak` host: ++ +[source,shell,subs="+attributes"] +---- +KEYCLOAK_HOST=keycloak.${DOMAIN_NAME} +---- ++ +[IMPORTANT] +==== +If you use a registrar such as GoDaddy, you will need to add the following DNS record +in your registrar and point it to the IP address of the ingress controller: + +* type: `**A**` +* name: `**keycloak**` +==== ++ +[TIP] +==== +Use the following command to figure out the external IP address of the NGINX Ingress Controller: +[source,shell,subs="attributes+"] +---- +{orch-cli} get services ingress-nginx-controller \ + --namespace ingress-nginx \ + --output jsonpath="{.status.loadBalancer.ingress[0].ip}" +---- +==== ++ +[TIP] +==== +Use the following command to wait until `Keycloak` host is known: +[source,shell,subs="attributes+"] +---- +until ping -c1 ${KEYCLOAK_HOST} >/dev/null 2>&1; do :; done +---- +==== + +. Install link:https://www.keycloak.org/[Keycloak] with a self-signed certificate: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} apply -f - < /tmp/vcluster-values.yaml << EOF +api: + image: registry.k8s.io/kube-apiserver:v1.27.1 + extraArgs: + - --oidc-issuer-url=https://${KEYCLOAK_HOST}/realms/che + - --oidc-client-id=che-public + - --oidc-username-claim=email + - --oidc-groups-claim=groups + - --oidc-ca-file=/tmp/certificates/keycloak-ca.crt + +init: + manifestsTemplate: |- + --- + kind: ClusterRoleBinding + apiVersion: rbac.authorization.k8s.io/v1 + metadata: + name: oidc-cluster-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: Group + name: vcluster +service: + type: LoadBalancer +EOF +---- + +. Install `vCluster`: ++ +[source,shell,subs="+attributes"] +---- +helm repo add loft-sh https://charts.loft.sh +helm repo update + +helm install vcluster loft-sh/vcluster-k8s \ + --create-namespace \ + --namespace vcluster \ + --values /tmp/vcluster-values.yaml +---- + +. Mount `Keycloak` CA certificate into the `vcluster` pod: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} get secret ca.crt \ + --output "jsonpath={.data['ca\.crt']}" \ + --namespace keycloak \ + | base64 -d > /tmp/keycloak-ca.crt + +{orch-cli} create configmap keycloak-cert \ + --from-file=keycloak-ca.crt=/tmp/keycloak-ca.crt \ + --namespace vcluster + +{orch-cli} patch deployment vcluster -n vcluster --type json -p='[ + { + "op": "add", + "path": "/spec/template/spec/volumes/-", + "value": { + "name": "keycloak-cert", + "configMap": { + "name": "keycloak-cert" + } + } + }, + { + "op": "add", + "path": "/spec/template/spec/containers/0/volumeMounts/-", + "value": { + "name": "keycloak-cert", + "mountPath": "/tmp/certificates" + } + } +]' +---- + +. Wait until `vc-vcluster` secret is created: +[source,shell,subs="+attributes"] ++ +---- +timeout 120 bash -c 'while :; do {orch-cli} get secret vc-vcluster -n vcluster && break || sleep 5; done' +---- + +. Verify the `vCluster` cluster status: ++ +[source,shell,subs="+attributes"] +---- +vcluster list +---- + +. Update `kubeconfig` file: +[source,shell,subs="+attributes"] ++ +---- +{orch-cli} config set-credentials vcluster \ + --exec-api-version=client.authentication.k8s.io/v1beta1 \ + --exec-command=kubectl \ + --exec-arg=\ +oidc-login,\ +get-token,\ +--oidc-issuer-url=https://${KEYCLOAK_HOST}/realms/che,\ +--certificate-authority=/tmp/keycloak-ca.crt,\ +--oidc-client-id=che-public,\ +--oidc-extra-scope="email offline_access profile openid" + +{orch-cli} get secret vc-vcluster -n vcluster -o jsonpath="{.data.certificate-authority}" | base64 -d > /tmp/vcluster-ca.crt +{orch-cli} config set-cluster vcluster \ + --server=https://$(kubectl get svc vcluster-lb \ + --namespace vcluster \ + --output jsonpath="{.status.loadBalancer.ingress[0].ip}"):443 \ + --certificate-authority=/tmp/vcluster-ca.crt + +{orch-cli} config set-context vcluster \ + --cluster=vcluster \ + --user=vcluster +---- + +. Use `vcluster` `kubeconfig` context: +[source,shell,subs="+attributes"] ++ +---- +{orch-cli} config use-context vcluster +---- + +. View the pods in the cluster. By running the following command, you will be redirected to the authenticate page: ++ +[source,shell,subs="+attributes"] +---- +{orch-cli} get pods --all-namespaces +---- +. Verification ++ +All pods in the running state are displayed. + +. Install link:https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/[Ingress Controller] on the virtual {kubernetes} cluster. ++ +[TIP] +==== +Use the following command to install link:https://docs.nginx.com/nginx-ingress-controller/[NGINX Ingress Controller] +on Azure Kubernetes Service cluster: +[source,shell,subs="attributes+"] +---- +helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx +helm repo update + +helm upgrade --install ingress-nginx ingress-nginx/ingress-nginx \ + --namespace ingress-nginx \ + --create-namespace \ + --set controller.service.annotations."service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path"=/healthz \ + --set controller.service.externalTrafficPolicy=Cluster +---- +==== ++ +[IMPORTANT] +==== +If you use a registrar such as GoDaddy, you will need to add the following two DNS records in your registrar and point them to the IP address of the ingress controller: + +* type: `**A**` +* name: `**@**` and `*****` +==== ++ +[TIP] +==== +Use the following command to figure out the external IP address of the NGINX Ingress Controller: +[source,shell,subs="attributes+"] +---- +{orch-cli} get services ingress-nginx-controller \ +--namespace ingress-nginx \ +--output jsonpath="{.status.loadBalancer.ingress[0].ip}" +---- +==== ++ +[TIP] +==== +Use the following command to wait until {kubernetes} host is known: +[source,shell,subs="attributes+"] +---- +until ping -c1 ${DOMAIN_NAME} >/dev/null 2>&1; do :; done +---- +==== + +. Create `CheCluster` patch YAML file and replace `CHE_PRIVATE_CLIENT_SECRET` saved above: ++ +[source,shell,subs="+attributes,+quotes"] +---- +cat > /tmp/che-patch.yaml << EOF +kind: CheCluster +apiVersion: org.eclipse.che/v2 +spec: + networking: + ingressClassName: nginx + auth: + oAuthClientName: che-private + oAuthSecret: __CHE_PRIVATE_CLIENT_SECRET__ + identityProviderURL: https://$KEYCLOAK_HOST/realms/che + gateway: + oAuthProxy: + cookieExpireSeconds: 300 + components: + cheServer: + extraProperties: + CHE_OIDC_USERNAME__CLAIM: email +EOF +---- + +. Create `{prod-namespace}` namespace: ++ +[source,shell,subs="+attributes,"] +---- +{orch-cli} create namespace {prod-namespace} +---- + +. Copy `Keycloak` CA certificate into the `{prod-namespace}` namespace: ++ +[source,shell,subs="+attributes,"] +---- +{orch-cli} create configmap keycloak-certs \ + --from-file=keycloak-ca.crt=/tmp/keycloak-ca.crt \ + --namespace {prod-namespace} + +{orch-cli} label configmap keycloak-certs \ + app.kubernetes.io/part-of=che.eclipse.org \ + app.kubernetes.io/component=ca-bundle \ + --namespace {prod-namespace} +---- + +. Deploy {prod-short}: ++ +[source,shell,subs="+attributes,"] +---- +{prod-cli} server:deploy \ + --platform k8s \ + --domain $DOMAIN_NAME \ + --che-operator-cr-patch-yaml /tmp/che-patch.yaml +---- + +.Verification steps +. Verify the {prod-short} instance status: ++ +[subs="+attributes,+quotes"] +---- +$ {prod-cli} server:status +---- + +. Navigate to the {prod-short} cluster instance: ++ +[subs="+attributes,+quotes"] +---- +$ {prod-cli} dashboard:open +---- +. Log in to the {prod-short} instance with *Username:* `che` and *Password:* `che`. diff --git a/modules/administration-guide/partials/proc_configuring-dns-on-microsoft-azure.adoc b/modules/administration-guide/partials/proc_configuring-dns-on-microsoft-azure.adoc index 37735d3122..267f6c27a1 100644 --- a/modules/administration-guide/partials/proc_configuring-dns-on-microsoft-azure.adoc +++ b/modules/administration-guide/partials/proc_configuring-dns-on-microsoft-azure.adoc @@ -17,7 +17,7 @@ Configure DNS on Microsoft Azure. Before you start, make sure you have a registe + [source,shell] ---- -export DOMAIN_NAME=azr.my-ide.cloud +DOMAIN_NAME=azr.my-ide.cloud ---- . Create a DNS zone: diff --git a/modules/administration-guide/partials/proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc index ff650ac191..a87a486a3f 100644 --- a/modules/administration-guide/partials/proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc +++ b/modules/administration-guide/partials/proc_installing-cert-manager-on-microsoft-azure-kubernetes-service.adoc @@ -9,7 +9,7 @@ Learn how to install cert-manager on Microsoft Azure {kubernetes} Service. .Procedure -. Install the cert-manager: +. Install link:https://cert-manager.io[cert-manager] + [source,shell,subs="attributes+"] ---- diff --git a/modules/administration-guide/partials/proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc b/modules/administration-guide/partials/proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc index 4e3b6b7f96..15b638857b 100644 --- a/modules/administration-guide/partials/proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc +++ b/modules/administration-guide/partials/proc_installing-nginx-ingress-controller-on-microsoft-azure-kubernetes-service.adoc @@ -9,7 +9,7 @@ Use the following instructions to install the NGINX Ingress Controller on Micros .Procedure -. Install NGINX Ingress Controller: +. Install link:https://docs.nginx.com/nginx-ingress-controller[NGINX Ingress Controller]: + [source,shell,subs="attributes+"] ----