View Source K8s.Client (k8s v2.4.2)

Kubernetes API Client.

Functions return K8s.Operations that represent kubernetes operations.

To run operations pass them to: run/2, or run/3

When specifying kinds the format should either be in the literal kubernetes kind name (eg "ServiceAccount") or the downcased version seen in kubectl (eg "serviceaccount"). A string or atom may be used.

Examples

"Deployment", "deployment", :Deployment, :deployment
"ServiceAccount", "serviceaccount", :ServiceAccount, :serviceaccount
"HorizontalPodAutoscaler", "horizontalpodautoscaler", :HorizontalPodAutoscaler, :horizontalpodautoscaler

http_opts to K8s.Client.Runner modules are K8s.Client.HTTPProvider HTTP options.

Summary

Functions

Returns a PATCH operation to server-side-apply the given resource.

Returns a PATCH operation to server-side-apply the given subresource given a resource's details and a subresource map.

Returns a CONNECT operation for a pods/exec resource by version, kind/resource type, name, and optionally namespace.

Returns a POST K8s.Operation to create the given resource.

Returns a POST K8s.Operation to create the given subresource.

Returns a POST K8s.Operation to create the given subresource.

Returns a DELETE operation for a resource by manifest. May be a partial manifest as long as it contains

Returns a DELETE operation for a resource by version, kind, name, and optionally namespace.

Returns a DELETE collection operation for all instances of a cluster scoped resource kind.

Returns a DELETE collection operation for all instances of a resource kind in a specific namespace.

Returns a GET operation for a resource given a Kubernetes manifest. May be a partial manifest as long as it contains

Returns a GET operation for a resource by version, kind/resource type, name, and optionally namespace.

Returns a GET operation to list all resources by version, kind, and namespace.

Returns a PATCH operation to patch the given resource.

Returns a PATCH operation to patch the given subresource given a resource map and a subresource map.

Returns a PATCH operation to patch the given subresource given a resource's details and a subresource map.

Returns a PUT operation to replace/update the given resource.

Returns a PUT operation to replace/update the given subresource given a resource map and a subresource map.

Returns a PUT operation to replace/update the given subresource given a resource's details and a subresource map.

Returns a GET operation to list all resources by version, kind, and namespace.

Types

@type path_param() :: {:name, String.t()} | {:namespace, binary() | :all}
@type path_params() :: [path_param()]

Functions

Link to this function

apply(resource, mgmt_params \\ [])

View Source
@spec apply(
  map(),
  keyword()
) :: K8s.Operation.t()

Returns a PATCH operation to server-side-apply the given resource.

K8s Docs:

Examples

Apply a deployment with management parameteres

iex> deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> K8s.Client.apply(deployment, field_manager: "my-operator", force: true)
%K8s.Operation{
  method: :patch,
  verb: :patch,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"],
  data: K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml"),
  query_params: [fieldManager: "my-operator", force: true],
  header_params: ["Content-Type": "application/apply-patch+yaml"],
}
Link to this function

apply(api_version, kind, path_params, subresource, mgmt_params \\ [])

View Source

Returns a PATCH operation to server-side-apply the given subresource given a resource's details and a subresource map.

Examples

Apply a status to a pod:

iex> pod_with_status_subresource = K8s.Resource.from_file!("test/support/manifests/nginx-pod.yaml") |> Map.put("status", %{"message" => "some message"})
...> K8s.Client.apply("v1", "pods/status", [namespace: "default", name: "nginx"], pod_with_status_subresource, field_manager: "my-operator", force: true)
%K8s.Operation{
  method: :patch,
  verb: :patch,
  api_version: "v1",
  name: "pods/status",
  path_params: [namespace: "default", name: "nginx"],
  data: K8s.Resource.from_file!("test/support/manifests/nginx-pod.yaml") |> Map.put("status", %{"message" => "some message"}),
  query_params: [fieldManager: "my-operator", force: true],
  header_params: ["Content-Type": "application/apply-patch+yaml"]
}

alias of K8s.Client.Runner.Async.run/3

Link to this function

async(conn, operations, http_opts)

View Source

alias of K8s.Client.Runner.Async.run/3

Link to this function

connect(api_version, kind, list, opts \\ [])

View Source
@spec connect(
  binary(),
  binary() | atom(),
  [namespace: binary(), name: binary()],
  keyword()
) ::
  K8s.Operation.t()

Returns a CONNECT operation for a pods/exec resource by version, kind/resource type, name, and optionally namespace.

K8s Docs:

Examples

connect to the nginx deployment in the test namespace:

