Before looking at Jenkins specifically, we need the general idea an operator is built on.

Kubernetes as an operations platform

Kubernetes is a system for running containerised applications across a cluster of machines. On its own, it understands generic building blocks: a Pod runs one or more containers, a Deployment keeps a set number of Pods running, a Service gives them a stable network address. These building blocks are powerful, but Kubernetes has no built-in understanding of what “a healthy Jenkins controller” specifically means, or how to safely upgrade one without losing data.

The Operator pattern

An Operator is software that extends Kubernetes with that missing, application-specific knowledge. It introduces a new kind of object, called a Custom Resource, that describes the desired state of an application in the application’s own vocabulary, and it runs a controller process that continuously watches that object and takes whatever real actions are needed to make the cluster match it. In effect, an Operator encodes an experienced administrator’s operational knowledge into running software.

Why Jenkins specifically benefits

Jenkins is not a simple stateless web application. It holds important state on disk (job configuration, build history, credentials, plugin installations), needs careful handling during upgrades, and is configured through a mix of a web UI, XML files and, increasingly, configuration as code. A generic Kubernetes Deployment can keep a Jenkins container running, but it has no idea how to safely apply a configuration change, wait for Jenkins to actually finish starting up, or restore from a backup. The Jenkins Operator exists to close that gap.

A handful of ideas underpin every Kubernetes Operator, and learning them here makes the rest of this guide much easier to follow.

Desired state versus imperative commands

A traditional installation script is imperative: it lists the exact steps to run once, in order, right now. A Custom Resource is declarative: it states what the end result should look like, and the Operator figures out, continuously, what steps are needed to get there and keep it there, even if something changes underneath it later. This distinction matters enormously in practice, because a declarative system self-heals: if someone manually deletes a Pod or a ConfigMap the Operator created, the next reconciliation loop simply recreates it.

flowchart LR
    A["Administrator writes/updates a Jenkins Custom Resource"] --> B["Kubernetes API Server stores it"]
    B --> C["Jenkins Operator watches for changes"]
    C --> D["Reconciler compares desired vs actual state"]
    D --> E{"Do they match?"}
    E -->|"No"| F["Operator creates/updates/deletes Kubernetes objects"]
    F --> D
    E -->|"Yes"| G["Operator waits, watching for the next change"]
        

The Jenkins Custom Resource is the single document that describes an entire Jenkins installation to the Operator.

What it typically contains

A single, versionable source of truth

Because the entire desired setup lives in one YAML document, that document can live in a Git repository, be reviewed through a pull request, and be applied through the same continuous deployment tooling used for any other Kubernetes workload. This turns “how is our Jenkins configured?” from a question answered by clicking through screens into a question answered by reading a file.

Understanding what the Operator actually creates inside the cluster demystifies what would otherwise feel like magic.

flowchart TD
    CR["Jenkins Custom Resource"] --> OP["Jenkins Operator Controller"]
    OP --> CM1["ConfigMap: base configuration as code"]
    OP --> CM2["ConfigMap: seed job definitions"]
    OP --> SEC["Secret: initial admin credentials"]
    OP --> PVC["PersistentVolumeClaim: Jenkins home"]
    OP --> DEP["StatefulSet or Deployment running Jenkins"]
    OP --> SVC["Service exposing Jenkins"]
    DEP --> POD["Jenkins Controller Pod"]
    PVC --> POD
    CM1 --> POD
    CM2 --> POD
    SEC --> POD
        

The generated objects, one by one

The init and reconciliation flow at startup

When a new Jenkins Custom Resource is first created, the Operator’s reconciler works through an ordered sequence: create the storage claim, create the configuration ConfigMaps and Secret, then create the Pod definition referencing all of them, and finally wait for the Jenkins process inside that Pod to report itself genuinely ready, not merely “container started.” Only once Jenkins is truly ready does the Operator consider that reconciliation cycle successful.

Configuration as Code and the Operator are natural partners, and understanding how they fit together is central to using the Operator well.

