From ff0dca41cbd1cc17866adf1c67d074602170eb82 Mon Sep 17 00:00:00 2001 From: florent1s Date: Mon, 9 Nov 2026 14:19:58 +0100 Subject: [PATCH 1/6] docs(kaas): azDomains config Signed-off-by: florent1s --- docs/paas/kaas/initial-setup.md | 41 +++++++++++++++++++++++++++++++++ zensical.toml | 1 + 2 files changed, 42 insertions(+) create mode 100644 docs/paas/kaas/initial-setup.md diff --git a/docs/paas/kaas/initial-setup.md b/docs/paas/kaas/initial-setup.md new file mode 100644 index 00000000..32d65129 --- /dev/null +++ b/docs/paas/kaas/initial-setup.md @@ -0,0 +1,41 @@ +# Initial setup + +For the *Kubernetes as a service* system to function, you need to pick and configure 2 DNS entries on your DNS server +for each AZ and set those entries in your configuration file. You need to define those domains for every AZ that your +*superphenix-api* deployment controlls. + +```yaml +clusters: + local: + systemConfiguration: + apps: + superphenix-api: + values: + config: + productsConfig: + argoApp: + kubernetes: + azDomains: + # add domains for all AZs which are controlled + # by this superphenix-api instance + local: + external: "%s.kaas.local.example.org" + internal: "azs.my-region.example.org" +``` + +## External domain + +This *wildcard* domain serves to build the URLs used to talk to KaaS controlplanes. For each new cluster an ingress is created where the `%s` part is replaced by the cluster's ID. +The DNS record needs to point to the public IP of your AZ. + +!!! tip "No DNS?" + Use **[nip.io](https://nip.io)** against your AZ's public IP, for example `%s.1.2.3.4.nip.io`. + +## Internal domain + +This domain is used by the kubernetes nodes to find their controlplane, even if the cluster was migrated to another AZ (in case of disaster recovery). The DNS record consists of a list containing +the public IPs of all AZs in your region. The internal proxy running on each KaaS node will check all listed AZs and forward requests to the one listening for the corresponding *external domain*. + +!!! tip "No DNS?" + You can use **[nip.io](https://nip.io)** against your AZ's public IP, for example `local.1.2.3.4.nip.io`. + Keep in mind that if you have multiple AZ's, the disaster recovery function will not work in this configuration. diff --git a/zensical.toml b/zensical.toml index a41c1769..defed5b3 100644 --- a/zensical.toml +++ b/zensical.toml @@ -67,6 +67,7 @@ nav = [ { "PaaS" = [ { "KaaS" = [ { "Overview" = "paas/kaas/index.md" }, + { "Initial setup" = "paas/kaas/initial-setup.md" }, { "Basic operations" = "paas/kaas/basic-operations.md" }, { "Advanced configuration" = "paas/kaas/advanced-configuration.md" }, { "Disaster recovery" = "paas/kaas/disaster-recovery.md" }, From 4000d823a26346f242858a980821ce6ba1eaca66 Mon Sep 17 00:00:00 2001 From: florent1s Date: Mon, 9 Nov 2026 15:26:08 +0100 Subject: [PATCH 2/6] fix(kaas): code example Signed-off-by: florent1s --- docs/paas/kaas/initial-setup.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/paas/kaas/initial-setup.md b/docs/paas/kaas/initial-setup.md index 32d65129..802bd049 100644 --- a/docs/paas/kaas/initial-setup.md +++ b/docs/paas/kaas/initial-setup.md @@ -5,22 +5,21 @@ for each AZ and set those entries in your configuration file. You need to define *superphenix-api* deployment controlls. ```yaml -clusters: - local: - systemConfiguration: - apps: - superphenix-api: - values: - config: - productsConfig: - argoApp: - kubernetes: - azDomains: - # add domains for all AZs which are controlled - # by this superphenix-api instance - local: - external: "%s.kaas.local.example.org" - internal: "azs.my-region.example.org" +management: + systemConfiguration: + apps: + superphenix-api: + values: + config: + productsConfig: + argoApp: + kubernetes: + azDomains: + # add domains for all AZs which are controlled + # by this superphenix-api instance + local: + external: "%s.kaas.local.example.org" + internal: "azs.my-region.example.org" ``` ## External domain From 21c47ae14eaef1eee132bba04f543f26dee26e4f Mon Sep 17 00:00:00 2001 From: florent1s Date: Mon, 9 Nov 2026 16:00:52 +0100 Subject: [PATCH 3/6] docs(kaas): add spx-cluster-info CM details Signed-off-by: florent1s --- docs/paas/kaas/advanced-configuration.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/paas/kaas/advanced-configuration.md b/docs/paas/kaas/advanced-configuration.md index 3f61b732..389b7301 100644 --- a/docs/paas/kaas/advanced-configuration.md +++ b/docs/paas/kaas/advanced-configuration.md @@ -80,3 +80,13 @@ To accomplish this follow these steps: ``` Full chart values: [sfs-kaas](https://github.com/super-phenix/superphenix/blob/main/components/dependencies/sfs-kaas/values.yaml). + +For example, this feature can be leveraged to automatically enroll the cluster to an ArgoCD instance. A custom chart deploys a job that sets up the service account, +ArgoCD connection and git repository. To assist in such endeavours, KaaS clusters contain a configmap which presents details about the cluster. + +This configmap is called `spx-cluster-info` and can be found in the `kube-system` namespace. It provides the following information under a `cluster` key: + +- **clusterID**: The unique SPXID of the cluster. +- **friendlyName**: User-defined, humand readable name. +- **kubeVersion**: Kubernetes release version. +- **name**: Name of the cluster, used to generate its ID. Either UUIDv4 for console deployment or same as *friendlyName* for GitOps clusters. From c65f3f614e521aa77554a2b7bb5917404913149b Mon Sep 17 00:00:00 2001 From: florent1s Date: Mon, 9 Nov 2026 16:24:14 +0100 Subject: [PATCH 4/6] docs(kaas): restructure Signed-off-by: florent1s --- docs/paas/kaas/{ => installation}/initial-setup.md | 0 .../{ => user-guides}/advanced-configuration.md | 0 .../kaas/{ => user-guides}/basic-operations.md | 0 .../kaas/{ => user-guides}/disaster-recovery.md | 0 .../{ => user-guides}/network-configuration.md | 0 zensical.toml | 14 +++++++++----- 6 files changed, 9 insertions(+), 5 deletions(-) rename docs/paas/kaas/{ => installation}/initial-setup.md (100%) rename docs/paas/kaas/{ => user-guides}/advanced-configuration.md (100%) rename docs/paas/kaas/{ => user-guides}/basic-operations.md (100%) rename docs/paas/kaas/{ => user-guides}/disaster-recovery.md (100%) rename docs/paas/kaas/{ => user-guides}/network-configuration.md (100%) diff --git a/docs/paas/kaas/initial-setup.md b/docs/paas/kaas/installation/initial-setup.md similarity index 100% rename from docs/paas/kaas/initial-setup.md rename to docs/paas/kaas/installation/initial-setup.md diff --git a/docs/paas/kaas/advanced-configuration.md b/docs/paas/kaas/user-guides/advanced-configuration.md similarity index 100% rename from docs/paas/kaas/advanced-configuration.md rename to docs/paas/kaas/user-guides/advanced-configuration.md diff --git a/docs/paas/kaas/basic-operations.md b/docs/paas/kaas/user-guides/basic-operations.md similarity index 100% rename from docs/paas/kaas/basic-operations.md rename to docs/paas/kaas/user-guides/basic-operations.md diff --git a/docs/paas/kaas/disaster-recovery.md b/docs/paas/kaas/user-guides/disaster-recovery.md similarity index 100% rename from docs/paas/kaas/disaster-recovery.md rename to docs/paas/kaas/user-guides/disaster-recovery.md diff --git a/docs/paas/kaas/network-configuration.md b/docs/paas/kaas/user-guides/network-configuration.md similarity index 100% rename from docs/paas/kaas/network-configuration.md rename to docs/paas/kaas/user-guides/network-configuration.md diff --git a/zensical.toml b/zensical.toml index defed5b3..8b8c8ab9 100644 --- a/zensical.toml +++ b/zensical.toml @@ -67,11 +67,15 @@ nav = [ { "PaaS" = [ { "KaaS" = [ { "Overview" = "paas/kaas/index.md" }, - { "Initial setup" = "paas/kaas/initial-setup.md" }, - { "Basic operations" = "paas/kaas/basic-operations.md" }, - { "Advanced configuration" = "paas/kaas/advanced-configuration.md" }, - { "Disaster recovery" = "paas/kaas/disaster-recovery.md" }, - { "Network configuration" = "paas/kaas/network-configuration.md" } + { "Installation" = [ + { "Initial setup" = "paas/kaas/installation/initial-setup.md" }, + ]}, + { "User Guides" = [ + { "Basic operations" = "paas/kaas/user-guides/basic-operations.md" }, + { "Advanced configuration" = "paas/kaas/user-guides/advanced-configuration.md" }, + { "Disaster recovery" = "paas/kaas/user-guides/disaster-recovery.md" }, + { "Network configuration" = "paas/kaas/user-guides/network-configuration.md" }, + ]}, ]} ]}, { "Multi-tenancy" = [ From 93c0c52c9536d6983c151ee51b8e54352ba80518 Mon Sep 17 00:00:00 2001 From: florent1s Date: Mon, 9 Nov 2026 17:00:40 +0100 Subject: [PATCH 5/6] docs(kaas): redirects, typo & limitations Signed-off-by: florent1s --- docs/paas/kaas/installation/initial-setup.md | 6 +++++- docs/paas/kaas/user-guides/advanced-configuration.md | 2 +- zensical.toml | 4 ++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/paas/kaas/installation/initial-setup.md b/docs/paas/kaas/installation/initial-setup.md index 802bd049..77f8c674 100644 --- a/docs/paas/kaas/installation/initial-setup.md +++ b/docs/paas/kaas/installation/initial-setup.md @@ -30,6 +30,8 @@ The DNS record needs to point to the public IP of your AZ. !!! tip "No DNS?" Use **[nip.io](https://nip.io)** against your AZ's public IP, for example `%s.1.2.3.4.nip.io`. + If you only want to access controlplanes locally, you can use a local node IP, but beware of [current limitations](../../../operations/limitations.md#nat-gateway-traffic-to-its-host-node). + ## Internal domain This domain is used by the kubernetes nodes to find their controlplane, even if the cluster was migrated to another AZ (in case of disaster recovery). The DNS record consists of a list containing @@ -37,4 +39,6 @@ the public IPs of all AZs in your region. The internal proxy running on each Kaa !!! tip "No DNS?" You can use **[nip.io](https://nip.io)** against your AZ's public IP, for example `local.1.2.3.4.nip.io`. - Keep in mind that if you have multiple AZ's, the disaster recovery function will not work in this configuration. + Using a local node IP is also possible, but beware of [current limitations](../../../operations/limitations.md#nat-gateway-traffic-to-its-host-node). + + If you have multiple AZ's, keep in mind that the disaster recovery function will not work in these configurations. diff --git a/docs/paas/kaas/user-guides/advanced-configuration.md b/docs/paas/kaas/user-guides/advanced-configuration.md index 389b7301..1d91dc2e 100644 --- a/docs/paas/kaas/user-guides/advanced-configuration.md +++ b/docs/paas/kaas/user-guides/advanced-configuration.md @@ -87,6 +87,6 @@ ArgoCD connection and git repository. To assist in such endeavours, KaaS cluster This configmap is called `spx-cluster-info` and can be found in the `kube-system` namespace. It provides the following information under a `cluster` key: - **clusterID**: The unique SPXID of the cluster. -- **friendlyName**: User-defined, humand readable name. +- **friendlyName**: User-defined, human-readable name. - **kubeVersion**: Kubernetes release version. - **name**: Name of the cluster, used to generate its ID. Either UUIDv4 for console deployment or same as *friendlyName* for GitOps clusters. diff --git a/zensical.toml b/zensical.toml index 8b8c8ab9..68c512ee 100644 --- a/zensical.toml +++ b/zensical.toml @@ -187,6 +187,10 @@ authors_profiles = true [project.plugins.redirects.redirect_maps] "index.md" = "home.md" +"paas/kaas/basic-operations.md" = "paas/kaas/user-guides/basic-operations.md" +"paas/kaas/advanced-configuration.md" = "paas/kaas/user-guides/advanced-configuration.md" +"paas/kaas/disaster-recovery.md" = "paas/kaas/user-guides/disaster-recovery.md" +"paas/kaas/network-configuration.md" = "paas/kaas/user-guides/network-configuration.md" # SEO and meta tags [[project.extra.meta]] From ee2708db390e4b62835a7d0856f232f088fc4ad4 Mon Sep 17 00:00:00 2001 From: florent1s Date: Tue, 10 Nov 2026 09:02:13 +0100 Subject: [PATCH 6/6] docs(kaas): update cluster-info CM details Signed-off-by: florent1s --- docs/paas/kaas/user-guides/advanced-configuration.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/paas/kaas/user-guides/advanced-configuration.md b/docs/paas/kaas/user-guides/advanced-configuration.md index 1d91dc2e..ab65f3e6 100644 --- a/docs/paas/kaas/user-guides/advanced-configuration.md +++ b/docs/paas/kaas/user-guides/advanced-configuration.md @@ -90,3 +90,8 @@ This configmap is called `spx-cluster-info` and can be found in the `kube-system - **friendlyName**: User-defined, human-readable name. - **kubeVersion**: Kubernetes release version. - **name**: Name of the cluster, used to generate its ID. Either UUIDv4 for console deployment or same as *friendlyName* for GitOps clusters. +- **organizationID**: SPXID of the organization. +- **projectID**: SPXID of the project. +- **location**: AZ in which the cluster is deployed. + +You can also find those values here: [kaas-essentials](https://github.com/super-phenix/superphenix/blob/main/components/dependencies/kaas-essentials/values.yaml).