• Stars
    star
    2,987
  • Rank 14,483 (Top 0.3 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated about 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Repository for sample controller. Complements sample-apiserver

sample-controller

This repository implements a simple controller for watching Foo resources as defined with a CustomResourceDefinition (CRD).

Note: go-get or vendor this package as k8s.io/sample-controller.

This particular example demonstrates how to perform basic operations such as:

  • How to register a new custom resource (custom resource type) of type Foo using a CustomResourceDefinition.
  • How to create/get/list instances of your new resource type Foo.
  • How to setup a controller on resource handling create/update/delete events.

It makes use of the generators in k8s.io/code-generator to generate a typed client, informers, listers and deep-copy functions. You can do this yourself using the ./hack/update-codegen.sh script.

The update-codegen script will automatically generate the following files & directories:

  • pkg/apis/samplecontroller/v1alpha1/zz_generated.deepcopy.go
  • pkg/generated/

Changes should not be made to these files manually, and when creating your own controller based off of this implementation you should not copy these files and instead run the update-codegen script to generate your own.

Details

The sample controller uses client-go library extensively. The details of interaction points of the sample controller with various mechanisms from this library are explained here.

Fetch sample-controller and its dependencies

Like the rest of Kubernetes, sample-controller has used godep and $GOPATH for years and is now adopting go 1.11 modules. There are thus two alternative ways to go about fetching this demo and its dependencies.

Fetch with godep

When NOT using go 1.11 modules, you can use the following commands.

go get -d k8s.io/sample-controller
cd $GOPATH/src/k8s.io/sample-controller
godep restore

When using go 1.11 modules

When using go 1.11 modules (GO111MODULE=on), issue the following commands --- starting in whatever working directory you like.

git clone https://github.com/kubernetes/sample-controller.git
cd sample-controller

Note, however, that if you intend to generate code then you will also need the code-generator repo to exist in an old-style location. One easy way to do this is to use the command go mod vendor to create and populate the vendor directory.

A Note on kubernetes/kubernetes

If you are developing Kubernetes according to https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md then you already have a copy of this demo in kubernetes/staging/src/k8s.io/sample-controller and its dependencies --- including the code generator --- are in usable locations (valid for all Go versions).

Purpose

This is an example of how to build a kube-like controller with a single type.

Running

Prerequisite: Since the sample-controller uses apps/v1 deployments, the Kubernetes cluster version should be greater than 1.9.

# assumes you have a working kubeconfig, not required if operating in-cluster
go build -o sample-controller .
./sample-controller -kubeconfig=$HOME/.kube/config

# create a CustomResourceDefinition
kubectl create -f artifacts/examples/crd-status-subresource.yaml

# create a custom resource of type Foo
kubectl create -f artifacts/examples/example-foo.yaml

# check deployments created through the custom resource
kubectl get deployments

Use Cases

CustomResourceDefinitions can be used to implement custom resource types for your Kubernetes cluster. These act like most other Resources in Kubernetes, and may be kubectl apply'd, etc.

Some example use cases:

  • Provisioning/Management of external datastores/databases (eg. CloudSQL/RDS instances)
  • Higher level abstractions around Kubernetes primitives (eg. a single Resource to define an etcd cluster, backed by a Service and a ReplicationController)

Defining types

Each instance of your custom resource has an attached Spec, which should be defined via a struct{} to provide data format validation. In practice, this Spec is arbitrary key-value data that specifies the configuration/behavior of your Resource.

For example, if you were implementing a custom resource for a Database, you might provide a DatabaseSpec like the following:

type DatabaseSpec struct {
	Databases []string `json:"databases"`
	Users     []User   `json:"users"`
	Version   string   `json:"version"`
}

type User struct {
	Name     string `json:"name"`
	Password string `json:"password"`
}

Note, the JSON tag json: is required on all user facing fields within your type. Typically API types contain only user facing fields. When the JSON tag is omitted from the field, Kubernetes generators consider the field to be internal and will not expose the field in their generated external output. For example, this means that the field would not be included in a generated CRD schema.

Validation

To validate custom resources, use the CustomResourceValidation feature. Validation in the form of a structured schema is mandatory to be provided for apiextensions.k8s.io/v1.

Example

The schema in crd.yaml applies the following validation on the custom resource: spec.replicas must be an integer and must have a minimum value of 1 and a maximum value of 10.

Subresources

Custom Resources support /status and /scale subresources. The CustomResourceSubresources feature is in GA from v1.16.

Example

The CRD in crd-status-subresource.yaml enables the /status subresource for custom resources. This means that UpdateStatus can be used by the controller to update only the status part of the custom resource.

To understand why only the status part of the custom resource should be updated, please refer to the Kubernetes API conventions.

In the above steps, use crd-status-subresource.yaml to create the CRD:

# create a CustomResourceDefinition supporting the status subresource
kubectl create -f artifacts/examples/crd-status-subresource.yaml

A Note on the API version

The group version of the custom resource in crd.yaml is v1alpha, this can be evolved to a stable API version, v1, using CRD Versioning.

Cleanup

You can clean up the created CustomResourceDefinition with:

kubectl delete crd foos.samplecontroller.k8s.io

Compatibility

HEAD of this repository will match HEAD of k8s.io/apimachinery and k8s.io/client-go.

Where does it come from?

sample-controller is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-controller. Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.

More Repositories

1

kubernetes

Production-Grade Container Scheduling and Management
Go
105,869
star
2

minikube

Run Kubernetes locally
Go
28,262
star
3

ingress-nginx

Ingress-NGINX Controller for Kubernetes
Go
16,503
star
4

kops

Kubernetes Operations (kOps) - Production Grade k8s Installation, Upgrades and Management
Go
15,486
star
5

dashboard

General-purpose web UI for Kubernetes clusters
Go
13,699
star
6

community

Kubernetes community content
Jupyter Notebook
11,570
star
7

kompose

Convert Compose to Kubernetes
Go
9,056
star
8

client-go

Go client for Kubernetes.
Go
8,516
star
9

autoscaler

Autoscaling components for Kubernetes
Go
7,628
star
10

examples

Kubernetes application example tutorials
Shell
5,992
star
11

kube-state-metrics

Add-on agent to generate and expose cluster-level metrics.
Go
5,018
star
12

website

Kubernetes website and documentation repo:
HTML
4,237
star
13

test-infra

Test infrastructure for the Kubernetes project.
Go
3,775
star
14

kubeadm

Aggregator for issues filed against kubeadm
Go
3,632
star
15

enhancements

Enhancements tracking repo for Kubernetes
Go
3,220
star
16

node-problem-detector

This is a place for various problem detectors running on the Kubernetes nodes.
Go
2,706
star
17

kubectl

Issue tracker and mirror of kubectl code
Go
2,653
star
18

git-sync

A sidecar app which clones a git repo and keeps it in sync with the upstream.
Shell
1,994
star
19

code-generator

Generators for kube-like API types
Go
1,596
star
20

ingress-gce

Ingress controller for Google Cloud
Go
1,248
star
21

dns

Kubernetes DNS service
Go
871
star
22

perf-tests

Performance tests and benchmarks
Go
849
star
23

apimachinery

Go
774
star
24

k8s.io

Code and configuration to manage Kubernetes project infrastructure, including various *.k8s.io sites
HCL
667
star
25

apiserver

Library for writing a Kubernetes-style API server.
Go
613
star
26

api

The canonical location of the Kubernetes API definition.
Go
609
star
27

cloud-provider-openstack

Go
582
star
28

gengo

gengo library for code generation.
Go
533
star
29

sig-release

Repo for SIG release
Shell
512
star
30

sample-apiserver

Reference implementation of an apiserver for a custom Kubernetes API.
Go
496
star
31

metrics

Kubernetes metrics-related API types and clients
Go
478
star
32

release

Release infrastructure for Kubernetes and related components
Go
470
star
33

design-proposals-archive

Archive of Kubernetes Design Proposals
Makefile
442
star
34

cri-api

Container Runtime Interface (CRI) โ€“ a plugin interface which enables kubelet to use a wide variety of container runtimes.
Go
357
star
35

cloud-provider-aws

Cloud provider for AWS
Go
350
star
36

cloud-provider-alibaba-cloud

CloudProvider for Alibaba Cloud
Go
345
star
37

registry.k8s.io

This project is the repo for registry.k8s.io, the production OCI registry service for Kubernetes' container image artifacts
Go
340
star
38

utils

Non-Kubernetes-specific utility libraries which are consumed by multiple projects.
Go
306
star
39

kube-openapi

Kubernetes OpenAPI spec generation & serving
Go
289
star
40

kubelet

kubelet component configs
Go
281
star
41

sample-cli-plugin

Sample kubectl plugin
Go
278
star
42

cli-runtime

Set of helpers for creating kubectl commands and plugins.
Go
270
star
43

kube-aggregator

Aggregator for Kubernetes-style API servers: dynamic registration, discovery summarization, secure proxy
Go
242
star
44

org

Meta configuration for Kubernetes Github Org
Go
232
star
45

apiextensions-apiserver

API server for API extensions like CustomResourceDefinitions
Go
223
star
46

cloud-provider-vsphere

Kubernetes Cloud Provider for vSphere https://cloud-provider-vsphere.sigs.k8s.io
Go
221
star
47

cloud-provider

cloud-provider defines the shared interfaces which Kubernetes cloud providers implement. These interfaces allow various controllers to integrate with any cloud provider in a pluggable fashion. Also serves as an issue tracker for SIG Cloud Provider.
Go
219
star
48

kubernetes-template-project

A template for starting new projects on the github.com/kubernetes organization
176
star
49

kube-proxy

kube-proxy component configs
Go
166
star
50

committee-security-response

Kubernetes Security Process and Security Committee docs
161
star
51

kube-scheduler

kube-scheduler component configs
Go
150
star
52

sig-security

Process documentation, non-code deliverables, and miscellaneous artifacts of Kubernetes SIG Security
Python
146
star
53

component-base

Shared code for kubernetes core components
Go
102
star
54

repo-infra

Kubernetes repository infrastucture tools
Starlark
95
star
55

cloud-provider-gcp

cloud-provider-gcp contains several projects used to run Kubernetes in Google Cloud
Go
95
star
56

pod-security-admission

Kubernetes Pod Security Standards implementation - https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/2579-psp-replacement/README.md
Go
94
star
57

kube-controller-manager

kube-controller-manager component configs
Go
81
star
58

publishing-bot

Code behind the robot to publish from staging to real repositories.
Go
79
star
59

steering

The Kubernetes Steering Committee
79
star
60

controller-manager

This repo is intended to contain common public library code for kube-controller-manager, cloud-controller-manager as well as any other controller managers which people build.
Go
61
star
61

contributor-site

Code for kubernetes.dev
HTML
58
star
62

mount-utils

Package mount defines an interface to mounting filesystems.
Go
50
star
63

legacy-cloud-providers

This repository hosts the legacy in-tree cloud providers. Out-of-tree cloud providers can consume packages in this repo to support legacy implementations of their Kubernetes cloud provider.
Go
49
star
64

cluster-bootstrap

Go
32
star
65

system-validators

A set of system-oriented validators for kubeadm preflight checks.
Go
32
star
66

dynamic-resource-allocation

Go
20
star
67

kms

Kubernetes KMS implementation
Go
18
star
68

cloud-provider-sample

Sample of how to build a cloud provider repo. This will build a Kubernetes image which deploys on bare metal. It uses the fake cloud provider. It consumes the K8s/K8s build artifact and adds to it the Cloud Controller Manager and CSI Daemon Set.
18
star
69

node-api

Go
15
star
70

component-helpers

High-level helpers for Kubernetes components
Go
14
star
71

cel-admission-webhook

Go
12
star
72

csi-translation-lib

Staging repo for CSI Migration/Translation libraries
Go
12
star
73

endpointslice

Go
7
star
74

sig-testing

Home for SIG Testing discussion and documents.
5
star
75

.github

Default files for all repos in the Kubernetes GitHub org
2
star