Skip to main content
Version: Weekly Build

Private Cloud Installer Config Reference

config.yaml is generated by oms init install-config (see Prepare the jumpbox and generate the configuration) and consumed by oms install codesphere. It has twelve top-level keys.

dataCenter​

Identifies this installation.

dataCenter:
id: 1
name: dev
city: Karlsruhe
countryCode: DE

An installation spanning several data centers has one config per data center and two more top-level keys, dataCenters and defaultDataCenterId — see Multiple data centers: configuration.

secrets​

secrets:
baseDir: /etc/codesphere/secrets

baseDir is the directory containing the vault (prod.vault.yaml). It should match the directory passed to --vault when running oms install codesphere.

registry​

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

server is the container registry nodes pull images from. loadContainerImages loads image tarballs bundled in the (deprecated) full installer package instead of pulling from server; leave it false when using the lite package. See Run the installer.

postgres​

postgres:
mode: install # or external
primary:
ip: 10.10.0.20
hostname: postgres-1

mode: install has the installer manage PostgreSQL on a host you provide via primary (and optionally replica). mode: external instead requires serverAddress pointing at a database you operate yourself; serverAddress must be empty when mode: install. For mode: external, the database's superuser must be named postgres — this is not configurable — and the connection is always made over TLS, so the certificate the database presents must be trusted (for a managed database service such as AWS RDS, this means using that service's actual CA bundle).

ceph​

ceph:
csiKubeletDir: /var/lib/k0s/kubelet # /var/lib/kubelet for most non-k0s clusters
nodesSubnet: 10.10.0.0/20
hosts:
- hostname: ceph-1
ipAddress: 10.10.0.31
isMaster: true
osds:
- specId: default
dataDevices:
size: "240G:300G"
dbDevices:
size: "120G:150G"

hosts must list at least one Ceph host, exactly one of which is the master. csiKubeletDir must match the kubelet directory of the Kubernetes distribution in use — see Use an existing Kubernetes cluster. osds[].dataDevices/dbDevices select disks by size range; to signal "there is no separate DB/WAL disk," set a size range that matches none of the node's disks.

kubernetes​

kubernetes:
managedByCodesphere: true # false to bring your own cluster
apiServerHost: 10.10.0.11
controlPlanes:
- ipAddress: 10.10.0.11
workers:
- ipAddress: 10.10.0.14

When managedByCodesphere is false, apiServerHost/controlPlanes/workers are not used; instead set podCidr and serviceCidr to the existing cluster's real network ranges (both required, no defaults) and supply the cluster's kubeConfig as a vault secret. See Use an existing Kubernetes cluster.

cluster​

Cluster-level infrastructure: certificates, monitoring, and the two gateway services. See Cluster ingress CA options, Gateway and load balancing, and Cluster monitoring for the relevant sub-sections (cluster.certificates, cluster.gateway, cluster.publicGateway, cluster.monitoring).

metallb​

metallb:
enabled: false

Disabled by default. See Gateway and load balancing for the pool and advertisement configuration when enabled.

codesphere​

The largest section: platform domains, certificate issuer, feature flags, plans, Git and identity providers, and managed services.

codesphere:
domain: example.com
workspaceHostingBaseDomain: dc1.example.com
certIssuer:
type: self-signed
internal: []
preview: {}
features: {}

domain is the bare base domain and resolves to the platform gateway. workspaceHostingBaseDomain is the datacenter-specific hostname that gets wildcarded to the workspace gateway.

vpn.leftPeerId is an optional field that sets the local peer identity (leftid) sent by workspace VPN tunnels during IKE authentication. When omitted, strongSwan uses the workspace's local/private IP address as its identity. Many VPN gateways instead expect the workspace's public egress IP address. Set vpn.leftPeerId when your gateway requires that or another specific identity to match its connection policy. Accepted formats follow strongSwan identity syntax: an IPv4 address (203.0.113.1), a fully qualified domain name (vpn.example.com), an email address ([email protected]), or a distinguished name (C=DE, O=Example, CN=vpn.example.com).

codesphere:
vpn:
leftPeerId: vpn.example.com

sshWorkspaceProxy​

Configures the workspace SSH proxy. The proxy is always deployed. This block only controls how its Kubernetes Service is exposed:

codesphere:
sshWorkspaceProxy:
service:
type: LoadBalancer # default; or NodePort or ClusterIP
nodePort: 30022 # default; NodePort only
loadBalancerIP: 203.0.113.30 # optional; LoadBalancer only
annotations: {}

baseDomain is optional and defaults to codesphere.domain. All service keys are optional. See Gateway and load balancing for what each key does and how the installer validates it. An explicit pcApps.applications.ssh-workspace-proxy block still overrides the values derived from this block.

