chore(docs): Add installation documentation by NautiluX · Pull Request #580 · codesphere-cloud/oms

NautiluX · 2026-07-16T07:27:15Z

No description provided.

clemensfreitagdev · 2026-07-16T13:06:35Z

+  k0s supports combined control-plane/worker nodes. However, the current OMS k0sctl configuration generator treats an IP present in both lists as control-plane-only and ignores the duplicate worker entry. Until combined-role generation is supported by OMS, use dedicated control-plane and worker entries in this workflow.
+- The platform and public gateways use `LoadBalancer`, or `ExternalIP` where that is the chosen integration.
+- `codesphere.domain` is `cs.<base-domain>`.
+- `codesphere.workspaceHostingBaseDomain` and the custom-domain CNAME base are `ws.<base-domain>`.


for the workspaceBaseDomain the de-facto standard we use is ., I'd put this in the Guide as well. The dcId shall be part of it.

Not sure what you mean by this, can you propose an edit?

The problem is that the codesphere.workspaceHostingBaseDomain parameter was never really configured to something else than <dataCenter.id>.<codesphere.domain> at all.
And nothing in the guide tells you that the value must differ between multiple DCs (e.g. by prefixing the datacenter id).
IMO we should

make this parameter optional and default to <dataCenter.id>.<codesphere.domain> if undefined
and

document the requirement adequately

walzph · 2026-07-16T16:37:19Z

+test -r /etc/codesphere/secrets/prod.vault.yaml
+```
+
+Run the installation from the jumpbox. The lite package does not contain the platform container images, so skip `load-container-images`; the cluster pulls them directly from GHCR using the credentials in the vault:


I think that we require --skip-steps load-container-images is just a bug. The installer script should know that it can skip this for the lite installation if configured here:

registry: loadContainerImages: false

Need to double-check, but I think I fixed that bug also 😅

nope, fails for me on csa demo cluster:

Loading container image postgres of component database. open /etc/codesphere/deps/database/images/postgres.tar: no such file or directory

still open 😅
https://github.com/codesphere-cloud/codesphere-monorepo/pull/16318

🫢 I try to rebase it tmrw

No, don't think this PR can be merged as it is. It's introducing a breaking config change.
I've moved the corresponding CU task to the PE board for triage.
Tell me if you disagree that this is an OMS task.

So you think https://github.com/codesphere-cloud/codesphere-monorepo/pull/17934 is also breaking?

nope that one looks better :) We let Manuel decide, I'd say.

I guess we can completely remove that step from the installer since we don't plan to support the full package anymore. For now I tend to leave it as is in case we need to circle back for whatever reason.

Agree, but shouldn't we fix the --skip-step bug at least?
https://github.com/codesphere-cloud/codesphere-monorepo/pull/17934 should be non breaking and we can still control the load-container-images step by using the existing config option.

walzph · 2026-07-16T16:41:04Z

+
+  ```yaml
+  kubernetes:
+    managedByCodesphere: true


Is this the current best practice? I remember SRE telling me they install it externally using k0sctl because of k8s version update issues. This information can be outdated though.
And maybe for external users, it's still better to document the intended way instead of the temporary workaround.

we have a k0sctl based installation in OMS, but not sure if and how it can be used currently. I'll collect input from the team.

clemensfreitagdev · 2026-07-17T07:06:50Z

+
+  k0s supports combined control-plane/worker nodes. However, the current OMS k0sctl configuration generator treats an IP present in both lists as control-plane-only and ignores the duplicate worker entry. Until combined-role generation is supported by OMS, use dedicated control-plane and worker entries in this workflow.
+- The platform and public gateways use `LoadBalancer`, or `ExternalIP` where that is the chosen integration.
+- `codesphere.domain` is `cs.<base-domain>`.


Suggested change

- `codesphere.domain` is `cs.<base-domain>`.

- `codesphere.domain` is `<base-domain>`, can be a sub-domain like `codesphere.corp42.net`

