# Technical Documentation: alibaba/kubernetes > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/alibaba/kubernetes) ### Overview (README.md) # Kubernetes [](https://bestpractices.coreinfrastructure.org/projects/569) ---- Kubernetes is an open source system for managing [containerized applications] across multiple hosts; providing basic mechanisms for deployment, maintenance, and scaling of applications. Kubernetes builds upon a decade and a half of experience at Google running production workloads at scale using a system called [Borg], combined with best-of-breed ideas and practices from the community. Kubernetes is hosted by the Cloud Native Computing Foundation ([CNCF]). If you are a company that wants to help shape the evolution of technologies that are container-packaged, dynamically-scheduled and microservices-oriented, consider joining the CNCF. For details about who's involved and how Kubernetes plays a role, read the CNCF [announcement]. ---- ## To start using Kubernetes See our documentation on [kubernetes.io]. Try our [interactive tutorial]. Take a free course on [Scalable Microservices with Kubernetes]. ## To start developing Kubernetes The [community repository] hosts all information about building Kubernetes from source, how to contribute code and documentation, who to contact about what, etc. If you want to build Kubernetes right away there are two options: ##### You have a working [Go environment]. ``` go get -d k8s.io/kubernetes cd $GOPATH/src/k8s.io/kubernetes make ``` ##### You have a working [Docker environment]. ``` git clone https://github.com/kubernetes/kubernetes cd kubernetes make quick-release ``` For the full story, head over to the [developer's documentation]. ## Support If you need support, start with the [troubleshooting guide], and work your way through the process that we've outlined. That said, if you have questions, reach out to us [one way or another][communication]. [announcement]: https://cncf.io/news/announcement/2015/07/new-cloud-native-computing-foundation-drive-alignment-among-container [Borg]: https://research.google.com/pubs/pub43438.html [CNCF]: https://www.cncf.io/about [communication]: https://git.k8s.io/community/communication [community repository]: https://git.k8s.io/community [containerized applications]: https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/ [developer's documentation]: https://git.k8s.io/community/contributors/devel#readme [Docker environment]: https://docs.docker.com/engine [Go environment]: https://golang.org/doc/install [GoDoc]: https://godoc.org/k8s.io/kubernetes [GoDoc Widget]: https://godoc.org/k8s.io/kubernetes?status.svg [interactive tutorial]: https://kubernetes.io/docs/tutorials/kubernetes-basics [kubernetes.io]: https://kubernetes.io [Scalable Microservices with Kubernetes]: https://www.udacity.com/course/scalable-microservices-with-kubernetes--ud615 [troubleshooting guide]: https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/ []() --- ### Staging Src K8s.Io Sample Apiserver Docs Minikube Walkthrough (`staging/src/k8s.io/sample-apiserver/docs/minikube-walkthrough.md`) # Minikube walkthrough This document will take you through setting up and trying the sample apiserver on a local minikube from a fresh clone of this repo. ## Pre requisites - Go 1.7.x or later installed and setup. More infomration can be found at [go installation](https://golang.org/doc/install) - Dockerhub account to push the image to [Dockerhub](https://hub.docker.com/) ## Install Minikube Minikube is a single node Kubernetes cluster that runs on your local machine. The Minikube docs have installation instructions for your OS. - [minikube installation](https://github.com/kubernetes/minikube#installation) ## Clone the repository In order to build the sample apiserver image we will need to build the apiserver binary. ``` cd $GOPATH/src mkdir -p k8s.io cd k8s.io git clone https://github.com/kubernetes/sample-apiserver.git ``` ## Build the binary Next we will want to create a new binary to both test we can build the server and to use for the container image. From the root of this repo, where ```main.go``` is located, run the following command: ``` export GOOS=linux; go build . ``` if everything went well, you should have a binary called ```sample-apiserver``` present in your current directory. ## Build the container image Using the binary we just built, we will now create a Docker image and push it to our Dockerhub registry so that we deploy it to our cluster. There is a sample ```Dockerfile``` located in ```artifacts/simple-image``` we will use this to build our own image. Again from the root of this repo run the following commands: ``` cp ./sample-apiserver ./artifacts/simple-image/kube-sample-apiserver docker build -t /kube-sample-apiserver:latest ./artifacts/simple-image docker push /kube-sample-apiserver ``` ## Modify the replication controller You need to modify the [artifacts/example/rc.yaml](/artifacts/example/rc.yaml) file to change the ```imagePullPolicy``` to ```Always``` or ```IfNotPresent```. You also need to change the image from ```kube-sample-apiserver:latest``` to ```/kube-sample-apiserver:latest```. For example: ```yaml ... containers: - name: wardle-server image: /kube-sample-apiserver:latest imagePullPolicy: Always ... ``` Save this file and we are then ready to deploy and try out the sample apiserver. ## Deploy to Minikube We will need to create several objects in order to setup the sample apiserver so you will need to ensure you have the ```kubectl``` tool installed. [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). ``` # create the namespace to run the apiserver in kubectl create ns wardle # create the service account used to run the server kubectl create -f artifacts/example/sa.yaml -n wardle # create the rolebindings that allow the service account user to delegate authz back to the kubernetes master for incoming requests to the apiserver kubectl create -f artifacts/example/auth-delegator.yaml -n kube-system kubectl create -f artifacts/example/auth-reader.yaml -n kube-system # create rbac roles and clusterrolebinding that allow the service account user to use admission webhooks kubectl create -f artifacts/example/rbac.yaml kubectl create -f artifacts/example/rbac-bind.yaml # create the service and replication controller kubectl create -f artifacts/example/rc.yaml -n wardle kubectl create -f artifacts/example/service.yaml -n wardle # create the apiservice object that tells kubernetes about your api extension and where in the cluster the server is located kubectl create -f artifacts/example/apiservice.yaml ``` ## Test that your setup has worked You should now be able to create the resource type ```Flunder``` which is the resource type registered by the sample apiserver. ``` kubectl create -f artifacts/flunders/01-flunder.yaml # outputs flunder "my-first-flunder" created ``` You can then get this resource by running: ``` kubectl get flunder my-first-flunder #outputs # NAME KIND # my-first-flunder Flunder.v1alpha1.wardle.k8s.io ``` --- ### Staging Src K8s.Io Sample Controller Docs Controller Client Go (`staging/src/k8s.io/sample-controller/docs/controller-client-go.md`) # client-go under the hood The [client-go](https://github.com/kubernetes/client-go/) library contains various mechanisms that you can use when developing your custom controllers. These mechanisms are defined in the [tools/cache folder](https://github.com/kubernetes/client-go/tree/master/tools/cache) of the library. Here is a pictorial representation showing how the various components in the client-go library work and their interaction points with the custom controller code that you will write.