email​

Configures a custom SMTP server for transactional email:

codesphere:
email:
provider: smtp
smtp:
host: smtp.example.com
port: 587
secure: false
username: codesphere

provider must be smtp; host, a positive integer port, and the Boolean secure value are required. username is optional. Store the corresponding password as the optional smtpPassword vault secret, not in config.yaml.

The sendGridApiKey vault secret is an alternative to this block. It automatically selects SendGrid's SMTP relay and takes precedence if both options are configured. If neither option is configured, the platform runs without delivering email. See Email delivery for examples and migration behavior.

openBao​

Connects secret management (the secret-management preview flag, see Feature flags) to an OpenBao server:

codesphere:
openBao:
uri: https://openbao.example.com
engine: cs-secrets-engine
user: codesphere

uri, engine, and user are required when the block is present. Store the password as the openBaoPassword vault secret, not in config.yaml. Codesphere logs in with the userpass auth method mounted at auth/userpass.

engine is the path of an existing KV version 2 secrets engine. Codesphere never creates mounts. To use an OpenBao namespace, prefix the engine with it, for example my-namespace/cs-secrets-engine. The user and its policy stay in the root namespace.

When Codesphere deploys OpenBao in the cluster, the engine, the user, and its policy are configured automatically. When connecting to an existing OpenBao (brownfield), its administrator must grant the user this policy, with cs-secrets-engine replaced by your engine value:

path "cs-secrets-engine/data/*" {
capabilities = ["create", "read", "update"]
}
path "cs-secrets-engine/metadata/*" {
capabilities = ["read", "list", "delete"]
}
path "sys/policies/password/*" {
capabilities = ["create", "update", "read", "delete"]
}
path "auth/token/renew-self" {
capabilities = ["update"]
}
  • sys/policies/password/* is used to generate secret values: Codesphere creates a temporary password policy, generates a value from it, and deletes the policy again.
  • auth/token/renew-self is already part of OpenBao's default policy and is only needed when the user's tokens do not get it.
  • Tokens must be renewable, or the user must be allowed to log in again: Codesphere renews its token before it expires and logs in again after the maximum TTL.

openfgaBackups​

Backs up the OpenFGA database, which holds every authorization decision Codesphere makes, to an S3-compatible bucket. Backups are off unless this block is set. Without a backup, losing the database means rebuilding permissions by hand.

codesphere:
openfgaBackups:
enabled: true
destinationPath: s3://example-openfga-backups
endpointURL: https://s3.example.com
schedule: "0 0 3 * * *" # optional, 6 fields: second minute hour day month weekday
retentionPolicy: 7d # optional

destinationPath (bucket and optional prefix) and endpointURL are required when enabled is true. schedule sets when the full base backup runs and defaults to daily at 03:00. retentionPolicy defaults to 7d. WAL is archived continuously, so the database can be restored to any point within the retention period.

The bucket's access key goes in the openfgaDbBackupAccessKeyId and openfgaDbBackupSecretAccessKey vault secrets. It needs to read, write, list and delete objects, because old backups are pruned. Backups also need the Barman Cloud plugin enabled under managedServiceBackends. In a multi-data-center installation, set this block only in the data center that deploys OpenFGA.

A backup block under pcApps.applications.openfga overrides openfgaBackups, so configure backups here only.

To check that backups run, after the installer has applied the change:

# WAL archiving: the ContinuousArchiving condition should be True
kubectl -n openfga get cluster openfga-pg \
-o jsonpath='{.status.conditions[?(@.type=="ContinuousArchiving")]}'

# Completed base backups. The first one runs at the next scheduled time.
kubectl -n openfga get backup

To be alerted when archiving or a backup fails, turn on the OpenFGA alert rules in the data center that deploys OpenFGA. This also turns on the OpenFGA availability, error and latency alerts. The backup alerts stay silent while backups are off.

cluster:
monitoring:
prometheus:
override:
alerting:
alertingRuleGroups:
openfga:
enabled: true

To restore from a backup, contact Codesphere support.

pcApps​

Free-form Helm values passed through to the pc-applications Argo CD chart (see Architecture). Use only when a specific pc-apps component needs a non-default value. oms init install-config does not generate this section; add it manually when needed.

managedServiceBackends​

Enables the backend implementation for each managed service enabled under codesphere.managedServices. See Managed services. For overrides such as underprovisioning, see Workload underprovisioning.

operations​

operations:
skip:
- load-container-images

Persists installer steps to skip on every run, in addition to whatever is passed with --skip-steps. See Install steps and profiles.