kubernetes Documentation

Production-Grade Container Scheduling and Management - Alibaba's Fork

23 stars Go Go 7 files · ~7,977 tokens #alibaba#alibabacloud#aliyun#container#docker#kubernetes
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy kubernetes on any server, homelab, or cloud container platform.

Technical Documentation: alibaba/kubernetes

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md)

Kubernetes

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].

text
go get -d k8s.io/kubernetes
cd $GOPATH/src/k8s.io/kubernetes
make

You have a working [Docker environment].

text
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.

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
  • Dockerhub account to push the image to Dockerhub

Install Minikube

Minikube is a single node Kubernetes cluster that runs on your local machine. The Minikube docs have installation instructions for your OS.

Clone the repository

In order to build the sample apiserver image we will need to build the apiserver binary.

text
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:

text
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:

text
cp ./sample-apiserver ./artifacts/simple-image/kube-sample-apiserver
docker build -t <YOUR_DOCKERHUB_USER>/kube-sample-apiserver:latest ./artifacts/simple-image
docker push <YOUR_DOCKERHUB_USER>/kube-sample-apiserver

Modify the replication controller

You need to modify the 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 <YOUR_DOCKERHUB_USER>/kube-sample-apiserver:latest. For example:

yaml
...
      containers:
      - name: wardle-server
        image: <YOUR_DOCKERHUB_USER>/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.

text
# 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.

text
kubectl create -f artifacts/flunders/01-flunder.yaml
# outputs flunder "my-first-flunder" created

You can then get this resource by running:

text
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 library contains various mechanisms that you can use when
developing your custom controllers. These mechanisms are defined in the
tools/cache folder 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,
    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 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. 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
    that generates an object’s key as <namespace>/<name> 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 or use factory methods for creating an informer.

  • 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, 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:

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:

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:

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 ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#alibaba Browse alibaba catalog → #alibabacloud Browse alibabacloud catalog → #aliyun Browse aliyun catalog → #container Browse container catalog → #docker Browse docker catalog → #kubernetes Browse kubernetes catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →