背景
前置条件
安装 kubebuilder 工具
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/
实践
创建项目
mkdir memcached-operator
cd memcached-operator
go mod init memcached-operator
kubebuilder init --domain=example.com
此时，项目目录结构如下：
.
├── Dockerfile
├── Makefile
├── PROJECT
├── README.md
├── cmd
│ └── main.go
├── config
│ ├── default
│ │ ├── kustomization.yaml
│ │ ├── manager_metrics_patch.yaml
│ │ └── metrics_service.yaml
│ ├── manager
│ │ ├── kustomization.yaml
│ │ └── manager.yaml
│ ├── network-policy
│ │ ├── allow-metrics-traffic.yaml
│ │ └── kustomization.yaml
│ ├── prometheus
│ │ ├── kustomization.yaml
│ │ └── monitor.yaml
│ └── rbac
│ ├── kustomization.yaml
│ ├── leader_election_role.yaml
│ ├── leader_election_role_binding.yaml
│ ├── metrics_auth_role.yaml
│ ├── metrics_auth_role_binding.yaml
│ ├── metrics_reader_role.yaml
│ ├── role.yaml
│ ├── role_binding.yaml
│ └── service_account.yaml
├── go.mod
├── go.sum
├── hack
│ └── boilerplate.go.txt
└── test
├── e2e
│ ├── e2e_suite_test.go
│ └── e2e_test.go
└── utils
└── utils.go
创建 API（CRD、控制器）
运行以下命令创建一个 API
kubebuilder create api --group cache --version v1alpha1 --kind Memcached
-RUN pip install -r requirements.txt
+RUN pip install -r requirements.txt -i https://pypi.douban.com/simple
此时，会在项目目录下生成一些新文件。
.
├── Dockerfile
├── Makefile
├── PROJECT
├── README.md
+├── api
+│ └── v1alpha1
+│ ├── groupversion_info.go
+│ ├── memcached_types.go
+│ └── zz_generated.deepcopy.go
├── bin
│ ├── controller-gen -> /home/wangkuan/workspace/PE/standardization/operators/memcached-operator/bin/controller-gen-v0.16.4
│ └── controller-gen-v0.16.4
├── cmd
│ └── main.go
├── config
+│ ├── crd
+│ │ ├── kustomization.yaml
+│ │ └── kustomizeconfig.yaml
│ ├── default
│ │ ├── kustomization.yaml
│ │ ├── manager_metrics_patch.yaml
│ │ └── metrics_service.yaml
│ ├── manager
│ │ ├── kustomization.yaml
│ │ └── manager.yaml
│ ├── network-policy
│ │ ├── allow-metrics-traffic.yaml
│ │ └── kustomization.yaml
│ ├── prometheus
│ │ ├── kustomization.yaml
│ │ └── monitor.yaml
│ ├── rbac
│ │ ├── kustomization.yaml
│ │ ├── leader_election_role.yaml
│ │ ├── leader_election_role_binding.yaml
+│ │ ├── memcached_editor_role.yaml
+│ │ ├── memcached_viewer_role.yaml
│ │ ├── metrics_auth_role.yaml
│ │ ├── metrics_auth_role_binding.yaml
│ │ ├── metrics_reader_role.yaml
│ │ ├── role.yaml
│ │ ├── role_binding.yaml
│ │ └── service_account.yaml
+│ └── samples
+│ ├── cache_v1alpha1_memcached.yaml
+│ └── kustomization.yaml
├── go.mod
├── go.sum
├── hack
│ └── boilerplate.go.txt
+├── internal
+│ └── controller
+│ ├── memcached_controller.go
+│ ├── memcached_controller_test.go
+│ └── suite_test.go
└── test
├── e2e
│ ├── e2e_suite_test.go
│ └── e2e_test.go
└── utils
└── utils.go
并且有些文件内容会产生变化：
PROJECT
# Code generated by tool. DO NOT EDIT.
# This file is used to track the info used to scaffold your project
# and allow the plugins properly work.
# More info: https://book.kubebuilder.io/reference/project-config.html
domain: example.com
layout:
- go.kubebuilder.io/v4
projectName: memcached-operator
repo: memcached-operator
+resources:
+- api:
+ crdVersion: v1
+ namespaced: true
+ controller: true
+ domain: example.com
+ group: cache
+ kind: Memcached
+ path: memcached-operator/api/v1alpha1
+ version: v1alpha1
version: "3"
cmd/main.go
/*
Copyright 2025.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package main
import (
"crypto/tls"
"flag"
"os"
// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
// to ensure that exec-entrypoint and run can make use of them.
_ "k8s.io/client-go/plugin/pkg/client/auth"
"k8s.io/apimachinery/pkg/runtime"
utilruntime "k8s.io/apimachinery/pkg/util/runtime"
clientgoscheme "k8s.io/client-go/kubernetes/scheme"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/healthz"
"sigs.k8s.io/controller-runtime/pkg/log/zap"
"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
"sigs.k8s.io/controller-runtime/pkg/webhook"
+
+ cachev1alpha1 "memcached-operator/api/v1alpha1"
+ "memcached-operator/internal/controller"
// +kubebuilder:scaffold:imports
)
var (
scheme = runtime.NewScheme()
setupLog = ctrl.Log.WithName("setup")
)
func init() {
utilruntime.Must(clientgoscheme.AddToScheme(scheme))
+ utilruntime.Must(cachev1alpha1.AddToScheme(scheme))
// +kubebuilder:scaffold:scheme
}
func main() {
var metricsAddr string
var enableLeaderElection bool
var probeAddr string
var secureMetrics bool
var enableHTTP2 bool
var tlsOpts []func(*tls.Config)
flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
"Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.")
flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
flag.BoolVar(&enableLeaderElection, "leader-elect", false,
"Enable leader election for controller manager. "+
"Enabling this will ensure there is only one active controller manager.")
flag.BoolVar(&secureMetrics, "metrics-secure", true,
"If set, the metrics endpoint is served securely via HTTPS. Use --metrics-secure=false to use HTTP instead.")
flag.BoolVar(&enableHTTP2, "enable-http2", false,
"If set, HTTP/2 will be enabled for the metrics and webhook servers")
opts := zap.Options{
Development: true,
}
opts.BindFlags(flag.CommandLine)
flag.Parse()
ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))
// if the enable-http2 flag is false (the default), http/2 should be disabled
// due to its vulnerabilities. More specifically, disabling http/2 will
// prevent from being vulnerable to the HTTP/2 Stream Cancellation and
// Rapid Reset CVEs. For more information see:
// - https://github.com/advisories/GHSA-qppj-fm5r-hxr3
// - https://github.com/advisories/GHSA-4374-p667-p6c8
disableHTTP2 := func(c *tls.Config) {
setupLog.Info("disabling http/2")
c.NextProtos = []string{"http/1.1"}
}
if !enableHTTP2 {
tlsOpts = append(tlsOpts, disableHTTP2)
}
webhookServer := webhook.NewServer(webhook.Options{
TLSOpts: tlsOpts,
})
// Metrics endpoint is enabled in 'config/default/kustomization.yaml'. The Metrics options configure the server.
// More info:
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.19.1/pkg/metrics/server
// - https://book.kubebuilder.io/reference/metrics.html
metricsServerOptions := metricsserver.Options{
BindAddress: metricsAddr,
SecureServing: secureMetrics,
TLSOpts: tlsOpts,
}
if secureMetrics {
// FilterProvider is used to protect the metrics endpoint with authn/authz.
// These configurations ensure that only authorized users and service accounts
// can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info:
// https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.19.1/pkg/metrics/filters#WithAuthenticationAndAuthorization
metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
// TODO(user): If CertDir, CertName, and KeyName are not specified, controller-runtime will automatically
// generate self-signed certificates for the metrics server. While convenient for development and testing,
// this setup is not recommended for production.
}
mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
Scheme: scheme,
Metrics: metricsServerOptions,
WebhookServer: webhookServer,
HealthProbeBindAddress: probeAddr,
LeaderElection: enableLeaderElection,
LeaderElectionID: "87a7d51f.example.com",
// LeaderElectionReleaseOnCancel defines if the leader should step down voluntarily
// when the Manager ends. This requires the binary to immediately end when the
// Manager is stopped, otherwise, this setting is unsafe. Setting this significantly
// speeds up voluntary leader transitions as the new leader don't have to wait
// LeaseDuration time first.
//
// In the default scaffold provided, the program ends immediately after
// the manager stops, so would be fine to enable this option. However,
// if you are doing or is intended to do any operation such as perform cleanups
// after the manager stops then its usage might be unsafe.
// LeaderElectionReleaseOnCancel: true,
})
if err != nil {
setupLog.Error(err, "unable to start manager")
os.Exit(1)
}
+ if err = (&controller.MemcachedReconciler{
+ Client: mgr.GetClient(),
+ Scheme: mgr.GetScheme(),
+ }).SetupWithManager(mgr); err != nil {
+ setupLog.Error(err, "unable to create controller", "controller", "Memcached")
+ os.Exit(1)
+ }
// +kubebuilder:scaffold:builder
if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
setupLog.Error(err, "unable to set up health check")
os.Exit(1)
}
if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
setupLog.Error(err, "unable to set up ready check")
os.Exit(1)
}
setupLog.Info("starting manager")
if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
setupLog.Error(err, "problem running manager")
os.Exit(1)
}
}
config/default/kustomization.yaml
# Adds namespace to all resources.
namespace: memcached-operator-system
# Value of this field is prepended to the
# names of all resources, e.g. a deployment named
# "wordpress" becomes "alices-wordpress".
# Note that it should also match with the prefix (text before '-') of the namespace
# field above.
namePrefix: memcached-operator-
# Labels to add to all resources and selectors.
#labels:
#- includeSelectors: true
# pairs:
# someName: someValue
resources:
-#- ../crd
+- ../crd
- ../rbac
- ../manager
# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
# crd/kustomization.yaml
#- ../webhook
# [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER'. 'WEBHOOK' components are required.
#- ../certmanager
# [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'.
#- ../prometheus
# [METRICS] Expose the controller manager metrics service.
- metrics_service.yaml
# [NETWORK POLICY] Protect the /metrics endpoint and Webhook Server with NetworkPolicy.
# Only Pod(s) running a namespace labeled with 'metrics: enabled' will be able to gather the metrics.
# Only CR(s) which requires webhooks and are applied on namespaces labeled with 'webhooks: enabled' will
# be able to communicate with the Webhook Server.
#- ../network-policy
# Uncomment the patches line if you enable Metrics, and/or are using webhooks and cert-manager
patches:
# [METRICS] The following patch will enable the metrics endpoint using HTTPS and the port :8443.
# More info: https://book.kubebuilder.io/reference/metrics
- path: manager_metrics_patch.yaml
target:
kind: Deployment
# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
# crd/kustomization.yaml
#- path: manager_webhook_patch.yaml
# [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER' prefix.
# Uncomment the following replacements to add the cert-manager CA injection annotations
#replacements:
# - source: # Uncomment the following block if you have any webhook
# kind: Service
# version: v1
# name: webhook-service
# fieldPath: .metadata.name # Name of the service
# targets:
# - select:
# kind: Certificate
# group: cert-manager.io
# version: v1
# fieldPaths:
# - .spec.dnsNames.0
# - .spec.dnsNames.1
# options:
# delimiter: '.'
# index: 0
# create: true
# - source:
# kind: Service
# version: v1
# name: webhook-service
# fieldPath: .metadata.namespace # Namespace of the service
# targets:
# - select:
# kind: Certificate
# group: cert-manager.io
# version: v1
# fieldPaths:
# - .spec.dnsNames.0
# - .spec.dnsNames.1
# options:
# delimiter: '.'
# index: 1
# create: true
#
# - source: # Uncomment the following block if you have a ValidatingWebhook (--programmatic-validation)
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.namespace # Namespace of the certificate CR
# targets:
# - select:
# kind: ValidatingWebhookConfiguration
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 0
# create: true
# - source:
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.name
# targets:
# - select:
# kind: ValidatingWebhookConfiguration
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 1
# create: true
#
# - source: # Uncomment the following block if you have a DefaultingWebhook (--defaulting )
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.namespace # Namespace of the certificate CR
# targets:
# - select:
# kind: MutatingWebhookConfiguration
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 0
# create: true
# - source:
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.name
# targets:
# - select:
# kind: MutatingWebhookConfiguration
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 1
# create: true
#
# - source: # Uncomment the following block if you have a ConversionWebhook (--conversion)
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.namespace # Namespace of the certificate CR
# targets:
# - select:
# kind: CustomResourceDefinition
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 0
# create: true
# - source:
# kind: Certificate
# group: cert-manager.io
# version: v1
# name: serving-cert # This name should match the one in certificate.yaml
# fieldPath: .metadata.name
# targets:
# - select:
# kind: CustomResourceDefinition
# fieldPaths:
# - .metadata.annotations.[cert-manager.io/inject-ca-from]
# options:
# delimiter: '/'
# index: 1
# create: true
config/rbac/kustomization.yaml
resources:
# All RBAC will be applied under this service account in
# the deployment namespace. You may comment out this resource
# if your manager will use a service account that exists at
# runtime. Be sure to update RoleBinding and ClusterRoleBinding
# subjects if changing service account names.
- service_account.yaml
- role.yaml
- role_binding.yaml
- leader_election_role.yaml
- leader_election_role_binding.yaml
# The following RBAC configurations are used to protect
# the metrics endpoint with authn/authz. These configurations
# ensure that only authorized users and service accounts
# can access the metrics endpoint. Comment the following
# permissions if you want to disable this protection.
# More info: https://book.kubebuilder.io/reference/metrics.html
- metrics_auth_role.yaml
- metrics_auth_role_binding.yaml
- metrics_reader_role.yaml
+# For each CRD, "Editor" and "Viewer" roles are scaffolded by
+# default, aiding admins in cluster management. Those roles are
+# not used by the Project itself. You can comment the following lines
+# if you do not want those helpers be installed with your Project.
+- memcached_editor_role.yaml
+- memcached_viewer_role.yaml
+
定义 CRD 结构体
编写 memcached_types.go 文件，定义相关 CRD 结构，代码变化如下：
/*
Copyright 2025.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package v1alpha1
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
// MemcachedSpec defines the desired state of Memcached.
type MemcachedSpec struct {
// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
// Important: Run "make" to regenerate code after modifying this file
- // Foo is an example field of Memcached. Edit memcached_types.go to remove/update
- Foo string `json:"foo,omitempty"`
+ // Size defines the number of Memcached instances
+ // The following markers will use OpenAPI v3 schema to validate the value
+ // More info: https://book.kubebuilder.io/reference/markers/crd-validation.html
+ // +kubebuilder:validation:Minimum=1
+ // +kubebuilder:validation:Maximum=3
+ // +kubebuilder:validation:ExclusiveMaximum=false
+ Size int32 `json:"size,omitempty"`
}
// MemcachedStatus defines the observed state of Memcached.
type MemcachedStatus struct {
- // INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
- // Important: Run "make" to regenerate code after modifying this file
+ // Represents the observations of a Memcached's current state.
+ // Memcached.status.conditions.type are: "Available", "Progressing", and "Degraded"
+ // Memcached.status.conditions.status are one of True, False, Unknown.
+ // Memcached.status.conditions.reason the value should be a CamelCase string and producers of specific
+ // condition types may define expected values and meanings for this field, and whether the values
+ // are considered a guaranteed API.
+ // Memcached.status.conditions.Message is a human readable message indicating details about the transition.
+ // For further information see: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties
+
+ Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
}
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// Memcached is the Schema for the memcacheds API.
type Memcached struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Spec MemcachedSpec `json:"spec,omitempty"`
Status MemcachedStatus `json:"status,omitempty"`
}
// +kubebuilder:object:root=true
// MemcachedList contains a list of Memcached.
type MemcachedList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []Memcached `json:"items"`
}
func init() {
SchemeBuilder.Register(&Memcached{}, &MemcachedList{})
}
生成 CRD 资源清单
修改了 CRD 的定义后，我们我们可以生成包含规范和验证的清单
make generate api/v1alpha1/zz_generated.deepcopy.go
make manifests config/crd/bases config/crd/samples
此时，会在项目目录下生成一些新文件。
.
├── Dockerfile
├── Makefile
├── PROJECT
├── README.md
├── api
│ └── v1alpha1
│ ├── groupversion_info.go
│ ├── memcached_types.go
│ └── zz_generated.deepcopy.go
├── bin
│ ├── controller-gen -> /home/wangkuan/workspace/PE/standardization/operators/memcached-operator/bin/controller-gen-v0.16.4
│ └── controller-gen-v0.16.4
├── cmd
│ └── main.go
├── config
│ ├── crd
+│ │ ├── bases
+│ │ │ └── cache.example.com_memcacheds.yaml
│ │ ├── kustomization.yaml
│ │ └── kustomizeconfig.yaml
│ ├── default
│ │ ├── kustomization.yaml
│ │ ├── manager_metrics_patch.yaml
│ │ └── metrics_service.yaml
│ ├── manager
│ │ ├── kustomization.yaml
│ │ └── manager.yaml
│ ├── network-policy
│ │ ├── allow-metrics-traffic.yaml
│ │ └── kustomization.yaml
│ ├── prometheus
│ │ ├── kustomization.yaml
│ │ └── monitor.yaml
│ ├── rbac
│ │ ├── kustomization.yaml
│ │ ├── leader_election_role.yaml
│ │ ├── leader_election_role_binding.yaml
│ │ ├── memcached_editor_role.yaml
│ │ ├── memcached_viewer_role.yaml
│ │ ├── metrics_auth_role.yaml
│ │ ├── metrics_auth_role_binding.yaml
│ │ ├── metrics_reader_role.yaml
│ │ ├── role.yaml
│ │ ├── role_binding.yaml
│ │ └── service_account.yaml
│ └── samples
│ ├── cache_v1alpha1_memcached.yaml
│ └── kustomization.yaml
├── go.mod
├── go.sum
├── hack
│ └── boilerplate.go.txt
├── internal
│ └── controller
│ ├── memcached_controller.go
│ ├── memcached_controller_test.go
│ └── suite_test.go
└── test
├── e2e
│ ├── e2e_suite_test.go
│ └── e2e_test.go
└── utils
└── utils.go
并且有些文件内容会产生变化：
api/v1alpha1/zz_generated.deepcopy.go
//go:build !ignore_autogenerated
/*
Copyright 2025.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
// Code generated by controller-gen. DO NOT EDIT.
package v1alpha1
import (
+ "k8s.io/apimachinery/pkg/apis/meta/v1"
runtime "k8s.io/apimachinery/pkg/runtime"
)
// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (in *Memcached) DeepCopyInto(out *Memcached) {
*out = *in
out.TypeMeta = in.TypeMeta
in.ObjectMeta.DeepCopyInto(&out.ObjectMeta)
out.Spec = in.Spec
- out.Status = in.Status
+ in.Status.DeepCopyInto(&out.Status)
}
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Memcached.
func (in *Memcached) DeepCopy() *Memcached {
if in == nil {
return nil
}
out := new(Memcached)
in.DeepCopyInto(out)
return out
}
// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
func (in *Memcached) DeepCopyObject() runtime.Object {
if c := in.DeepCopy(); c != nil {
return c
}
return nil
}
// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (in *MemcachedList) DeepCopyInto(out *MemcachedList) {
*out = *in
out.TypeMeta = in.TypeMeta
in.ListMeta.DeepCopyInto(&out.ListMeta)
if in.Items != nil {
in, out := &in.Items, &out.Items
*out = make([]Memcached, len(*in))
for i := range *in {
(*in)[i].DeepCopyInto(&(*out)[i])
}
}
}
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MemcachedList.
func (in *MemcachedList) DeepCopy() *MemcachedList {
if in == nil {
return nil
}
out := new(MemcachedList)
in.DeepCopyInto(out)
return out
}
// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
func (in *MemcachedList) DeepCopyObject() runtime.Object {
if c := in.DeepCopy(); c != nil {
return c
}
return nil
}
// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (in *MemcachedSpec) DeepCopyInto(out *MemcachedSpec) {
*out = *in
}
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MemcachedSpec.
func (in *MemcachedSpec) DeepCopy() *MemcachedSpec {
if in == nil {
return nil
}
out := new(MemcachedSpec)
in.DeepCopyInto(out)
return out
}
// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
func (in *MemcachedStatus) DeepCopyInto(out *MemcachedStatus) {
+ *out = *in
+ if in.Conditions != nil {
+ in, out := &in.Conditions, &out.Conditions
+ *out = make([]v1.Condition, len(*in))
+ for i := range *in {
+ (*in)[i].DeepCopyInto(&(*out)[i])
+ }
+ }
}
// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new MemcachedStatus.
func (in *MemcachedStatus) DeepCopy() *MemcachedStatus {
if in == nil {
return nil
}
out := new(MemcachedStatus)
in.DeepCopyInto(out)
return out
}
config/rbac/role.yaml
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
- labels:
- app.kubernetes.io/name: memcached-operator
- app.kubernetes.io/managed-by: kustomize
metadata:
name: manager-role
rules:
-- apiGroups: [""]
+- apiGroups:
+ - cache.example.com
- resources: ["pods"]
+ resources:
+ - memcacheds
- verbs: ["get", "list", "watch"]
+ verbs:
+ - create
+ - delete
+ - get
+ - list
+ - patch
+ - update
+ - watch
+- apiGroups:
+ - cache.example.com
+ resources:
+ - memcacheds/finalizers
+ verbs:
+ - update
+- apiGroups:
+ - cache.example.com
+ resources:
+ - memcacheds/status
+ verbs:
+ - get
+ - patch
+ - update
编写控制器
编写 memcached_controller.go 文件，定义控制器逻辑，代码变化如下：
/*
Copyright 2025.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package controller
import (
"context"
+ "fmt"
+ "time"
+
+ appsv1 "k8s.io/api/apps/v1"
+ corev1 "k8s.io/api/core/v1"
+ apierrors "k8s.io/apimachinery/pkg/api/errors"
+ "k8s.io/apimachinery/pkg/api/meta"
+ metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+ "k8s.io/apimachinery/pkg/types"
"k8s.io/apimachinery/pkg/runtime"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/log"
cachev1alpha1 "memcached-operator/api/v1alpha1"
)
+
+// Definitions to manage status conditions
+const (
+ // typeAvailableMemcached represents the status of the Deployment reconciliation
+ typeAvailableMemcached = "Available"
+ // typeDegradedMemcached represents the status used when the custom resource is deleted and the finalizer operations are yet to occur.
+ typeDegradedMemcached = "Degraded"
+)
// MemcachedReconciler reconciles a Memcached object
type MemcachedReconciler struct {
client.Client
Scheme *runtime.Scheme
}
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=cache.example.com,resources=memcacheds/finalizers,verbs=update
+// +kubebuilder:rbac:groups=core,resources=events,verbs=create;patch
+// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=core,resources=pods,verbs=get;list;watch
// Reconcile is part of the main kubernetes reconciliation loop which aims to
// move the current state of the cluster closer to the desired state.
-// TODO(user): Modify the Reconcile function to compare the state specified by
-// the Memcached object against the actual cluster state, and then
-// perform operations to make the cluster state reflect the state specified by
-// the user.
+// It is essential for the controller's reconciliation loop to be idempotent. By following the Operator
+// pattern you will create Controllers which provide a reconcile function
+// responsible for synchronizing resources until the desired state is reached on the cluster.
+// Breaking this recommendation goes against the design principles of controller-runtime.
+// and may lead to unforeseen consequences such as resources becoming stuck and requiring manual intervention.
+// For further info:
+// - About Operator Pattern: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
+// - About Controllers: https://kubernetes.io/docs/concepts/architecture/controller/
//
// For more details, check Reconcile and its Result here:
// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.19.1/pkg/reconcile
func (r *MemcachedReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
- _ = log.FromContext(ctx)
+ log := log.FromContext(ctx)
- // TODO(user): your logic here
+ // Fetch the Memcached instance
+ // The purpose is check if the Custom Resource for the Kind Memcached
+ // is applied on the cluster if not we return nil to stop the reconciliation
+ memcached := &cachev1alpha1.Memcached{}
+ err := r.Get(ctx, req.NamespacedName, memcached)
+ if err != nil {
+ if apierrors.IsNotFound(err) {
+ // If the custom resource is not found then it usually means that it was deleted or not created
+ // In this way, we will stop the reconciliation
+ log.Info("memcached resource not found. Ignoring since object must be deleted")
+ return ctrl.Result{}, nil
+ }
+ // Error reading the object - requeue the request.
+ log.Error(err, "Failed to get memcached")
+ return ctrl.Result{}, err
+ }
+
+ // Let's just set the status as Unknown when no status is available
+ if memcached.Status.Conditions == nil || len(memcached.Status.Conditions) == 0 {
+ meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached, Status: metav1.ConditionUnknown, Reason: "Reconciling", Message: "Starting reconciliation"})
+ if err = r.Status().Update(ctx, memcached); err != nil {
+ log.Error(err, "Failed to update Memcached status")
+ return ctrl.Result{}, err
+ }
+
+ // Let's re-fetch the memcached Custom Resource after updating the status
+ // so that we have the latest state of the resource on the cluster and we will avoid
+ // raising the error "the object has been modified, please apply
+ // your changes to the latest version and try again" which would re-trigger the reconciliation
+ // if we try to update it again in the following operations
+ if err := r.Get(ctx, req.NamespacedName, memcached); err != nil {
+ log.Error(err, "Failed to re-fetch memcached")
+ return ctrl.Result{}, err
+ }
+ }
+
+ // Check if the deployment already exists, if not create a new one
+ found := &appsv1.Deployment{}
+ err = r.Get(ctx, types.NamespacedName{Name: memcached.Name, Namespace: memcached.Namespace}, found)
+ if err != nil && apierrors.IsNotFound(err) {
+ // Define a new deployment
+ dep, err := r.deploymentForMemcached(memcached)
+ if err != nil {
+ log.Error(err, "Failed to define new Deployment resource for Memcached")
+
+ // The following implementation will update the status
+ meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
+ Status: metav1.ConditionFalse, Reason: "Reconciling",
+ Message: fmt.Sprintf("Failed to create Deployment for the custom resource (%s): (%s)", memcached.Name, err)})
+
+ if err := r.Status().Update(ctx, memcached); err != nil {
+ log.Error(err, "Failed to update Memcached status")
+ return ctrl.Result{}, err
+ }
+
+ return ctrl.Result{}, err
+ }
+
+ log.Info("Creating a new Deployment",
+ "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
+ if err = r.Create(ctx, dep); err != nil {
+ log.Error(err, "Failed to create new Deployment",
+ "Deployment.Namespace", dep.Namespace, "Deployment.Name", dep.Name)
+ return ctrl.Result{}, err
+ }
+
+ // Deployment created successfully
+ // We will requeue the reconciliation so that we can ensure the state
+ // and move forward for the next operations
+ return ctrl.Result{RequeueAfter: time.Minute}, nil
+ } else if err != nil {
+ log.Error(err, "Failed to get Deployment")
+ // Let's return the error for the reconciliation be re-trigged again
+ return ctrl.Result{}, err
+ }
+
+ // The CRD API defines that the Memcached type have a MemcachedSpec.Size field
+ // to set the quantity of Deployment instances to the desired state on the cluster.
+ // Therefore, the following code will ensure the Deployment size is the same as defined
+ // via the Size spec of the Custom Resource which we are reconciling.
+ size := memcached.Spec.Size
+ if *found.Spec.Replicas != size {
+ found.Spec.Replicas = &size
+ if err = r.Update(ctx, found); err != nil {
+ log.Error(err, "Failed to update Deployment",
+ "Deployment.Namespace", found.Namespace, "Deployment.Name", found.Name)
+
+ // Re-fetch the memcached Custom Resource before updating the status
+ // so that we have the latest state of the resource on the cluster and we will avoid
+ // raising the error "the object has been modified, please apply
+ // your changes to the latest version and try again" which would re-trigger the reconciliation
+ if err := r.Get(ctx, req.NamespacedName, memcached); err != nil {
+ log.Error(err, "Failed to re-fetch memcached")
+ return ctrl.Result{}, err
+ }
+
+ // The following implementation will update the status
+ meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
+ Status: metav1.ConditionFalse, Reason: "Resizing",
+ Message: fmt.Sprintf("Failed to update the size for the custom resource (%s): (%s)", memcached.Name, err)})
+
+ if err := r.Status().Update(ctx, memcached); err != nil {
+ log.Error(err, "Failed to update Memcached status")
+ return ctrl.Result{}, err
+ }
+
+ return ctrl.Result{}, err
+ }
+
+ // Now, that we update the size we want to requeue the reconciliation
+ // so that we can ensure that we have the latest state of the resource before
+ // update. Also, it will help ensure the desired state on the cluster
+ return ctrl.Result{Requeue: true}, nil
+ }
+
+ // The following implementation will update the status
+ meta.SetStatusCondition(&memcached.Status.Conditions, metav1.Condition{Type: typeAvailableMemcached,
+ Status: metav1.ConditionTrue, Reason: "Reconciling",
+ Message: fmt.Sprintf("Deployment for custom resource (%s) with %d replicas created successfully", memcached.Name, size)})
+
+ if err := r.Status().Update(ctx, memcached); err != nil {
+ log.Error(err, "Failed to update Memcached status")
+ return ctrl.Result{}, err
+ }
return ctrl.Result{}, nil
}
// SetupWithManager sets up the controller with the Manager.
+// The Deployment is also watched to ensure its
+// desired state in the cluster.
func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
+ // Watch the Memcached Custom Resource and trigger reconciliation whenever it
+ //is created, updated, or deleted
For(&cachev1alpha1.Memcached{}).
- Named("memcached").
+ // Watch the Deployment managed by the Memcached controller. If any changes occur to the Deployment
+ // owned and managed by this controller, it will trigger reconciliation, ensuring that the cluster
+ // state aligns with the desired state.
+ Owns(&appsv1.Deployment{}).
Complete(r)
}
+
+// deploymentForMemcached returns a Memcached Deployment object
+func (r *MemcachedReconciler) deploymentForMemcached(
+ memcached *cachev1alpha1.Memcached) (*appsv1.Deployment, error) {
+ replicas := memcached.Spec.Size
+ image := "memcached:1.6.26-alpine3.19"
+
+ dep := &appsv1.Deployment{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: memcached.Name,
+ Namespace: memcached.Namespace,
+ },
+ Spec: appsv1.DeploymentSpec{
+ Replicas: &replicas,
+ Selector: &metav1.LabelSelector{
+ MatchLabels: map[string]string{"app.kubernetes.io/name": "project"},
+ },
+ Template: corev1.PodTemplateSpec{
+ ObjectMeta: metav1.ObjectMeta{
+ Labels: map[string]string{"app.kubernetes.io/name": "project"},
+ },
+ Spec: corev1.PodSpec{
+ SecurityContext: &corev1.PodSecurityContext{
+ RunAsNonRoot: &[]bool{true}[0],
+ SeccompProfile: &corev1.SeccompProfile{
+ Type: corev1.SeccompProfileTypeRuntimeDefault,
+ },
+ },
+ Containers: []corev1.Container{{
+ Image: image,
+ Name: "memcached",
+ ImagePullPolicy: corev1.PullIfNotPresent,
+ // Ensure restrictive context for the container
+ // More info: https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted
+ SecurityContext: &corev1.SecurityContext{
+ RunAsNonRoot: &[]bool{true}[0],
+ RunAsUser: &[]int64{1001}[0],
+ AllowPrivilegeEscalation: &[]bool{false}[0],
+ Capabilities: &corev1.Capabilities{
+ Drop: []corev1.Capability{
+ "ALL",
+ },
+ },
+ },
+ Ports: []corev1.ContainerPort{{
+ ContainerPort: 11211,
+ Name: "memcached",
+ }},
+ Command: []string{"memcached", "--memory-limit=64", "-o", "modern", "-v"},
+ }},
+ },
+ },
+ },
+ }
+
+ // Set the ownerRef for the Deployment
+ // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/
+ if err := ctrl.SetControllerReference(memcached, dep, r.Scheme); err != nil {
+ return nil, err
+ }
+ return dep, nil
+}
