From 09281a33e6b7c7004f28f0bf74362eac3d6e909e Mon Sep 17 00:00:00 2001 From: SkalaNetworks Date: Thu, 12 Nov 2026 08:45:56 +0100 Subject: [PATCH] chore: improve install documentation Signed-off-by: SkalaNetworks --- docs/installation/deployment-guide/index.md | 2 +- .../installing-an-az/configuring-a-cluster.md | 244 ++++-------------- .../installing-an-az/index.md | 2 +- .../installing-hyperconverged.md | 4 +- .../full-configuration.md | 51 +--- .../installing-management/index.md | 30 +-- .../management-inside-az.md | 4 +- .../management-outside-az.md | 24 +- .../automated-os-installation.md | 2 +- docs/operations/adding-an-az.md | 2 +- .../applying-configuration-changes.md | 32 ++- .../management/changing-the-ingress-class.md | 44 ++++ .../configuring-postgres-storage.md | 41 +++ docs/reference/crds/cluster.md | 2 +- docs/reference/helm/index.md | 2 +- docs/reference/helm/superphenix-operator.md | 6 +- zensical.toml | 4 +- 17 files changed, 214 insertions(+), 282 deletions(-) create mode 100644 docs/operations/management/changing-the-ingress-class.md create mode 100644 docs/operations/management/configuring-postgres-storage.md diff --git a/docs/installation/deployment-guide/index.md b/docs/installation/deployment-guide/index.md index e682a8d3..c7fec250 100644 --- a/docs/installation/deployment-guide/index.md +++ b/docs/installation/deployment-guide/index.md @@ -65,7 +65,7 @@ Superphenix supports two provisioning models: bootstrap Talos clusters yourself, ## Installing an Availability Zone -Each **availability zone** runs the full Superphenix stack on Talos Kubernetes clusters. Choose how storage and workloads are deployed within the AZ. You can install multiple AZs with different topologies under the same management plane. +Each **availability zone** runs the full Superphenix stack on Kubernetes clusters. Choose how storage and workloads are deployed within the AZ. You can install multiple AZs with different topologies under the same management plane. Superphenix supports both **hyperconverged** (with the storage and workload running on the same cluster) and **decoupled** (separate clusters for the storage and the workload) installations. diff --git a/docs/installation/deployment-guide/installing-an-az/configuring-a-cluster.md b/docs/installation/deployment-guide/installing-an-az/configuring-a-cluster.md index 0e12812d..2540adff 100644 --- a/docs/installation/deployment-guide/installing-an-az/configuring-a-cluster.md +++ b/docs/installation/deployment-guide/installing-an-az/configuring-a-cluster.md @@ -1,207 +1,63 @@ # Configure a cluster -When you define a `Cluster` resource, you specify the topology, geography, and connection details. The field reference is [Cluster](../../../reference/crds/cluster.md). Below is an example configuration for a remote workload cluster: +An availability zone is an entry under `clusters` in the `superphenix-operator` values. The key is the zone code: `local` when the zone runs on the management cluster, and the code you chose otherwise. Add the entry to the values file you already use for the operator, then [upgrade the release](../../../operations/applying-configuration-changes.md#apply-a-change). + +[Installing hyperconverged](installing-hyperconverged.md) and [Installing decoupled](installing-decoupled.md) are the two layouts. Every field on an entry is listed on [Cluster](../../../reference/crds/cluster.md). The applications you can set on that cluster are the [superphenix-system](../../../reference/helm/superphenix-system.md) chart. ```yaml -apiVersion: operator.superphenix.net/v1alpha1 -kind: Cluster -metadata: - name: az-paris-1 - namespace: superphenix-system -spec: - # Hyperconverged, or Decoupled. Empty only for a management cluster (type Management). - deploymentTopology: Decoupled - - # Required when deploymentTopology is Decoupled: Storage or Workload. - # Required when deploymentTopology is empty: Management. - type: Workload - - # -- Geography information - region: europe-west - availabilityZone: paris-1 - - # -- Connection - # Defines how the operator connects to the cluster. - connection: - mode: Remote - url: https://api.paris-1.superphenix.net:6443 - secretRef: - name: cluster-paris-1-credentials - namespace: superphenix-system - - # Optional. Semantic version of the cluster. Empty inherits the operator's system chart version. - version: v0.1.0 - # Optional. Empty uses the operator defaults (ghcr.io/super-phenix/charts, superphenix-system). - systemLocation: - repoURL: ghcr.io/super-phenix/charts - chartName: superphenix-system - - # Passed through to the superphenix-system chart. Per-application overrides live under apps.. - systemConfiguration: {} - - lifecycle: - pause: false - manual: false - cleanupOnDeletion: false - - # Unmanaged (default) - Talos is installed outside the operator. - # Import - the operator imports an already installed Talos cluster and manages its configuration. - # Full - the operator installs and configures Talos. - talosManagementMode: Unmanaged +clusters: + paris-1: + deploymentTopology: Decoupled # Hyperconverged, or Decoupled + type: Workload # Storage or Workload when Decoupled + region: europe-west + availabilityZone: paris-1 + connection: + mode: Remote # Local when this is the cluster that runs the operator + url: https://api.paris-1.example.net:6443 + secretRef: + name: cluster-paris-1-credentials + namespace: superphenix-system + lifecycle: + pause: false + manual: false + cleanupOnDeletion: false + systemConfiguration: + apps: + kubeovn: + values: + masterNodes: "192.168.1.10,192.168.1.11,192.168.1.12" ``` -Set `connection.mode: Local` when the cluster being defined is the same Kubernetes cluster that hosts the operator (typical for management-on-AZ after bootstrap). +`connection.mode: Local` is the cluster where the operator is running. `Remote` needs the API address and a Secret with the connection credentials. You can put those credentials under `connection.credentials` instead of creating the Secret yourself. The credential fields are in the [operator chart values](https://github.com/super-phenix/superphenix/blob/main/components/system/superphenix-operator/values.yaml). -## talos-manager configuration +`version` selects the Superphenix release for this cluster. Leave it empty to use the operator's chart version. `systemLocation.repoURL` and `systemLocation.chartName` select a different system chart. Leave them empty to use `ghcr.io/super-phenix/charts` and `superphenix-system`. -If you want to use the [:octicons-arrow-right-24: automated OS installation method](../installing-the-os/automated-os-installation.md), you need to specify the configuration for the talos-manager chart using the field `talosManagerConfiguration`, as well as set `talosManagementMode` to either `Full` or `Import` in your `Cluster`'s specs. Below are the values of this chart: +## systemConfiguration -```yaml -# Cluster specific variables: -# Enable PXE features (optional, overrides the value set automatically by the operator depending on "talosManagementMode"): -pxeEnabled: false -# Network interface the DHCP server should listen to (optional if "talosManagementMode" set to "Import" or if "pxeEnabled" set to "false"): -dhcpInterface: "" -# IP address of the PXE server (the bootstrap server) (optional if "talosManagementMode" set to "Import" or if "pxeEnabled" set to "false"): -pxeIpAddr: "" -# Name of the Talos cluster: -clusterName: "" -# Cluster type (can be either "storage" or "virt"): -clusterType: "" -# Reconciliation mode of the Talos configuration, as defined by talos-operator ("Reconcile", "Disable" or "DryRun"): -reconciliationMode: "" -# Cluster network specifications: -clusterNetwork: - ipv4: "" - ipv6: "" - cidrIpv4: 0 - cidrIpv6: 0 - vlanId: 0 - gatewayIpv4: "" - gatewayIpv6: "" - linkMtu: 0 -# Public network specifications (optional if "clusterType" is not "storage"): -publicNetwork: - ipv4: "" - ipv6: "" - cidrIpv4: 0 - cidrIpv6: 0 - vlanId: 0 - linkMtu: 0 -# Storage network specifications (optional): -storageNetwork: - ipv4: "" - ipv6: "" - cidrIpv4: 0 - cidrIpv6: 0 - vlanId: 0 - linkMtu: 0 -# Kubernetes pod subnets specifications: -podSubnets: - ipv4: "" - ipv6: "" - cidrIpv4: 0 - cidrIpv6: 0 -# Kubernetes service subnets specifications: -serviceSubnets: - ipv4: "" - ipv6: "" - cidrIpv4: 0 - cidrIpv6: 0 -# IPv4 address of the Talos control plane node (optional if "controlplaneIpv6" is set): -controlplaneIpv4: "" -# IPv6 address of the Talos control plane node: -controlplaneIpv6: "" -# Port of the Talos control plane: -controlplanePort: 0 -# ArgoCD token: -argocdToken: "" -# Version of Talos to install on nodes: -talosVersion: "" -# Version of Kubernetes to install on Talos: -k8sVersion: "" -# 'MachineConfig' overrides for all types of nodes (array, optional): -machineGlobalOverrides: [] -# 'MachineConfig' overrides for control plane nodes (array, optional). -# Control planes must enable MutatingAdmissionPolicy: -machineOverridesControlPlane: - - cluster: - controllerManager: - extraArgs: - feature-gates: "MutatingAdmissionPolicy=true" - apiServer: - extraArgs: - feature-gates: "MutatingAdmissionPolicy=true" - runtime-config: "admissionregistration.k8s.io/v1beta1=true" -# 'MachineConfig' overrides for worker nodes (array, optional): -machineOverridesWorker: [] - -# Nodes specific variables: -nodes: - - hostname: "" - # Talos node type (can be either "controlplane" or "worker"): - type: "" - # CPU architecture of this node (optional if "talosManagementMode" set to "Import" or if "pxeEnabled" set to "false"): - cpuArchitecture: "" - # MAC address used by the PXE firmware (optional if "talosManagementMode" set to "Import" or if "pxeEnabled" set to "false"): - pxeMacAddress: "" - # Kernel command line arguments when booting in PXE (optional): - kernelCmdlineArgs: "" - # Specifies whether this machine should be set up for PXE: - pxeSetup: false - # IPv4 address of the node's IPMI (optional if "pxeSetup" set to "false"): - ipmiIpv4: "" - # Username of an administrator account on the IPMI (optional if "pxeSetup" set to "false"): - ipmiUser: "" - # Password of the aforementioned IPMI account (optional if "pxeSetup" set to "false"): - ipmiPassword: "" - # Name of the interface used by the PXE firmware, as given by the IPMI through Redfish (optional if "pxeSetup" set to "false"): - pxeInterfaceName: "" - # Specifications of the network interface: - interface: - # Name to give to the interface (avoid common names such as "ethX" or "enoXnpY"): - name: "" - # IP of this node on the cluster network (IPv6 is optional): - clusterNetwork: - ipv4: "" - ipv6: "" - # IP of this node on the public network (optional if "clusterType" is not "storage"): - publicNetwork: - ipv4: "" - ipv6: "" - # IP of this node on the storage network (optional): - storageNetwork: - ipv4: "" - ipv6: "" - # Specifies whether this interface should be connected to VLANs: - useVlan: false - # Specifications of the LACP bond, if applicable (setting "enabled" to "false" makes other sub-fields optional): - lacpBond: - enabled: false - lacpRate: "" - xmitHashPolicy: "" - miimon: 0 - updelay: 0 - downdelay: 0 - linkMtu: 0 - # Physical interfaces to be aggregated: - physicalInterfaces: - - name: "" - macAddress: "" - # MAC address of the single physical interface, if bond is disabled: - physicalMacAddress: "" - # Specifications of the installation disk: - installDisk: - # Indicates whether the installation disk should be selected automatically ("true" makes other sub-fields optional): - auto: false - # Selector for the installation disk, if not selected automatically (this is the same as the "diskSelector" field from the Talos documentation : https://docs.siderolabs.com/talos/v1.13/reference/configuration/v1alpha1/config#diskselector): - selector: "" - # 'MachineConfig' overrides for this node (array, optional): - machineOverrides: [] -``` +`systemConfiguration` is the configuration of the stack on this cluster. Each application is set under `apps..values`. + +The chart installs an application only when this cluster's layout is one that application supports: hyperconverged, decoupled storage, decoupled workload, or management. An application with no layout list is installed on every cluster where it is enabled. + +Every application and every value it accepts is in the [superphenix-system](../../../reference/helm/superphenix-system.md) reference. + +## Lifecycle {#lifecycle} + +`lifecycle` controls how this cluster's applications are synchronized. All three switches default to `false`. Day-2 use of the same switches, including on the management plane, is in [Applying configuration changes](../../../operations/applying-configuration-changes.md#lifecycle). + +## Talos + +`talosManagementMode` says who installs Talos on the nodes. The default is `Unmanaged`. + +| Value | Effect | +|-------|--------| +| `Unmanaged` | You install and configure Talos. The operator connects to the cluster you already have. | +| `Import` | Talos is already installed. The operator takes over its configuration. | +| `Full` | The operator installs and configures Talos. | + +`Import` and `Full` take their settings from `talosManagerConfiguration` on the same entry. Every key is on the [talos-manager](../../../reference/helm/talos-manager.md) chart. The install path is [Automated OS installation](../installing-the-os/automated-os-installation.md). ## Related -- [Installing an AZ](index.md): overview of AZ installation. +- [Installing an AZ](index.md): where this values file sits in the install. - [Adding a storage class](../../../operations/storage/adding-a-storage-class.md): hyperconverged and decoupled storage. -- [Deployment topology](../../../architecture/deployment-topology.md): hyperconverged vs decoupled layouts. +- [Deployment topology](../../../architecture/deployment-topology.md): hyperconverged and decoupled layouts. diff --git a/docs/installation/deployment-guide/installing-an-az/index.md b/docs/installation/deployment-guide/installing-an-az/index.md index bf237646..6f64e347 100644 --- a/docs/installation/deployment-guide/installing-an-az/index.md +++ b/docs/installation/deployment-guide/installing-an-az/index.md @@ -11,5 +11,5 @@ You then describe the AZ in the `superphenix-operator` Helm values, under `clust - **[Installing hyperconverged](installing-hyperconverged.md)**: storage and virtualization on the same cluster. - **[Installing decoupled](installing-decoupled.md)**: dedicated storage and workload clusters. -- **[Configure a cluster](configuring-a-cluster.md)**: geography, connection mode, and system configuration for a `Cluster` resource. +- **[Configure a cluster](configuring-a-cluster.md)**: operator values for an availability zone, including system configuration and lifecycle. - **[Adding a storage class](../../../operations/storage/adding-a-storage-class.md)**: attach storage to hyperconverged or decoupled clusters. diff --git a/docs/installation/deployment-guide/installing-an-az/installing-hyperconverged.md b/docs/installation/deployment-guide/installing-an-az/installing-hyperconverged.md index 9cbb536d..ea94371a 100644 --- a/docs/installation/deployment-guide/installing-an-az/installing-hyperconverged.md +++ b/docs/installation/deployment-guide/installing-an-az/installing-hyperconverged.md @@ -10,7 +10,7 @@ In a **hyperconverged** AZ, **storage** and **workload** run on the same Superph ## AZ on the management cluster -When this hyperconverged AZ runs on the same Kubernetes cluster as the management plane, the operator chart key is **`local`**. The API already lists that AZ. See [The default local AZ](../installing-management/index.md#the-default-local-az). Do not add a second `clusters` entry for that same cluster. +When this hyperconverged AZ runs on the same Kubernetes cluster as the management plane, the operator chart key is **`local`**. The API already lists that AZ, displayed as **Local AZ**. Do not add a second `clusters` entry for that same cluster. ## Install with the operator chart @@ -104,7 +104,7 @@ clusters: After the stack is installed, register that AZ with the console. The `local` entry is already registered. Every other AZ needs an API and controller entry: [Add an availability zone](../../../operations/adding-an-az.md). -The full field list is in [Configure a cluster](configuring-a-cluster.md) and the [operator chart values](https://github.com/super-phenix/superphenix/blob/main/components/system/superphenix-operator/values.yaml). +The fields on a cluster entry are in [Configure a cluster](configuring-a-cluster.md). The applications you can set are in the [superphenix-system](../../../reference/helm/superphenix-system.md) reference. ## Related diff --git a/docs/installation/deployment-guide/installing-management/full-configuration.md b/docs/installation/deployment-guide/installing-management/full-configuration.md index 9610caf5..54fdf166 100644 --- a/docs/installation/deployment-guide/installing-management/full-configuration.md +++ b/docs/installation/deployment-guide/installing-management/full-configuration.md @@ -1,31 +1,16 @@ # Configuring the management stack -The management plane is configured once, through the `superphenix-operator` Helm values, whether it runs [inside an AZ](management-inside-az.md) or [outside an AZ](management-outside-az.md). Both install procedures use the file described here. +The management plane is configured through the `superphenix-operator` Helm values, whether it runs [inside an AZ](management-inside-az.md) or [outside an AZ](management-outside-az.md). Both install procedures use the file described here. -The operator installs two things on the management cluster: - -- **ArgoCD**, from the operator chart, which synchronizes every Superphenix application. -- A `Cluster` of type `Management`. Its `systemConfiguration` is passed to the [superphenix-system](https://github.com/super-phenix/superphenix/tree/main/components/system/superphenix-system) chart, which renders one ArgoCD `Application` per management component. +The console, the API, Kratos, Permify, and PostgreSQL are set under `management.systemConfiguration`. Argo CD is set under `config.argocd`. Full upstream values: -- [Installing outside an AZ](management-outside-az.md): placement model and operator install. -- [Configure a cluster](../installing-an-az/configuring-a-cluster.md): `Cluster` resource fields for workload AZs. +- [Configure a cluster](../installing-an-az/configuring-a-cluster.md): operator values for a workload availability zone. - [Cluster toolbox](../../../operations/accessing-superphenix.md#use-the-cluster-toolbox): enable a shell with access to every managed cluster. - [superphenix-operator `values.yaml`](https://github.com/super-phenix/superphenix/blob/main/components/system/superphenix-operator/values.yaml) - [superphenix-system `values.yaml`](https://github.com/super-phenix/superphenix/blob/main/components/system/superphenix-system/values.yaml) -## What the management cluster must provide - -The management applications expect a **storage class** and an **ingress controller** on the cluster where they run. - -| Need | Used by | Where it comes from | -|------|---------|---------------------| -| Persistent volume | PostgreSQL (default **8Gi**) | A default `StorageClass` on the management cluster | -| HTTP on ports 80 and 443 | Console, API, Kratos, and ArgoCD | An ingress controller. Superphenix AZs use Traefik from the system chart | - -On a dedicated management cluster, provide both before you rely on the console. When management runs inside an AZ, Rook and Traefik are installed with that AZ, so the console stays unavailable until the AZ is installed. See [Installing inside an AZ](management-inside-az.md#console-availability). - ## Values file Create `values.yaml` and pass it to Helm from the placement guide you are following. Replace every example secret and hostname. @@ -44,14 +29,10 @@ config: hostname: argocd.example.org # or argocd.192.168.1.10.nip.io management: - # Optional. Defaults to "management". - region: management - availabilityZone: management lifecycle: # Set true to disable autosync of every management application. + # You'll have to apply any modification through ArgoCD by yourself. manual: false - pause: false - cleanupOnDeletion: false systemConfiguration: apps: superphenix-console: @@ -71,7 +52,7 @@ management: size: 8Gi ``` -`management.systemConfiguration` is copied onto the management `Cluster` and becomes the Helm values of `superphenix-system`. Per-application overrides live under `apps.`, matching the keys in the system chart. +Each application is configured under `apps..values`. ## DNS @@ -85,17 +66,13 @@ On a Superphenix AZ, Traefik listens on **every node** on ports **80** and **443 !!! warning "NAT gateway traffic to a node" Due to a macvlan limitation, traffic from a NAT gateway is blackholed when its destination is an address on the node hosting that gateway. VMs and Kubernetes as a Service clusters can therefore lose access to the console when DNS points directly at a node. Put a load balancer in front of the nodes and point DNS at the load balancer. See [Limitations](../../../operations/limitations.md#nat-gateway-traffic-to-its-host-node). -One hostname serves the whole console stack. The system chart publishes: -| Path | Component | TLS secret | -|------|-----------|------------| -| `/` | Web console | `superphenix-console-tls` | -| `/api` | API | `superphenix-api-tls` | -| `/accounts` | Kratos (login, registration, recovery) | `kratos-public-tls` | +TLS certificates are generated and updated automatically if the management is installed within an AZ. +If you're installing the management on a standalone cluster and wish for certificates to be auto-generated, you need to install cert-manager. -Ingress TLS annotations for cert-manager (`cert-manager.io/cluster-issuer: letsencrypt`) are present in the chart and commented out. Cert-manager is installed with an AZ (hyperconverged, storage, or workload), not with the management components. +## Ingress class and storage class -If you're installing the management on a standalone cluster and wish for certificates to be auto-generated, you need to install cert-manager. +The console, API, Kratos, and Argo CD use the cluster's default ingress class. PostgreSQL uses the cluster's default storage class. Name a different ingress class in [Changing the ingress class](../../../operations/management/changing-the-ingress-class.md). The database volume is covered in [Configuring Postgres storage](../../../operations/management/configuring-postgres-storage.md). ## Management components @@ -124,7 +101,7 @@ The API ingress is enabled on the console domain at `/api`. It connects to Postg `userIsActiveOnCreate` defaults to `true`, so a self-service registration can sign in immediately. [Validating users manually](../../../operations/management/validating-users.md) holds new accounts until an administrator activates them. [Accessing Superphenix](../../../operations/accessing-superphenix.md) describes the login page. -The chart's local AZ entry (`config.azs.local`) points the API at an in-cluster Superphenix controller named "Local AZ". Keep it when a hyperconverged AZ runs on this cluster. Set it to `null` when it does not. See [The default local AZ](index.md#the-default-local-az). Register any other AZ with [Add an availability zone](../../../operations/adding-an-az.md). +The chart's local AZ entry (`config.azs.local`) points the API at an in-cluster Superphenix controller named "Local AZ". Keep it when a hyperconverged AZ runs on this cluster. Set it to `null` when it does not, as in [Installing outside an AZ](management-outside-az.md#prepare-the-operator-values). Register any other AZ with [Add an availability zone](../../../operations/adding-an-az.md). ### Kratos @@ -149,7 +126,7 @@ One instance backs the three databases used by Superphenix components. Override `apps.postgres.values.auth.password`. The chart default is a public placeholder. The same value is substituted into the API, Kratos, and Permify configuration, so it only needs to be set on the `postgres` application. -`apps.postgres.values.persistence.size` defaults to `8Gi`, which the chart describes as enough for most deployments. The volume uses the cluster default storage class. No storage class name is set in the chart. +The volume size defaults to **8Gi** and the volume uses the cluster default storage class. [Configuring Postgres storage](../../../operations/management/configuring-postgres-storage.md) changes the size and the class. The operator connects to this database itself when `config.database.autoConnect` is `true` (the default): it reads the `postgres` secret. To point the operator at another database, set `config.database.host`, `port`, `user`, `password`, and `name`, and set `autoConnect` to `false`. @@ -163,7 +140,7 @@ Disabled by default (`apps.idrac-exporter.enabled: false`). Enable it to scrape ## ArgoCD -ArgoCD is installed by the operator chart. `config.argocd.values` is merged into the ArgoCD Helm values. The setting you need at install time is the ingress hostname, under `server.ingress.hostname`, as in the example above. +ArgoCD is installed by the operator chart. `config.argocd.values` is merged into the ArgoCD Helm values. The setting you need at install time is the ingress hostname, under `server.ingress.hostname`, as in the example above. [Changing the ingress class](../../../operations/management/changing-the-ingress-class.md) names the class for this route and for the console, the API, and Kratos. `config.argocd.ha.enabled: true` turns on Redis HA and autoscaling for the server and repo server. @@ -173,7 +150,7 @@ After the ingress controller is serving traffic, sign in as described in [Access ## Operator lifecycle -These fields are copied onto the management `Cluster`: +Set these fields in the same values file: | Field | Effect | |-------|--------| @@ -181,7 +158,7 @@ These fields are copied onto the management `Cluster`: | `management.lifecycle.pause` | Pauses synchronization of the management stack. | | `management.lifecycle.cleanupOnDeletion` | Cascade-deletes managed resources when the management cluster object is removed. | | `management.region`, `management.availabilityZone` | Labels stored on the management cluster. Default `management`. End users do not see this cluster as an AZ. | -| `management.version` | Superphenix version for the management `Cluster`. Empty inherits the operator chart version. Must be a semantic version. | +| `management.version` | Superphenix version of the management stack. Empty inherits the operator chart version. Must be a semantic version. | | `management.systemLocation.repoURL`, `management.systemLocation.chartName` | Override the system chart repository and name. The operator default is `ghcr.io/super-phenix/charts` and `superphenix-system`. There is no version field on `systemLocation`. | `installOnClusterWithoutCNI` is an operator-chart flag, not a system-chart value. When `true`, the operator and ArgoCD tolerate `NotReady` nodes and use the host network, so they can run before a CNI exists. [Installing inside an AZ](management-inside-az.md) sets it to `true` until Kube-OVN is healthy, then back to `false`. A management cluster that already has a CNI leaves it `false`. diff --git a/docs/installation/deployment-guide/installing-management/index.md b/docs/installation/deployment-guide/installing-management/index.md index f0a77bf4..ca413b6a 100644 --- a/docs/installation/deployment-guide/installing-management/index.md +++ b/docs/installation/deployment-guide/installing-management/index.md @@ -1,6 +1,6 @@ # Installing management plane -Superphenix is installed through an operator running on the management cluster. The operator installs each Superphenix cluster from the configuration in its `Cluster` resource, and it owns installation, upgrades, and lifecycle for those clusters. +Superphenix is installed through an operator running on the management cluster. The operator installs each Superphenix cluster remotely or locally, and it owns installation, upgrades, and lifecycle for those clusters. On the management cluster itself, the operator installs ArgoCD and a `Cluster` of type `Management`. That cluster pulls the management applications from the [superphenix-system](https://github.com/super-phenix/superphenix/tree/main/components/system/superphenix-system) chart: @@ -8,34 +8,6 @@ On the management cluster itself, the operator installs ArgoCD and a `Cluster` o - PostgreSQL, shared by the API, Kratos, and Permify - The Talos operator and the iDRAC exporter, both optional and disabled by default -Storage for the database and ingress for HTTP are not part of that management set. They have to exist on the management cluster. When management runs inside an AZ, they arrive with the local AZ. See [Configuring the management stack](full-configuration.md). - -## The default local AZ - -The system chart registers one AZ with the API under the code **`local`**, displayed as **Local AZ**. - -That entry is the hyperconverged AZ that shares the management cluster. Install it with the operator chart key `clusters.local`, as described in [Installing hyperconverged](../installing-an-az/installing-hyperconverged.md). - -When this management cluster should not run an AZ, disable that default. Set `local` to `null` in the API configuration, and do not set `clusters.local`: - -```yaml -management: - systemConfiguration: - apps: - superphenix-api: - values: - config: - azs: - local: null - productsConfig: - argoApp: - kubernetes: - azDomains: - local: null -``` - -[Installing outside an AZ](management-outside-az.md) uses this override. [Add an availability zone](../../../operations/adding-an-az.md) covers registering every other AZ with the API and its controller. - ## Next steps - [Installing inside an AZ](management-inside-az.md) or [Installing outside an AZ](management-outside-az.md): install the operator for your placement. diff --git a/docs/installation/deployment-guide/installing-management/management-inside-az.md b/docs/installation/deployment-guide/installing-management/management-inside-az.md index e652fb06..f8d00750 100644 --- a/docs/installation/deployment-guide/installing-management/management-inside-az.md +++ b/docs/installation/deployment-guide/installing-management/management-inside-az.md @@ -24,8 +24,6 @@ This cluster has no CNI yet, so the operator and its ArgoCD instance must schedu installOnClusterWithoutCNI: true ``` -While the local AZ is still absent, you can hold GitOps synchronization of the management applications by setting `management.lifecycle.manual: true` in the same file. Set it back to `false` once storage and ingress from that AZ are healthy. The field is described in [Configuring the management stack](full-configuration.md#operator-lifecycle). - ## 2. Install the operator ```bash @@ -61,6 +59,6 @@ The `management` cluster should be listed. PostgreSQL stays pending until a stor ## Next steps -1. [Installing hyperconverged](../installing-an-az/installing-hyperconverged.md) on this cluster, using the operator chart key `clusters.local`. That AZ is already registered with the API. Do not add a second one. See [The default local AZ](index.md#the-default-local-az). +1. [Installing hyperconverged](../installing-an-az/installing-hyperconverged.md) on this cluster, using the operator chart key `clusters.local`. That AZ is already registered with the API under the code **`local`**, displayed as **Local AZ**. Do not add a second one. 2. When Kube-OVN is healthy, set `installOnClusterWithoutCNI` back to `false` (and `management.lifecycle.manual` back to `false` if you enabled it) and run the Helm command again with the same values file. 3. [Accessing Superphenix](../../../operations/accessing-superphenix.md): open the console, retrieve the initial ArgoCD password, and follow synchronization. diff --git a/docs/installation/deployment-guide/installing-management/management-outside-az.md b/docs/installation/deployment-guide/installing-management/management-outside-az.md index e1adbce0..3bcca311 100644 --- a/docs/installation/deployment-guide/installing-management/management-outside-az.md +++ b/docs/installation/deployment-guide/installing-management/management-outside-az.md @@ -12,14 +12,30 @@ Provide a Kubernetes cluster that will host only the management plane. From the - **Helm** is installed ([install Helm](https://helm.sh/docs/intro/install/)). - The cluster is Kubernetes **v1.28+**. It can be Talos, another distribution, or a cluster hosted on another cloud. - The cluster can reach the **Kubernetes API** of every Superphenix AZ it will manage. -- A default **StorageClass** and an **ingress controller** are already running. PostgreSQL, the console, and ArgoCD use them, and the management components do not install Rook or Traefik. +- A default **StorageClass** and an **ingress controller** are already running. PostgreSQL, the console, and ArgoCD use them. - A CNI to operate the network of the cluster -## 1. Prepare the operator values +## 1. Prepare the operator values {#prepare-the-operator-values} Create a `values.yaml` for the `superphenix-operator` chart. Copy the management settings from [Configuring the management stack](full-configuration.md): console domain, Kratos secret, PostgreSQL password, and ArgoCD hostname. -This cluster does not host an AZ. Disable the default `local` AZ as described in [The default local AZ](index.md#the-default-local-az). +This cluster does not host an AZ. The system chart would otherwise register one with the API under the code **`local`**, displayed as **Local AZ**. Disable that default. Set `local` to `null` in the API configuration: + +```yaml +management: + systemConfiguration: + apps: + superphenix-api: + values: + config: + azs: + local: null + productsConfig: + argoApp: + kubernetes: + azDomains: + local: null +``` ## 2. Install the operator @@ -33,7 +49,7 @@ helm upgrade --install superphenix-operator \ -f values.yaml ``` -The chart creates a `Cluster` named `management`. The operator then installs the [superphenix-system](https://github.com/super-phenix/superphenix/tree/main/components/system/superphenix-system) management components on this cluster: the web console, API, Kratos, Permify, and PostgreSQL, together with ArgoCD. Optional components stay disabled unless you enable them in the configuration file. +The chart creates a `Cluster` named `management`. The operator then installs the [superphenix-system](https://github.com/super-phenix/superphenix/tree/main/components/system/superphenix-system) management components on this cluster: the web console, API, Kratos, Permify, and PostgreSQL, together with ArgoCD. Confirm the operator is up: diff --git a/docs/installation/deployment-guide/installing-the-os/automated-os-installation.md b/docs/installation/deployment-guide/installing-the-os/automated-os-installation.md index c7a3cab4..8e8b129f 100644 --- a/docs/installation/deployment-guide/installing-the-os/automated-os-installation.md +++ b/docs/installation/deployment-guide/installing-the-os/automated-os-installation.md @@ -163,7 +163,7 @@ Set `connection.mode: Local` when the cluster being defined is the same Kubernet Set `talosManagementMode: Full` to let talos-operator boot, install and configure Talos automatically, or `talosManagementMode: Import` to import an already installed Talos cluster and let talos-operator manage its lifecycle. -See [Configure a cluster](../installing-an-az/configuring-a-cluster.md) for the full field reference. +See [Configure a cluster](../installing-an-az/configuring-a-cluster.md) for where these values sit on a cluster entry, and the [talos-manager chart](../../../reference/helm/talos-manager.md) for every key. ## Step 3: Reconcile and verify diff --git a/docs/operations/adding-an-az.md b/docs/operations/adding-an-az.md index 5a3af84e..46744f60 100644 --- a/docs/operations/adding-an-az.md +++ b/docs/operations/adding-an-az.md @@ -8,7 +8,7 @@ Install the [management plane](../installation/deployment-guide/installing-manag A hyperconverged AZ on the management cluster is already registered. The system chart defines it under the code **`local`**, with destination `in-cluster`. Install that AZ as `clusters.local`. Do not add a second code for the same cluster. -See [The default local AZ](../installation/deployment-guide/installing-management/index.md#the-default-local-az). Set `local` to `null` there when the management cluster should not host an AZ. +When the management cluster should not host an AZ, set `local` to `null` while [preparing the operator values](../installation/deployment-guide/installing-management/management-outside-az.md#prepare-the-operator-values). ## Add any other AZ diff --git a/docs/operations/applying-configuration-changes.md b/docs/operations/applying-configuration-changes.md index 075b1f48..9d175936 100644 --- a/docs/operations/applying-configuration-changes.md +++ b/docs/operations/applying-configuration-changes.md @@ -1,10 +1,10 @@ # Applying configuration changes -Changes to the management plane and to an availability zone are values on the `superphenix-operator` release. The operator writes those values onto a `Cluster` resource, and Argo CD syncs the applications on that cluster. +Changes to the management plane and to an availability zone are values on the `superphenix-operator` release. Add them to the values file, then upgrade the release. Argo CD applies the applications. ## Management plane -Management applications (the console, the API, Kratos, Permify, and PostgreSQL) are set under `management.systemConfiguration`. That object is copied onto the management `Cluster`. +Management applications (the console, the API, Kratos, Permify, and PostgreSQL) are set under `management.systemConfiguration`. ```yaml management: @@ -38,6 +38,32 @@ clusters: name: ceph.admin.example.org ``` +## Lifecycle {#lifecycle} + +`lifecycle` decides whether an upgrade is applied on its own. The same three switches exist for the management plane (`management.lifecycle`) and for each availability zone (`clusters..lifecycle`). All three default to `false`. [Configure a cluster](../installation/deployment-guide/installing-an-az/configuring-a-cluster.md#lifecycle) is the same list on an availability-zone entry. + +```yaml +management: + lifecycle: + pause: false + manual: false + cleanupOnDeletion: false +clusters: + paris-1: + lifecycle: + pause: false + manual: false + cleanupOnDeletion: false +``` + +| Field | Effect | +|-------|--------| +| `pause` | Synchronization stops. Automatic and manual sync both wait until you set it back to `false`. The cluster is reported as **Paused**. | +| `manual` | Automatic sync is off. The applications stay as they are until you sync them in Argo CD, or set this back to `false`. | +| `cleanupOnDeletion` | Removing this cluster also deletes the applications it installed. Leave it `false` unless you intend to remove the stack. | + +Set `manual` to `true` when the values should be saved and the applications left untouched until you sync them. Set `pause` to `true` when nothing should sync, including a sync you start by hand. Set the switch back to `false` and upgrade again to resume. + ## Upgrade the release {#apply-a-change} Add the keys to the values file you already pass for this release, then upgrade: @@ -55,4 +81,4 @@ Replace `OPERATOR_VERSION` by your vesion of Superphenix or use the latest to up Helm merges that file with the chart defaults. A later upgrade still needs the same `-f` file, or the keys you added are dropped. -Wait until the application you changed is **Synced** and **Healthy** in Argo CD before you test. [Accessing Superphenix](accessing-superphenix.md) covers opening Argo CD. +With `pause` and `manual` left at `false`, wait until the application you changed is **Synced** and **Healthy** in Argo CD before you test. While `manual` is `true`, sync that application yourself. While `pause` is `true`, the sync waits until you turn it off. [Accessing Superphenix](accessing-superphenix.md) covers opening Argo CD. diff --git a/docs/operations/management/changing-the-ingress-class.md b/docs/operations/management/changing-the-ingress-class.md new file mode 100644 index 00000000..518e8340 --- /dev/null +++ b/docs/operations/management/changing-the-ingress-class.md @@ -0,0 +1,44 @@ +# Changing the ingress class + +The console, the API, Kratos, and Argo CD publish their HTTP routes with no ingress class name. Kubernetes sends those routes to the IngressClass marked default on the management cluster. + +On an availability zone, Traefik creates that class. The name is `traefik`, and the class is the cluster default. A dedicated management cluster uses the default class of the controller you installed there. [Configuring the management stack](../../installation/deployment-guide/installing-management/full-configuration.md) is the rest of the management values. + +## Name a class {#name-a-class} + +Set the same class on every route, then [upgrade the release](../applying-configuration-changes.md#apply-a-change). The class has to exist on the cluster before the routes answer. + +```yaml +config: + argocd: + values: + server: + ingress: + ingressClassName: + +management: + systemConfiguration: + apps: + superphenix-console: + values: + ingress: + className: + superphenix-api: + values: + ingress: + className: + kratos: + values: + ingress: + public: + className: +``` + +| Route | Value | +|-------|-------| +| Console | `apps.superphenix-console.values.ingress.className` | +| API | `apps.superphenix-api.values.ingress.className` | +| Kratos | `apps.kratos.values.ingress.public.className` | +| Argo CD | `config.argocd.values.server.ingress.ingressClassName` | + +Read the class names with `kubectl get ingressclass`. The one marked default is the class these routes use while the fields above are empty. diff --git a/docs/operations/management/configuring-postgres-storage.md b/docs/operations/management/configuring-postgres-storage.md new file mode 100644 index 00000000..44658adc --- /dev/null +++ b/docs/operations/management/configuring-postgres-storage.md @@ -0,0 +1,41 @@ +# Configuring Postgres storage + +PostgreSQL stores the API, Kratos, and Permify databases on one volume. Set the size and the storage class in the operator values, then [upgrade the release](../applying-configuration-changes.md#apply-a-change). [Configuring the management stack](../../installation/deployment-guide/installing-management/full-configuration.md) is the rest of the management values. + +## Set the size {#set-the-size} + +The chart default is **8Gi**. The chart comment calls that enough for most deployments. + +```yaml +management: + systemConfiguration: + apps: + postgres: + values: + persistence: + size: 8Gi +``` + +`apps.postgres.values.persistence.size` is the volume size. Raise it to give the database more room, then upgrade the release. A value smaller than the volume that already exists is rejected. + +## Name a storage class {#name-a-class} + +The chart leaves the storage class empty, so the volume uses the cluster's default StorageClass. + +On a hyperconverged availability zone, Rook creates that default when the AZ is installed. The class name is `spx-rbd-3x`. A dedicated management cluster uses the default class you installed there. This setting is the class for the database volume. Tenant disks use [Adding a storage class](../storage/adding-a-storage-class.md). + +Set the class before PostgreSQL creates the volume: + +```yaml +management: + systemConfiguration: + apps: + postgres: + values: + persistence: + storageClass: +``` + +`apps.postgres.values.persistence.storageClass` is the class name. Read the names with `kubectl get storageclass`. The one marked default is the class the volume uses while this field is empty. + +Set the class before the first sync. Kubernetes keeps the storage class of a volume that already exists and rejects a change to that claim. diff --git a/docs/reference/crds/cluster.md b/docs/reference/crds/cluster.md index dcf0e0f4..c2aa1d3e 100644 --- a/docs/reference/crds/cluster.md +++ b/docs/reference/crds/cluster.md @@ -10,7 +10,7 @@ A **Cluster** is one Superphenix Kubernetes cluster. The operator uses it to con | **Plural** | `clusters` | | **Scope** | Namespaced | -An install example is in [Configure a cluster](../../installation/deployment-guide/installing-an-az/configuring-a-cluster.md). Talos provisioning values passed through `spec.talosManagerConfiguration` are documented on the [talos-manager chart](../helm/talos-manager.md). Values passed through `spec.systemConfiguration` are the [superphenix-system chart](../helm/superphenix-system.md). +The operator values for an install are in [Configure a cluster](../../installation/deployment-guide/installing-an-az/configuring-a-cluster.md). Talos provisioning values in `talosManagerConfiguration` are the [talos-manager chart](../helm/talos-manager.md). Values in `systemConfiguration` are the [superphenix-system chart](../helm/superphenix-system.md). ## Spec diff --git a/docs/reference/helm/index.md b/docs/reference/helm/index.md index 0e0b9c71..71640cb9 100644 --- a/docs/reference/helm/index.md +++ b/docs/reference/helm/index.md @@ -2,7 +2,7 @@ Each page lists the chart's values and the documentation that ships with that chart in the [Superphenix repository](https://github.com/super-phenix/superphenix), under `components/`. A default is the chart default. Replace placeholder secrets before use. The pages call those placeholders out when the chart says they must be overridden. -The operator installs clusters by rendering **superphenix-system**. Per-cluster overrides go in `Cluster.spec.systemConfiguration`, documented on [Cluster](../crds/cluster.md). +The operator installs clusters by rendering **superphenix-system**. Per-cluster settings go in `clusters..systemConfiguration` in the operator values. Those settings are the [superphenix-system](superphenix-system.md) values. The other fields on a cluster entry are on [Cluster](../crds/cluster.md). ## Platform diff --git a/docs/reference/helm/superphenix-operator.md b/docs/reference/helm/superphenix-operator.md index 41ba79ab..5ef0f436 100644 --- a/docs/reference/helm/superphenix-operator.md +++ b/docs/reference/helm/superphenix-operator.md @@ -354,7 +354,7 @@ true { "availabilityZone": "", "lifecycle": { - "cleanupOnDeletion": true, + "cleanupOnDeletion": false, "manual": false, "pause": false }, @@ -384,7 +384,7 @@ true object 
 {
-  "cleanupOnDeletion": true,
+  "cleanupOnDeletion": false,
   "manual": false,
   "pause": false
 }
@@ -396,7 +396,7 @@ true
 			management.lifecycle.cleanupOnDeletion
 			bool
 			
-true
+false
 

 
 			Whether to clean up resources deployed by the management stack applications when they get deleted.
diff --git a/zensical.toml b/zensical.toml
index 81bbb475..d4820c49 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -110,7 +110,9 @@ nav = [
       { "Private availability zones" = "operations/management/private-azs.md" },
       { "Default cloud-init" = "operations/management/default-cloud-init.md" },
       { "Custom CSS" = "operations/management/custom-css.md" },
-      { "Hardening exposed dashboards" = "operations/management/hardening-dashboards.md" }
+      { "Hardening exposed dashboards" = "operations/management/hardening-dashboards.md" },
+      { "Changing the ingress class" = "operations/management/changing-the-ingress-class.md" },
+      { "Configuring Postgres storage" = "operations/management/configuring-postgres-storage.md" }
     ]},
     { "Add an availability zone" = "operations/adding-an-az.md" },
     { "Add an organization quota" = "operations/adding-an-organization-quota.md" },