oscommon

README

Gardener Extension for OS Configurations

Project Gardener implements the automated management and operation of Kubernetes clusters as a service. Its main principle is to leverage Kubernetes concepts for all of its tasks.

Recently, most of the vendor specific logic has been developed in-tree. However, the project has grown to a size where it is very hard to extend, maintain, and test. With GEP-1 we have proposed how the architecture can be changed in a way to support external controllers that contain their very own vendor specifics. This way, we can keep Gardener core clean and independent.

The oscommon offers a generic controller that operates on the OperatingSystemConfig resource in the extensions.gardener.cloud/v1alpha1 API group. It manages those objects that are requesting for an specific operating system.

---
apiVersion: extensions.gardener.cloud/v1alpha1
kind: OperatingSystemConfig
metadata:
  name: pool-01-original
  namespace: default
spec:
  type: <os type>
  units:
    ...
  files:
    ...

Please find a concrete example in the example folder.

After reconciliation the resulting data will be stored in a secret within the same namespace (as the config itself might contain confidential data). The name of the secret will be written into the resource's .status field:

...
status:
  ...
  cloudConfig:
    secretRef:
      name: osc-result-pool-01-original
      namespace: default
  command: <machine configuration command>
  units:
  - docker-monitor.service
  - kubelet-monitor.service
  - kubelet.service

The secret has one data key cloud_config that stores the generation.

The generation of this operating system representation is executed by a Generator. A default implementation for the generator based on go templates is provided in pkg/template.

In addition, oscommon provides set of basic tests which can be used to test the operating system specific generator.

Please find more information regarding the extensibility concepts and a detailed proposal here.

---

How to use oscommon in a new operating system configuration controller

When implemening a controller for a specific operating system, it is necessary to provide:

• A command line application for launching the controller
• A template for translating the cloud-config to the format requried by the operating system.
• Alternatively, a new generator can also be provided, in case the transformations required by the operating system requires more complex logic than provided by go templates.
• A test that uses the test description provided in [pkg/generator/test]
• A directory with test files
• The helm Chart for operator registration and installation

Please refer to the os-suse-jeos controller for a concrete example.

Feedback and Support

Feedback and contributions are always welcome. Please report bugs or suggestions as GitHub issues or join our Slack channel #gardener (please invite yourself to the Kubernetes workspace here).

Learn more!

Please find further resources about out project here:

• Our landing page gardener.cloud
• "Gardener, the Kubernetes Botanist" blog on kubernetes.io
• GEP-1 (Gardener Enhancement Proposal) on extensibility

Documentation

Index

• Variables
• func AddToManager(mgr manager.Manager, ctrlName string, osTypes []string, ...) error
• func AddToManagerWithOptions(mgr manager.Manager, ctrlName string, osTypes []string, ...) error
• type AddOptions

Variables

var DefaultAddOptions = AddOptions{}

DefaultAddOptions are the default AddOptions for AddToManager.

Functions

func AddToManager

func AddToManager(mgr manager.Manager, ctrlName string, osTypes []string, generator generator.Generator) error

AddToManager adds a controller with the default Options.

func AddToManagerWithOptions

func AddToManagerWithOptions(mgr manager.Manager, ctrlName string, osTypes []string, generator generator.Generator, opts AddOptions) error

AddToManagerWithOptions adds a controller with the given Options to the given manager. The opts.Reconciler is being set with a newly instantiated actuator.

Types

type AddOptions

type AddOptions struct {
	// Controller are the controller.Options.
	Controller controller.Options
	// IgnoreOperationAnnotation specifies whether to ignore the operation annotation or not.
	IgnoreOperationAnnotation bool
}

AddOptions are options to apply when adding the OSC controller to the manager.