Operator Builder for Tanzu

VMware

• VMware Tanzu Kubernetes Grid (or other Kubernetes distribution): this is where your operator will run.
• Tanzu CLI >= 1.3: this plugin will be run on top of the Tanzu CLI.

Other

• Kubernetes YAML Manifests: these are your known good manifests that are the input to the generated source code.
• Go >= 1.16: this is used to test the generated source code.
• Kubectl: this is to interact with the target Kubernetes cluster.
• Git: used for version controlling the generated source code.

Suggested (Optional)

• Docker: used for building images to run the source code in a Kubernetes cluster.
• Make: used for running simple tasks within the project such as running the operator or building an image.
• Bash: the underlying shell used for running make targets.

For full documentation, please visit: https://github.com/vmware-tanzu-labs/operator-builder

Be sure to review the requirements section prior to proceeding with installation and configuration instructions.

Run the following command to install the plugin to be used by the Tanzu CLI:

            tanzu plugin install operator -l {PATH_TO_DOWNLOADED_PLUGIN}
            

Mark Your YAML

Mark your YAML manifests with the appropriate workload markers. See workload markers for more details. These markers serve as options that you are exposing to end users to be able to modify your underlying application.

Once your YAML manifests have been marked, you need to tell the marked manfiests to be used in the generated source code output. See workload configuration for more details.

Initialize the operator codebase. This will generate some base code for your operator:

        tanzu operator init --workload-config {CONFIG_FROM_LAST_STEP}.yaml --repo {GIT_REPO}
        

Generate the source code for the operator's custom API and controller:

        tanzu operator create api --workload-config {CONFIG_FROM_LAST_STEP}.yaml --controller --resource
        

Install the custom resource definition in your test cluster:

        make install
        

        make run
        

        kubectl apply -f config/samples
        

This process is what you will use if you were to run the operator within a cluster on a persistent basis.

        export IMG={MY_IMAGE_REPO}/{MY_IMAGE}:{MY_IMAGE_VERSION}; make docker-build; make docker-push
        

The above command builds an image with your source code in it, and will push the image to a repository. The MY_IMAGE settings above will need to be replaced with your specific image repository information.

        make deploy
        

The above command will deploy the source code given the image you just pushed above into a Kubernetes cluster.

The following is additional information that is helpful when configuring your operator.

Workload Markers

Workload Markers

Operator Builder uses commented markers as the basis for defining a new API. The fields for a custom resource kind are created when it finds a +operator-builder:field marker in a source manifest. Alternatively, for fields which are shared across workloads when using the workload collection feature, you can use +operator-builder:collection:field instead.

A workload marker is commented out so the manifest is still valid and can be used if needed. The marker must begin with +operator-builder followed by some comma-separated fields. Markers can either be at the end of a line or at the head of a line:

• name: The name field is required. It should be provided as you want it to be in the spec of the resulting custom resource.
• type: This field is provided as type=[value]. It is also a required field. The supported data types:
  • bool
  • string
  • int
  • int32
  • int64
  • float32
  • float64
• default: This field is provided as default=[value]. It is an optional field. If provided it will make the field optional in the custom resource and when not included will get the default value provided.
• description: This field is provided as description=[value]. It is an optional field. If provided, it will give documentation to the generated resource definition. For more information, see workload docs.

Consider the following Deployment:

            ---
            apiVersion: apps/v1
            kind: Deployment
            metadata:
              name: webapp-deploy
              labels:
                production: false  # +operator-builder:field:name=production,default=false,type=bool
            spec:
              # +operator-builder:field:name=webAppReplicas,default=2,type=int
              replicas: 2
              selector:
                matchLabels:
                  app: webapp
              template:
                metadata:
                  labels:
                    app: webapp
                spec:
                  containers:
                  - name: webapp-container
                    image: nginx:1.17  # +operator-builder:field:name=webAppImage,type=string
                    ports:
                    - containerPort: 8080
            

In this case, operator-builder will create and add three fields to the custom resource:

• A production field that is a boolean. It will have a default of false and will inform the value of the label when the deployment is configured.
• A webAppReplicas field that will default to 2 and allow the user to specify the number of replicas for the deployment in the custom resource manifest.
• A webAppImage field that will set the value for the images used in the pods.

Now the end-user of the operator will be able to define a custom resource similar to the following to configure the deployment created:

            ---
            apiVersion: product.apps.acme.com/v1alpha1
            kind: WebApp
            metadata:
              name: dev-webapp
            spec:
              production: false
              webAppReplicas: 2
              webAppImage: acmerepo/webapp:3.5.3
            

Workload document adds functionality to workload markers (see workload markers for more information) by allowing the user to inject documentation into the CRD that gets generated by using a description tag in the operator-builder marker. By injecting documentation to the CRD, the consumer of the custom resource gets the added benefit of being able to run kubectl explain against their resource and having documentation right at their fingertips without having to navigate to API documentation in order to see the usage of the API.

