Kubebuilder

The Getting Started guide uses a Memcached sample project to demonstrate the following operator capabilities:

• Reconciliation: Managing a Memcached Custom Resource (CR) representing a Memcached instance.
• Resource Management: Automatically creating a Deployment using the Memcached image.
• Constraint Enforcement: Ensuring the number of running instances does not exceed the size defined in the Memcached CR.
• Status Updates: Updating the Memcached CR status field to reflect the current state.

A Scheme is a registry used to keep track of which Go type corresponds to a specific GroupVersionKind (GVK).

It allows the system to perform two critical tasks:

1. Decoding: Converting JSON received from the API server into a specific Go struct instance.
2. Encoding/Lookup: Identifying the correct Group and Version when submitting a Go struct (like &CronJob{}) back to the API server.

Example Mapping: If you define a type tutorial.kubebuilder.io/api/v1.CronJob{} and associate it with the batch.tutorial.kubebuilder.io/v1 API group, the Scheme enables the following mapping:

Input JSON:

{
    "kind": "CronJob",
    "apiVersion": "batch.tutorial.kubebuilder.io/v1",
    ...
}

Resulting Go Type: &CronJob{}

In a Kubebuilder project, the cmd/main.go file initializes a Manager (from controller-runtime). The Manager manages Controllers, which implement a reconcile function.

Reconciliation is an ongoing control loop that executes operations to synchronize the actual state of resources in the cluster with the desired state defined in your Custom Resources. It follows the Kubernetes control loop pattern to ensure the cluster continuously moves toward the target state.

Kubebuilder is an opinionated project generator designed to provide a reasonable project layout that is simple for beginners but scalable for complex projects. It follows a 'batteries included' approach, meaning scaffolded projects include necessary deployment files, testing infrastructure, and development tools to move from code to running containers efficiently.

Key principles include:

• Libraries Over Code Generation: Preference for maintainable library code over messy, hard-to-update generated code.
• Common Cases Should Be Easy: The 80-90% of standard use cases are designed to be simple and intuitive.
• Uncommon Cases Should Be Possible: While standard paths are easy, the system allows for advanced customization and interoperability with lower-level components without unreasonable friction.

Kubebuilder's functionality can be extended by external tools using its plugin system. The architecture relies on specialized plugins for different tasks:

1. Kustomize Plugins: Responsible for scaffolding Kustomize files within the config/ directory.
2. Base Language Plugins: Responsible for scaffolding language-specific files (e.g., Golang). These serve as the foundation for creating plugins for other languages or adding specialized functionality.

External projects like Operator-SDK leverage this by implementing plugins that add features (such as OLM integration) on top of the core Kubebuilder scaffolding.

Kubebuilder does not provide direct, built-in support for third-party project integrations to maintain a focused scope and minimal dependency footprint. Instead, Kubebuilder is designed as a library that allows any project to create its own compatible plugins. This approach delegates the maintenance of integrations to the respective project owners while allowing users to extend Kubebuilder's functionality.

If you need to integrate a specific tool or project with Kubebuilder, you should develop a custom plugin.

Kubebuilder supports a chain of plugins. When a command is issued, kubebuilder passes the request through the sequence of plugins defined in the layout.

Error Handling: If any plugin in the chain returns an error in its PluginResponse, the entire execution chain is halted immediately. To prevent a half-committed state, kubebuilder will not write any of the scaffolded files to disk if a plugin fails.

In Kubernetes APIs, resource.Quantity is used for decimal numbers that require a fixed, portable representation across different machines. It is commonly used for resource requests and limits.

How Quantities Work

Quantities use a notation consisting of a whole number and a suffix to represent values. They support two bases:

1. Decimal (Base 10): Uses standard SI suffixes like M (Mega) and K (Kilo).
2. Binary (Base 2): Uses 'mebi' notation like Mi (Mebibyte) and Ki (Kibibyte).

Common Notation Examples

Tip: To specify fractions, use a suffix that allows you to express the value as a whole number. For example, instead of 2.5, use 2500m.

Kubebuilder manages plugin chains through the project configuration (v3).

• Plugin Resolution: The layout field (a string) is used to resolve plugins. To represent a chain of plugins, this field stores a comma-separated string of plugin names.
• Plugin Configuration: The plugin field (a map[string]interface{}) is used to store raw configuration data for specific plugins.

Important Constraints:

• Commas are not allowed within individual plugin keys/names.
• The order of plugins in the comma-separated layout string is significant, as plugins modify/update shared items.

Manager scope and CRD scope are independent concepts.

• Manager Scope determines which namespace(s) your manager watches and manages resources in (e.g., Cluster-scoped vs Namespace-scoped).
• CRD Scope determines the scope of the Custom Resource Definition itself (e.g., whether the resource is cluster-wide or namespaced).

You must configure both correctly to ensure your controller has the necessary visibility and permissions.