Black lives matter.

We stand in solidarity with the Black community.

Racism is unacceptable.

It conflicts with the core values of the Kubernetes project and our community does not tolerate it.

Project Config

Overview

The Project Config represents the configuration of a KubeBuilder project. All projects that are scaffolded with the CLI (KB version 3.0 and higher) will generate the PROJECT file in the projects’ root directory. Therefore, it will store all plugins and input data used to generate the project and APIs to better enable plugins to make useful decisions when scaffolding.

Example

Following is an example of a PROJECT config file which is the result of a project generated with two APIs using the Deploy Image Plugin.

# 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: testproject.org
layout:
- go.kubebuilder.io/v4
plugins:
  deploy-image.go.kubebuilder.io/v1-alpha:
    resources:
    - domain: testproject.org
      group: example.com
      kind: Memcached
      options:
        containerCommand: memcached,-m=64,-o,modern,-v
        containerPort: "11211"
        image: memcached:1.4.36-alpine
        runAsUser: "1001"
      version: v1alpha1
    - domain: testproject.org
      group: example.com
      kind: Busybox
      options:
        image: busybox:1.28
      version: v1alpha1
projectName: project-v4-with-deploy-image
repo: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image
resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  domain: testproject.org
  group: example.com
  kind: Memcached
  path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
  version: v1alpha1
  webhooks:
    validation: true
    webhookVersion: v1
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  domain: testproject.org
  group: example.com
  kind: Busybox
  path: sigs.k8s.io/kubebuilder/testdata/project-v4-with-deploy-image/api/v1alpha1
  version: v1alpha1
version: "3"

Why do we need to store the plugins and data used?

Following some examples of motivations to track the input used:

  • check if a plugin can or cannot be scaffolded on top of an existing plugin (i.e.) plugin compatibility while chaining multiple of them together.
  • what operations can or cannot be done such as verify if the layout allow API(s) for different groups to be scaffolded for the current configuration or not.
  • verify what data can or not be used in the CLI operations such as to ensure that WebHooks can only be created for pre-existent API(s)

Note that KubeBuilder is not only a CLI tool but can also be used as a library to allow users to create their plugins/tools, provide helpers and customizations on top of their existing projects - an example of which is Operator-SDK. SDK leverages KubeBuilder to create plugins to allow users to work with other languages and provide helpers for their users to integrate their projects with, for example, the Operator Framework solutions/OLM. You can check the plugin’s documentation to know more about creating custom plugins.

Additionally, another motivation for the PROJECT file is to help us to create a feature that allows users to easily upgrade their projects by providing helpers that automatically re-scaffold the project. By having all the required metadata regarding the APIs, their configurations and versions in the PROJECT file. For example, it can be used to automate the process of re-scaffolding while migrating between plugin versions. (More info).

Versioning

The Project config is versioned according to its layout. For further information see Versioning.

Layout Definition

The PROJECT version 3 layout looks like:

domain: testproject.org
layout:
- go.kubebuilder.io/v3
plugins:
  declarative.go.kubebuilder.io/v1:
    resources:
    - domain: testproject.org
      group: crew
      kind: FirstMate
      version: v1
projectName: example
repo: sigs.k8s.io/kubebuilder/example
resources:
- api:
    crdVersion: v1
    namespaced: true
  controller: true
  domain: testproject.org
  group: crew
  kind: Captain
  path: sigs.k8s.io/kubebuilder/example/api/v1
  version: v1
  webhooks:
    defaulting: true
    validation: true
    webhookVersion: v1

Now let’s check its layout fields definition:

FieldDescription
layoutDefines the global plugins, e.g. a project init with --plugins="go/v3,declarative" means that any sub-command used will always call its implementation for both plugins in a chain.
domainStore the domain of the project. This information can be provided by the user when the project is generate with the init sub-command and the domain flag.
pluginsDefines the plugins used to do custom scaffolding, e.g. to use the optional declarative plugin to do scaffolding for just a specific api via the command kubebuider create api [options] --plugins=declarative/v1.
projectNameThe name of the project. This will be used to scaffold the manager data. By default it is the name of the project directory, however, it can be provided by the user in the init sub-command via the --project-name flag.
repoThe project repository which is the Golang module, e.g github.com/example/myproject-operator.
resourcesAn array of all resources which were scaffolded in the project.
resources.apiThe API scaffolded in the project via the sub-command create api.
resources.api.crdVersionThe Kubernetes API version (apiVersion) used to do the scaffolding for the CRD resource.
resources.api.namespacedThe API RBAC permissions which can be namespaced or cluster scoped.
resources.controllerIndicates whether a controller was scaffolded for the API.
resources.domainThe domain of the resource which is provided by the --domain flag when the sub-command create api is used.
resources.groupThe GKV group of the resource which is provided by the --group flag when the sub-command create api is used.
resources.versionThe GKV version of the resource which is provided by the --version flag when the sub-command create api is used.
resources.kindStore GKV Kind of the resource which is provided by the --kind flag when the sub-command create api is used.
resources.pathThe import path for the API resource. It will be <repo>/api/<kind> unless the API added to the project is an external or core-type. For the core-types scenarios, the paths used are mapped here.
resources.webhooksStore the webhooks data when the sub-command create webhook is used.
resources.webhooks.webhookVersionThe Kubernetes API version (apiVersion) used to scaffold the webhook resource.
resources.webhooks.conversionIt is true when the webhook was scaffold with the --conversion flag which means that is a conversion webhook.
resources.webhooks.defaultingIt is true when the webhook was scaffold with the --defaulting flag which means that is a defaulting webhook.
resources.webhooks.validationIt is true when the webhook was scaffold with the --programmatic-validation flag which means that is a validation webhook.