iex> K8s.Client.connect("apps/v1", "pods/exec", [namespace: "test", name: "nginx"], command: "ls")
%K8s.Operation{
  method: :post,
  verb: :connect,
  api_version: "apps/v1",
  name: "pods/exec",
  path_params: [namespace: "test", name: "nginx"],
  query_params: [{:stdin, true}, {:stdout, true}, {:stderr, true}, {:tty, false}, {:command, "ls"}]
}
@spec create(map()) :: K8s.Operation.t()

Returns a POST K8s.Operation to create the given resource.

Examples

iex>  deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> K8s.Client.create(deployment)
%K8s.Operation{
  method: :post,
  path_params: [namespace: "test", name: "nginx"],
  verb: :create,
  api_version: "apps/v1",
  name: "Deployment",
  data: K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
}
Link to this function

create(map, subresource)

View Source
@spec create(map(), map()) :: K8s.Operation.t()

Returns a POST K8s.Operation to create the given subresource.

Used for creating subresources like Scale or Eviction.

Examples

Evicting a pod

iex> pod = K8s.Resource.from_file!("test/support/manifests/nginx-pod.yaml")
...> eviction = K8s.Resource.from_file!("test/support/manifests/eviction-policy.yaml")
...> K8s.Client.create(pod, eviction)
%K8s.Operation{
  api_version: "v1",
  data: K8s.Resource.from_file!("test/support/manifests/eviction-policy.yaml"),
  method: :post, name: {"Pod", "Eviction"},
  path_params: [namespace: "default", name: "nginx"],
  verb: :create
}
Link to this function

create(api_version, kind, path_params, subresource)

View Source
@spec create(binary(), K8s.Operation.name_t(), Keyword.t(), map()) ::
  K8s.Operation.t()

Returns a POST K8s.Operation to create the given subresource.

Used for creating subresources like Scale or Eviction.

Examples

Evicting a pod

iex> eviction = K8s.Resource.from_file!("test/support/manifests/eviction-policy.yaml")
...>  K8s.Client.create("v1", "pods/eviction", [namespace: "default", name: "nginx"], eviction)
%K8s.Operation{
  api_version: "v1",
  method: :post,
  name: "pods/eviction",
  path_params: [namespace: "default", name: "nginx"],
  verb: :create,
  data: K8s.Resource.from_file!("test/support/manifests/eviction-policy.yaml")
}
@spec delete(map()) :: K8s.Operation.t()

Returns a DELETE operation for a resource by manifest. May be a partial manifest as long as it contains:

  • apiVersion
  • kind
  • metadata.name
  • metadata.namespace (if applicable)

K8s Docs:

Delete will delete a resource. Depending on the specific resource, child objects may or may not be garbage collected by the server. See notes on specific resource objects for details.

Examples

iex> deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> K8s.Client.delete(deployment)
%K8s.Operation{
  method: :delete,
  verb: :delete,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"]
}
Link to this function

delete(api_version, kind, path_params)

View Source
@spec delete(binary(), K8s.Operation.name_t(), path_params() | nil) ::
  K8s.Operation.t()

Returns a DELETE operation for a resource by version, kind, name, and optionally namespace.

Examples

iex> K8s.Client.delete("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Operation{
  method: :delete,
  verb: :delete,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"]
}
Link to this function

delete_all(api_version, kind)

View Source
@spec delete_all(binary(), binary() | atom()) :: K8s.Operation.t()

Returns a DELETE collection operation for all instances of a cluster scoped resource kind.

Examples

iex> K8s.Client.delete_all("extensions/v1beta1", "PodSecurityPolicy")
%K8s.Operation{
  method: :delete,
  verb: :deletecollection,
  api_version: "extensions/v1beta1",
  name: "PodSecurityPolicy",
  path_params: []
}

iex> K8s.Client.delete_all("storage.k8s.io/v1", "StorageClass")
%K8s.Operation{
  method: :delete,
  verb: :deletecollection,
  api_version: "storage.k8s.io/v1",
  name: "StorageClass",
  path_params: []
}
Link to this function

delete_all(api_version, kind, list)

View Source
@spec delete_all(binary(), binary() | atom(), [{:namespace, binary()}]) ::
  K8s.Operation.t()

Returns a DELETE collection operation for all instances of a resource kind in a specific namespace.

Examples

iex> K8s.Client.delete_all("apps/v1beta1", "ControllerRevision", namespace: "default")
%K8s.Operation{
  method: :delete,
  verb: :deletecollection,
  api_version: "apps/v1beta1",
  name: "ControllerRevision",
  path_params: [namespace: "default"]
}

