Update docs on virtual-kubelet.io (#754)
* Update website content * Add PodLifecycleHandler
This commit is contained in:
Ernest Wong
@@ -26,69 +26,54 @@ Virtual Kubelet currently has a wide variety of providers:
|
||||
|
||||
## Adding new providers {#adding}
|
||||
|
||||
To add a new Virtual Kubelet provider, create a new directory for your provider in the [`providers`](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers) directory.
|
||||
To add a new Virtual Kubelet provider, create a new directory for your provider.
|
||||
|
||||
```shell
|
||||
git clone https://github.com/virtual-kubelet/virtual-kubelet
|
||||
cd virtual-kubelet
|
||||
mkdir providers/my-provider
|
||||
```
|
||||
In that created directory, implement [`PodLifecycleHandler`](https://godoc.org/github.com/virtual-kubelet/virtual-kubelet/node#PodLifecycleHandler) interface in [Go](https://golang.org).
|
||||
|
||||
In that created directory, implement the [`Provider`](https://godoc.org/github.com/virtual-kubelet/virtual-kubelet/providers#Provider) interface in [Go](https://golang.org).
|
||||
|
||||
> For an example implementation of the Virtual Kubelet `Provider` interface, see the [Virtual Kubelet CRI Provider](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers/cri), especially [`cri.go`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/providers/cri/cri.go).
|
||||
> For an example implementation of the Virtual Kubelet `PodLifecycleHandler` interface, see the [Virtual Kubelet CRI Provider](https://github.com/virtual-kubelet/cri), especially [`cri.go`](https://github.com/virtual-kubelet/cri/blob/master/cri.go).
|
||||
|
||||
Each Virtual Kubelet provider can be configured using its own configuration file and environment variables.
|
||||
|
||||
You can see the list of required methods, with relevant descriptions of each method, below:
|
||||
|
||||
```go
|
||||
// Provider contains the methods required to implement a Virtual Kubelet provider
|
||||
type Provider interface {
|
||||
// Takes a Kubernetes Pod and deploys it within the provider
|
||||
CreatePod(ctx context.Context, pod *v1.Pod) error
|
||||
// PodLifecycleHandler defines the interface used by the PodController to react
|
||||
// to new and changed pods scheduled to the node that is being managed.
|
||||
//
|
||||
// Errors produced by these methods should implement an interface from
|
||||
// github.com/virtual-kubelet/virtual-kubelet/errdefs package in order for the
|
||||
// core logic to be able to understand the type of failure.
|
||||
type PodLifecycleHandler interface {
|
||||
// CreatePod takes a Kubernetes Pod and deploys it within the provider.
|
||||
CreatePod(ctx context.Context, pod *corev1.Pod) error
|
||||
|
||||
// Takes a Kubernetes Pod and updates it within the provider
|
||||
UpdatePod(ctx context.Context, pod *v1.Pod) error
|
||||
// UpdatePod takes a Kubernetes Pod and updates it within the provider.
|
||||
UpdatePod(ctx context.Context, pod *corev1.Pod) error
|
||||
|
||||
// Takes a Kubernetes Pod and deletes it from the provider
|
||||
DeletePod(ctx context.Context, pod *v1.Pod) error
|
||||
// DeletePod takes a Kubernetes Pod and deletes it from the provider.
|
||||
DeletePod(ctx context.Context, pod *corev1.Pod) error
|
||||
|
||||
// Retrieves a pod by name from the provider (can be cached)
|
||||
GetPod(ctx context.Context, namespace, name string) (*v1.Pod, error)
|
||||
// GetPod retrieves a pod by name from the provider (can be cached).
|
||||
// The Pod returned is expected to be immutable, and may be accessed
|
||||
// concurrently outside of the calling goroutine. Therefore it is recommended
|
||||
// to return a version after DeepCopy.
|
||||
GetPod(ctx context.Context, namespace, name string) (*corev1.Pod, error)
|
||||
|
||||
// Retrieves the logs of a container by name from the provider
|
||||
GetContainerLogs(ctx context.Context, namespace, podName, containerName string, tail int) (string, error)
|
||||
// GetPodStatus retrieves the status of a pod by name from the provider.
|
||||
// The PodStatus returned is expected to be immutable, and may be accessed
|
||||
// concurrently outside of the calling goroutine. Therefore it is recommended
|
||||
// to return a version after DeepCopy.
|
||||
GetPodStatus(ctx context.Context, namespace, name string) (*corev1.PodStatus, error)
|
||||
|
||||
// Executes a command in a container in the pod, copying data between
|
||||
// in/out/err and the container's stdin/stdout/stderr
|
||||
ExecInContainer(name string, uid types.UID, container string, cmd []string, in io.Reader, out, err io.WriteCloser, tty bool, resize <-chan remotecommand.TerminalSize, timeout time.Duration) error
|
||||
|
||||
// Retrieves the status of a pod by name from the provider
|
||||
GetPodStatus(ctx context.Context, namespace, name string) (*v1.PodStatus, error)
|
||||
|
||||
// Retrieves a list of all pods running on the provider (can be cached)
|
||||
GetPods(context.Context) ([]*v1.Pod, error)
|
||||
|
||||
// Returns a resource list with the capacity constraints of the provider
|
||||
Capacity(context.Context) v1.ResourceList
|
||||
|
||||
// Returns a list of conditions (Ready, OutOfDisk, etc), which is polled
|
||||
// periodically to update the node status within Kubernetes
|
||||
NodeConditions(context.Context) []v1.NodeCondition
|
||||
|
||||
// Returns a list of addresses for the node status within Kubernetes
|
||||
NodeAddresses(context.Context) []v1.NodeAddress
|
||||
|
||||
// Returns NodeDaemonEndpoints for the node status within Kubernetes.
|
||||
NodeDaemonEndpoints(context.Context) *v1.NodeDaemonEndpoints
|
||||
|
||||
// Returns the operating system the provider is for
|
||||
OperatingSystem() string
|
||||
// GetPods retrieves a list of all pods running on the provider (can be cached).
|
||||
// The Pods returned are expected to be immutable, and may be accessed
|
||||
// concurrently outside of the calling goroutine. Therefore it is recommended
|
||||
// to return a version after DeepCopy.
|
||||
GetPods(context.Context) ([]*corev1.Pod, error)
|
||||
}
|
||||
```
|
||||
|
||||
In addition to `Provider`, there's an optional [`PodMetricsProvider`](https://godoc.org/github.com/virtual-kubelet/virtual-kubelet/providers#PodMetricsProvider) interface that providers can implement to expose Kubernetes Pod stats:
|
||||
In addition to `PodLifecycleHandler`, there's an optional [`PodMetricsProvider`](https://godoc.org/github.com/virtual-kubelet/virtual-kubelet/cmd/virtual-kubelet/internal/provider#PodMetricsProvider) interface that providers can implement to expose Kubernetes Pod stats:
|
||||
|
||||
```go
|
||||
type PodMetricsProvider interface {
|
||||
@@ -102,8 +87,6 @@ For a Virtual Kubelet provider to be considered viable, it must support the foll
|
||||
1. It must conform to the current API provided by Virtual Kubelet (see [above](#adding))
|
||||
1. It won't have access to the [Kubernetes API server](https://kubernetes.io/docs/concepts/overview/kubernetes-api/), so it must provide a well-defined callback mechanism for fetching data like [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) and [ConfigMaps](https://kubernetes.io/docs/tutorials/configuration/).
|
||||
|
||||
In addition to implementing the `Provider` interface in `providers/<your provider>`, you also need to add your provider to the [`providers/register`](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers/register) directory, in `provider_<your provider>.go`. Current examples include [`provider_azure.go`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/providers/register/provider_azure.go) and [`provider_aws.go`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/providers/register/provider_aws.go), which you can use as templates.
|
||||
|
||||
## Documentation
|
||||
|
||||
No Virtual Kubelet provider is complete without solid documentation. We strongly recommend providing a README for your provider in its directory. The READMEs for the currently existing implementations can provide a blueprint.
|
||||
|
||||
@@ -27,7 +27,7 @@ and the YAML config in data/cli.yaml
|
||||
|
||||
It's possible to run the Virtual Kubelet as a Kubernetes Pod inside a [Minikube](https://kubernetes.io/docs/setup/minikube/) or [Docker for Desktop](https://docs.docker.com/docker-for-windows/kubernetes/) Kubernetes cluster.
|
||||
|
||||
> At this time, automation of this deployment is supported only for the [`mock`](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers/mock) provider.
|
||||
> At this time, automation of this deployment is supported only for the [`mock`](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/cmd/virtual-kubelet/internal/provider/mock) provider.
|
||||
|
||||
In order to deploy the Virtual Kubelet, you need to install [Skaffold](https://skaffold.dev/), a Kubernetes development tool. You also need to make sure that your current [kubectl context](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) is either `minikube` or `docker-for-desktop` (depending on which Kubernetes platform you're using).
|
||||
|
||||
@@ -44,7 +44,7 @@ Then:
|
||||
make skaffold
|
||||
```
|
||||
|
||||
By default, this will run Skaffold in [development mode](https://github.com/GoogleContainerTools/skaffold#skaffold-dev), which will make Skaffold watch [`hack/skaffold/virtual-kubelet/Dockerfile`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/hack/skaffold/virtual-kubelet/Dockerfile) and its dependencies for changes and re-deploy the Virtual Kubelet when changes happen. It will also make Skaffold stream logs from the Virtual Kubelet Pod.
|
||||
By default, this will run Skaffold in [development mode](https://github.com/GoogleContainerTools/skaffold#a-glance-at-skaffold-workflow-and-architecture), which will make Skaffold watch [`hack/skaffold/virtual-kubelet/Dockerfile`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/hack/skaffold/virtual-kubelet/Dockerfile) and its dependencies for changes and re-deploy the Virtual Kubelet when changes happen. It will also make Skaffold stream logs from the Virtual Kubelet Pod.
|
||||
|
||||
Alternative, you can run Skaffold outside of development mode—if you aren't concerned about continuous deployment and log streaming—by running:
|
||||
|
||||
|
||||
@@ -1,8 +1,17 @@
|
||||
description: The command-line tool for running Virtual Kubelets
|
||||
flags:
|
||||
- name: --cluster-domain
|
||||
arg: string
|
||||
description: Kubernetes cluster domain
|
||||
default: cluster.local
|
||||
- name: --disable-taint
|
||||
arg: bool
|
||||
description: Disable the Virtual Kubelet [Node taint](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/)
|
||||
default: "false"
|
||||
- name: --enable-node-lease
|
||||
arg: bool
|
||||
description: Use node leases (1.13) for node heartbeats
|
||||
default: "false"
|
||||
- name: --full-resync-period
|
||||
arg: duration
|
||||
description: How often to perform a full resync of Pods between Kubernetes and the provider
|
||||
@@ -41,9 +50,13 @@ flags:
|
||||
- name: --provider-config
|
||||
arg: string
|
||||
description: The Virtual Kubelet [provider](/docs/providers) configuration file
|
||||
- name: --startup-timeout
|
||||
arg: duration
|
||||
description: How long to wait for the virtual-kubelet to start
|
||||
default: 0
|
||||
- name: --trace-exporter
|
||||
arg: strings
|
||||
description: The tracing exporter to use. Available exporters are `jaeger` and `ocagent`.
|
||||
description: The tracing exporter to use. Available exporters are `jaeger` and `ocagent`
|
||||
- name: --trace-sample-rate
|
||||
arg: string
|
||||
description: The probability of tracing samples
|
||||
@@ -53,8 +66,4 @@ flags:
|
||||
default: virtual-kubelet
|
||||
- name: --trace-tag
|
||||
arg: map
|
||||
description: Tags to include with traces, in `key=value` form
|
||||
- name: --version
|
||||
description: The Virtual Kubelet version
|
||||
- name: --help
|
||||
description: Command help information
|
||||
description: Tags to include with traces, in `key=value` form
|
||||
Reference in New Issue
Block a user