View Source Kubereq (kubereq v0.3.0)
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. Theattach/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
- SeeKubereq.Step.FieldSelector
:label_selectors
- SeeKubereq.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
orscale
)
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 name
in namespace
or its subresource
using the given
json_patch
.
Get a resource list.
Patches the resource name
in namespace
or its subresource
using the given
merge_patch
.
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 name
in 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_response() :: :ok | {:error, :watch_timeout}
@type watch_response() :: {:ok, Enumerable.t(map())} | {:ok, Task.t()} | {:error, Exception.t()}
Functions
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{...}
@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: %{...}}}
@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: %{...}}}
@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: %{...}}}
@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: %{...}}}
@spec json_patch( Req.Request.t(), json_patch :: map(), namespace :: namespace(), name :: String.t(), opts :: Keyword.t() ) :: response()
Patches the resource name
in 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{...}
@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: %{...}}}
@spec merge_patch( Req.Request.t(), merge_patch :: String.t(), namespace :: namespace(), name :: String.t(), opts :: Keyword.t() ) :: response()
Patches the resource name
in 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{...}
@spec new(kubeconfig :: Kubereq.Kubeconfig.t()) :: Req.Request.t()
@spec new(kubeconfig :: Kubereq.Kubeconfig.t(), resource_path :: binary()) :: Req.Request.t()
@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: %{...}}}
@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}
@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 givenresourceVersion
of the resource list. Otherwise starts streaming from HEAD.:stream_to
- If set to apid
, streams events to the given pid. If set to{pid, ref}
, the messages are in the form{ref, event}
.
@spec watch_single( Req.Request.t(), namespace :: namespace(), name :: String.t(), opts :: keyword() ) :: watch_response()
Watch events of a single resources name
in 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 apid
, streams events to the given pid. If set to{pid, ref}
, the messages are in the form{ref, event}