From cfa8574035f0d9330ad44d7c5ef321df5ea0c867 Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Thu, 17 Oct 2024 17:42:53 +0200 Subject: [PATCH 01/10] initial cluster domain docs --- modules/guides/nav.adoc | 1 + modules/guides/pages/cluster-domain.adoc | 43 ++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 modules/guides/pages/cluster-domain.adoc diff --git a/modules/guides/nav.adoc b/modules/guides/nav.adoc index f61767420..6507f7210 100644 --- a/modules/guides/nav.adoc +++ b/modules/guides/nav.adoc @@ -4,3 +4,4 @@ ** xref:running-stackable-in-an-airgapped-environment.adoc[] ** xref:viewing-and-verifying-sboms.adoc[] ** xref:enabling-verification-of-image-signatures.adoc[] +** xref:cluster-domain.adoc[] diff --git a/modules/guides/pages/cluster-domain.adoc b/modules/guides/pages/cluster-domain.adoc new file mode 100644 index 000000000..cfbf28582 --- /dev/null +++ b/modules/guides/pages/cluster-domain.adoc @@ -0,0 +1,43 @@ += Configuring the Kubernetes cluster domain +:description: Configure Stackable operators to use a different cluster domain other than 'cluster.local'. +:dns-custom-nameservers: https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/ +:dns-pod-service: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/ + +Stackable operators allow to configure a non-default cluster domain as described in {dns-custom-nameservers}[`Customizing DNS Service`] (and more in {dns-pod-service}[`DNS for Services and Pods`]). +The configuration is primarily done via and environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechansim to auto detect the cluster domain using the `/etc/resolv.conf` file. + +The following steps explain the use of the environment variable and the auto detection mechanism in detail. + +== Steps + +=== Setting `KUBERNETES_CLUSTER_DOMAIN` variable + +The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. This means that the desired cluster domain can be configured in a Helm values file via the property`kubernetesClusterDomain` or via the install command like: + +``` +helm install hive-operator stackable-stable/hive-operator --set kubernetesClusterDomain="my-cluster.local" +``` + +=== Using auto detection + +As a first step, the auto detection is checking the runtime environment of the operator. In most cases this is a clusterized environment like Kubernetes or Openshift. +This is determined by checking if the `KUBERNETES_SERVICE_HOST` environment variable is set in the operator Pod. + +If clusterized, the auto detection parses the `/etc/resolv.conf` file for the last entry starting with the `search` keyword. Within that `search` entry the shortest option is selected. + +An example for the `/etc/resolv.conf` in a Kubelet looks like: + +``` +nameserver 10.32.0.10 +search .svc.cluster.local svc.cluster.local cluster.local +options ndots:5 +``` + +Using this example as a base for the cluster domain auto detection, the operator would choose the `cluster.local` option. + +=== Running locally + +This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. This would be the case if the operator is not running in a clusterized environment like e.g. locally a Laptop or PC. +Running the operator locally is mostly for development and therefore not relevant for most users. + +If running locally, and `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set, the operator will default its cluster domain to `cluster.local`. From 85f5b12ebfef718c9cb32e815b91d2a3c009bd2e Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Thu, 17 Oct 2024 17:50:24 +0200 Subject: [PATCH 02/10] add note in kubernetes section for cluster domain --- modules/ROOT/pages/kubernetes/index.adoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/modules/ROOT/pages/kubernetes/index.adoc b/modules/ROOT/pages/kubernetes/index.adoc index a515cf95b..b92a6a2d4 100644 --- a/modules/ROOT/pages/kubernetes/index.adoc +++ b/modules/ROOT/pages/kubernetes/index.adoc @@ -77,3 +77,8 @@ Kubernetes control plane is running at https://127.0.0.1:6443 CoreDNS is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-system/services/https:metrics-server:https/proxy ---- + +=== Configuring the cluster domain + +In case a non-default cluster domain is used as described in https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/[Customizing DNS Service], +Stackable operators can be configured accordingly. This is described in detail in this guide xref:cluster-domain.adoc[Configuring the Kubernetes cluster domain]. From 7a0e4f76c156aa0539de5251c008de660ee72c8b Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Thu, 17 Oct 2024 18:13:00 +0200 Subject: [PATCH 03/10] fix link --- modules/ROOT/pages/kubernetes/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/kubernetes/index.adoc b/modules/ROOT/pages/kubernetes/index.adoc index b92a6a2d4..b10a135d2 100644 --- a/modules/ROOT/pages/kubernetes/index.adoc +++ b/modules/ROOT/pages/kubernetes/index.adoc @@ -81,4 +81,4 @@ Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-syste === Configuring the cluster domain In case a non-default cluster domain is used as described in https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/[Customizing DNS Service], -Stackable operators can be configured accordingly. This is described in detail in this guide xref:cluster-domain.adoc[Configuring the Kubernetes cluster domain]. +Stackable operators can be configured accordingly. This is described in detail in this guide xref:guides:cluster-domain.adoc[Configuring the Kubernetes cluster domain]. From c95fb51876c5bf87a29badc9dd3a181a8f8af778 Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Thu, 17 Oct 2024 18:23:47 +0200 Subject: [PATCH 04/10] fixes --- modules/guides/pages/cluster-domain.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/guides/pages/cluster-domain.adoc b/modules/guides/pages/cluster-domain.adoc index cfbf28582..cbf9522df 100644 --- a/modules/guides/pages/cluster-domain.adoc +++ b/modules/guides/pages/cluster-domain.adoc @@ -10,15 +10,15 @@ The following steps explain the use of the environment variable and the auto det == Steps -=== Setting `KUBERNETES_CLUSTER_DOMAIN` variable +=== Use environment variable -The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. This means that the desired cluster domain can be configured in a Helm values file via the property`kubernetesClusterDomain` or via the install command like: +The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. This means that the desired cluster domain can be configured in a Helm values file via the property `kubernetesClusterDomain` or via the install command like: ``` helm install hive-operator stackable-stable/hive-operator --set kubernetesClusterDomain="my-cluster.local" ``` -=== Using auto detection +=== Use auto detection As a first step, the auto detection is checking the runtime environment of the operator. In most cases this is a clusterized environment like Kubernetes or Openshift. This is determined by checking if the `KUBERNETES_SERVICE_HOST` environment variable is set in the operator Pod. From 884bc37005cda4f4b354de1103a2c5fd797843c8 Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Fri, 18 Oct 2024 09:30:13 +0200 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Sebastian Bernauer --- modules/ROOT/pages/kubernetes/index.adoc | 2 +- modules/guides/pages/cluster-domain.adoc | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/kubernetes/index.adoc b/modules/ROOT/pages/kubernetes/index.adoc index b10a135d2..85902a23b 100644 --- a/modules/ROOT/pages/kubernetes/index.adoc +++ b/modules/ROOT/pages/kubernetes/index.adoc @@ -81,4 +81,4 @@ Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-syste === Configuring the cluster domain In case a non-default cluster domain is used as described in https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/[Customizing DNS Service], -Stackable operators can be configured accordingly. This is described in detail in this guide xref:guides:cluster-domain.adoc[Configuring the Kubernetes cluster domain]. +Stackable operators can be configured accordingly. This is described in detail in the xref:guides:cluster-domain.adoc[Configuring the Kubernetes cluster domain] guide. diff --git a/modules/guides/pages/cluster-domain.adoc b/modules/guides/pages/cluster-domain.adoc index cbf9522df..d568f7d41 100644 --- a/modules/guides/pages/cluster-domain.adoc +++ b/modules/guides/pages/cluster-domain.adoc @@ -3,16 +3,17 @@ :dns-custom-nameservers: https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/ :dns-pod-service: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/ -Stackable operators allow to configure a non-default cluster domain as described in {dns-custom-nameservers}[`Customizing DNS Service`] (and more in {dns-pod-service}[`DNS for Services and Pods`]). -The configuration is primarily done via and environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechansim to auto detect the cluster domain using the `/etc/resolv.conf` file. +Stackable operators allow to configure a non-default cluster domain as described in {dns-custom-nameservers}[Customizing DNS Service] (and more in {dns-pod-service}[DNS for Services and Pods]). +The configuration is primarily done via and environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechanism to auto detect the cluster domain using the `/etc/resolv.conf` file. -The following steps explain the use of the environment variable and the auto detection mechanism in detail. +The following steps explain the use of the environment variable and the auto detection mechanism in detail: == Steps === Use environment variable -The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. This means that the desired cluster domain can be configured in a Helm values file via the property `kubernetesClusterDomain` or via the install command like: +The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. +This means that the desired cluster domain can be configured in a Helm values file via the property `kubernetesClusterDomain` or via the install command like: ``` helm install hive-operator stackable-stable/hive-operator --set kubernetesClusterDomain="my-cluster.local" @@ -37,7 +38,7 @@ Using this example as a base for the cluster domain auto detection, the operator === Running locally -This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. This would be the case if the operator is not running in a clusterized environment like e.g. locally a Laptop or PC. +This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. This would be the case if the operator is not running in a clusterized environment like e.g. locally on a Laptop or PC. Running the operator locally is mostly for development and therefore not relevant for most users. If running locally, and `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set, the operator will default its cluster domain to `cluster.local`. From 48798fb8ecb8415f4866de0bad79cbdef658c5fc Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Fri, 18 Oct 2024 09:31:02 +0200 Subject: [PATCH 06/10] rename to kubernetes-cluster-domain.adoc --- modules/ROOT/pages/kubernetes/index.adoc | 2 +- modules/guides/nav.adoc | 2 +- .../{cluster-domain.adoc => kubernetes-cluster-domain.adoc} | 0 3 files changed, 2 insertions(+), 2 deletions(-) rename modules/guides/pages/{cluster-domain.adoc => kubernetes-cluster-domain.adoc} (100%) diff --git a/modules/ROOT/pages/kubernetes/index.adoc b/modules/ROOT/pages/kubernetes/index.adoc index 85902a23b..a525bd2a1 100644 --- a/modules/ROOT/pages/kubernetes/index.adoc +++ b/modules/ROOT/pages/kubernetes/index.adoc @@ -81,4 +81,4 @@ Metrics-server is running at https://127.0.0.1:6443/api/v1/namespaces/kube-syste === Configuring the cluster domain In case a non-default cluster domain is used as described in https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/[Customizing DNS Service], -Stackable operators can be configured accordingly. This is described in detail in the xref:guides:cluster-domain.adoc[Configuring the Kubernetes cluster domain] guide. +Stackable operators can be configured accordingly. This is described in detail in the xref:guides:kubernetes-cluster-domain.adoc[Configuring the Kubernetes cluster domain] guide. diff --git a/modules/guides/nav.adoc b/modules/guides/nav.adoc index 6507f7210..12e65a172 100644 --- a/modules/guides/nav.adoc +++ b/modules/guides/nav.adoc @@ -4,4 +4,4 @@ ** xref:running-stackable-in-an-airgapped-environment.adoc[] ** xref:viewing-and-verifying-sboms.adoc[] ** xref:enabling-verification-of-image-signatures.adoc[] -** xref:cluster-domain.adoc[] +** xref:kubernetes-cluster-domain.adoc[] diff --git a/modules/guides/pages/cluster-domain.adoc b/modules/guides/pages/kubernetes-cluster-domain.adoc similarity index 100% rename from modules/guides/pages/cluster-domain.adoc rename to modules/guides/pages/kubernetes-cluster-domain.adoc From e82c01f1aaabe9ce5b5064c52e1cfa8d8a72eb86 Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Fri, 18 Oct 2024 09:39:37 +0200 Subject: [PATCH 07/10] fix typo --- modules/guides/pages/kubernetes-cluster-domain.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/guides/pages/kubernetes-cluster-domain.adoc b/modules/guides/pages/kubernetes-cluster-domain.adoc index d568f7d41..d435ea10f 100644 --- a/modules/guides/pages/kubernetes-cluster-domain.adoc +++ b/modules/guides/pages/kubernetes-cluster-domain.adoc @@ -4,7 +4,7 @@ :dns-pod-service: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/ Stackable operators allow to configure a non-default cluster domain as described in {dns-custom-nameservers}[Customizing DNS Service] (and more in {dns-pod-service}[DNS for Services and Pods]). -The configuration is primarily done via and environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechanism to auto detect the cluster domain using the `/etc/resolv.conf` file. +The configuration is primarily done via an environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechanism to auto detect the cluster domain using the `/etc/resolv.conf` file. The following steps explain the use of the environment variable and the auto detection mechanism in detail: From fa9b6f404493dafb71cd19b8b1581233465546fb Mon Sep 17 00:00:00 2001 From: Sebastian Bernauer Date: Fri, 18 Oct 2024 09:40:58 +0200 Subject: [PATCH 08/10] review comments --- modules/guides/pages/kubernetes-cluster-domain.adoc | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/modules/guides/pages/kubernetes-cluster-domain.adoc b/modules/guides/pages/kubernetes-cluster-domain.adoc index d435ea10f..9487557c6 100644 --- a/modules/guides/pages/kubernetes-cluster-domain.adoc +++ b/modules/guides/pages/kubernetes-cluster-domain.adoc @@ -21,12 +21,14 @@ helm install hive-operator stackable-stable/hive-operator --set kubernetesCluste === Use auto detection -As a first step, the auto detection is checking the runtime environment of the operator. In most cases this is a clusterized environment like Kubernetes or Openshift. +If the `KUBERNETES_CLUSTER_DOMAIN` environment variable is not set, the auto detection is checking the runtime environment of the operator. +In most cases this is a clusterized environment like Kubernetes or Openshift. This is determined by checking if the `KUBERNETES_SERVICE_HOST` environment variable is set in the operator Pod. -If clusterized, the auto detection parses the `/etc/resolv.conf` file for the last entry starting with the `search` keyword. Within that `search` entry the shortest option is selected. +If clusterized, the auto detection parses the `/etc/resolv.conf` file for the last entry starting with the `search` keyword. +Within that `search` entry the shortest option is selected. -An example for the `/etc/resolv.conf` in a Kubelet looks like: +An example `/etc/resolv.conf` in a Pod looks like: ``` nameserver 10.32.0.10 @@ -34,11 +36,12 @@ search .svc.cluster.local svc.cluster.local cluster.local options ndots:5 ``` -Using this example as a base for the cluster domain auto detection, the operator would choose the `cluster.local` option. +Using this example as a base for the cluster domain auto detection, the operator would choose `cluster.local` as cluster domain. === Running locally -This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. This would be the case if the operator is not running in a clusterized environment like e.g. locally on a Laptop or PC. +This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. +This would be the case if the operator is not running in a clusterized environment like e.g. locally a Laptop or PC. Running the operator locally is mostly for development and therefore not relevant for most users. If running locally, and `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set, the operator will default its cluster domain to `cluster.local`. From 8acb55b41165ccfa0bd145b767b46984dd6071cf Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Tue, 22 Oct 2024 11:37:12 +0200 Subject: [PATCH 09/10] remove auto-dectection explanation --- .../pages/kubernetes-cluster-domain.adoc | 42 +++---------------- 1 file changed, 5 insertions(+), 37 deletions(-) diff --git a/modules/guides/pages/kubernetes-cluster-domain.adoc b/modules/guides/pages/kubernetes-cluster-domain.adoc index 9487557c6..9153f7018 100644 --- a/modules/guides/pages/kubernetes-cluster-domain.adoc +++ b/modules/guides/pages/kubernetes-cluster-domain.adoc @@ -3,45 +3,13 @@ :dns-custom-nameservers: https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/ :dns-pod-service: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/ -Stackable operators allow to configure a non-default cluster domain as described in {dns-custom-nameservers}[Customizing DNS Service] (and more in {dns-pod-service}[DNS for Services and Pods]). -The configuration is primarily done via an environment variable `KUBERNETES_CLUSTER_DOMAIN`, but there is also a mechanism to auto detect the cluster domain using the `/etc/resolv.conf` file. +Stackable operators allow the configuration of a non-default cluster domain as described in {dns-custom-nameservers}[Customizing DNS Service] (and more in {dns-pod-service}[DNS for Services and Pods]). -The following steps explain the use of the environment variable and the auto detection mechanism in detail: - -== Steps - -=== Use environment variable - -The environment variable `KUBERNETES_CLUSTER_DOMAIN` takes precedence over auto detection. -This means that the desired cluster domain can be configured in a Helm values file via the property `kubernetesClusterDomain` or via the install command like: +The cluster domain can be configured using an environment variable `KUBERNETES_CLUSTER_DOMAIN` set on the operators. +This environment variable can be configured via the helm values property `kubernetesClusterDomain` during the installation of the operators. ``` -helm install hive-operator stackable-stable/hive-operator --set kubernetesClusterDomain="my-cluster.local" +helm install -operator stackable-stable/-operator --set kubernetesClusterDomain="my-cluster.local" ``` -=== Use auto detection - -If the `KUBERNETES_CLUSTER_DOMAIN` environment variable is not set, the auto detection is checking the runtime environment of the operator. -In most cases this is a clusterized environment like Kubernetes or Openshift. -This is determined by checking if the `KUBERNETES_SERVICE_HOST` environment variable is set in the operator Pod. - -If clusterized, the auto detection parses the `/etc/resolv.conf` file for the last entry starting with the `search` keyword. -Within that `search` entry the shortest option is selected. - -An example `/etc/resolv.conf` in a Pod looks like: - -``` -nameserver 10.32.0.10 -search .svc.cluster.local svc.cluster.local cluster.local -options ndots:5 -``` - -Using this example as a base for the cluster domain auto detection, the operator would choose `cluster.local` as cluster domain. - -=== Running locally - -This section covers the case when both `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set. -This would be the case if the operator is not running in a clusterized environment like e.g. locally a Laptop or PC. -Running the operator locally is mostly for development and therefore not relevant for most users. - -If running locally, and `KUBERNETES_CLUSTER_DOMAIN` and `KUBERNETES_SERVICE_HOST` are not set, the operator will default its cluster domain to `cluster.local`. +If the environment variable `KUBERNETES_CLUSTER_DOMAIN` (or the helm property `kubernetesClusterDomain`) are not set / overriden, the operator will default its cluster domain to `cluster.local`. From e8c89187daf566829b60da6d13deb00651de3a63 Mon Sep 17 00:00:00 2001 From: Malte Sander Date: Wed, 23 Oct 2024 14:53:08 +0200 Subject: [PATCH 10/10] Update modules/guides/pages/kubernetes-cluster-domain.adoc Co-authored-by: Sebastian Bernauer --- modules/guides/pages/kubernetes-cluster-domain.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/guides/pages/kubernetes-cluster-domain.adoc b/modules/guides/pages/kubernetes-cluster-domain.adoc index 9153f7018..d10e9fda7 100644 --- a/modules/guides/pages/kubernetes-cluster-domain.adoc +++ b/modules/guides/pages/kubernetes-cluster-domain.adoc @@ -12,4 +12,4 @@ This environment variable can be configured via the helm values property `kubern helm install -operator stackable-stable/-operator --set kubernetesClusterDomain="my-cluster.local" ``` -If the environment variable `KUBERNETES_CLUSTER_DOMAIN` (or the helm property `kubernetesClusterDomain`) are not set / overriden, the operator will default its cluster domain to `cluster.local`. +If the environment variable `KUBERNETES_CLUSTER_DOMAIN` (or the helm property `kubernetesClusterDomain`) are not set / overriden, the operator will default the cluster domain to `cluster.local`.