Foreman¶
Spec¶
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
fqdn |
string | Yes | Primary hostname. Used for foreman_url, the client certificate CN, and the frontend |
|
aliases |
[]string | No | Additional accepted hostnames | |
image |
image | No | Foreman image | |
plugins |
[]string | No | Plugins to enable from the catalog. Dependencies are enabled with them, and a change runs a migration | |
tls |
tls | Yes | Source of the client certificate Foreman presents to Smart Proxies | |
database.cluster.name |
string | Yes | CloudNativePG Cluster name. The operator reads the uri key of its credentials Secret |
|
database.cluster.credentialsSecretRef |
string | No | <cluster>-app |
Overrides the credentials Secret |
valkey.host |
string | Yes | Valkey host | |
valkey.port |
integer | No | 6379 |
Valkey port |
secretsRef |
string | No | <name>-secrets |
Secret with encryption-key, secret-key-base, admin-password, oauth-consumer-key, and oauth-consumer-secret. Missing keys are generated |
web.replicas |
integer | No | 2 |
Web pods. Each pod runs Puma and its own frontend container |
web.resources |
ResourceRequirements | No | requests 200m CPU and 1Gi, limit 3Gi | Compute resources. Puma workers are derived from the memory limit |
dynflow.workerReplicas |
integer | No | 1 |
General workers |
dynflow.hostsQueueReplicas |
integer | No | 0 |
Hosts queue workers, used by Remote Execution |
dynflow.resources |
ResourceRequirements | No | requests 100m CPU and 512Mi, limit 1536Mi | Compute resources of all Dynflow workloads |
frontend |
object | Yes | Apache container in every web pod, see spec.frontend |
spec.frontend¶
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
image |
image | No | Frontend image | |
resources |
ResourceRequirements | No | requests 20m CPU and 64Mi, limit 256Mi | Compute resources of the httpd container |
tls.server |
tls | Yes | Certificate presented to clients | |
tls.clientCA |
tls | Yes | CA that verifies client certificates. Only ca.crt of the Secret is used |
|
exposure.type |
string | No | Auto |
Auto, LoadBalancer, Route, TLSRoute, or ClusterIP |
exposure.gatewayRef.name |
string | For TLSRoute |
Gateway name | |
exposure.gatewayRef.namespace |
string | No | Foreman namespace | Gateway namespace |
exposure.gatewayRef.tlsSectionName |
string | No | Listener with TLS passthrough for the TLSRoute | |
exposure.gatewayRef.httpSectionName |
string | No | Listener for the HTTPRoute used by installers. Without it, no HTTPRoute is created and an existing one is deleted | |
exposure.annotations |
map | No | Added to the Service <name>-web for LoadBalancer and ClusterIP, or to the Route for Route |
There is no separate replica count. web.replicas scales Puma and the frontend together, see Traffic Flow.
Auto resolves to Route when the cluster serves the OpenShift Route API, and to LoadBalancer otherwise. Route and TLSRoute fail with a reconcile error when the API is not installed.
Status¶
| Field | Type | Description |
|---|---|---|
observedGeneration |
integer | Last processed generation |
phase |
string | Pending, Migrating, Progressing, Running, Blocked, RollForwardRequired, or Failed |
appliedMigrationHash |
string | Hash of the image reference and the sorted plugin list the database was last migrated for |
pendingMigrationHash |
string | Hash of a migration that passed the preflight but has not completed. Once its Job exists, the database may be partly migrated |
verifiedMigrationHash |
string | Hash of the last migration whose smoke checks passed |
foremanVersion |
string | Foreman version the database was last migrated to, read from the image by the preflight Job |
appliedPlugins |
[]string | Plugins with dependencies the database was last migrated for |
conditions |
[]Condition | See Conditions. Verified reports the smoke checks after the last migration |
Created objects¶
| Object | Name | Owner reference | Notes |
|---|---|---|---|
| Secret | <name>-secrets or secretsRef |
No | Generated once; deleting the Foreman never deletes the encryption key |
| Secret | <name>-settings |
Yes | settings.yaml, contains the OAuth consumer secret |
| ConfigMap | <name>-dynflow |
Yes | Sidekiq configurations of the orchestrator, worker, and hosts queue |
| Certificate | <name>-client |
Yes | Only with tls.issuerRef. CN and DNS name equal fqdn, client authentication usage |
| Certificate | <name>-server |
Yes | Only with frontend.tls.server.issuerRef. DNS names are fqdn and aliases |
| Certificate | <name>-client-ca |
Yes | Only with frontend.tls.clientCA.issuerRef. A small client certificate, requested only to obtain the issuer CA in ca.crt |
| ConfigMap | <name>-frontend |
Yes | Apache configuration generated by the operator |
| Service | <name>-web |
Yes | Ports 443 (HTTPS) and 80 (HTTP) of the frontend containers. Type LoadBalancer for exposure LoadBalancer, otherwise ClusterIP. Used by clients and the operator |
| Route | <name> |
Yes | Exposure Route, or Auto on OpenShift. Host is fqdn, termination passthrough, target <name>-web |
| TLSRoute | <name> |
Yes | Exposure TLSRoute. Hostnames are fqdn and aliases, backend <name>-web port 443 |
| HTTPRoute | <name> |
Yes | Exposure TLSRoute with httpSectionName set. Backend <name>-web port 80 |
| Job | <name>-preflight-<hash> |
Yes | Reads the Foreman version from /usr/share/foreman/VERSION of the new image into its termination message |
| Job | <name>-migrate-<hash> |
Yes | First eight characters of the migration hash. The annotation platform.theforeman.org/foreman-version records the version it migrates to |
| CronJob | <name>-cron-hourly, -daily, -weekly, -monthly |
Yes | bin/rails cron:<period> on the schedules of /etc/cron.d/foreman in the Foreman RPM: 30 * * * *, 0 2 * * *, 0 5 * * 0, 0 3 1 * *, in the time zone of the kube-controller-manager. Runs never overlap, a run missed by more than ten minutes is skipped. Suspended while a migration stops the writers |
| Deployment | <name>-web |
Yes | Containers foreman (Puma, about 1.5 GiB memory limit per worker, 1 to 16 workers) and httpd (Apache on ports 8443 and 8080) |
| Deployment | <name>-dynflow-orchestrator |
Yes | Always one replica, strategy Recreate |
| Deployment | <name>-dynflow-worker |
Yes | dynflow.workerReplicas |
| Deployment | <name>-dynflow-hosts-queue |
Yes | dynflow.hostsQueueReplicas |
All Foreman pods disable service links. A Service named foreman would otherwise inject FOREMAN_PORT, which Puma reads as its listen port.
In the web pods, Puma binds only to the Unix socket /run/puma/puma.sock in a shared emptyDir (FOREMAN_BIND=unix:///run/puma/puma.sock?umask=0007) and has no TCP listener. Its readiness and liveness probes are exec probes that run curl against /api/v2/ping over the socket. A change to the frontend configuration or its certificates rolls only the web pods, not Dynflow.
Migration¶
The operator computes a hash over the image reference and the sorted plugin list. When it differs from status.appliedMigrationHash, it runs the preflight, then the migration, and the smoke checks after the rollout. See Upgrades for the checks and how to recover.
| Situation | Phase | Condition and reason |
|---|---|---|
| Preflight Job reads the version | Progressing |
Progressing, Preflight |
| Preflight Job failed, for example because the image cannot be pulled | Blocked |
Degraded, PreflightFailed |
| Unsupported version path | Blocked |
Degraded, UnsupportedUpgradePath |
| A plugin that schedules tasks would be disabled | Blocked |
Degraded, PluginRemovalRefused |
| Tasks are planning, running, or paused | Progressing |
Progressing, WaitingForTasks |
| Writers stopping, migration running | Migrating |
Progressing, StoppingWriters or Migrating |
| Migration Job failed | RollForwardRequired |
Degraded, MigrationFailed |
| Previous image requested after the migration Job started | RollForwardRequired |
Degraded and Ready, RollForwardRequired |
| Rolled out, smoke checks pending | Running |
Verified is False, Verifying or VerificationFailed |
| Smoke checks passed | Running |
Verified, SmokeChecksPassed |
While the preflight runs or blocks, the previous version keeps running.
Example¶
apiVersion: platform.theforeman.org/v1alpha1
kind: Foreman
metadata:
name: production
spec:
fqdn: foreman.example.com
plugins:
- foreman_discovery
tls:
issuerRef:
name: foreman-internal-ca
database:
cluster:
name: foreman-db
valkey:
host: valkey
web:
replicas: 2
resources:
limits:
memory: 8Gi
frontend:
tls:
server:
issuerRef:
name: letsencrypt-dns01
kind: ClusterIssuer
clientCA:
issuerRef:
name: foreman-internal-ca
exposure:
type: Auto