Documentation is injected by simply placing a single or multi-line description tag in the +operator-builder marker. Multi-line documentation can be used by using a backtick surrounding the documentation (`).

Considering the following simple resource which is being managed by operator-builder:

            ---
            apiVersion: tenancy.platform.cnr.vmware.com/v1alpha1
            kind: TanzuNamespace
            metadata:
              name: cnpo-security-system #+operator-builder:field:name=namespace,default="cnpo-security-system",type=string
              spec:
                #+operator-builder:field:name=namespace,default="cnpo-security-system",type=string,description=`
                # Defines the namespace in which all
                # resources for this component will be placed into.`
                tanzuNamespaceName: cnpo-security-system

In this case, operator-builder will simply manage the tanzuNamespaceName field as a workload marker which we are calling namespace in our custom CRD. In addition to managing that field, the +operator-builder marker with the description tag is used as the docmentation for that marker.

The end state of this configuration is templated Go code which looks like so:

            // SecurityCommonComponentSpec defines the desired state of SecurityCommonComponent.
            type SecurityCommonComponentSpec struct {
                // INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
                // Important: Run "make" to regenerate code after modifying this file

                // +kubebuilder,default="cnpo-security-system"
                // +kubebuilder:validation:Optional
                // Defines the namespace in which all resources for this component will be placed into.
                Namespace string `json:"namespace"`

And when the make manifests command is run, the CRD is generated with the documentation in the description filed which looks like:

            ...
                          namespace:
                            default: cnpo-security-system
                            description: Defines the namespace in which all resources for this
                              component will be placed into.
                            type: string
            ...

Finally, the kubectl explain command now contains the documentation so that users may see the documentation by way of kubectl and not any other tooling:

            kubectl explain securitycommoncomponents.spec.namespace

            KIND:     SecurityCommonComponent
            VERSION:  security.cnpo.tanzulabs.vmware.com/v1alpha1

            FIELD:    namespace <string>

            DESCRIPTION:
                 Defines the namespace in which all resources for this component will be
                 placed into.

API documentation in markdown can also be generated after building an operator. To do so, simply run the command make docs from the root of your repository. This will build the documentation in the docs/apis.md file.

Standalone Workload

When you are building an operator for a single workload, you will just need a single standalone WorkloadConfig along with the source manifests to define the resources that will be created to fulfill an instance of your workload.

For example if your organization develops and maintains a web application as a part of its core business, you may consider using an operator to deploy and maintain that app in different environments. We refer to all the various resources that comprise that web app collectively as a "workload."

This is the simplest and most common implemetation of operator-builder.

If you have multiple workloads that have dependencies upon one another, and it makes sense to orchestrate them with an operator, a standalone workload will not suffice. For that you will need to leverage a workload collection.

Below is an example standalone workload:

        ---
        name: webstore
        kind: StandaloneWorkload
        spec:
          api:
            domain: acme.com
            group: apps
            version: v1alpha1
            kind: WebStore
            clusterScoped: false
          companionCliRootcmd:
            name: webstorectl
            description: Manage webstore application
          resources:
            - app.yaml
        

        ---
        name: webstore
        kind: ComponentWorkload
        spec:
          api:
            domain: acme.com
            group: apps
            version: v1alpha1
            kind: WebStore
            clusterScoped: false
          companionCliRootcmd:
            name: webstorectl
            description: Manage webstore application
          dependencies:
            - my-other-webstore-name
          resources:
            - app.yaml
        

If you are building an operator to manage a collection of workloads that have dependencies upon one another, you will need to use a workload collection. If, instead, you have just a single workload to manage, you will want to use a standalone workload.

A workload collection is defined by a WorkloadConfig - just like any other workload used with Operator Builder. The only differences are that it will include collection: true and an array of workload definitions under the componentFiles field.

            ---
            name: webstore-collection
            kind: WorkloadCollection
            spec:
              api:
                domain: plugins.operator-builder.tanzulabs.vmware.com
                group: webstorecollection
                version: v1alpha1
                kind: WebStoreCollection
                clusterScoped: true
              companionCliRootcmd:
                name: wsc
                description: Manage webstore-collection component
              componentFiles:
                - webstore.yaml
                - my-other-webstore-name.yaml
            

Each of the componentFiles are ComponentWorkload configurations that may have dependencies upon one another which the operator will manage. This project will include a custom resource for each of the component workloads as well as a distinct controller for each component workload. Each of these controllers will run in a single containerized controller manager in the cluster when it is deployed.

• Aligned with new upstream version v0.5.1
• See https://github.com/vmware-tanzu-labs/operator-builder/releases for full release notes

• Fixes bug https://flings.vmware.com/operator-builder-for-tanzu/bugs/1331 which excluded YAML metadata required for CLI plugin installation
• Packaged as a single bundle rather than individual artifacts to make download process simpler

• Initial Public Release