## client-go components * Reflector: A reflector, which is defined in [type *Reflector* inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/reflector.go), watches the Kubernetes API for the specified resource type (kind). The function in which this is done is *ListAndWatch*. The watch could be for an in-built resource or it could be for a custom resource. When the reflector receives notification about existence of new resource instance through the watch API, it gets the newly created object using the corresponding listing API and puts it in the Delta Fifo queue inside the *watchHandler* function. * Informer: An informer defined in the [base controller inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/controller.go) pops objects from the Delta Fifo queue. The function in which this is done is *processLoop*. The job of this base controller is to save the object for later retrieval, and to invoke our controller passing it the object. * Indexer: An indexer provides indexing functionality over objects. It is defined in [type *Indexer* inside package *cache*](https://github.com/kubernetes/client-go/blob/master/tools/cache/index.go). A typical indexing use-case is to create an index based on object labels. Indexer can maintain indexes based on several indexing functions. Indexer uses a thread-safe data store to store objects and their keys. There is a default function named *MetaNamespaceKeyFunc* defined in [type Store inside package cache](https://github.com/kubernetes/client-go/blob/master/tools/cache/store.go) that generates an object’s key as `/` combination for that object. ## Custom Controller components * Informer reference: This is the reference to the Informer instance that knows how to work with your custom resource objects. Your custom controller code needs to create the appropriate Informer. * Indexer reference: This is the reference to the Indexer instance that knows how to work with your custom resource objects. Your custom controller code needs to create this. You will be using this reference for retrieving objects for later processing. The base controller in client-go provides the *NewIndexerInformer* function to create Informer and Indexer. In your code you can either [directly invoke this function](https://github.com/kubernetes/client-go/blob/master/examples/workqueue/main.go#L174) or [use factory methods for creating an informer.](https://github.com/kubernetes/sample-controller/blob/master/main.go#L61) * Resource Event Handlers: These are the callback functions which will be called by the Informer when it wants to deliver an object to your controller. The typical pattern to write these functions is to obtain the dispatched object’s key and enqueue that key in a work queue for further processing. * Work queue: This is the queue that you create in your controller code to decouple delivery of an object from its processing. Resource event handler functions are written to extract the delivered object’s key and add that to the work queue. * Process Item: This is the function that you create in your code which processes items from the work queue. There can be one or more other functions that do the actual processing. These functions will typically use the [Indexer reference](https://github.com/kubernetes/client-go/blob/master/examples/workqueue/main.go#L73), or a Listing wrapper to retrieve the object corresponding to the key. --- ### Vendor Github.Com Spf13 Cobra Doc Man Docs (`vendor/github.com/spf13/cobra/doc/man_docs.md`) # Generating Man Pages For Your Own cobra.Command Generating man pages from a cobra command is incredibly easy. An example is as follows: ```go package main import ( "log" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" ) func main() { cmd := &cobra.Command{ Use: "test", Short: "my test program", } header := &doc.GenManHeader{ Title: "MINE", Section: "3", } err := doc.GenManTree(cmd, header, "/tmp") if err != nil { log.Fatal(err) } } ``` That will get you a man page `/tmp/test.3` --- ### Vendor Github.Com Spf13 Cobra Doc Md Docs (`vendor/github.com/spf13/cobra/doc/md_docs.md`) # Generating Markdown Docs For Your Own cobra.Command Generating man pages from a cobra command is incredibly easy. An example is as follows: ```go package main import ( "log" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" ) func main() { cmd := &cobra.Command{ Use: "test", Short: "my test program", } err := doc.GenMarkdownTree(cmd, "/tmp") if err != nil { log.Fatal(err) } } ``` That will get you a Markdown document `/tmp/test.md` ## Generate markdown docs for the entire command tree This program can actually generate docs for the kubectl command in the kubernetes project ```go package main import ( "log" "io/ioutil" "os" "k8s.io/kubernetes/pkg/kubectl/cmd" cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util" "github.com/spf13/cobra/doc" ) func main() { kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard) err := doc.GenMarkdownTree(kubectl, "./") if err != nil { log.Fatal(err) } } ``` This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./") ## Generate markdown docs for a single command You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenMarkdown` instead of `GenMarkdownTree` ```go out := new(bytes.Buffer) err := doc.GenMarkdown(cmd, out) if err != nil { log.Fatal(err) } ``` This will write the markdown doc for ONLY "cmd" into the out, buffer. ## Customize the output Both `GenMarkdown` and `GenMarkdownTree` have alternate versions with callbacks to get some control of the output: ```go func GenMarkdownTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error { //... } ``` ```go func GenMarkdownCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error { //... } ``` The `filePrepender` will prepend the return value given the full filepath to the rendered Markdown file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/): ```go const fmTemplate = `--- date: %s title: "%s" slug: %s url: %s --- ` filePrepender := func(filename string) string { now := time.Now().Format(time.RFC3339) name := filepath.Base(filename) base := strings.TrimSuffix(name, path.Ext(name)) url := "/commands/" + strings.ToLower(base) + "/" return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url) } ``` The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename: ```go linkHandler := func(name string) string { base := strings.TrimSuffix(name, path.Ext(name)) return "/commands/" + strings.ToLower(base) + "/" } ``` --- ### Vendor Github.Com Spf13 Cobra Doc Rest Docs (`vendor/github.com/spf13/cobra/doc/rest_docs.md`) # Generating ReStructured Text Docs For Your Own cobra.Command Generating ReST pages from a cobra command is incredibly easy. An example is as follows: ```go package main import ( "log" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" ) func main() { cmd := &cobra.Command{ Use: "test", Short: "my test program", } err := doc.GenReSTTree(cmd, "/tmp") if err != nil { log.Fatal(err) } } ``` That will get you a ReST document `/tmp/test.rst` ## Generate ReST docs for the entire command tree This program can actually generate docs for the kubectl command in the kubernetes project ```go package main import ( "log" "io/ioutil" "os" "k8s.io/kubernetes/pkg/kubectl/cmd" cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util" "github.com/spf13/cobra/doc" ) func main() { kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard) err := doc.GenReSTTree(kubectl, "./") if err != nil { log.Fatal(err) } } ``` This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./") ## Generate ReST docs for a single command You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenReST` instead of `GenReSTTree` ```go out := new(bytes.Buffer) err := doc.GenReST(cmd, out) if err != nil { log.Fatal(err) } ``` This will write the ReST doc for ONLY "cmd" into the out, buffer. ## Customize the output Both `GenReST` and `GenReSTTree` have alternate versions with callbacks to get some control of the output: ```go func GenReSTTreeCustom(cmd *Command, dir string, filePrepender func(string) string, linkHandler func(string, string) string) error { //... } ``` ```go func GenReSTCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string, string) string) error { //... } ``` The `filePrepender` will prepend the return value given the full filepath to the rendered ReST file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/): ```go const fmTemplate = `--- date: %s title: "%s" slug: %s url: %s --- ` filePrepender := func(filename string) string { now := time.Now().Format(time.RFC3339) name := filepath.Base(filename) base := strings.TrimSuffix(name, path.Ext(name)) url := "/commands/" + strings.ToLower(base) + "/" return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url) } ``` The `linkHandler` can be used to customize the rendered links to the commands, given a command name and reference. This is useful while converting rst to html or while generating documentation with tools like Sphinx where `:ref:` is used: ```go // Sphinx cross-referencing format linkHandler := func(name, ref string) string { return fmt.Sprintf(":ref:`%s <%s>`", name, ref) } ``` --- ### Vendor Github.Com Spf13 Cobra Doc Yaml Docs (`vendor/github.com/spf13/cobra/doc/yaml_docs.md`) # Generating Yaml Docs For Your Own cobra.Command Generating yaml files from a cobra command is incredibly easy. An example is as follows: ```go package main import ( "log" "github.com/spf13/cobra" "github.com/spf13/cobra/doc" ) func main() { cmd := &cobra.Command{ Use: "test", Short: "my test program", } err := doc.GenYamlTree(cmd, "/tmp") if err != nil { log.Fatal(err) } } ``` That will get you a Yaml document `/tmp/test.yaml` ## Generate yaml docs for the entire command tree This program can actually generate docs for the kubectl command in the kubernetes project ```go package main import ( "io/ioutil" "log" "os" "k8s.io/kubernetes/pkg/kubectl/cmd" cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util" "github.com/spf13/cobra/doc" ) func main() { kubectl := cmd.NewKubectlCommand(cmdutil.NewFactory(nil), os.Stdin, ioutil.Discard, ioutil.Discard) err := doc.GenYamlTree(kubectl, "./") if err != nil { log.Fatal(err) } } ``` This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "./") ## Generate yaml docs for a single command You may wish to have more control over the output, or only generate for a single command, instead of the entire command tree. If this is the case you may prefer to `GenYaml` instead of `GenYamlTree` ```go out := new(bytes.Buffer) doc.GenYaml(cmd, out) ``` This will write the yaml doc for ONLY "cmd" into the out, buffer. ## Customize the output Both `GenYaml` and `GenYamlTree` have alternate versions with callbacks to get some control of the output: ```go func GenYamlTreeCustom(cmd *Command, dir string, filePrepender, linkHandler func(string) string) error { //... } ``` ```go func GenYamlCustom(cmd *Command, out *bytes.Buffer, linkHandler func(string) string) error { //... } ``` The `filePrepender` will prepend the return value given the full filepath to the rendered Yaml file. A common use case is to add front matter to use the generated documentation with [Hugo](http://gohugo.io/): ```go const fmTemplate = `--- date: %s title: "%s" slug: %s url: %s --- ` filePrepender := func(filename string) string { now := time.Now().Format(time.RFC3339) name := filepath.Base(filename) base := strings.TrimSuffix(name, path.Ext(name)) url := "/commands/" + strings.ToLower(base) + "/" return fmt.Sprintf(fmTemplate, now, strings.Replace(base, "_", " ", -1), base, url) } ``` The `linkHandler` can be used to customize the rendered internal links to the commands, given a filename: ```go linkHandler := func(name string) string { base := strings.TrimSuffix(name, path.Ext(name)) return "/commands/" + strings.ToLower(base) + "/" } ``` --- --- METRICS --- - Files Extracted: 7 - Estimated Token Budget: ~5216 tokens - Canonical Reference: https://codewiki.google/github.com/alibaba/kubernetes