{"id":13542088,"url":"https://github.com/kubernetes/sample-controller","last_synced_at":"2025-10-05T23:15:53.824Z","repository":{"id":37334775,"uuid":"107556189","full_name":"kubernetes/sample-controller","owner":"kubernetes","description":"Repository for sample controller. Complements sample-apiserver","archived":false,"fork":false,"pushed_at":"2025-09-23T00:27:41.000Z","size":11272,"stargazers_count":3406,"open_issues_count":1,"forks_count":1183,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-10-05T21:19:46.282Z","etag":null,"topics":["k8s-staging"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubernetes.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-10-19T14:19:04.000Z","updated_at":"2025-10-05T13:21:26.000Z","dependencies_parsed_at":"2023-11-13T19:28:00.412Z","dependency_job_id":"d7cbe229-eb42-4238-a301-9fb8942b88e9","html_url":"https://github.com/kubernetes/sample-controller","commit_stats":{"total_commits":1428,"total_committers":215,"mean_commits":6.641860465116279,"dds":0.4411764705882353,"last_synced_commit":"17d15174a72572491a991fd0613d48e30d049afc"},"previous_names":[],"tags_count":1425,"template":false,"template_full_name":null,"purl":"pkg:github/kubernetes/sample-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubernetes","download_url":"https://codeload.github.com/kubernetes/sample-controller/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-controller/sbom","scorecard":{"id":572719,"data":{"date":"2025-08-11","repo":{"name":"github.com/kubernetes/sample-controller","commit":"8f92f95c749a6693ca6e300c16c3505b2c5fcc44"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.5,"checks":[{"name":"Maintained","score":10,"reason":"30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/kubernetes/.github/SECURITY.md:1","Info: Found linked content: github.com/kubernetes/.github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: github.com/kubernetes/.github/SECURITY.md:1","Info: Found text in security policy: github.com/kubernetes/.github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2024-2748 / GHSA-33c5-9fx5-fvjm","Warn: Project is vulnerable to: GO-2021-0065 / GHSA-jmrx-5g74-6v2f","Warn: Project is vulnerable to: GO-2021-0064 / GHSA-8cfg-vx93-jvxw"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-20T16:46:38.775Z","repository_id":37334775,"created_at":"2025-08-20T16:46:38.776Z","updated_at":"2025-08-20T16:46:38.776Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278532352,"owners_count":26002346,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["k8s-staging"],"created_at":"2024-08-01T10:01:01.212Z","updated_at":"2025-10-05T23:15:53.811Z","avatar_url":"https://github.com/kubernetes.png","language":"Go","funding_links":[],"categories":["Awesome tutorials","HarmonyOS","Go"],"sub_categories":["Windows Manager"],"readme":"\u003e ⚠️ **This is an automatically published [staged repository](https://git.k8s.io/kubernetes/staging#external-repository-staging-area) for Kubernetes**.   \n\u003e Contributions, including issues and pull requests, should be made to the main Kubernetes repository: [https://github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).  \n\u003e This repository is read-only for importing, and not used for direct contributions.  \n\u003e See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.\n\n# 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/generated/`\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## Fetch sample-controller and its dependencies\n\nIssue the following commands --- starting in whatever working directory you\nlike.\n\n```sh\ngit clone https://github.com/kubernetes/sample-controller\ncd sample-controller\n```\n\nNote, however, that if you intend to\ngenerate code then you will also need the\ncode-generator repo to exist in an old-style location.  One easy way\nto do this is to use the command `go mod vendor` to create and\npopulate the `vendor` directory.\n\n### A Note on kubernetes/kubernetes\n\nIf you are developing Kubernetes according to\nhttps://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md\nthen you already have a copy of this demo in\n`kubernetes/staging/src/k8s.io/sample-controller` and its dependencies\n--- including the code generator --- are in usable locations\n(valid for all Go versions).\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\ngo build -o sample-controller .\n./sample-controller -kubeconfig=$HOME/.kube/config\n\n# create a CustomResourceDefinition\nkubectl create -f artifacts/examples/crd-status-subresource.yaml\n\n# create a custom resource of type Foo\nkubectl create -f artifacts/examples/example-foo.yaml\n\n# check deployments created through the custom resource\nkubectl 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\nNote, 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.\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. Validation in the form of a [structured schema](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/#specifying-a-structural-schema) is mandatory to be provided for `apiextensions.k8s.io/v1`.\n\n### Example\n\nThe schema in [`crd.yaml`](./artifacts/examples/crd.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\n## Subresources\n\nCustom Resources support `/status` and `/scale` [subresources](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/#subresources). The `CustomResourceSubresources` feature is in GA from v1.16.\n\n### Example\n\nThe CRD in [`crd-status-subresource.yaml`](./artifacts/examples/crd-status-subresource.yaml) enables the `/status` subresource for custom resources.\nThis means that [`UpdateStatus`](./controller.go) 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/sig-architecture/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\nkubectl create -f artifacts/examples/crd-status-subresource.yaml\n```\n\n## A Note on the API version\nThe [group](https://kubernetes.io/docs/reference/using-api/#api-groups) version of the custom resource in `crd.yaml` is `v1alpha`, this can be evolved to a stable API version, `v1`, using [CRD Versioning](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/).\n\n## Cleanup\n\nYou can clean up the created CustomResourceDefinition with:\n```sh\nkubectl delete crd foos.samplecontroller.k8s.io\n```\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\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more information. Please note that [kubernetes/sample-controller](https://github.com/kubernetes/sample-controller/) is a readonly mirror repository, all development is done at [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes%2Fsample-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubernetes%2Fsample-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes%2Fsample-controller/lists"}