View Source Kubereq (kubereq v0.3.1)

Kubereq processes requests to your Kubernetes API Server.

Usage

This library can used with plan Req but the function in this module provide an easier API to people used to kubectl and friends.

Plain Req

Use Kubereq.Kubeconfig.Default to create connection to cluster and plain Req.request() to make the request

req = Req.new() |> Kubereq.attach()

Req.request!(req,
  api_version: "v1",
  kind: "ServiceAccount",
  operation: :get,
  path_params: [namespace: "default", name: "default"]
)

You can pass your own Kubeconfigloader pipeline when attaching:

req = Req.new() |> Kubereq.attach(kubeconfig: {Kubereq.Kubeconfig.File, path: "/path/to/kubeconfig.yaml"})

Req.request!(req,
  api_version: "v1",
  kind: "ServiceAccount",
  operation: :get,
  path_params: [namespace: "default", name: "default"]
)

Prepare a Req struct for a specific resource:

sa_req = Req.new() |> Kubereq.attach(api_version: "v1", kind: "ServiceAccount")

Req.request!(sa_req,  operation: :get, path_params: [namespace: "default", name: "default"])
Req.request!(sa_req,  operation: :list, path_params: [namespace: "default"])

Kubectl API

While this library can attach to any Req struct, it is sometimes easier to prepare Req for a specific resource and then use the functions defined in the Kubereq module.

sa_req = Req.new() |> Kubereq.attach(api_version: "v1", kind: "ServiceAccount")

Kubereq.get(sa_req, "my-namespace", "default")
Kubereq.list(sa_req, "my-namespace")

Or use the functions right away, defining the resource through options:

req = Req.new() |> Kubereq.attach()

Kubereq.get(req, "my-namespace", "default", api_version: "v1", kind: "ServiceAccount")

# get the "status" subresource of the default namespace
Kubereq.get(req, "my-namespace", api_version: "v1", kind: "Namespace", subresource: "status")

For resources defined by Kubernetes, the api_version can be omitted:

Req.new()
|> Kubereq.attach(kind: "Namespace")
|> Kubereq.get("my-namespace")

Options

kubereq registeres the following options with Req:

  • :kubeconfig - A %Kubereq.Kubeconfig{} struct. The attach/2 function also accepts a Kubeconf pipeline (e.g. Kubereq.Kubeconfig.Default)
  • :api_version - The group and version of the targeted resource (case sensitive)
  • :kind - The kind of the targeted resource (case sensitive)
  • :resource_path - Can be defined instead of :api_version and :kind. The path to the targeted resource with placeholders for :namespace and :name (e.g. api/v1/namespaces/:namespace/configmaps/:name)
  • :field_selectors - See Kubereq.Step.FieldSelector
  • :label_selectors - See Kubereq.Step.LabelSelector
  • :operation - The operation on the resource (one of :create, :get :update, :delete, :delete_all, :apply, :json_patch, :merge_patch, :watch)
  • :subresource - Some operations can be performed on subresources (e.g. status or scale)

Summary

Functions

Applies the given resource using a Server-Side-Apply Patch.

Attaches kubereq to a Req.Request struct for making HTTP requests to a Kubernetes cluster. You can optionally pass a Kubernetes configuration or pipeline via kubeconfig option. If it is omitted, the default config Kubereq.Kubeconfig.Default is loaded.

Create the resource or its subresource on the cluster.

Deletes the resource or its subresource from the cluster.

Deletes all resources in the given namespace.

Get the resource name in namespace or its subresource.

Patches the resource namein namespace or its subresource using the given json_patch.

Patches the resource namein namespace or its subresource using the given merge_patch.

new(kubeconfig) deprecated

Updates the given resource.

GET a resource and wait until the given callback returns true or the given timeout (ms) has expired.

Watch events of all resources in namespace.

Watch events of a single resources namein namespace. The req struct should have been created using Kubereq.new/1.

Types

@type namespace() :: String.t() | nil
@type response() :: {:ok, Req.Response.t()} | {:error, Exception.t()}
@type subresource() :: String.t() | nil
@type wait_until_callback() :: (map() | :deleted -> boolean() | {:error, any()})
@type wait_until_response() :: :ok | {:error, :watch_timeout}
@type watch_response() ::
  {:ok, Enumerable.t(map())} | {:ok, Task.t()} | {:error, Exception.t()}

Functions

Link to this function

apply(req, resource, field_manager \\ "Elixir", force \\ true, opts \\ [])

View Source
@spec apply(
  Req.Request.t(),
  resource :: map(),
  field_manager :: binary(),
  force :: boolean(),
  opts :: Keyword.t()
) :: response()

Applies the given resource using a Server-Side-Apply Patch.

See the documentation for a documentation on field_manager and force arguments.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.apply(resource)
{:ok, %Req.Response{status: 200, body: %{...}}}
@spec attach(req :: Req.Request.t(), opts :: Keyword.t()) :: Req.Request.t()