iex> K8s.Client.delete_all("apps/v1", "Deployment", namespace: "staging")
%K8s.Operation{
  method: :delete,
  verb: :deletecollection,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "staging"]
}
@spec get(map()) :: K8s.Operation.t()

Returns a GET operation for a resource given a Kubernetes manifest. May be a partial manifest as long as it contains:

  • apiVersion
  • kind
  • metadata.name
  • metadata.namespace (if applicable)

K8s Docs:

Get will retrieve a specific resource object by name.

Examples

Getting a pod

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.get(pod)
%K8s.Operation{
  method: :get,
  verb: :get,
  api_version: "v1",
  name: "Pod",
  path_params: [namespace: "test", name: "nginx-pod"],
}
Link to this function

get(api_version, kind, path_params \\ [])

View Source
@spec get(binary(), K8s.Operation.name_t(), path_params() | nil) :: K8s.Operation.t()

Returns a GET operation for a resource by version, kind/resource type, name, and optionally namespace.

K8s Docs:

Get will retrieve a specific resource object by name.

Examples

Get the nginx deployment in the default namespace:

iex> K8s.Client.get("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Operation{
  method: :get,
  verb: :get,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"]
}

Get the nginx deployment in the default namespace by passing the kind as atom.

iex> K8s.Client.get("apps/v1", :deployment, namespace: "test", name: "nginx")
%K8s.Operation{
  method: :get,
  verb: :get,
  api_version: "apps/v1",
  name: :deployment,
  path_params: [namespace: "test", name: "nginx"]}

Get the nginx deployment's status:

iex> K8s.Client.get("apps/v1", "deployments/status", namespace: "test", name: "nginx")
%K8s.Operation{
  method: :get,
  verb: :get,
  api_version: "apps/v1",
  name: "deployments/status",
  path_params: [namespace: "test", name: "nginx"]}

Get the nginx deployment's scale:

iex> K8s.Client.get("v1", "deployments/scale", namespace: "test", name: "nginx")
%K8s.Operation{
  method: :get,
  verb: :get,
  api_version: "v1",
  name: "deployments/scale",
  path_params: [namespace: "test", name: "nginx"]}
Link to this function

list(api_version, kind, path_params \\ [])

View Source
@spec list(binary(), K8s.Operation.name_t(), path_params() | nil) :: K8s.Operation.t()

Returns a GET operation to list all resources by version, kind, and namespace.

Given the namespace :all as an atom, will perform a list across all namespaces.

K8s Docs:

List will retrieve all resource objects of a specific type within a namespace, and the results can be restricted to resources matching a selector query. List All Namespaces: Like List but retrieves resources across all namespaces.

Examples

iex> K8s.Client.list("v1", "Pod", namespace: "default")
%K8s.Operation{
  method: :get,
  verb: :list,
  api_version: "v1",
  name: "Pod",
  path_params: [namespace: "default"]
}

iex> K8s.Client.list("apps/v1", "Deployment", namespace: :all)
%K8s.Operation{
  method: :get,
  verb: :list_all_namespaces,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: []
}
Link to this function

parallel(conn, operations, http_opts)

View Source

alias of K8s.Client.Runner.Async.run/3

@spec patch(map()) :: K8s.Operation.t()

Returns a PATCH operation to patch the given resource.

K8s Docs:

Patch will apply a change to a specific field. How the change is merged is defined per field. Lists may either be replaced or merged. Merging lists will not preserve ordering. Patches will never cause optimistic locking failures, and the last write will win. Patches are recommended when the full state is not read before an update, or when failing on optimistic locking is undesirable. When patching complex types, arrays and maps, how the patch is applied is defined on a per-field basis and may either replace the field's current value, or merge the contents into the current value.

Examples

iex>  deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> K8s.Client.patch(deployment)
%K8s.Operation{
  method: :patch,
  verb: :patch,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"],
  data: K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml"),
  header_params: ["Content-Type": "application/merge-patch+json"]
}
Link to this function

patch(resource, patch_type)

View Source
@spec patch(map(), patch_type_or_resource :: K8s.Operation.patch_type() | map()) ::
  K8s.Operation.t()
Link to this function

patch(map, subresource, patch_type)

View Source
@spec patch(map(), map(), patch_type :: K8s.Operation.patch_type()) ::
  K8s.Operation.t()

Returns a PATCH operation to patch the given subresource given a resource map and a subresource map.

Link to this function

patch(api_version, kind, path_params, subresource, patch_type \\ :merge)

View Source
@spec patch(
  binary(),
  K8s.Operation.name_t(),
  Keyword.t(),
  map(),
  patch_type :: K8s.Operation.patch_type()
) :: K8s.Operation.t()

Returns a PATCH operation to patch the given subresource given a resource's details and a subresource map.

