Skip to main content
Version: Weekly Build

Prepare the Jumpbox and Generate the Configuration

Before you start​

The hosts from Provision the hosts should be reachable over SSH from the jumpbox, tuned, and time-synchronized.

Prepare the jumpbox​

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

The jumpbox must have enough free space for the installer package and extracted installation dependencies. Create a root-only secrets directory:

install -d -m 0700 /etc/codesphere/secrets

Installer packages are always browsed and downloaded from the Codesphere package portal. Set the portal API key in the environment of the user that will run OMS on the jumpbox:

export OMS_PORTAL_API_KEY='<portal-api-key>'

The API key must remain set for subsequent OMS portal operations. Supply it through an approved secret manager or protected session setup, and do not commit it to a shell profile, image, or source repository.

Prepare access to GitHub Container Registry​

Codesphere images are pulled directly from GitHub Container Registry. Every k0s node must have outbound HTTPS access to ghcr.io and the related GitHub package endpoints.

Request the GHCR username and token from Codesphere before generating the install configuration. Customer-created GitHub personal access tokens do not automatically have access to the private Codesphere packages.

note

Registry authentication is currently in a transitional stage. For now, Codesphere provides separate GHCR credentials, and the token must be supplied to the install-configuration workflow as the registry password. A future version will use OMS portal authentication for registry access, removing the need to request and configure a separate GHCR token.

Keep the token ready for the configuration-generation step, but do not write it into shell history or config.yaml. Store it only in prod.vault.yaml as registryPassword, as shown below. Unauthenticated pulls or a token without package access will cause the platform installation to fail.

Generate the install configuration and secrets​

The OMS command for configuration generation is oms init install-config. It creates both inputs required by the installer:

  • config.yaml describes the infrastructure, network, storage, registry, domains, authentication providers, plans, and enabled features. See Private cloud installer config reference for the full field structure.
  • prod.vault.yaml contains generated passwords, private keys, certificates, and provider credentials. It is plaintext when generated and must be encrypted before it is stored or copied through an untrusted system.

Run the interactive generator from a trusted workstation or the jumpbox:

oms init install-config \
  --profile production \
  --config config.yaml \
  --vault prod.vault.yaml \
  --with-comments

Choose an install configuration profile​

The profile controls the default Codesphere software footprint, allowing the installation to fit differently sized infrastructure. It does not provision machines or automatically decide how many PostgreSQL, Ceph, control-plane, or worker nodes to use. The wizard or command flags must still describe the actual topology and IP addresses.

See Install steps and profiles for the full profile comparison table and the noRequests resource profile it applies.

Use production for the production baseline and minimal for the POC topology. Use dev only when disabling the bundled monitoring components is appropriate.

Optional Ansible inventory

Users who already maintain host topology in an Ansible inventory can import it with --ansible-inventory inventory.yaml. OMS reads the optional k8s-cp, k8s-workers, and ceph groups; each host needs a private_ip. For example:

k8s-cp:
  hosts:
    cp-1:
      private_ip: 10.10.0.11
k8s-workers:
  hosts:
    worker-1:
      private_ip: 10.10.0.21
ceph:
  hosts:
    ceph-1:
      private_ip: 10.10.0.31

Interactive mode is enabled by default. In that mode, the profile seeds the wizard, while individual non-interactive configuration flags are not applied. For automation, pass --interactive=false and provide every required value through flags and the profile. Treat a non-interactive validation failure as a missing or inconsistent input rather than bypassing it.

After generation, set the registry section in config.yaml to:

registry:
  server: ghcr.io
  replaceImagesInBom: false
  loadContainerImages: false

As part of install-config generation, set the existing registry entries in prod.vault.yaml to the GHCR username and token supplied by Codesphere. The token is the registry password:

secrets:
  - name: registryUsername
    fields:
      password: <codesphere-provided-ghcr-username>
  - name: registryPassword
    fields:
      password: <codesphere-provided-ghcr-token>

The username is intentionally stored in the password field used by the installer secret format. Keep both values in the vault and never place the token directly in config.yaml.

Use an existing Kubernetes cluster​

Bring an already-running Kubernetes cluster instead of letting OMS install k0s. This applies to a cloud-managed cluster, a cluster provisioned by another tool, or any cluster whose lifecycle Codesphere should not own.

Set kubernetes.managedByCodesphere to false and replace the managed-cluster fields with the cluster's actual pod and service network ranges:

kubernetes:
  managedByCodesphere: false
  podCidr: "100.96.0.0/11"     # Pod network CIDR of the existing cluster
  serviceCidr: "100.64.0.0/13" # Service network CIDR of the existing cluster

