View Source K8s.Conn (k8s v2.6.0)

Handles authentication and connection configuration details for a Kubernetes cluster. The %K8s.Conn{} struct is required in order to run any object against the cluster. Use any of the functions defined in this module to create a %K8s.Conn{} struct and pass it to the functions of K8s.Client.

Example

{:ok, conn} = K8s.Conn.from_file("~/.kube/config")

{:ok, default_ns} =
  K8s.Client.get("v1", "Namespace", name: "default")
  |> K8s.Client.put_conn(conn)
  |> K8s.Client.run()

Alternatively, you can pass conn to K8s.Client.run().

{:ok, conn} = K8s.Conn.from_file("~/.kube/config")
op = K8s.Client.get("v1", "Namespace", name: "default")
{:ok, default_ns} = K8s.Client.run(op, conn)

Scenarios

If your cluster connection is defined in a file, e.g. ~/.kube/config, use K8s.Conn.from_file/2.
If running in a pod inside the cluster you're connecting to, use K8s.Conn.from_service_account/2
If an environment variable points to a config file, use K8s.Conn.from_env/2

Summary

Types

t()

cluster_name - The cluster name if read from a kubeconfig file
user_name - The user name if read from a kubeconfig file
namespace - The namespace if read from a service account token
url - The Kubernetes API URL

Functions

from_env(env_variable, opts)

Generates the configuration from a file whose location is defined by the given env_var. Defaults to KUBECONFIG.

from_file(config_file, opts \\ [])

Reads configuration details from a kubernetes config file.

from_service_account(service_account_path, opts)

Generates the configuration from a Kubernetes service account.

Types

t()

@type t() :: %K8s.Conn{
  auth: auth_t(),
  ca_cert: String.t() | nil,
  cacertfile: String.t(),
  cluster_name: String.t() | nil,
  discovery_driver: module(),
  discovery_opts: Keyword.t(),
  http_provider: module(),
  insecure_skip_tls_verify: boolean(),
  middleware: K8s.Middleware.Stack.t(),
  namespace: String.t() | nil,
  url: String.t(),
  user_name: String.t() | nil
}

cluster_name - The cluster name if read from a kubeconfig file
user_name - The user name if read from a kubeconfig file
namespace - The namespace if read from a service account token
url - The Kubernetes API URL

Functions

from_env(env_variable, opts)

@spec from_env(env_variable :: binary(), opts :: keyword()) ::
  {:ok, t()} | {:error, :enoent | K8s.Conn.Error.t()}

Generates the configuration from a file whose location is defined by the given env_var. Defaults to KUBECONFIG.

Options

See from_file/2.

Examples

if KUBECONFIG is set:

{:ok, conn} = K8s.Conn.from_env()

Pass the env variable name:

{:ok, conn} = K8s.Conn.from_env("TEST_KUBECONFIG")

Pass the env variable name and options:

{:ok, conn} = K8s.Conn.from_env("TEST_KUBECONFIG", insecure_skip_tls_verify: true)

from_file(config_file, opts \\ [])

@spec from_file(
  binary(),
  keyword()
) :: {:ok, t()} | {:error, :enoent | K8s.Conn.Error.t()}

Reads configuration details from a kubernetes config file.

If you run your code on your machine, you most likely have a config file at ~/.kube/config. If you created a local cluster using kind, k3d or similar, a context entry is either added to that config file or you saved it to a specific location upon cluster creation. Either way, this function reads the config from any of these files.

Example

Using the currently selected context:

{:ok, conn} = K8s.Conn.from_file("~/.kube/config")

Pass the context and allow insecure TLS verification :

{:ok, conn} =
  K8s.Conn.from_file("~/.kube/config",
    context: "my-kind-cluster",
    insecure_skip_tls_verify: true
  )

Options

:context - sets an alternate context - defaults to current-context.
:cluster - set or override the cluster read from the context
:user- set or override the user read from the context
:discovery_driver - module name to use for discovery
:discovery_opts - options for discovery module
:insecure_skip_tls_verify - Skip TLS verification

from_service_account(service_account_path, opts)

@spec from_service_account(service_account_path :: String.t(), opts :: Keyword.t()) ::
  {:ok, t()} | {:error, :enoent | K8s.Conn.Error.t()}

Generates the configuration from a Kubernetes service account.

This is used when running in a Pod inside the cluster you're accessing. Make sure to setup RBAC for the service account running the Pod.

Documentation: kubernetes.io :: Accessing the API from a Pod

Options

:insecure_skip_tls_verify - Skip TLS verification

Example

Using the currently selected context:

{:ok, conn} = K8s.Conn.from_service_account()

You can set a specific path to the service account token file:

{:ok, conn} =
  K8s.Conn.from_service_account("/path/to/token",
    insecure_skip_tls_verify: true
  )

Allow insecure TLS verification:

{:ok, conn} =
  K8s.Conn.from_service_account(
    insecure_skip_tls_verify: true
  )

{:ok, conn} =
  K8s.Conn.from_service_account(
    "/path/to/token",
    insecure_skip_tls_verify: true
  )