Link to this function

put_conn(operation, conn)

View Source

See K8s.Operation.put_conn/2.

alias of K8s.Client.Runner.Base.run/1

alias of K8s.Client.Runner.Base.run/2

Link to this function

run(conn, operation, http_opts)

View Source

alias of K8s.Client.Runner.Base.run/3

alias of K8s.Client.Runner.Stream.run/1

alias of K8s.Client.Runner.Stream.run/2

Link to this function

stream(conn, operation, http_opts)

View Source

alias of K8s.Client.Runner.Stream.run/3

Link to this function

stream_to(operation, stream_to)

View Source

alias of K8s.Client.Runner.StreamTo.run/2

Link to this function

stream_to(conn, operation, stream_to)

View Source

alias of K8s.Client.Runner.StreamTo.run/3

Link to this function

stream_to(conn, operation, http_opts, stream_to)

View Source

alias of K8s.Client.Runner.StreamTo.run/4

@spec update(map()) :: K8s.Operation.t()

Returns a PUT operation to replace/update the given resource.

K8s Docs:

Replacing a resource object will update the resource by replacing the existing spec with the provided one. For read-then-write operations this is safe because an optimistic lock failure will occur if the resource was modified between the read and write. Note: The ResourceStatus will be ignored by the system and will not be updated. To update the status, one must invoke the specific status update operation. Note: Replacing a resource object may not result immediately in changes being propagated to downstream objects. For instance replacing a ConfigMap or Secret resource will not result in all Pods seeing the changes unless the Pods are restarted out of band.

Examples

iex>  deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> K8s.Client.update(deployment)
%K8s.Operation{
  method: :put,
  verb: :update,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: [namespace: "test", name: "nginx"],
  data: K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
}
Link to this function

update(map, subresource)

View Source
@spec update(map(), map()) :: K8s.Operation.t()

Returns a PUT operation to replace/update the given subresource given a resource map and a subresource map.

Used for updating subresources like Scale or Status.

Examples

Scaling a deployment:

iex> deployment = K8s.Resource.from_file!("test/support/manifests/nginx-deployment.yaml")
...> scale = K8s.Resource.from_file!("test/support/manifests/scale-replicas.yaml")
...> K8s.Client.update(deployment, scale)
%K8s.Operation{
  api_version: "apps/v1",
  method: :put,
  path_params: [namespace: "test", name: "nginx"],
  verb: :update,
  data: K8s.Resource.from_file!("test/support/manifests/scale-replicas.yaml"),
  name: {"Deployment", "Scale"}
}
Link to this function

update(api_version, kind, path_params, subresource)

View Source
@spec update(binary(), K8s.Operation.name_t(), Keyword.t(), map()) ::
  K8s.Operation.t()

Returns a PUT operation to replace/update the given subresource given a resource's details and a subresource map.

Used for updating subresources like Scale or Status.

Examples

Scaling a deployment

iex> scale = K8s.Resource.from_file!("test/support/manifests/scale-replicas.yaml")
...>  K8s.Client.update("apps/v1", "deployments/scale", [namespace: "default", name: "nginx"], scale)
%K8s.Operation{
  api_version: "apps/v1",
  data: K8s.Resource.from_file!("test/support/manifests/scale-replicas.yaml"),
  method: :put,
  name: "deployments/scale",
  path_params: [namespace: "default", name: "nginx"],
  verb: :update
}
Link to this function

wait_until(operation, wait_opts)

View Source

alias of K8s.Client.Runner.Wait.run/2

Link to this function

wait_until(conn, operation, wait_opts)

View Source

alias of K8s.Client.Runner.Wait.run/3

Link to this function

watch(api_version, kind, path_params \\ [])

View Source
@spec watch(binary(), K8s.Operation.name_t(), path_params() | nil) ::
  K8s.Operation.t()

Returns a GET operation to list all resources by version, kind, and namespace.

Given the namespace :all as an atom, will perform a list across all namespaces.

K8s Docs:

List will retrieve all resource objects of a specific type within a namespace, and the results can be restricted to resources matching a selector query. List All Namespaces: Like List but retrieves resources across all namespaces.

Examples

iex> K8s.Client.list("v1", "Pod", namespace: "default")
%K8s.Operation{
  method: :get,
  verb: :list,
  api_version: "v1",
  name: "Pod",
  path_params: [namespace: "default"]
}

iex> K8s.Client.list("apps/v1", "Deployment", namespace: :all)
%K8s.Operation{
  method: :get,
  verb: :list_all_namespaces,
  api_version: "apps/v1",
  name: "Deployment",
  path_params: []
}