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 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 implementing 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-chost 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(ctx context.Context, mgr manager.Manager, ctrlName string, osTypes []string, ...) error
• func AddToManagerWithOptions(ctx context.Context, 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(ctx context.Context, mgr manager.Manager, ctrlName string, osTypes []string, generator generator.Generator) error

AddToManager adds a controller with the default Options.

func AddToManagerWithOptions

func AddToManagerWithOptions(ctx context.Context, 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.