podCidr and serviceCidr are required for this option and have no defaults. They must match the cluster's real network ranges, because Codesphere uses them to configure workspace network policies; an incorrect value blocks or over-permits workspace traffic. apiServerHost, controlPlanes, and workers only apply to the Codesphere-managed option and are not used here.

Provide administrator access to the cluster as the kubeConfig secret in prod.vault.yaml instead of provisioning control-plane and worker hosts:

secrets:
  - name: kubeConfig
    file:
      name: kubeConfig # Internal name, doesn't need to match a filename
      content: |
        apiVersion: v1
        kind: Config
        clusters:
        - cluster:
            certificate-authority-data: ...
            server: https://<your-k8s-api-server>
          name: external-cluster
        contexts:
        - context:
            cluster: external-cluster
            user: external-admin
          name: external-context
        current-context: external-context
        users:
        - name: external-admin
          user:
            client-certificate-data: ...
            client-key-data: ...

The kubeconfig must grant administrator-level access. OMS uses it directly to install Argo CD, cluster dependencies, managed-service backends, and the Codesphere platform; it does not create, modify, or otherwise take over management of the cluster. Before deploying, OMS only checks that the kubeConfig secret is present and that the cluster's Kubernetes server version satisfies the minimum supported versions (the same major version, and a minor version at or above the installer's configured minimum). No --skip-steps flag is needed to skip the k0s installation; OMS skips it automatically based on managedByCodesphere.

Also set ceph.csiKubeletDir to the cluster's actual kubelet directory (for example /var/lib/kubelet on most non-k0s distributions) instead of the k0s default /var/lib/k0s/kubelet, and complete Complete the infrastructure integration using whatever load-balancer or ingress mechanism the cluster already provides.

Review the generated configuration​

Review the generated files and ensure they describe the actual infrastructure:

  • dataCenter contains the intended ID, name, city, and country code.

  • secrets.baseDir is /etc/codesphere/secrets when following this layout.

  • postgres.primary contains the PostgreSQL hostname and private IP, or postgres.mode describes the external database.

  • ceph.nodesSubnet matches the private host network.

  • ceph.hosts lists three hosts for a POC or at least four hosts for production, with exactly one initial master.

  • ceph.csiKubeletDir is /var/lib/k0s/kubelet when Codesphere manages k0s.

  • Each Ceph OSD definition selects only the intended, empty data and DB/WAL devices.

  • kubernetes.apiServerHost is the first control-plane node's private IP, or a stable load-balancer address or DNS name when using multiple control-plane nodes.

  • kubernetes.controlPlanes and kubernetes.workers assign every k0s node to its intended role. The production baseline uses three dedicated control-plane nodes and a separate worker pool:

    kubernetes:
      managedByCodesphere: true
      apiServerHost: 10.10.0.11
      controlPlanes:
        - ipAddress: 10.10.0.11
        - ipAddress: 10.10.0.12
        - ipAddress: 10.10.0.13
      workers:
        - ipAddress: 10.10.0.14
        - ipAddress: 10.10.0.15
        - ipAddress: 10.10.0.16

    Always list at least three addresses under controlPlanes for a highly available control plane. Dedicated worker addresses go under workers; increase that list for the expected workload CPU, memory, and failure tolerance.

    The interactive oms init install-config wizard asks separately for the comma-separated control-plane and worker IPs.

    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. See Gateway and load balancing.

  • codesphere.domain is <base-domain> and resolves to the platform gateway.

  • codesphere.workspaceHostingBaseDomain and the custom-domain CNAME base are <dc-id>.<base-domain>, the hostname wildcarded to the workspace gateway.

  • The workspace SSH proxy application is enabled and assigned its reserved address.

  • ACME or another certificate issuer is configured for the selected DNS and load-balancer design; see Cluster ingress CA options.

  • Git provider and OIDC redirect URLs use the final https://<base-domain> address; see Git providers and Identity providers.

  • The registry server is ghcr.io, replaceImagesInBom and loadContainerImages are false, and the vault contains valid registryUsername and registryPassword entries.

Use only annotations supported by the selected load-balancer implementation, or omit annotations when the implementation honors loadBalancerIP directly.

Verify this step​

oms init install-config --validate --config config.yaml --vault prod.vault.yaml

What you should have now​

  • OMS, sops, and age installed on the jumpbox.
  • config.yaml and prod.vault.yaml generated and reviewed against the checklist above.
  • Registry credentials from Codesphere staged for the vault.

Next​

Continue to Prepare the secrets vault and configure DNS.