A Kubernetes application for managing Renovate jobs, developed by Contane.
Foreman is intended to be deployed together with self-hosted Mend Renovate, either in the same or a secondary Kubernetes cluster. It provides a user interface for monitoring the Renovate CronJob including interactive progress and logs as well as the ability to trigger custom jobs, speeding up the dependency upgrade cycle in the case of many repositories.
- GitHub: https://github.com/contane/foreman
- Docker Hub: https://hub.docker.com/r/contane/foreman
- Helm chart: https://github.com/contane/charts/tree/main/charts/foreman
- Artifact Hub: https://artifacthub.io/packages/helm/contane-github/foreman
We recommend deploying Foreman on Kubernetes via Helm. Alternatively, you can run Foreman via Docker or locally on your machine.
This guide assumes that you already have a Kubernetes CronJob running self-hosted Renovate. There are two options to set this up:
- (Recommended) Use Renovate's Helm chart.
- Create a CronJob manually, following the Renovate self-hosting examples.
Please refer to the official Helm chart for deploying Foreman on Kubernetes.
When deploying Foreman to the same Kubernetes cluster as Renovate, we recommend setting up separate namespaces for both
applications and giving Foreman access to Renovate via a Role
and RoleBinding
.
Foreman requires the following permissions within the Renovate namespace:
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
name: renovate-foreman-role
namespace: renovate
rules:
- apiGroups: [""]
resources: ["pods", "pods/log"]
verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
resources: ["cronjobs"]
verbs: ["get", "list", "watch"]
- apiGroups: ["batch"]
resources: ["jobs"]
verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
For more information, refer to the Kubernetes RBAC documentation.
You can run Foreman via Docker:
docker run --detach \
--restart=unless-stopped \
--cap-drop=all \
--security-opt=no-new-privileges \
--read-only \
--volume=/path/to/config:/app/config:ro \
-p=8080:8080/tcp \
contane/foreman:latest
Here, /path/to/config
is the path to the configuration directory on the host, and Foreman will be accessible on
host port 8008.
The configuration must include a reference to the KubeConfig file and how to find the Renovate CronJob.
Running Foreman locally is useful for development and testing. To do this, you need to have Node.js and NPM installed. After cloning the repository, run the following commands:
npm install
npm run build
npm start
Note that you will need to authenticate on the web interface. During development, it is recommended to set a password for local login. You will also need to have a KubeConfig file available on your machine to access the Kubernetes API.
Create a YAML configuration file inside the config
directory. The file can have any name ending with .yaml
.
If there are multiple configuration files, they will be merged in alphabetical order. For example, if you have
config/00-config.yaml
and config/01-config.yaml
, the settings in config/01-config.yaml
will take precedence.
The following sections describe the available configuration options.
Environment variables can be set on the command line or in an .env
file in the root directory of the project.
Foreman supports multiple KubeConfig sources. The source to use can be specified by setting the kubeConfig.source
to one of the following values:
in-cluster
: Use the KubeConfig from the Kubernetes cluster environment. This is the default.file
: Use the KubeConfig from the file specified by theKUBECONFIG
environment variable, or~/.kube/config
.
In the in-cluster
mode, Foreman will look at the KUBERNETES_SERVICE_HOST
and KUBERNETES_SERVICE_PORT
environment
variables to determine the location of the Kubernetes API server. These variables are automatically set by Kubernetes.
You can use the file
mode when developing Foreman locally, or when deploying it outside of Kubernetes.
If necessary, override the KUBECONFIG
environment variable to point to the correct file.
You can select a context by setting kubeConfig.context
. This defaults to the KubeConfig file's current context.
Foreman queries a defined CronJob resource to determine which Renovate jobs to manage. By default, this is
renovate/renovate
(namespace/name). You can override this by setting cronJob.namespace
and cronJob.name
.
Foreman authentication is stateless. Client auth information is stored in a cookie, which is encrypted using a key. The key is generated on startup and is stored in memory. This means that the key will be different on each startup, and that all clients will be logged out when Foreman is restarted. Note that key generation consumes about 256 MiB of memory.
To avoid this, you can set cookies.key
to a fixed value. This will cause the same key to be used on each startup,
and will allow clients to stay logged in across restarts, and less memory to be used.
cookies.key
must be base64-encoded. To generate a key on Linux, run:
npx --yes @fastify/secure-session | base64
Sessions are valid for 24 hours by default. You can change this by setting cookies.maxAge
to a duration string
such as "6h" or "14 days".
Foreman supports local authentication, which allows users to log in using a username and password. This is disabled by default. To enable it, set the following config options:
auth:
local:
enabled: true
username: "any username (default: admin)"
password: "any password"
Foreman supports authentication via OpenID Connect. To enable it, set the following config options:
auth:
oidc:
enabled: true
issuer: "https://oidc.example.com"
clientId: "client-id"
clientSecret: "client-secret"
publicUrl: "https://foreman.example.com"
The following configuration must be set in the OIDC provider, assuming Foreman is running at
https://foreman.example.com
:
- Response Type: Code
- Grant Type: Authorization Code
- Authentication Method: Basic
- Auth Token Type: Bearer
- Redirect URL:
https://foreman.example.com/api/auth/oidc/callback
It is assumed that your OIDC provider restricts which users can log in to Foreman, as no additional role checks are performed by Foreman. Additionally, the issuer must use HTTPS.
Some GitLab-related functionality can be enabled by setting the following configuration options:
gitlab:
host: "https://gitlab.example.com"
This will enable the following features:
- Linking to GitLab repositories in the Renovate job list.
The following additional environment variables can be set:
PORT
: The port to listen on. Defaults to8080
.
We welcome contributions from the community! If you have suggestions, find a bug, or want to add new features, please open an issue or submit a pull request.