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.
domainandworkspaceHostingBaseDomain— see Requirements and sizing and Encrypt the secrets and configure DNS.certIssuer— see Cluster ingress CA options.internal,preview,features— three separate flag buckets; see Feature flags.plans— see Workspace and hosting plans.gitProviders— see Git providers.oauth.oidc— see Identity providers. Claim-based role assignment is covered in OIDC role mapping.managedServices— see Managed services.sshWorkspaceProxy— seesshWorkspaceProxybelow.- workload underprovisioning overrides — see Workload underprovisioning.
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-selfis already part of OpenBao'sdefaultpolicy 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.