{"id":14975786,"url":"https://github.com/kubernetes/sample-apiserver","last_synced_at":"2025-05-13T22:07:09.277Z","repository":{"id":45660529,"uuid":"81978413","full_name":"kubernetes/sample-apiserver","owner":"kubernetes","description":"Reference implementation of an apiserver for a custom Kubernetes API.","archived":false,"fork":false,"pushed_at":"2025-05-08T04:41:37.000Z","size":23022,"stargazers_count":573,"open_issues_count":1,"forks_count":221,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-05-08T05:28:14.440Z","etag":null,"topics":["k8s-staging"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"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}},"created_at":"2017-02-14T18:54:36.000Z","updated_at":"2025-05-08T04:41:41.000Z","dependencies_parsed_at":"2024-01-03T00:21:46.910Z","dependency_job_id":"681dd59e-551f-4d13-baa1-0814ebe47a3a","html_url":"https://github.com/kubernetes/sample-apiserver","commit_stats":{"total_commits":2087,"total_committers":268,"mean_commits":7.787313432835821,"dds":0.5855294681360805,"last_synced_commit":"edd866e7c9ccc8090faeee45e4cce63397591f36"},"previous_names":[],"tags_count":1428,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-apiserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-apiserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-apiserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubernetes%2Fsample-apiserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubernetes","download_url":"https://codeload.github.com/kubernetes/sample-apiserver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036822,"owners_count":22003654,"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","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-09-24T13:52:33.665Z","updated_at":"2025-05-13T22:07:04.256Z","avatar_url":"https://github.com/kubernetes.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# sample-apiserver\n\nDemonstration of how to use the k8s.io/apiserver library to build a functional API server.\n\n**Note:** go-get or vendor this package as `k8s.io/sample-apiserver`.\n\n## Purpose\n\nYou may use this code if you want to build an Extension API Server to use with API Aggregation, or to build a stand-alone Kubernetes-style API server.\n\nHowever, consider two other options:\n  * **CRDs**:  if you just want to add a resource to your kubernetes cluster, then consider using Custom Resource Definition a.k.a CRDs.  They require less coding and rebasing.  Read about the differences between Custom Resource Definitions vs Extension API Servers [here](https://kubernetes.io/docs/concepts/api-extension/custom-resources).\n  * **Apiserver-builder**: If you want to build an Extension API server, consider using [apiserver-builder](https://github.com/kubernetes-incubator/apiserver-builder) instead of this repo.  The Apiserver-builder is a complete framework for generating the apiserver, client libraries, and the installation program.\n\nIf you do decide to use this repository, then the recommended pattern is to fork this repository, modify it to add your types, and then periodically rebase your changes on top of this repo, to pick up improvements and bug fixes to the apiserver.\n\n\n## Compatibility\n\nHEAD of this repo will match HEAD of k8s.io/apiserver, k8s.io/apimachinery, and k8s.io/client-go.\n\n## Where does it come from?\n\n`sample-apiserver` is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/sample-apiserver.\nCode changes are made in that location, merged into `k8s.io/kubernetes` and later synced here.\n\n## Fetch sample-apiserver 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-apiserver\ncd sample-apiserver\n```\n\nNote, however, that if you intend to\n[generate code](#changes-to-the-types) 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-apiserver` and its dependencies\n--- including the code generator --- are in usable locations.\n\n\n## Normal Build and Deploy\n\n### Changes to the Types\n\nIf you change the API object type definitions in any of the\n`pkg/apis/.../types.go` files then you will need to update the files\ngenerated from the type definitions.  To do this, first\n[create the vendor directory if necessary](#when-using-go-111-modules)\nand then invoke `hack/update-codegen.sh` with `sample-apiserver` as\nyour current working directory; the script takes no arguments.\n\n### Authentication plugins\n\nThe normal build supports only a very spare selection of\nauthentication methods.  There is a much larger set available in\nhttps://github.com/kubernetes/client-go/tree/master/plugin/pkg/client/auth\n.  If you want your server to support one of those, such as `oidc`,\nthen add an import of the appropriate package to\n`sample-apiserver/main.go`.  Here is an example:\n\n``` go\nimport _ \"k8s.io/client-go/plugin/pkg/client/auth/oidc\"\n```\n\nAlternatively you could add support for all of them, with an import\nlike this:\n\n``` go\nimport _ \"k8s.io/client-go/plugin/pkg/client/auth\"\n```\n\n### Build the Binary\n\nWith `sample-apiserver` as your current working directory, issue the\nfollowing command:\n\n```\nCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -o artifacts/simple-image/kube-sample-apiserver\n```\n\n### Build the Container Image\n\nWith `sample-apiserver` as your current working directory, issue the\nfollowing commands with `MYPREFIX` and `MYTAG` replaced by something\nsuitable.\n\n```\ndocker build -t MYPREFIX/kube-sample-apiserver:MYTAG ./artifacts/simple-image\ndocker push MYPREFIX/kube-sample-apiserver:MYTAG\n```\n\n### Deploy into a Kubernetes Cluster\n\nEdit `artifacts/example/deployment.yaml`, updating the pod template's image\nreference to match what you pushed and setting the `imagePullPolicy`\nto something suitable.  Then call:\n\n```\nkubectl apply -f artifacts/example\n```\n\n## Running it stand-alone\n\nDuring development it is helpful to run sample-apiserver stand-alone, i.e. without\na Kubernetes API server for authn/authz and without aggregation. This is possible, but needs\na couple of flags, keys and certs as described below. You will still need some kubeconfig,\ne.g. `~/.kube/config`, but the Kubernetes cluster is not used for authn/z. A minikube or\nhack/local-up-cluster.sh cluster will work.\n\nInstead of trusting the aggregator inside kube-apiserver, the described setup uses local\nclient certificate based X.509 authentication and authorization. This means that the client\ncertificate is trusted by a CA and the passed certificate contains the group membership\nto the `system:masters` group. As we disable delegated authorization with `--authorization-skip-lookup`,\nonly this superuser group is authorized.\n\n1. First we need a CA to later sign the client certificate:\n\n   ``` shell\n   openssl req -nodes -new -x509 -keyout ca.key -out ca.crt\n   ```\n\n2. Then we create a client cert signed by this CA for the user `development` in the superuser group\n   `system:masters`:\n\n   ``` shell\n   openssl req -out client.csr -new -newkey rsa:4096 -nodes -keyout client.key -subj \"/CN=development/O=system:masters\"\n   openssl x509 -req -days 365 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -sha256 -out client.crt\n   ```\n\n3. As curl requires client certificates in p12 format with password, do the conversion:\n\n   ``` shell\n   openssl pkcs12 -export -in ./client.crt -inkey ./client.key -out client.p12 -passout pass:password\n   ```\n\n4. With these keys and certs in-place, we start the server:\n\n   ``` shell\n   etcd \u0026\n   sample-apiserver --secure-port 8443 --etcd-servers http://127.0.0.1:2379 --v=7 \\\n      --client-ca-file ca.crt \\\n      --kubeconfig ~/.kube/config \\\n      --authentication-kubeconfig ~/.kube/config \\\n      --authorization-kubeconfig ~/.kube/config\n   ```\n\n   The first kubeconfig is used for the shared informers to access\n   Kubernetes resources. The second kubeconfig passed to\n   `--authentication-kubeconfig` is used to satisfy the delegated\n   authenticator. The third kubeconfig passed to\n   `--authorized-kubeconfig` is used to satisfy the delegated\n   authorizer. Neither the authenticator, nor the authorizer will\n   actually be used: due to `--client-ca-file`, our development X.509\n   certificate is accepted and authenticates us as `system:masters`\n   member. `system:masters` is the superuser group such that delegated\n   authorization is skipped.\n\n5. Use curl to access the server using the client certificate in p12 format for authentication:\n\n   ``` shell\n   curl -fv -k --cert-type P12 --cert client.p12:password \\\n      https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders\n   ```\n\n   Or use wget:\n   ``` shell\n   wget -O- --no-check-certificate \\\n      --certificate client.crt --private-key client.key \\\n      https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders\n   ```\n\n   Note: Recent OSX versions broke client certs with curl. On Mac try `brew install httpie` and then:\n\n   ``` shell\n   http --verify=no --cert client.crt --cert-key client.key \\\n      https://localhost:8443/apis/wardle.example.com/v1alpha1/namespaces/default/flunders\n   ```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes%2Fsample-apiserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubernetes%2Fsample-apiserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubernetes%2Fsample-apiserver/lists"}