Getting Started¶
This guide installs a released operator from the chart registry and creates a Foreman with its frontend and, optionally, a provisioning Smart Proxy. The resources follow config/samples and the E2E test in tests/e2e/mvp/resources.yaml.
Experimental
This is an unofficial, unsupported prototype. It is not affiliated with or endorsed by the Foreman project. Use a test cluster.
Prerequisites¶
| Component | Required | Used for |
|---|---|---|
| Kubernetes 1.30 or later | Yes | Tested on k3s |
| cert-manager | Yes, for issuerRef |
Internal CA, server, client, and proxy certificates |
| CloudNativePG | Yes | PostgreSQL for Foreman |
| Valkey | Yes | Rails cache and Dynflow. The operator does not deploy it |
| Gateway API with TLSRoute | No | Exposure TLSRoute. Tested with Envoy Gateway |
| A LoadBalancer implementation | No | Exposure LoadBalancer or Auto outside OpenShift |
| Multus | For provisioning | Attaches the Smart Proxy to the provisioning network |
The operator detects cert-manager, the Gateway API, and OpenShift Routes when it starts. Install them before the operator, or restart the operator afterwards.
The images are amd64 only, except the operator and the frontend.
Install the operator¶
Releases publish the charts to oci://ghcr.io/slauger/charts, see the releases for the versions. Helm installs CRDs only on the first install and never upgrades them, so apply them explicitly from the chart before every install or upgrade:
VERSION=0.1.0
helm pull oci://ghcr.io/slauger/charts/foreman-operator --version "${VERSION}" --untar
kubectl apply --server-side -f foreman-operator/crds/
helm install foreman-operator oci://ghcr.io/slauger/charts/foreman-operator \
--version "${VERSION}" \
--namespace foreman-operator \
--create-namespace
The chart appVersion is the tag of the operator image and the default tag of the Foreman, frontend, Smart Proxy, and boot-files images. By default, the operator watches all namespaces. See the chart README for all values. To test the develop branch instead, install the chart from a checkout as described there.
Create the namespace and database¶
kubectl create namespace foreman
helm install foreman-db oci://ghcr.io/slauger/charts/foreman-db-cnpg \
--version "${VERSION}" \
--namespace foreman
The chart creates the CloudNativePG Cluster foreman-db. CloudNativePG then writes the Secret foreman-db-app, which the Foreman reads.
Create the internal CA¶
Foreman, the frontend client verification, and Smart Proxies share one internal CA. See Certificates for the reasoning.
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: selfsigned
namespace: foreman
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: foreman-internal-ca
namespace: foreman
spec:
isCA: true
commonName: foreman-internal-ca
secretName: foreman-internal-ca
duration: 175200h
privateKey:
algorithm: RSA
size: 4096
rotationPolicy: Never
issuerRef:
name: selfsigned
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: foreman-internal-ca
namespace: foreman
spec:
ca:
secretName: foreman-internal-ca
Provide Valkey¶
Any Valkey or Redis-compatible server without authentication works. For a test, a single Deployment is enough:
apiVersion: v1
kind: Service
metadata:
name: valkey
namespace: foreman
spec:
selector:
app: valkey
ports:
- port: 6379
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: valkey
namespace: foreman
spec:
replicas: 1
selector:
matchLabels:
app: valkey
template:
metadata:
labels:
app: valkey
spec:
containers:
- name: valkey
image: quay.io/sclorg/valkey-8-c10s:latest
ports:
- containerPort: 6379
Create Foreman¶
Replace foreman.example.com with a name that resolves to the address the frontend is exposed on. The frontend runs as the container httpd in every web pod, so web.replicas also sets the number of frontends.
apiVersion: platform.theforeman.org/v1alpha1
kind: Foreman
metadata:
name: foreman
namespace: foreman
spec:
fqdn: foreman.example.com
tls:
issuerRef:
name: foreman-internal-ca
database:
cluster:
name: foreman-db
valkey:
host: valkey
web:
replicas: 1
frontend:
tls:
server:
issuerRef:
name: foreman-internal-ca
clientCA:
issuerRef:
name: foreman-internal-ca
exposure:
type: Auto
Auto makes the Service foreman-web a LoadBalancer, or creates a passthrough Route on OpenShift. For a Gateway with TLS passthrough, use:
frontend:
exposure:
type: TLSRoute
gatewayRef:
name: foreman
tlsSectionName: https
httpSectionName: http
For a server certificate from a public issuer, set frontend.tls.server.issuerRef to that issuer. Keep frontend.tls.clientCA on the internal CA.
Watch the rollout¶
The Foreman passes these phases:
Pendinguntil the database Secret exists.Progressingwhile the Jobforeman-preflight-<hash>reads the Foreman version of the image.Migratingwhile the Jobforeman-migrate-<hash>runsdb:migrate,db:seed, andupgrade:run. The first migration takes several minutes.Progressingwhile web and Dynflow roll out.Runningwhen web and the Dynflow orchestrator are available. The conditionVerifiedbecomesTrueonce the smoke checks pass.
If the migration Job fails, the phase is RollForwardRequired. Read the Job logs, fix the cause, and delete the Job to retry. See Upgrades.
Log in¶
The operator generates the admin password into the Secret <name>-secrets. The user name is admin.
kubectl -n foreman get secret foreman-secrets -o jsonpath='{.data.admin-password}' | base64 -d; echo
Keep a copy of the whole Secret. It also holds the encryption key of the database, and it is not deleted together with the Foreman.
With the server certificate from the internal CA, clients must trust that CA:
kubectl -n foreman get secret foreman-internal-ca -o jsonpath='{.data.ca\.crt}' | base64 -d > foreman-ca.crt
curl --cacert foreman-ca.crt https://foreman.example.com/api/v2/ping
Add a provisioning Smart Proxy¶
This step needs Multus and a NetworkAttachmentDefinition for the provisioning network. The E2E test runs it on a node-local bridge; a real VLAN has not been tested.
The dnsmasq container runs as root with NET_ADMIN and other capabilities, so the namespace needs the Pod Security level privileged:
The Smart Proxy assigns its static address itself, so the NetworkAttachmentDefinition needs no IPAM:
apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
name: pxe
namespace: foreman
spec:
config: |
{
"cniVersion": "1.0.0",
"name": "pxe",
"type": "bridge",
"bridge": "pxe0",
"ipam": {}
}
For DNS, store a TSIG key in a Secret under key:
apiVersion: platform.theforeman.org/v1alpha1
kind: SmartProxy
metadata:
name: pxe
namespace: foreman
spec:
foremanRef: foreman
profile: Provisioning
url: https://pxe.foreman.svc:8443
tls:
issuerRef:
name: foreman-internal-ca
networks:
- attachment: pxe
address: 10.99.0.10/24
features:
tftp: {}
templates:
url: http://10.99.0.10:8000
dhcp:
provider: dnsmasq
subnets:
- network: 10.99.0.0/24
range: 10.99.0.100-10.99.0.150
gateway: 10.99.0.1
dns:
server: dns.example.com
keySecretRef: tsig
storage:
size: 5Gi
Once the proxy pod is available and the Foreman is Ready, the operator registers the proxy in Foreman under the name pxe and sets status.foremanID. Deleting the SmartProxy removes it from Foreman. The PVC pxe-data stays.
Next steps¶
- Remote Execution to enable plugins and add an
Executionproxy - Plugins for the catalog, compute resources, and boot disks
- Upgrades for image changes and migrations
- Backup and Restore before the first upgrade
- Provisioning for the pod layout and network rules
- API Reference for all fields