Skip to content

chore: improve install documentation #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SkalaNetworks merged 1 commit into from
Nov 12, 2026
Merged

chore: improve install documentation #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/installation/deployment-guide/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
244 changes: 50 additions & 194 deletions docs/installation/deployment-guide/installing-an-az/configuring-a-cluster.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.<name>.
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.<name>.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.
2 changes: 1 addition & 1 deletion docs/installation/deployment-guide/installing-an-az/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions docs/installation/deployment-guide/installing-an-az/installing-hyperconverged.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
Loading
Loading