What Configuration as Code contributes

Configuration as Code, often shortened to CasC, is a Jenkins mechanism that reads a YAML file and applies it to global Jenkins settings: security realm, authorization strategy, system messages, tool installations and much more. On its own, CasC needs that YAML file to exist somewhere Jenkins can read it. The Operator’s role is to manage exactly that: it takes the CasC content you provide in the Custom Resource, packages it as a ConfigMap, and mounts it into the Jenkins Pod at the path CasC expects.

sequenceDiagram
    participant A as Administrator
    participant CR as Jenkins Custom Resource
    participant OP as Operator
    participant CM as ConfigMap
    participant J as Jenkins Pod
    A->>CR: Define CasC YAML content
    OP->>CM: Create/update ConfigMap from CR
    OP->>J: Mount ConfigMap, restart if needed
    J->>J: CasC plugin applies configuration at startup
        

Seed jobs as code

Beyond global settings, most teams also want their actual pipeline jobs defined as code rather than clicked together in the UI. The Operator supports referencing seed job definitions, commonly using the Job DSL plugin, which the Operator arranges to run automatically at startup, populating Jenkins with the intended set of jobs and folders from a version-controlled source.

Because Jenkins is stateful, storage decisions are among the most consequential choices in an Operator-managed deployment.

What actually needs to persist

The Jenkins home directory holds build history, artifacts, credentials, plugin binaries and any configuration not managed as code. If this directory is lost, so is everything in it, regardless of how well the Custom Resource describes the intended setup. The Operator therefore provisions a Persistent Volume Claim and mounts it as the Jenkins home directory inside the Pod, so this data survives Pod restarts, rescheduling to a different node, and even Operator upgrades.

Choosing a storage class

The underlying performance of the persistent volume matters more than many teams expect, because Jenkins performs many small file operations against its home directory during normal use. A storage class backed by slow network storage can noticeably slow down job scheduling and plugin loading, while a storage class with strong sequential and random read/write performance keeps the controller responsive even under heavy build load.

An Operator makes recreating the shape of Jenkins easy, but recovering its actual data still requires a deliberate backup plan.

What a backup and restore plugin adds

A companion backup and restore capability, whether provided by the Operator itself or a paired Jenkins plugin, periodically archives the Jenkins home directory, or the specific parts of it that matter, to external storage such as an object storage bucket. This runs independently of the Custom Resource’s reconciliation loop, focused specifically on capturing the data that CasC and seed jobs cannot regenerate.

flowchart LR
    J["Running Jenkins Pod"] --> B["Backup Job (scheduled)"]
    B --> S["External Object Storage"]
    S --> R["Restore Job"]
    R --> NJ["New or Recovered Jenkins Pod"]
    CR["Jenkins Custom Resource in Git"] --> NJ
        

A layered recovery strategy

Running the controller under the Operator is only half the picture; most teams also want builds themselves to run as short-lived Kubernetes Pods.

The Kubernetes plugin, working alongside the Operator

The Kubernetes plugin, a separate component from the Operator itself, lets a Jenkins controller request a fresh Pod as a build agent for each job, running the build inside that Pod, and then discarding it when the job finishes. This means build capacity is not a fixed pool of always-on agents but scales up and down dynamically with actual build demand, which is a natural fit for a controller already running inside Kubernetes.

sequenceDiagram
    participant J as Jenkins Controller
    participant K as Kubernetes API
    participant P as Agent Pod
    J->>K: Job queued, request agent Pod
    K->>P: Schedule and start Pod
    P->>J: Agent connects to controller
    J->>P: Run build steps
    P->>J: Build completes, results reported
    J->>K: Request Pod deletion
    K->>P: Pod terminated
        

Pod templates

A Pod template describes what an agent Pod should look like: which container image to use, how much CPU and memory to request, which volumes to mount, and any special scheduling requirements. Different job types can use different templates, for example a lightweight template for simple scripts and a heavier template with more memory for large builds, all declared as configuration rather than by manually provisioning separate static agents.

