k8s v0.3.2 K8s.Client
An experimental k8s client.
Functions return K8s.Operation
s that represent kubernetes operations.
To run operations pass them to: run/2
, run/3
, or run/4
.
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
opts
to K8s.Client.Runner
modules are HTTPoison HTTP option overrides.
Link to this section Summary
Functions
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 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.
Link to this section Types
option()
options()
options() :: [option()]
options() :: [option()]
Link to this section Functions
async(operations, cluster_name)
alias of K8s.Client.Runner.Async.run/3
async(operations, cluster_name, opts)
alias of K8s.Client.Runner.Async.run/3
create(resource)
create(map()) :: K8s.Operation.t()
create(map()) :: K8s.Operation.t()
Returns a POST
K8s.Operation
to create the given resource.
Examples
iex> deployment = %{
...> "apiVersion" => "apps/v1",
...> "kind" => "Deployment",
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> },
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 2,
...> "selector" => %{
...> "matchLabels" => %{
...> "app" => "nginx"
...> }
...> },
...> "template" => %{
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> }
...> },
...> "spec" => %{
...> "containers" => %{
...> "image" => "nginx",
...> "name" => "nginx"
...> }
...> }
...> }
...> }
...> }
...> K8s.Client.create(deployment)
%K8s.Operation{
method: :post,
path_params: [namespace: "test", name: "nginx"],
verb: :create,
api_version: "apps/v1",
name: "Deployment",
data: %{
"apiVersion" => "apps/v1",
"kind" => "Deployment",
"metadata" => %{
"labels" => %{
"app" => "nginx"
},
"name" => "nginx",
"namespace" => "test"
},
"spec" => %{
"replicas" => 2,
"selector" => %{
"matchLabels" => %{
"app" => "nginx"
}
},
"template" => %{
"metadata" => %{
"labels" => %{
"app" => "nginx"
}
},
"spec" => %{
"containers" => %{
"image" => "nginx",
"name" => "nginx"
}
}
}
}
}
}
create(map, subresource)
create(map(), map()) :: K8s.Operation.t()
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
Eviction a pod
iex> pod = %{
...> "apiVersion" => "v1",
...> "kind" => "Pod",
...> "metadata" => %{
...> "name" => "nginx",
...> "namespace" => "default"
...> }
...> }
...> eviction = %{
...> "apiVersion" => "policy/v1beta1",
...> "kind" => "Eviction",
...> "metadata" => %{
...> "name" => "nginx",
...> "namespace" => "default"
...> }
...> }
...> K8s.Client.create(pod, eviction)
%K8s.Operation{api_version: "v1", data: %{"apiVersion" => "policy/v1beta1", "kind" => "Eviction", "metadata" => %{"name" => "nginx", "namespace" => "default"}}, method: :post, name: {"Pod", "Eviction"}, path_params: [namespace: "default", name: "nginx"], verb: :create}
create(api_version, kind, path_params, subresource)
Returns a POST
K8s.Operation
to create the given subresource.
Used for creating subresources like Scale
or Eviction
.
Examples
Eviction a pod
iex> eviction = %{
...> "apiVersion" => "policy/v1beta1",
...> "kind" => "Eviction",
...> "metadata" => %{
...> "name" => "nginx",
...> "namespace" => "default"
...> }
...> }
...> K8s.Client.create("v1", "pods/eviction", [namespace: "default", name: "nginx"], eviction)
%K8s.Operation{api_version: "v1", data: %{"apiVersion" => "policy/v1beta1", "kind" => "Eviction", "metadata" => %{"name" => "nginx", "namespace" => "default"}}, method: :post, name: "pods/eviction", path_params: [namespace: "default", name: "nginx"], verb: :create}
delete(resource)
delete(map()) :: K8s.Operation.t()
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)
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 = %{
...> "apiVersion" => "apps/v1",
...> "kind" => "Deployment",
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> },
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 2,
...> "selector" => %{
...> "matchLabels" => %{
...> "app" => "nginx"
...> }
...> },
...> "template" => %{
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> }
...> },
...> "spec" => %{
...> "containers" => %{
...> "image" => "nginx",
...> "name" => "nginx"
...> }
...> }
...> }
...> }
...> }
...> K8s.Client.delete(deployment)
%K8s.Operation{
method: :delete,
verb: :delete,
api_version: "apps/v1",
name: "Deployment",
path_params: [namespace: "test", name: "nginx"]
}
delete(api_version, kind, opts)
delete(binary(), binary() | atom(), options() | nil) :: K8s.Operation.t()
delete(binary(), binary() | atom(), options() | 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"]
}
delete_all(api_version, kind)
delete_all(binary(), binary() | atom()) :: K8s.Operation.t()
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: []
}
delete_all(api_version, kind, list)
delete_all(binary(), binary() | atom(), [{:namespace, binary()}]) ::
K8s.Operation.t()
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"]
}
get(resource)
get(map()) :: K8s.Operation.t()
get(map()) :: K8s.Operation.t()
Returns a GET
operation for a resource given a manifest. May be a partial manifest as long as it contains:
- apiVersion
- kind
- metadata.name
- metadata.namespace (if applicable)
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"],
}
get(api_version, kind, opts \\ [])
get(binary(), binary() | atom(), options() | nil) :: K8s.Operation.t()
get(binary(), binary() | atom(), options() | nil) :: K8s.Operation.t()
Returns a GET
operation for a resource by version, kind/resource type, name, and optionally namespace.
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:
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"]}
list(api_version, kind, opts \\ [])
list(binary(), binary() | atom(), options() | nil) :: K8s.Operation.t()
list(binary(), binary() | atom(), options() | 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.
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: []
}
parallel(operations, cluster_name, opts)
alias of K8s.Client.Runner.Async.run/3
patch(resource)
patch(map()) :: K8s.Operation.t()
patch(map()) :: K8s.Operation.t()
Returns a PATCH
operation to patch the given resource.
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 = %{
...> "apiVersion" => "apps/v1",
...> "kind" => "Deployment",
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> },
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 2,
...> "selector" => %{
...> "matchLabels" => %{
...> "app" => "nginx"
...> }
...> },
...> "template" => %{
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> }
...> },
...> "spec" => %{
...> "containers" => %{
...> "image" => "nginx",
...> "name" => "nginx"
...> }
...> }
...> }
...> }
...> }
...> K8s.Client.patch(deployment)
%K8s.Operation{
method: :patch,
verb: :patch,
api_version: "apps/v1",
name: "Deployment",
path_params: [namespace: "test", name: "nginx"],
data: %{
"apiVersion" => "apps/v1",
"kind" => "Deployment",
"metadata" => %{
"labels" => %{
"app" => "nginx"
},
"name" => "nginx",
"namespace" => "test"
},
"spec" => %{
"replicas" => 2,
"selector" => %{
"matchLabels" => %{
"app" => "nginx"
}
},
"template" => %{
"metadata" => %{
"labels" => %{
"app" => "nginx"
}
},
"spec" => %{
"containers" => %{
"image" => "nginx",
"name" => "nginx"
}
}
}
}
}
}
patch(map, subresource)
patch(map(), map()) :: K8s.Operation.t()
patch(map(), map()) :: K8s.Operation.t()
Returns a PATCH
operation to patch the given subresource given a resource map and a subresource map.
patch(api_version, kind, path_params, subresource)
Returns a PATCH
operation to patch the given subresource given a resource's details and a subresource map.
run(operation, cluster_name)
alias of K8s.Client.Runner.Base.run/2
run(operation, cluster_name, opts)
alias of K8s.Client.Runner.Base.run/3
run(operation, cluster_name, resource, opts)
alias of K8s.Client.Runner.Base.run/4
stream(operation, cluster_name)
alias of K8s.Client.Runner.Stream.run/2
stream(operation, cluster_name, opts)
alias of K8s.Client.Runner.Stream.run/3
update(resource)
update(map()) :: K8s.Operation.t()
update(map()) :: K8s.Operation.t()
Returns a PUT
operation to replace/update the given resource.
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 = %{
...> "apiVersion" => "apps/v1",
...> "kind" => "Deployment",
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> },
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 2,
...> "selector" => %{
...> "matchLabels" => %{
...> "app" => "nginx"
...> }
...> },
...> "template" => %{
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> }
...> },
...> "spec" => %{
...> "containers" => %{
...> "image" => "nginx",
...> "name" => "nginx"
...> }
...> }
...> }
...> }
...> }
...> K8s.Client.update(deployment)
%K8s.Operation{
method: :put,
verb: :update,
api_version: "apps/v1",
name: "Deployment",
path_params: [namespace: "test", name: "nginx"],
data: %{
"apiVersion" => "apps/v1",
"kind" => "Deployment",
"metadata" => %{
"labels" => %{
"app" => "nginx"
},
"name" => "nginx",
"namespace" => "test"
},
"spec" => %{
"replicas" => 2,
"selector" => %{
"matchLabels" => %{
"app" => "nginx"
}
},
"template" => %{
"metadata" => %{
"labels" => %{
"app" => "nginx"
}
},
"spec" => %{
"containers" => %{
"image" => "nginx",
"name" => "nginx"
}
}
}
}
}
}
update(map, subresource)
update(map(), map()) :: K8s.Operation.t()
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 = %{
...> "apiVersion" => "apps/v1",
...> "kind" => "Deployment",
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> },
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 2,
...> "selector" => %{
...> "matchLabels" => %{
...> "app" => "nginx"
...> }
...> },
...> "template" => %{
...> "metadata" => %{
...> "labels" => %{
...> "app" => "nginx"
...> }
...> },
...> "spec" => %{
...> "containers" => %{
...> "image" => "nginx",
...> "name" => "nginx"
...> }
...> }
...> }
...> }
...> }
...> scale = %{
...> "kind" => "Scale",
...> "apiVersion" => "apps/v1beta1",
...> "metadata" => %{
...> "name" => "nginx",
...> "namespace" => "test"
...> },
...> "spec" => %{
...> "replicas" => 3
...> }
...> }
...> K8s.Client.update(deployment, scale)
%K8s.Operation{api_version: "apps/v1", method: :put, path_params: [namespace: "test", name: "nginx"], verb: :update, data: %{"apiVersion" => "apps/v1beta1", "kind" => "Scale", "metadata" => %{"name" => "nginx", "namespace" => "test"}, "spec" => %{"replicas" => 3}}, name: {"Deployment", "Scale"}}
update(api_version, kind, path_params, subresource)
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 = %{
...> "kind" => "Scale",
...> "apiVersion" => "apps/v1beta1",
...> "metadata" => %{
...> "name" => "nginx",
...> "namespace" => "default"
...> },
...> "spec" => %{
...> "replicas" => 3
...> }
...> }
...> K8s.Client.update("apps/v1", "deployments/scale", [namespace: "default", name: "nginx"], scale)
%K8s.Operation{api_version: "apps/v1", data: %{"apiVersion" => "apps/v1beta1", "kind" => "Scale", "metadata" => %{"name" => "nginx", "namespace" => "default"}, "spec" => %{"replicas" => 3}}, method: :put, name: "deployments/scale", path_params: [namespace: "default", name: "nginx"], verb: :update}
wait_until(operation, cluster_name, opts)
alias of K8s.Client.Runner.Wait.run/3
watch(operation, cluster_name, opts)
alias of K8s.Client.Runner.Watch.run/3
watch(operation, cluster_name, rv, opts)
alias of K8s.Client.Runner.Watch.run/4