Kubernetes operators: install one, configure it and read what it creates
Install a Kubernetes operator with kubectl apply, give it a MongoDB database, change it through its resource and read what it creates, owns and leaves.
The issue opens pre-filled with this page title and URL.
An operator is a program that runs in the cluster and manages an application for you, by driving the Kubernetes API. It relies on a CRD (a new type of object, for example MongoDBCommunity) and on a controller that watches these objects and acts so that reality matches what they ask for. A Deployment knows how to restart a Pod that fails; an operator also knows how to configure a database, update it in the right order or back it up.
In this lesson you install a real operator, MongoDB Controllers for Kubernetes (MCK), hand it a replica set (a group of MongoDB instances that copy each other's data), change a setting by touching only the resource, then delete the resource and read what is left. You also check that a CRD alone does nothing, and you learn how to judge an operator before installing it.
What you will learn
Explain what an operator automates that a Deployment cannot do.
Name the building blocks of an operator (CRD, controller, finalizers, status, webhooks, RBAC, events) and say what each one does.
Check that a CRD installed alone triggers no behavior without a controller.
Judge an operator before installing it: compatibility with your Kubernetes version, permissions, license, uninstallation.
Install an operator with kubectl apply, create a resource and read the objects the operator creates and who owns them.
Modify the resource, see the operator apply the setting, then delete the resource and say what remains.
Decide between adopting a public operator and writing your own, and place Operator SDK and Kubebuilder.
Prerequisites
You have read DaemonSets, so you know the workload controllers (Deployment, StatefulSet, DaemonSet). You have also seen StatefulSets, because the operator of this lesson creates one.
You need Docker, kind 0.33.0 or later and kubectl 1.37, on a machine with 2 processors and about 4 GB of memory. Versions used: Kubernetes v1.37.0, MCK 1.15.0, MongoDB Community Server 9.0.8. Pulling the MongoDB images (433 MB for the server) needs a good connection.
Why operators?
A Deployment knows how to run Pods, nothing more. Operating a replicated database takes other actions, which neither a Deployment nor a StatefulSet knows: choosing the member that accepts writes (the primary), adding a replica by copying the data first, scheduling backups, updating in a precise order. Written by hand, these actions end up as scripts that nobody dares to run again.
An operator puts this operating know-how in a controller. You declare in an object what you want (a cluster of three instances, in a given version) and the operator continuously corrects any gap between that declaration and the real state.
What are the building blocks of an operator?
An operator assembles seven elements. The first two are indispensable, the others are common.
Block
Role
CRD
adds an object type to the API (MongoDBCommunity), with a schema that says what you are allowed to write
Controller
watches the objects of the new type and acts to reach the declared state
Finalizers
delay the deletion of an object until a cleanup is finished
status
field written by the controller to say where the object stands (phase, version, last operation)
Admission webhooks
modify (mutating) or refuse (validating) an object before it is stored
RBAC
the permissions the operator needs to act on the API
Events
messages visible in kubectl describe that tell the operator's actions
Swipe to see more
RBAC deserves two sentences right now, because you will read it again before installing an operator. A Role grants permissions in a single namespace, a ClusterRole grants them across the whole cluster. When you read those of an operator, two signals should alert you: a * in the verbs or the resources, and the right to read Secrets in all namespaces. To go further, the lesson Kubernetes RBAC details these objects.
The controller works in a loop: it reads the real state, compares it to the declared state, then acts to reduce the gap. This loop never stops, and it is called reconciliation. On the diagram, follow the arrows: the controller observes, compares, acts, then starts again.
Two of these blocks deserve a few more words, because the controller writes them itself. The status field is never filled in by the user: the controller records the state of the object there.
A finalizer is a mark that the controller puts on the object. When you ask for deletion, the API notes the date of the request but does not erase the object while the mark is there. The operator uses this to clean up, for example to delete the files of a backup, then it removes the mark and the object disappears.
Prepare a cluster for the lesson
The whole lesson runs on a one-node kind cluster, created for it and deleted at the end. A new cluster guarantees that nothing is left over from a previous lesson.
The progress lines of kind, before Set kubectl context, are omitted. Look at the last line of each command: the node is Ready and the client and the server are both in v1.37.0.
The names and messages of this lesson are in French on purpose, so that the outputs stay those of the tested cluster: demo-operateur means "demo-operator", ws-operateurs "ws-operators", atelier "workshop", Sauvegarde and sauvegardes "backup" and "backups", sauv is the short name of sauvegarde, nuit "night", donnees-boutique "shop-data", retentionJours "retentionDays", operateur "operator", Demo-Operateur-2026 "Demo-Operator-2026", and formation "training". In the polling loops, debut means "start" and ecoule "elapsed", and in their output <vide> means <empty>, <aucun><none> and abandon après 600 s "giving up after 600 s".
A CRD alone does nothing
People often believe that installing a CRD is enough to get a behavior. A short experiment removes the doubt: install a CRD without any controller and see whether anything happens. The file below defines a Sauvegarde type in the atelier.formation.k8s group; the lesson Operators and CRDs for developers writes it and explains it line by line. Here, you copy it as it is.
The API accepted, validated and stored the object, and kubectl get shows it with its columns. The PHASE column is empty: nobody filled it in. Wait 30 seconds, then look for a status or any trace of activity in the namespace.
The first line is empty: the object has no status. The second says that there is no Pod, no Job and no event in the namespace. Your cluster accepts the object, keeps it and displays it, and does nothing with it. A CRD without a controller is only a form: it defines what you are allowed to write, not what happens next.
This helps with diagnosis: a custom object that "does nothing" does not necessarily have a faulty manifest. Before rereading the YAML, check that the operator's controller is running. This CRD has done its demonstration job, so delete it with its namespace before moving on to a real operator.
How to find and judge an operator before installing it?
An installed operator is third-party code that runs in your cluster with broad permissions, often on every resource of a type. You therefore judge it before installing it, on six points that no catalog checks for you.
Compatibility with the Kubernetes version of the cluster, read in the operator's documentation before any kubectl apply.
Project activity: a repository that is not archived, a recent release, issues that get handled.
Requested permissions: the ClusterRole and the RBAC provided, reread for what they really allow.
Installed content: CRDs, webhooks, the controller's Deployment, read in the manifests before applying them.
The license of the operator and the one of the application it drives, which can differ.
The way out: how to uninstall without leaving CRDs or orphan resources behind.
Three sources exist to find an operator. OperatorHub.io is a catalog of operators. A Helm (in French) chart can also install an operator with its CRDs. Finally, the project's GitHub repository is the source to consult: it shows the real activity of the operator. The deployment of Keycloak by its operator, described in Deploy Keycloak on Kubernetes with the Operator, shows another official operator used from end to end.
The first point of the list, compatibility, is not theoretical. On 2026-11-12, the page cert-manager.io/docs/releases declares the latest stable series of cert-manager, 1.21 (whose latest published version is 1.21.3), compatible with Kubernetes 1.33 to 1.36. On a 1.37 cluster, this series is therefore not supported, and the site's cert-manager guide must be read with this matrix in front of you.
The operator of this lesson passes the same check: the MCK compatibility page lists Kubernetes 1.35, 1.36 and 1.37 for version 1.15.0. Reading the matrix before installing avoids an operator that starts halfway, with failing webhooks.
The license deserves the same attention. The LICENSE-MCK file of MCK is a dual license: Apache 2.0 to drive MongoDB Community databases, the MongoDB Customer Agreement otherwise. The server that the operator launches is under the Server Side Public License (SSPL) version 1, which the /licenses/LICENSE file of the image recalls. The operator and the database therefore have two distinct licenses.
How to install an operator with kubectl apply?
An operator is installed in three steps: create the namespace, apply the CRDs, then apply the manifest that brings the controller and its permissions. The order matters, because the MCK manifest targets the mongodb namespace without creating it, and a resource of an unknown type is refused. Both files come from the project's repository, at the version tag, never from the main branch, which moves.
Download the manifests and pin the images
Download the two files at the 1.15.0 tag, then keep a copy of the manifest before changing it, so you can compare.
The manifest names its images by a tag, which a publisher can move to another image without warning. The digest is the SHA-256 fingerprint of the exact content of an image: it does not move. So pin the images by their digest, in the name:tag@sha256:… format: the tag stays readable, and the runtime pulls only the digest. You read the digest of an image with docker buildx imagetools inspect <image:tag>, Digest line.
The diff must show eight changed lines: the image of the operator's container and seven environment variables that name the other images. Its exit code is 1, which is normal: this is how diff reports that it found differences.
Two of these seven variables, those of Envoy (a network proxy) and OpenTelemetry (a collector of metrics and traces), name images that your database will never launch: they serve other resource types of MCK, which this lesson does not create. The two matching sed lines stay in the command, so that no mutable reference remains in the manifest you apply.
One image escapes this manifest: the MongoDB server one. The operator builds it itself from the version requested in the resource, in the form quay.io/mongodb/mongodb-community-server:<version>-ubi8, so with a mutable tag. It is pinned later, in the resource.
Apply the CRDs, then the operator
Create the namespace, then apply the CRDs. Each line of the output is a new object type that the API can serve.
Terminal window
kubectlcreatenamespacemongodb
kubectlapply-fcrds.yaml
namespace/mongodb created
customresourcedefinition.apiextensions.k8s.io/voyageais.ai.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/clustermongodbroles.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/mongodb.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/mongodbmulticluster.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/mongodbsearch.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/mongodbusers.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/opsmanagers.mongodb.com created
customresourcedefinition.apiextensions.k8s.io/mongodbcommunity.mongodbcommunity.mongodb.com created
Eight CRDs are created. The one that matters to us is mongodbcommunity.mongodbcommunity.mongodb.com, the MongoDBCommunity type. At this stage, the API would accept an object of this type, as it accepted Sauvegarde, but nothing would process it while the controller is absent. Apply the operator's manifest and wait for its Deployment to be available.
role.rbac.authorization.k8s.io/mongodb-kubernetes-operator created
rolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-operator created
clusterrole.rbac.authorization.k8s.io/mongodb-kubernetes-operator-mongodb-cluster-mongodb-role created
clusterrolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-operator-mongodb-cluster-mongodb-role-binding created
role.rbac.authorization.k8s.io/mongodb-kubernetes-operator-pvc-resize created
rolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-operator-pvc-resize-binding created
clusterrole.rbac.authorization.k8s.io/mongodb-kubernetes-operator-cluster-telemetry created
clusterrolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-operator-mongodb-cluster-telemetry-binding created
clusterrole.rbac.authorization.k8s.io/mongodb-kubernetes-operator-mongodb-webhook-cr created
clusterrolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-operator-mongodb-webhook-crb created
serviceaccount/mongodb-kubernetes-appdb created
serviceaccount/mongodb-kubernetes-database-pods created
serviceaccount/mongodb-kubernetes-ops-manager created
role.rbac.authorization.k8s.io/mongodb-kubernetes-appdb created
rolebinding.rbac.authorization.k8s.io/mongodb-kubernetes-appdb created
serviceaccount/mongodb-kubernetes-operator created
deployment.apps/mongodb-kubernetes-operator created
Waiting for deployment "mongodb-kubernetes-operator" rollout to finish: 0 of 1 updated replicas are available...
deployment "mongodb-kubernetes-operator" successfully rolled out
The first seventeen lines are the content of the manifest: Roles, ClusterRoles and their bindings (the operator's permissions, the ones you would have reread before applying), service accounts, and the controller's Deployment. The last two lines say that the controller is available. Finally, check that the Pod really runs on the pinned image.
The first line is the requested image, the second is the one the kubelet actually pulled: the digest is the same. The controller's log, kubectl -n mongodb logs deployment/mongodb-kubernetes-operator, shows its controllers starting. Look for the Starting Controller and Starting workers lines of the mongodbcommunity controller: it is the one that will process your resource.
What does the operator create when you give it a resource?
A MongoDBCommunity resource describes the wanted database: the type, the version, the number of members, the users. The operator deduces from it all the Kubernetes objects that are needed. The file below asks for a replica set with a single member, because the cluster has only one node, with a user whose password lives in a Secret.
Two settings differ from the project's example. The first lowers the resource requests to 100m of CPU per container. By default, mongod and its agent request 500m each, so 1000m for the Pod, whereas on a 2-processor machine, the announced minimum, only 550m remain free once the operator is installed (the node's 2000m minus the requests of the system Pods and of the operator): the scheduler could not place the Pod. A bigger machine leaves more room.
The second pins the server image by its digest, in spec.statefulSet, the field that lets you modify the Pod template that the operator builds. Finally, the password is written in clear text for demonstration convenience, which you do not do in production (see Kubernetes Secrets).
Apply the file and follow the status.phase field, which the operator writes itself. The loop prints the phase and the state of the Pod every 5 seconds, until Running.
The intermediate lines are omitted. The phase goes from empty to Pending as soon as the operator has reacted, then to Running after 108 seconds, 44 of which are spent pulling the server image. A single Pod exists, demo-mongodb-0, with two containers: mongod and the MongoDB agent that the operator drives. Check the state of the resource, then list the created objects with their owner.
Pod mongodb-kubernetes-operator-7f9c78dc9f-mqpws ReplicaSet mongodb-kubernetes-operator-7f9c78dc9f true
The ownerReferences field of an object says "I am owned by this object". Kubernetes uses it to clean up: when the owner is deleted, its garbage collector deletes the objects it owns, as with the Pods of a ReplicaSet (see ReplicaSets).
Read the OWNER_KIND column. The operator created two StatefulSets, a headless demo-mongodb-svc Service and five Secrets, all owned by the demo-mongodbMongoDBCommunity resource. The Pod, for its part, belongs to the StatefulSet. The second StatefulSet, demo-mongodb-arb, serves arbiters, members that vote without storing data: it stays at zero replicas here.
Several objects have no owner. The demo-user-password Secret is yours, written by hand. The two PVCs, data-volume-demo-mongodb-0 and logs-volume-demo-mongodb-0, are born from the StatefulSet's volumeClaimTemplates, which does not own them. The operator-webhook Service and the mongodb-enterprise-operator-telemetry ConfigMap are created by the operator when it starts, before your resource, for its own use. The kube-root-ca.crt ConfigMap is added by Kubernetes to every namespace. No ConfigMap belongs to the replica set: its configuration is in the demo-mongodb-config Secret.
The operator also writes the state of the resource. This excerpt comes from kubectl -n mongodb get mongodbcommunity demo-mongodb -o yaml.
The status carries the phase, the version, the number of members and the connection URI, everything you would have had to collect by hand. The resource's metadata has no finalizers field: you will see the consequence at deletion.
If the resource stays in Pending, read its events with kubectl -n mongodb describe mongodbcommunity demo-mongodb and those of the Pod with kubectl -n mongodb get events. You can follow the creation of the PVCs, the pull of each image, and failures of the readiness probe (Mongod is not ready) that normally come before the switch to Running.
What happens when you modify the resource?
To change a database setting, you touch neither the StatefulSet nor the Pod: you modify the resource, and the operator does the rest. The chosen setting is the slow query threshold of mongod (slowOpThresholdMs), 100 ms by default, which you raise to 250 ms. First read its current value in mongod, with mongosh (MongoDB's command-line client) and the user that the operator created.
The operator wrote the user's connection string in the demo-mongodb-admin-demo-user Secret, and mongosh uses it. The grep -v EACCES filter removes a harmless warning: mongosh cannot create its history directory.
Read slowms=100: it is the default value. The uptime, the lifetime of the process, will be different on your side. Now modify the resource, then follow the generation of the resource, its phase and the state of the Pod. In the command, mdbc is the short name of mongodbcommunity.
The intermediate lines are omitted. Three things can be read. The resource's generation goes to 2 as soon as the patch is applied, and the phase goes back to Pending: the operator has seen the gap. The Pod's restart counter goes from 0 to 1: the Pod was not recreated, one of its containers restarted. The phase returns to Running about one minute after the patch. Now read the setting again in mongod, with the same command.
slowms=250: mongod took the setting, and its uptime of 14 seconds says that it has just restarted. In this demonstration, the Pod keeps its identifier (uid) and the StatefulSet stays at generation 1: the operator did not change the Pod template. It updated the configuration that the MongoDB agent reads (the demo-mongodb-config Secret), the agent stopped mongod cleanly (exit code 0), and the kubelet restarted the container.
The operator's log tells the story: it repeats The Pod 'demo-mongodb-0' hasn't reached the goal state yet, then writes All 1 Agents have reached Goal state. This is reconciliation at work: the operator rewrote the configuration and waited, until the real state reached the declared state.
What remains when you delete the resource?
Deleting the resource removes some of the objects, not all of them. No finalizer is set on demo-mongodb: kubectl delete returns immediately, and the garbage collector removes the owned objects. Then list what remains in the namespace and in the cluster.
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS VOLUMEATTRIBUTESCLASS REASON AGE
pvc-2101f7a0-3e8e-46cd-b2b0-2d5bb9ed03fb 2G RWO Delete Bound mongodb/logs-volume-demo-mongodb-0 standard <unset> 3m56s
pvc-df5024f7-1349-4d98-a8fc-6adaea303abd 10G RWO Delete Bound mongodb/data-volume-demo-mongodb-0 standard <unset> 3m56s
The two StatefulSets, the replica set's Service and the five owned Secrets are gone, and so is the Pod. The objects without an owner stayed: the two PVCs and their volumes, so the database's data, the password Secret that you wrote, and what the operator created for itself (operator-webhook, the telemetry ConfigMap). Keeping the data when you delete the resource protects against a deletion by mistake, but you have to delete the PVCs yourself to free the storage: their volumes have a Delete reclaim policy (the one that decides the fate of a volume when its PVC disappears), so they go away with them.
Uninstalling the operator has the same limits. kubectl delete -f mongodb-kubernetes.yaml deletes the seventeen objects of the manifest, and kubectl delete -f crds.yaml the eight CRDs, but the operator-webhook Service and the telemetry ConfigMap, created by the controller and not by the manifest, remain in the namespace. Deleting the CRDs also deletes all the resources of these types: reread the lesson Operators and CRDs for developers before doing it on a cluster that matters.
Should you adopt an existing operator or write your own?
Adopt an existing operator in the general case: it carries the operating experience of a community, and you only maintain its configuration. Writing your own makes sense when the application is specific to your company, the component is critical enough to need to be controlled, and no existing operator covers the need. A homemade operator is code to maintain, test and update with every Kubernetes version.
If you write your own, two frameworks generate a project skeleton (CRD, controller, RBAC) from a description: Kubebuilder, from the Kubernetes SIG API Machinery project, and Operator SDK, from the Operator Framework project. Both rely on the same controller libraries, so learning one helps with the other. The steps stay the same: define the CRD, write the reconciliation loop, generate the RBAC, test, package.
Clean up the cluster
Delete the cluster by its name: the objects left by the demonstration (volumes, Secret, Service) go with it. Then check that no kind cluster remains.
Terminal window
kinddeletecluster--namedemo-operateur
kindgetclusters
Deleting cluster "demo-operateur" ...
Deleted nodes: ["demo-operateur-control-plane"]
No kind clusters found.
The cluster is deleted and kind get clusters returns nothing. The files in the ~/atelier-k8s/workloads/operators and ~/atelier-k8s/workloads/operateur folders remain on your disk; delete them if you no longer need them.
Put it into practice
The guided lab repeats these actions, for about 40 minutes, on a kubeadm virtual machine. Its preparation installs only the local-path storage class: no operator, no CRD, no namespace. In Install an operator and configure what it runs, you install the MongoDB operator from its versioned manifests, with its images pinned by digest, you hand it a one-member replica set, then you change a mongod setting by modifying only the resource.
The validation checks six states: the CRD established, the operator available on its image pinned by digest, the resource in the Running phase, the StatefulSet and the Service that belong to the resource, mongod on the server image pinned by digest, and mongod restarted with the 250 ms threshold. Pulling the server image (433 MB) takes several minutes on the virtual machine.
Key takeaways
An operator automates the operation of an application (configuration, ordered update, backup), where a Deployment is limited to restarting Pods.
It relies on a CRD, which adds an object type to the API, and on a controller that reconciles the real state and the declared state in a loop.
A CRD installed without a controller accepts, validates and stores its objects, and does nothing with them: empty status, no Pod, no event. An object that does nothing is diagnosed by first checking that the controller is running.
Before installing an operator, read its compatibility matrix with your Kubernetes version, its activity, the permissions it requests, the manifests it installs, its license and its uninstallation. Adopt an existing operator in the general case, and write your own (Kubebuilder, Operator SDK) only for a critical component that no operator covers.
An operator is installed with kubectl apply in this order: namespace, CRDs, manifest, taking the files at the version tag and pinning the images by digest. An image that the operator builds itself, like the MongoDB server, is pinned in the resource.
The operator creates the objects of a resource with an ownerReferences that points to it: kubectl get ... -o custom-columns on this field tells who owns what.
Modifying the resource is enough to reconfigure the application: the operator rewrites the configuration, and here only the mongod container restarts, without the Pod or the StatefulSet being recreated.
Deleting the resource removes the owned objects, but keeps the PVCs, the Secrets written by hand and the objects that the operator creates for itself.
Test your knowledge
This quiz covers the building blocks of an operator, the behavior of a CRD without a controller, the installation of an operator and the ownership of the objects it creates, and the criteria to judge it. Allow five minutes and aim for 80%; below that, reread "A CRD alone does nothing" and "What does the operator create when you give it a resource?".
Knowledge check
Check what you have learned with this interactive quiz
7 questions
5 min
80% to pass
How it works
The timer starts when you click Start
Multiple choice, true/false and short answer questions
You can move between questions
Detailed results are shown at the end
Starts the quiz and the timer
⏱️--:--
0 / 7
Review
(0/0)
--:--
0%
0Correct
0To review
0:00Time
-Level
Score by domain
A domain groups several guides and gets several questions, so its score is more reliable than a per-topic score, which often rests on a single question.
Summary
Strengths
No topic passed at 80% on at least two questions yet.