Attaches kubereq to a Req.Request struct for making HTTP requests to a Kubernetes cluster. You can optionally pass a Kubernetes configuration or pipeline via kubeconfig option. If it is omitted, the default config Kubereq.Kubeconfig.Default is loaded.

Examples

iex> Req.new() |> Kubereq.attach()
%Request.Req{...}
Link to this function

create(req, resource, opts \\ [])

View Source
@spec create(Req.Request.t(), resource :: map(), opts :: Keyword.t()) :: response()

Create the resource or its subresource on the cluster.

Example

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.create(resource)
{:ok, %Req.Response{status: 201, body: %{...}}}
Link to this function

delete(req, namespace \\ nil, name, opts \\ [])

View Source
@spec delete(
  Req.Request.t(),
  namespace :: namespace(),
  name :: String.t(),
  opts :: Keyword.t()
) :: response()

Deletes the resource or its subresource from the cluster.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.delete("default", "foo")
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

delete_all(req, namespace \\ nil, opts \\ [])

View Source
@spec delete_all(Req.Request.t(), namespace :: namespace(), opts :: keyword()) ::
  response()

Deletes all resources in the given namespace.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.delete_all("default", label_selectors: [{"app", "my-app"}])
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

get(req, namespace \\ nil, name, opts \\ [])

View Source
@spec get(
  Req.Request.t(),
  namespace :: namespace(),
  name :: String.t(),
  opts :: Keyword.t() | nil
) :: response()

Get the resource name in namespace or its subresource.

Omit namespace to get cluster resources.

Example

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.get("default", "foo")
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

json_patch(req, json_patch, namespace \\ nil, name, opts \\ [])

View Source
@spec json_patch(
  Req.Request.t(),
  json_patch :: map(),
  namespace :: namespace(),
  name :: String.t(),
  opts :: Keyword.t()
) :: response()

Patches the resource namein namespace or its subresource using the given json_patch.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.json_patch(%{...}, "default", "foo")
{:ok, %Req.Response{...}
Link to this function

list(req, namespace \\ nil, opts \\ [])

View Source
@spec list(Req.Request.t(), namespace :: namespace(), opts :: keyword()) :: response()

Get a resource list.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.list("default")
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

merge_patch(req, merge_patch, namespace \\ nil, name, opts \\ [])

View Source
@spec merge_patch(
  Req.Request.t(),
  merge_patch :: String.t(),
  namespace :: namespace(),
  name :: String.t(),
  opts :: Keyword.t()
) :: response()

Patches the resource namein namespace or its subresource using the given merge_patch.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.merge_patch(%{...}, "default", "foo")
{:ok, %Req.Response{...}
This function is deprecated. Use Kubereq.attach/2.
@spec new(kubeconfig :: Kubereq.Kubeconfig.t()) :: Req.Request.t()
Link to this function

new(kubeconfig, resource_path)

View Source
This function is deprecated. Use Kubereq.attach/2.
@spec new(kubeconfig :: Kubereq.Kubeconfig.t(), resource_path :: binary()) ::
  Req.Request.t()
Link to this function

update(req, resource, opts \\ [])

View Source
@spec update(Req.Request.t(), resource :: map(), opts :: Keyword.t()) :: response()

Updates the given resource.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.update(resource)
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

wait_until(req, namespace \\ nil, name, callback, opts \\ [])

View Source
@spec wait_until(
  Req.Request.t(),
  namespace :: namespace(),
  name :: String.t(),
  callback :: wait_until_callback(),
  opts :: Keyword.t()
) :: wait_until_response()

GET a resource and wait until the given callback returns true or the given timeout (ms) has expired.

Options

All options described in the moduledoc plus:

  • timeout - Timeout in ms after function terminates with {:error, :timeout}
Link to this function

watch(req, namespace \\ nil, opts \\ [])

View Source
@spec watch(
  Req.Request.t(),
  namespace :: namespace(),
  opts :: keyword()
) :: watch_response()

Watch events of all resources in namespace.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.watch("default")
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Omit the second argument in order to watch events in all namespaces:

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.watch()
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Options

All options described in the moduledoc plus:

  • :resource_version - If given, starts to stream from the given resourceVersion of the resource list. Otherwise starts streaming from HEAD.
  • :stream_to - If set to a pid, streams events to the given pid. If set to {pid, ref}, the messages are in the form {ref, event}.
Link to this function

watch_single(req, namespace \\ nil, name, opts \\ [])

View Source
@spec watch_single(
  Req.Request.t(),
  namespace :: namespace(),
  name :: String.t(),
  opts :: keyword()
) :: watch_response()

Watch events of a single resources namein namespace. The req struct should have been created using Kubereq.new/1.

Examples

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.watch_single("default")
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Omit the second argument in order to watch events in all namespaces:

iex> Req.new()
...> |> Kubereq.attach(api_version: "v1", kind: "ConfigMap")
...> |> Kubereq.watch_single()
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Options

All options described in the moduledoc plus:

  • :stream_to - If set to a pid, streams events to the given pid. If set to {pid, ref}, the messages are in the form {ref, event}