gitlab-runner-operator-fips

packaged by Chainguard

Chainguard Container for gitlab-runner-operator-fips

gitlab-runner-operator is a Kubernetes/OpenShift operator that manages the lifecycle of GitLab Runner instances via the Runner custom resource.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/gitlab-runner-operator-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The Chainguard gitlab-runner-operator-fips image is the FIPS-enabled variant of the gitlab-runner-operator image. It shares the same minimal, distroless design and is a drop-in replacement for the upstream GitLab Runner Operator image, with the following differences:

• The operator is compiled against a FIPS 140-validated cryptographic module, and the image ships the FIPS-hardened OpenSSL configuration so that cryptographic operations run in FIPS mode.
• The image is built with STIG (Security Technical Implementation Guide) hardening enforced.
• Like all Chainguard Containers, the image contains only the operator binary and its runtime dependencies. It does not include a shell or package manager.
• The image runs as a non-root user (UID 1001) by default.
• The operator binary is installed at /usr/bin/manager, which is also the image entrypoint. A relative /manager symlink mirrors the upstream entrypoint path, so existing manifests and Operator Lifecycle Manager (OLM) bundles continue to work unchanged.
• The runner configuration templates that the operator renders at runtime are installed under /templates, matching the upstream image layout.

Aside from its FIPS and hardening properties, the gitlab-runner-operator-fips image is operated in exactly the same way as the standard gitlab-runner-operator image. It manages GitLab Runner instances through the Runner custom resource and is typically installed through OLM or the upstream config/ manifests; there is no official Helm chart.

The operator's admission webhooks are enabled by default and require TLS serving certificates in the cluster, which are normally provisioned by OLM or cert-manager. When deploying the operator without them, set the ENABLE_WEBHOOKS environment variable to "false" so the manager starts without attempting to serve webhooks. This mirrors upstream operator behavior and is not specific to the Chainguard image.

FIPS images are intended for environments that must comply with FIPS 140 requirements. Achieving end-to-end compliance also depends on running the operator on a host and cluster whose kernel and node configuration meet your compliance requirements.

FIPS Support

The gitlab-runner-operator-fips Chainguard Image ships with a validated redistribution of the OpenSSL's FIPS provider module. For more on FIPS support in Chainguard Images, consult the guide on FIPS-enabled Chainguard Images on Chainguard Academy

Prerequisites

To follow the examples in this section, you need the following:

• A running Kubernetes or OpenShift cluster, along with a kubectl client configured to reach it.
• Permission to create cluster-scoped resources, such as custom resource definitions.

Getting Started

The gitlab-runner-operator-fips image is designed to run inside a Kubernetes or OpenShift cluster, where it watches for Runner resources and reconciles them into running GitLab Runner instances.

Begin by registering the Runner custom resource definition (CRD) that the operator reconciles. The following command applies the CRD from the operator's upstream repository:

kubectl apply -f https://gitlab.com/gitlab-org/gl-openshift/gitlab-runner-operator/-/raw/master/config/crd/bases/apps.gitlab.com_runners.yaml

customresourcedefinition.apps.gitlab.com/runners.apps.gitlab.com created

Next, define a namespace, a service account, and a deployment that runs the operator. The following command writes these resources to a file:

cat > gitlab-runner-operator.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: gitlab-runner-system
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gitlab-runner-operator
  namespace: gitlab-runner-system
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gitlab-runner-operator
  namespace: gitlab-runner-system
  labels:
    app.kubernetes.io/name: gitlab-runner-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: gitlab-runner-operator
  template:
    metadata:
      labels:
        app.kubernetes.io/name: gitlab-runner-operator
    spec:
      serviceAccountName: gitlab-runner-operator
      containers:
        - name: manager
          image: cgr.dev/ORGANIZATION/gitlab-runner-operator-fips:latest
          env:
            - name: ENABLE_WEBHOOKS
              value: "false"
EOF

This example omits the role-based access control (RBAC) rules that the operator needs to manage runners in a real cluster. For a production deployment, apply the ServiceAccount, Role, and RoleBinding resources from the upstream config/ manifests or the OLM bundle, then bind them to the operator's service account.

Apply the manifest to your cluster:

kubectl apply -f gitlab-runner-operator.yaml

namespace/gitlab-runner-system created
serviceaccount/gitlab-runner-operator created
deployment.apps/gitlab-runner-operator created

Once the deployment is available, confirm that the operator has started and is reconciling resources by checking its logs:

kubectl logs -n gitlab-runner-system -l app.kubernetes.io/name=gitlab-runner-operator

INFO    controller-runtime.metrics      Serving metrics server  {"bindAddress": ":8080"}
INFO    Starting Controller     {"controller": "runner"}
INFO    Starting workers        {"controller": "runner", "worker count": 1}

With the operator running, you can register a runner. The following command creates a secret that holds the GitLab registration token, along with a Runner resource that references it:

cat > runner.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: gitlab-runner-secret
  namespace: gitlab-runner-system
stringData:
  runner-registration-token: REPLACE_WITH_YOUR_TOKEN
---
apiVersion: apps.gitlab.com/v1beta2
kind: Runner
metadata:
  name: example-runner
  namespace: gitlab-runner-system
spec:
  gitlabUrl: https://gitlab.example.com
  token: gitlab-runner-secret
EOF

Apply the runner definition:

kubectl apply -f runner.yaml

secret/gitlab-runner-secret created
runner.apps.gitlab.com/example-runner created

The operator renders the runner configuration into a ConfigMap named after the Runner resource, then deploys a GitLab Runner instance that registers with the GitLab URL you provided.

Configuration

The gitlab-runner-operator-fips image uses the same configuration interface as the upstream operator, which is driven through command-line flags and environment variables on the manager container.

As an example, the deployment above disables the admission webhooks by setting the ENABLE_WEBHOOKS environment variable to "false". The webhooks validate Runner resources but require TLS certificates to be provisioned in the cluster, so disabling them is a convenient way to evaluate the operator before you configure certificate management. In a production cluster where certificates are available, omit this variable to benefit from webhook validation.

Because this image is built with STIG hardening enforced, you should run it on cluster nodes whose configuration also satisfies your hardening baseline; the image hardening complements, but does not replace, node-level controls.

For the full set of supported flags, environment variables, and Runner fields, refer to the upstream GitLab Runner Operator documentation.

Documentation and Resources

• GitLab Runner Operator documentation
• GitLab Runner documentation
• Chainguard FIPS Images overview
• Getting Started with Chainguard Containers

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.