From 9e245f373726f8bd439ed834bb79d0b8fc0c0b79 Mon Sep 17 00:00:00 2001 From: Luc Perkins Date: Mon, 25 Mar 2019 14:16:33 -0700 Subject: [PATCH] Additional provider docs (#498) * Modify providers shortcode Signed-off-by: lucperkins * Add extra note to provider section Signed-off-by: lucperkins * More info in Providers doc Signed-off-by: lucperkins * Update Alibaba tag Signed-off-by: lucperkins * Add resources directory back to Git Signed-off-by: lucperkins --- website/assets/sass/style.sass | 4 ++ website/content/docs/providers.md | 78 ++++++++++++++++++++++++++++++- 2 files changed, 81 insertions(+), 1 deletion(-) diff --git a/website/assets/sass/style.sass b/website/assets/sass/style.sass index 5e822f883..147f1a84c 100644 --- a/website/assets/sass/style.sass +++ b/website/assets/sass/style.sass @@ -64,6 +64,10 @@ $colors: mergeColorMaps(("twitter-blue": ($twitter-blue, $white), "slack-green": .main flex: 1 +blockquote + code + background-color: $grey-lighter + =hide display: none diff --git a/website/content/docs/providers.md b/website/content/docs/providers.md index bd3c1ea7b..a0ecd9502 100644 --- a/website/content/docs/providers.md +++ b/website/content/docs/providers.md @@ -36,4 +36,80 @@ mkdir providers/my-provider 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 a basic example, see the [Virtual Kubelet CRI Provider](https://github.com/virtual-kubelet/virtual-kubelet/tree/master/providers/cri). +> 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). + +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 + + // Takes a Kubernetes Pod and updates it within the provider + UpdatePod(ctx context.Context, pod *v1.Pod) error + + // Takes a Kubernetes Pod and deletes it from the provider + DeletePod(ctx context.Context, pod *v1.Pod) error + + // Retrieves a pod by name from the provider (can be cached) + GetPod(ctx context.Context, namespace, name string) (*v1.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) + + // 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 +} +``` + +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: + +```go +type PodMetricsProvider interface { + GetStatsSummary(context.Context) (*stats.Summary, error) +} +``` + +For a Virtual Kubelet provider to be considered viable, it must support the following functionality: + +1. It must provide the backend plumbing necessary to support the lifecycle management of Pods, containers, and supporting resources in the Kubernetes context. +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/`, 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_.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. + +You'll also likely want your provider to appear in the [list of current providers](#current-providers). That list is generated from a [`provider.yaml`](https://github.com/virtual-kubelet/virtual-kubelet/blob/master/website/data/providers.yaml) file. Add a `name` field for the displayed name of the provider and the subdirectory as the `tag` field. The `name` field supports Markdown, so feel free to use bold text or a hyperlink. + +## Testing + +In order to test the provider you're developing, simply run `make test` from the root of the Virtual Kubelet directory.