clemensfreitagdev · 2026-07-17T09:22:56Z

+  k0s supports combined control-plane/worker nodes. However, the current OMS k0sctl configuration generator treats an IP present in both lists as control-plane-only and ignores the duplicate worker entry. Until combined-role generation is supported by OMS, use dedicated control-plane and worker entries in this workflow.
+- The platform and public gateways use `LoadBalancer`, or `ExternalIP` where that is the chosen integration.
+- `codesphere.domain` is `cs.<base-domain>`.
+- `codesphere.workspaceHostingBaseDomain` and the custom-domain CNAME base are `ws.<base-domain>`.


Suggested change

- `codesphere.workspaceHostingBaseDomain` and the custom-domain CNAME base are `ws.<base-domain>`.

- `codesphere.workspaceHostingBaseDomain`: recommended to set to `<dc-id>.<base-domain>', e.g. `1.codesphere.corp42.net`

- `codesphere.customDomains.cNameBaseDomain`: recommended to set to `workspaces.<base-domain>`.

joka134 · 2026-07-16T07:35:08Z

+
+## What the installation builds
+
+The installation uses a management host as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.


Suggested change

The installation uses a management host as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.

The installation uses a jumphost as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.

another name for jumpbox/jumphost/controller? 😄

joka134 · 2026-07-17T08:13:17Z

+- A datacenter ID, name, city, and country code.
+- Stable private IP addresses for every machine.
+- A public IP address for the jumpbox. This is separate from the service addresses and should accept SSH only from trusted administrator networks.
+- Three stable, externally reachable service IP addresses: platform gateway, workspace gateway, and workspace SSH proxy.


Should we give some examples how we do it or mention the CCM here?

joka134 · 2026-07-17T08:21:22Z

+
+## 2. Provision the machines
+
+Provision x86-64 machines running Ubuntu 22.04 LTS or an equivalent supported operating system. Choose a topology based on the purpose of the installation.


What's blocking us from recommending newer versions? 🫣

joka134 · 2026-07-17T08:51:12Z

+
+## 7. Prepare the jumpbox
+
+Install OMS on the jumpbox together with `sops` and `age`. Pin and verify approved versions so the environment is repeatable.


Link to oms installation guide? Especially useful if we move this doc out of github

Simply link to OMS I guess: https://github.com/codesphere-cloud/oms

joka134 · 2026-07-17T10:13:35Z

+> ```yaml
+> k8s-cp:
+>   hosts:
+>     cp-1: {private_ip: 10.10.0.11}


Suggested change

> cp-1: {private_ip: 10.10.0.11}

> cp-1:

private_ip: 10.10.0.11

No brackets in yaml inventory

json is yaml no?

joka134 · 2026-07-17T10:13:59Z

+>     worker-1: {private_ip: 10.10.0.21}
+> ceph:
+>   hosts:
+>     ceph-1: {private_ip: 10.10.0.31}


Suggested change

> ceph-1: {private_ip: 10.10.0.31}

> ceph-1:

private_ip: 10.10.0.31

joka134 · 2026-07-17T10:25:29Z

+| Record | Target |
+| --- | --- |
+| `cs.<base-domain>` | Platform gateway IP |
+| `*.cs.<base-domain>` | Platform gateway IP |
+| `ws.<base-domain>` | Workspace gateway IP |
+| `*.ws.<base-domain>` | Workspace gateway IP |
+| `*.ssh.cs.<base-domain>` | Workspace SSH proxy IP |


We should stick to the names of the kubernetes services to make it simple to identify.
These are gateway-controller, public-gateway-controller and ssh-workspace-proxy

joka134 · 2026-07-17T10:36:01Z

+
+## 14. Complete the infrastructure integration
+
+If the selected infrastructure needs a Kubernetes cloud controller, install its supported provider integration and enable external cloud-provider mode on the k0s controller and workers. Use only manifests and service annotations intended for that infrastructure.