Upgrading a stateful application safely is one of the hardest parts of operations, and it is exactly where an Operator’s judgment matters most.

Three different things can be upgraded

A safe upgrade sequence

Running Jenkins inside Kubernetes through an Operator introduces a distinct set of security responsibilities layered on top of Jenkins’ own security model.

An Operator-managed Jenkins should be observed like any other production Kubernetes workload, with a few Jenkins-specific signals added on top.

What to watch at the Kubernetes level

What to watch at the Jenkins level

Everything covered in a general Jenkins operations context still applies: build queue length, executor utilisation, plugin health, and — where relevant — the support bundle diagnostics discussed elsewhere are equally useful whether Jenkins is running on a bare virtual machine or inside a Kubernetes Pod managed by an Operator.

flowchart TD
    A["Cluster Monitoring"] --> B["Pod Health and Restarts"]
    A --> C["Resource Usage vs Limits"]
    A --> D["Persistent Volume Capacity"]
    A --> E["Operator Reconciliation Errors"]
    F["Jenkins-Level Monitoring"] --> G["Build Queue and Executors"]
    F --> H["Plugin Health"]
    F --> I["Support Bundle Diagnostics"]
        

Teams that have run the Jenkins Operator in production for years converge on a similar set of good habits, and repeat a similar set of avoidable mistakes.

Patterns that work

The following stories are composites of patterns that repeat across organisations running Jenkins on Kubernetes at scale.

Adopting the Operator is a real architectural decision with genuine costs alongside its benefits, and being honest about both makes for a better rollout.

Best practices at a glance

No. Running Jenkins in a container is just packaging the application. The Operator is a separate piece of software running inside Kubernetes that watches a Custom Resource and manages the entire lifecycle of that containerised Jenkins — creation, configuration, upgrades and health — on an ongoing basis.

Yes, if you want dynamic, on-demand build agents. The Operator manages the controller itself; the Kubernetes plugin, configured inside that controller, manages requesting and running build agent Pods. They solve different, complementary problems.

Deleting the Custom Resource typically causes the Operator to remove the objects it created, such as the Deployment and Service. Whether the persistent volume itself is deleted depends on its reclaim policy and how it was provisioned, so always confirm your storage class’s behaviour before deleting a Custom Resource in production.

Yes. A single Operator deployment typically watches for Jenkins Custom Resources across the namespaces it is configured to manage, reconciling each one independently, which is how organisations run many separate team-level controllers from one Operator installation.

It covers most global settings and can be extended to cover a great deal more, but some configuration, particularly certain credentials or highly dynamic settings, may still be entered manually or managed through other automation. CasC significantly reduces manual configuration; it does not always eliminate it entirely.

It is possible but not advisable as a default. Scoping the Operator’s permissions to only the namespaces where Jenkins resources actually live significantly reduces the impact of any misconfiguration or compromise.

The general approach is to back up the existing Jenkins home directory, provision a new Operator-managed Jenkins with a persistent volume, restore the backed-up data into that volume, and then gradually express as much configuration as possible through CasC and seed jobs going forward.

Assuming the declarative Custom Resource and Configuration as Code alone constitute a complete backup strategy. They reliably recreate structure and settings, but build history, artifacts and manually entered credentials still require their own separate, tested backup of the persistent volume.

The Jenkins Operator brings the discipline of Kubernetes-native, declarative operations to a tool that was originally designed around manual clicks and hand-run scripts. By describing the desired Jenkins setup once, in a single Custom Resource backed by Configuration as Code and seed jobs, teams gain a reproducible, version-controlled, self-healing installation that plays naturally with dynamic build agents and modern GitOps workflows. None of this removes the fundamental responsibilities of good operations — securing access tightly, backing up real data, and testing upgrades carefully — but it does turn most of the tedious, error-prone parts of running Jenkins into something a machine handles continuously, freeing engineers to focus on the pipelines themselves rather than the plumbing beneath them.