View Source Kubereq (kubereq v0.1.4)

Kubereq defines a set of Request Steps for Req. All steps combined turn a Kubernetes configuration in the form of a %Kubereq.Kubeconfig{} struct into a %Req.Request{} struct containing all headers and options required to connect to the cluster and perform the given operations.

In order to build %Kubereq.Kubeconfig{} struct you can either use the steps defined in the Kubeconf library or create your own Kubernetes configuration loader module combining those steps.

Instead of using this module directly, consider using Kubegen to generate your API clients.

Examples

The following is a simple but incomplete example for a Client dealing with ConfigMaps. This code is an extraction of what is generated by Kubegen when generating a client for ConfigMaps.

defmodule MyApp.K8sClient.Core.V1.ConfigMap do
  @resource_path "api/v1/namespaces/:namespace/configmaps/:name"

  defp req() do
    kubeconfig = Kubereq.Kubeconfig.load(Kubereq.Kubeconfig.Default)
    Kubereq.new(kubeconfig, @resource_path)
  end

  def get(namespace, name) do
    Kubereq.get(req(), namespace, name)
  end

  def list(namespace, opts \\ []) do
    Kubereq.list(req(), namespace, opts)
  end
end

Summary

Functions

Applies the given resource using a Server-Side-Apply Patch. The req struct should have been created using Kubereq.new/2.

Create the resource object. The req struct should have been created using Kubereq.new/2.

Deletes a resource. The req struct should have been created using Kubereq.new/2.

Deletes all resources in the given namespace. The req struct should have been created using Kubereq.new/2.

Get the resource name in namespace. The req struct should have been created using Kubereq.new/2.

Patches the resource namein namespace using the given json_patch. The req struct should have been created using Kubereq.new/2.

Get a resource list. The req struct should have been created using Kubereq.new/2.

Patches the resource namein namespace using the given merge_patch. The req struct should have been created using Kubereq.new/2.

Prepares a Req.Request struct for making HTTP requests to a Kubernetes cluster. The kubeconfig is the Kubernetes configuration in the form of a %Kubereq.Kubeconfig{} struct and should contain all informations required to connect to the Kubernetes cluster.

Prepares a Req.Request struct for a specific resource on a specific Kubernetes cluster. The kubeconfig is the Kubernetes configuration in the form of a %Kubereq.Kubeconfig{} struct and should contain all informations required to connect to the Kubernetes cluster.

Updates the given resource. The req struct should have been created using Kubereq.new/2.

GET a resource and wait until the given callback returns true or the given timeout (ms) has expired. The req struct should have been created using Kubereq.new/2.

Watch events of all resources in namespace. The req struct should have been created using Kubereq.new/2.

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

Types

@type namespace() :: String.t() | nil
@type response() :: {:ok, Req.Response.t()} | {:error, Exception.t()}
@type wait_until_callback() :: (map() | :deleted -> boolean())
@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)

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

Applies the given resource using a Server-Side-Apply Patch. The req struct should have been created using Kubereq.new/2.

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

Examples

iex> Kubereq.Client.apply(req, %{...})
{:ok, %Req.Response{...}
@spec create(Req.Request.t(), resource :: map()) :: response()

Create the resource object. The req struct should have been created using Kubereq.new/2.

Example

iex> Kubereq.Client.create(req, resource)
{:ok, %Req.Response{status: 201, body: %{...}}}
Link to this function

delete(req, namespace, name)

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

Deletes a resource. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.delete(req, "default", "foo")
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

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

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

Deletes all resources in the given namespace. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.delete_all(req, "default", "foo")
{:ok, %Req.Response{...}

Options

Link to this function

get(req, namespace, name)

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

Get the resource name in namespace. The req struct should have been created using Kubereq.new/2.

Example

iex> Kubereq.Client.get(req, "default", "foo")
{:ok, %Req.Response{status: 200, body: %{...}}}
Link to this function

json_patch(req, json_patch, namespace, name)

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

Patches the resource namein namespace using the given json_patch. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.json_patch(req, %{...}, "default", "foo")
{:ok, %Req.Response{...}
Link to this function

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

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

Get a resource list. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.list(req, "api/v1/namespaces/:namespace/configmaps", "default", [])
{:ok, %Req.Response{status: 200, body: %{...}}}

Options

Link to this function

merge_patch(req, merge_patch, namespace, name)

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

Patches the resource namein namespace using the given merge_patch. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.merge_patch(req, %{...}, "default", "foo")
{:ok, %Req.Response{...}
@spec new(kubeconfig :: Kubereq.Kubeconfig.t()) :: Req.Request.t()

Prepares a Req.Request struct for making HTTP requests to a Kubernetes cluster. The kubeconfig is the Kubernetes configuration in the form of a %Kubereq.Kubeconfig{} struct and should contain all informations required to connect to the Kubernetes cluster.

Examples

iex> kubeconfig = Kubereq.Kubeconfig.load(Kubereq.Kubeconfig.Default)
...> Kubereq.new(kubeconfig)
%Request.Req{...}
Link to this function

new(kubeconfig, resource_path)

View Source
@spec new(kubeconfig :: Kubereq.Kubeconfig.t(), resource_path :: binary()) ::
  Req.Request.t()

Prepares a Req.Request struct for a specific resource on a specific Kubernetes cluster. The kubeconfig is the Kubernetes configuration in the form of a %Kubereq.Kubeconfig{} struct and should contain all informations required to connect to the Kubernetes cluster.

The parameter resource_path should be the path on which the Kubernetes API Server listens for requests for the targeted resource kind. It should contain placeholders for :namespace and :name.

The :namespace and :name are provided through the :path_params option built into Req when making the request.

Examples

Prepare a Req.Request for ConfigMaps:

iex> kubeconfig = Kubereq.Kubeconfig.load(Kubereq.Kubeconfig.Default)
...> Kubereq.new(kubeconfig, "api/v1/namespaces/:namespace/configmaps/:name")
%Request.Req{...}
@spec update(Req.Request.t(), resource :: map()) :: response()

Updates the given resource. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.update(req, %{...})
{:ok, %Req.Response{...}
Link to this function

wait_until(req, namespace, name, callback, timeout \\ 10000)

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

GET a resource and wait until the given callback returns true or the given timeout (ms) has expired. The req struct should have been created using Kubereq.new/2.

Options

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

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

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

Watch events of all resources in namespace. The req struct should have been created using Kubereq.new/2.

Examples

iex> Kubereq.Client.watch(req, "default", [])
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

In order to watch events in all namespaces, pass nil as namespace:

iex> Kubereq.Client.watch(req, nil, [])
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Options

  • :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}.
  • :field_selectors - A list of field selectors. See Kubereq.Step.FieldSelector for more infos.
  • :label_selectors - A list of field selectors. See Kubereq.Step.LabelSelector for more infos.
Link to this function

watch_single(req, namespace, 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/2.

Examples

iex> Kubereq.Client.watch_single(req, "default", [])
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

In order to watch events in all namespaces, pass nil as namespace:

iex> Kubereq.Client.watch_single(req, nil, [])
{:ok, #Function<60.48886818/2 in Stream.transform/3>}

Options

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