cloud controller could be related to the DNS step

joka134 · 2026-07-17T10:39:25Z

+
+```bash
+/etc/codesphere/deps/kubernetes/files/k0s kubectl \
+  get services --all-namespaces


Suggested change

get services --all-namespaces

get services -n codesphere

Could grep for LoadBalancer as well.

joka134 · 2026-07-17T10:40:28Z

+4. `https://cs.<base-domain>` presents a trusted certificate and loads Codesphere.
+5. A workspace can be created, reached over HTTPS, and reached through the workspace SSH proxy.
+
+Run the Codesphere smoke test when credentials for the environment are available:


Suggested change

Run the Codesphere smoke test when credentials for the environment are available:

Run the Codesphere smoke test when an API key for the environment is available:

NautiluX force-pushed the docs branch from c9e3030 to 1211c2c Compare July 16, 2026 07:43

clemensfreitagdev reviewed Jul 16, 2026

View reviewed changes

Comment thread docs/install-codesphere-on-any-infrastructure.md Outdated

clemensfreitagdev reviewed Jul 16, 2026

View reviewed changes

Comment thread docs/install-codesphere-on-any-infrastructure.md Outdated

clemensfreitagdev reviewed Jul 16, 2026

View reviewed changes

chore(docs): Add installation documentation

a790a4b

NautiluX force-pushed the docs branch from 1211c2c to a790a4b Compare July 16, 2026 13:43

walzph reviewed Jul 16, 2026

View reviewed changes

NautiluX force-pushed the docs branch from 3946bf4 to 57c53ad Compare July 17, 2026 07:01

applied review comments

62cd24d

NautiluX force-pushed the docs branch from 57c53ad to 62cd24d Compare July 17, 2026 07:09

clemensfreitagdev reviewed Jul 17, 2026

View reviewed changes

joka134 reviewed Jul 17, 2026

View reviewed changes

	- `codesphere.domain` is `cs.<base-domain>`.
	- `codesphere.domain` is `<base-domain>`, can be a sub-domain like `codesphere.corp42.net`

	- `codesphere.workspaceHostingBaseDomain` and the custom-domain CNAME base are `ws.<base-domain>`.
	- `codesphere.workspaceHostingBaseDomain`: recommended to set to `<dc-id>.<base-domain>', e.g. `1.codesphere.corp42.net`
	- `codesphere.customDomains.cNameBaseDomain`: recommended to set to `workspaces.<base-domain>`.


		## What the installation builds

		The installation uses a management host as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.

	The installation uses a management host as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.
	The installation uses a jumphost as the single entry point into a private network. From there, OMS installs and configures PostgreSQL, Ceph, k0s, and the Codesphere platform.


		## 2. Provision the machines

		Provision x86-64 machines running Ubuntu 22.04 LTS or an equivalent supported operating system. Choose a topology based on the purpose of the installation.


		## 7. Prepare the jumpbox

		Install OMS on the jumpbox together with `sops` and `age`. Pin and verify approved versions so the environment is repeatable.

	> cp-1: {private_ip: 10.10.0.11}
	> cp-1:
	private_ip: 10.10.0.11

	> ceph-1: {private_ip: 10.10.0.31}
	> ceph-1:
	private_ip: 10.10.0.31


		## 14. Complete the infrastructure integration

		If the selected infrastructure needs a Kubernetes cloud controller, install its supported provider integration and enable external cloud-provider mode on the k0s controller and workers. Use only manifests and service annotations intended for that infrastructure.

	Run the Codesphere smoke test when credentials for the environment are available:
	Run the Codesphere smoke test when an API key for the environment is available:

Uh oh!

Conversation

NautiluX commented Jul 16, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clemensfreitagdev Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

clemensfreitagdev Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clemensfreitagdev Jul 16, 2026 •

edited

Loading

clemensfreitagdev Jul 17, 2026 •

edited

Loading