{"id":37108088,"url":"https://github.com/mandelsoft/sample-controller","last_synced_at":"2026-01-14T12:58:39.027Z","repository":{"id":57605184,"uuid":"140268992","full_name":"mandelsoft/sample-controller","owner":"mandelsoft","description":"Repository for sample controller. Complements sample-apiserver","archived":false,"fork":true,"pushed_at":"2018-07-08T03:23:21.000Z","size":6865,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T04:26:57.502Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"kubernetes/sample-controller","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mandelsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_CONTACTS","support":null}},"created_at":"2018-07-09T10:21:10.000Z","updated_at":"2018-07-09T10:21:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mandelsoft/sample-controller","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"purl":"pkg:github/mandelsoft/sample-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandelsoft%2Fsample-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandelsoft%2Fsample-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandelsoft%2Fsample-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandelsoft%2Fsample-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mandelsoft","download_url":"https://codeload.github.com/mandelsoft/sample-controller/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mandelsoft%2Fsample-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28420815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T12:58:38.287Z","updated_at":"2026-01-14T12:58:39.018Z","avatar_url":"https://github.com/mandelsoft.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sample-controller\n\nThis repository implements a simple controller for watching Foo resources as\ndefined with a CustomResourceDefinition (CRD).\n\n**Note:** go-get or vendor this package as `k8s.io/sample-controller`.\n\nThis particular example demonstrates how to perform basic operations such as:\n\n* How to register a new custom resource (custom resource type) of type `Foo` using a CustomResourceDefinition.\n* How to create/get/list instances of your new resource type `Foo`.\n* How to setup a controller on resource handling create/update/delete events.\n\nIt makes use of the generators in [k8s.io/code-generator](https://github.com/kubernetes/code-generator)\nto generate a typed client, informers, listers and deep-copy functions. You can\ndo this yourself using the `./hack/update-codegen.sh` script.\n\nThe `update-codegen` script will automatically generate the following files \u0026\ndirectories:\n\n* `pkg/apis/samplecontroller/v1alpha1/zz_generated.deepcopy.go`\n* `pkg/client/`\n\nChanges should not be made to these files manually, and when creating your own\ncontroller based off of this implementation you should not copy these files and\ninstead run the `update-codegen` script to generate your own.\n\n## Details\n\nThe sample controller uses [client-go library](https://github.com/kubernetes/client-go/tree/master/tools/cache) extensively.\nThe details of interaction points of the sample controller with various mechanisms from this library are\nexplained [here](docs/controller-client-go.md).\n\n\n## Purpose\n\nThis is an example of how to build a kube-like controller with a single type.\n\n## Running\n\n**Prerequisite**: Since the sample-controller uses `apps/v1` deployments, the Kubernetes cluster version should be greater than 1.9.\n\n```sh\n# assumes you have a working kubeconfig, not required if operating in-cluster\n$ go build -o sample-controller .\n$ ./sample-controller -kubeconfig=$HOME/.kube/config\n\n# create a CustomResourceDefinition\n$ kubectl create -f artifacts/examples/crd.yaml\n\n# create a custom resource of type Foo\n$ kubectl create -f artifacts/examples/example-foo.yaml\n\n# check deployments created through the custom resource\n$ kubectl get deployments\n```\n\n## Use Cases\n\nCustomResourceDefinitions can be used to implement custom resource types for your Kubernetes cluster.\nThese act like most other Resources in Kubernetes, and may be `kubectl apply`'d, etc.\n\nSome example use cases:\n\n* Provisioning/Management of external datastores/databases (eg. CloudSQL/RDS instances)\n* Higher level abstractions around Kubernetes primitives (eg. a single Resource to define an etcd cluster, backed by a Service and a ReplicationController)\n\n## Defining types\n\nEach instance of your custom resource has an attached Spec, which should be defined via a `struct{}` to provide data format validation.\nIn practice, this Spec is arbitrary key-value data that specifies the configuration/behavior of your Resource.\n\nFor example, if you were implementing a custom resource for a Database, you might provide a DatabaseSpec like the following:\n\n``` go\ntype DatabaseSpec struct {\n\tDatabases []string `json:\"databases\"`\n\tUsers     []User   `json:\"users\"`\n\tVersion   string   `json:\"version\"`\n}\n\ntype User struct {\n\tName     string `json:\"name\"`\n\tPassword string `json:\"password\"`\n}\n```\n\n## Validation\n\nTo validate custom resources, use the [`CustomResourceValidation`](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#validation) feature.\n\nThis feature is beta and enabled by default in v1.9.\n\n### Example\n\nThe schema in [`crd-validation.yaml`](./artifacts/examples/crd-validation.yaml) applies the following validation on the custom resource:\n`spec.replicas` must be an integer and must have a minimum value of 1 and a maximum value of 10.\n\nIn the above steps, use `crd-validation.yaml` to create the CRD:\n\n```sh\n# create a CustomResourceDefinition supporting validation\n$ kubectl create -f artifacts/examples/crd-validation.yaml\n```\n\n## Subresources\n\nCustom Resources support `/status` and `/scale` subresources as an\n[alpha feature](https://kubernetes.io/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/#subresources) in v1.10.\nEnable this feature using the `CustomResourceSubresources` feature gate on the [kube-apiserver](https://kubernetes.io/docs/admin/kube-apiserver):\n\n```sh\n--feature-gates=CustomResourceSubresources=true\n```\n\n### Example\n\nThe CRD in [`crd-status-subresource.yaml`](./artifacts/examples/crd-status-subresource.yaml) enables the `/status` subresource\nfor custom resources.\nThis means that [`UpdateStatus`](./controller.go#L330) can be used by the controller to update only the status part of the custom resource.\n\nTo understand why only the status part of the custom resource should be updated, please refer to the [Kubernetes API conventions](https://git.k8s.io/community/contributors/devel/api-conventions.md#spec-and-status).\n\nIn the above steps, use `crd-status-subresource.yaml` to create the CRD:\n\n```sh\n# create a CustomResourceDefinition supporting the status subresource\n$ kubectl create -f artifacts/examples/crd-status-subresource.yaml\n```\n\n## Cleanup\n\nYou can clean up the created CustomResourceDefinition with:\n\n    $ kubectl delete crd foos.samplecontroller.k8s.io\n\n## Compatibility\n\nHEAD of this repository will match HEAD of k8s.io/apimachinery and\nk8s.io/client-go.\n\n## Where does it come from?\n\n`sample-controller` is synced from\nhttps://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-controller.\nCode changes are made in that location, merged into k8s.io/kubernetes and\nlater synced here.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmandelsoft%2Fsample-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmandelsoft%2Fsample-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmandelsoft%2Fsample-controller/lists"}