k8s_client

v0.1.3

k8s_client v0.1.3 K8s.Client

An experimental k8s client.

Functions return K8s.Client.Operations 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

Link to this section Summary

Types

http_method()
operation_or_error()
option()
options()
result()

Functions

async(operations, conf)

Async run multiple operations. Operations will be returned in same order given. Operations will not cease in event of failure

create(resource)

Returns a POST operation to create the given resource

delete(resource)

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

delete(api_version, kind, opts)

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

delete_all(api_version, kind)

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

delete_all(api_version, kind, list)

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

get(resource)

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

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

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

get_log(resource)

Returns a GET operation for a pod's logs given a manifest. May be a partial manifest as long as it contains

get_log(api_version, kind, opts)

Returns a GET operation for a pod's logs given a namespace and a pod name

get_status(resource)

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

get_status(api_version, kind, opts \\ [])

Returns a GET operation for a resource's status by version, kind, name, and optionally namespace

list(api_version, kind, list)

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

patch(resource)

Returns a PATCH operation to patch the given resource

patch_status(resource)

Returns a PATCH operation for a resource's status given a manifest. May be a partial manifest as long as it contains

patch_status(api_version, kind, opts \\ [])

Returns a PATCH operation for a resource's status by version, kind, name, and optionally namespace

post(resource)

Alias of create/1

put(resource)

Alias of replace/1

put_status(resource)

Returns a PUT operation for a resource's status given a manifest. May be a partial manifest as long as it contains

put_status(api_version, kind, opts \\ [])

Returns a PUT operation for a resource's status by version, kind, name, and optionally namespace

replace(resource)

Returns a PUT operation to replace/update the given resource

run(request, config)

Runs a K8s.Client.Operation

run(request, config, opts)

See run/2

run(request, config, body, opts \\ [])

See run/2

update(resource)

Alias of replace/1

Link to this section Types

Link to this type

http_method() 
http_method() :: :get | :put | :patch | :post | :head | :options | :delete

Link to this type

operation_or_error() 
operation_or_error() :: K8s.Client.Operation.t() | {:error, binary()}

Link to this type

option() 
option() :: {:name, String.t()} | {:namespace, binary() | :all}

Link to this type

options() 
options() :: [option()]

Link to this type

result() 
result() :: :ok | {:ok, map()} | {:error, binary()}

Link to this section Functions

Link to this function

async(operations, conf) 
async([K8s.Client.Operation.t()], K8s.Conf.t()) :: [
  ok: struct(),
  error: struct()
]

Async run multiple operations. Operations will be returned in same order given. Operations will not cease in event of failure.

Example

Get a list of pods, then map each one to an individual GET operation:

  # Get a config reference
  conf = K8s.Conf.from_file "~/.kube/config"

  # Get the pods
  operation = K8s.Client.list("v1", "Pod", namespace: :all)
  {:ok, %{"items" => pods}} = K8s.Client.run(operation, conf)

  # Map each one to an individual `GET` operation.
  operations = Enum.map(pods, fn(%{"metadata" => %{"name" => name, "namespace" => ns}}) ->
     K8s.Client.get("v1", "Pod", namespace: ns, name: name)
  end)

  # Get the results asynchronously
  results = K8s.Client.async(operations, conf)
Link to this function

create(resource) 
create(map()) :: operation_or_error()

Returns a POST 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.Client.Operation{
  method: :post,
  path: "/apis/apps/v1/namespaces/test/deployments",
  resource: %{
    "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"
          }
        }
      }
    }
  }
}
Link to this function

delete(resource) 
delete(map()) :: operation_or_error()

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 = %{
...>    "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.Client.Operation{
  method: :delete,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx"
}
Link to this function

delete(api_version, kind, opts) 
delete(binary(), binary(), options() | nil) :: operation_or_error()

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.Client.Operation{
  method: :delete,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx"
}
Link to this function

delete_all(api_version, kind) 
delete_all(binary(), binary()) :: operation_or_error()

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

Examples 

iex> K8s.Client.delete_all("extensions/v1beta1", "PodSecurityPolicy")
%K8s.Client.Operation{
  method: :delete,
  path: "/apis/extensions/v1beta1/podsecuritypolicies"
}

iex> K8s.Client.delete_all("storage.k8s.io/v1", "StorageClass")
%K8s.Client.Operation{
  method: :delete,
  path: "/apis/storage.k8s.io/v1/storageclasses"
}
Link to this function

delete_all(api_version, kind, list) 
delete_all(binary(), binary(), [{:namespace, binary()}]) :: operation_or_error()

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

Examples 

iex> Client.delete_all("apps/v1beta1", "ControllerRevision", namespace: "default")
%K8s.Client.Operation{
  method: :delete,
  path: "/apis/apps/v1beta1/namespaces/default/controllerrevisions"
}

iex> Client.delete_all("apps/v1", "Deployment", namespace: "staging")
%K8s.Client.Operation{
  method: :delete,
  path: "/apis/apps/v1/namespaces/staging/deployments"
}
Link to this function

get(resource) 
get(map()) :: operation_or_error()

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)

K8s Docs:

Get will retrieve a specific resource object by name.

Examples 

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.get(pod)
%K8s.Client.Operation{
  method: :get,
  path: "/api/v1/namespaces/test/pods/nginx-pod"
}
Link to this function

get(api_version, kind, opts \\ []) 
get(binary(), binary(), options() | nil) :: operation_or_error()

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

K8s Docs:

Get will retrieve a specific resource object by name.

Examples 

iex> K8s.Client.get("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Client.Operation{
  method: :get,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx"
}

iex> K8s.Client.get("apps/v1", :deployment, namespace: "test", name: "nginx")
%K8s.Client.Operation{
  method: :get,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx"
}
Link to this function

get_log(resource) 
get_log(map()) :: operation_or_error()

Returns a GET operation for a pod's logs given a manifest. May be a partial manifest as long as it contains:

  • apiVersion
  • kind
  • metadata.name
  • metadata.namespace

Examples 

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.get_log(pod)
%K8s.Client.Operation{
  method: :get,
  path: "/api/v1/namespaces/test/pods/nginx-pod/log"
}
Link to this function

get_log(api_version, kind, opts) 
get_log(binary(), binary(), options()) :: operation_or_error()

Returns a GET operation for a pod's logs given a namespace and a pod name.

Examples 

iex> K8s.Client.get_log("v1", "Pod", namespace: "test", name: "nginx-pod")
%K8s.Client.Operation{
  method: :get,
  path: "/api/v1/namespaces/test/pods/nginx-pod/log"
}
Link to this function

get_status(resource) 
get_status(map()) :: operation_or_error()

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

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

Examples 

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.get_status(pod)
%K8s.Client.Operation{
  method: :get,
  path: "/api/v1/namespaces/test/pods/nginx-pod/status"
}
Link to this function

get_status(api_version, kind, opts \\ []) 
get_status(binary(), binary(), options() | nil) :: operation_or_error()

Returns a GET operation for a resource's status by version, kind, name, and optionally namespace.

Examples 

iex> K8s.Client.get_status("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Client.Operation{
  method: :get,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx/status"
}
Link to this function

list(api_version, kind, list) 
list(binary(), binary(), options() | nil) :: operation_or_error()

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.Client.Operation{
  method: :get,
  path: "/api/v1/namespaces/default/pods"
}

iex> K8s.Client.list("apps/v1", "Deployment", namespace: :all)
%K8s.Client.Operation{
  method: :get,
  path: "/apis/apps/v1/deployments"
}
Link to this function

patch(resource) 
patch(map()) :: operation_or_error()

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 = %{
...>    "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.Client.Operation{
  method: :patch,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx",
  resource: %{
    "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"
          }
        }
      }
    }
  }
}
Link to this function

patch_status(resource) 
patch_status(map()) :: operation_or_error()

Returns a PATCH operation for a resource's status given a manifest. May be a partial manifest as long as it contains:

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

Examples 

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.patch_status(pod)
%K8s.Client.Operation{
  method: :patch,
  path: "/api/v1/namespaces/test/pods/nginx-pod/status",
  resource: %{
    "apiVersion" => "v1",
    "kind" => "Pod",
    "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
    "spec" => %{"containers" => %{"image" => "nginx"}}
  }
}
Link to this function

patch_status(api_version, kind, opts \\ []) 
patch_status(binary(), binary(), options() | nil) :: operation_or_error()

Returns a PATCH operation for a resource's status by version, kind, name, and optionally namespace.

Examples 

iex> K8s.Client.patch_status("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Client.Operation{
  method: :patch,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx/status"
}
Link to this function

post(resource)

Alias of create/1

Link to this function

put(resource)

Alias of replace/1

Link to this function

put_status(resource) 
put_status(map()) :: operation_or_error()

Returns a PUT operation for a resource's status given a manifest. May be a partial manifest as long as it contains:

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

Examples 

iex> pod = %{
...>   "apiVersion" => "v1",
...>   "kind" => "Pod",
...>   "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
...>   "spec" => %{"containers" => %{"image" => "nginx"}}
...> }
...> K8s.Client.put_status(pod)
%K8s.Client.Operation{
  method: :put,
  path: "/api/v1/namespaces/test/pods/nginx-pod/status",
  resource: %{
    "apiVersion" => "v1",
    "kind" => "Pod",
    "metadata" => %{"name" => "nginx-pod", "namespace" => "test"},
    "spec" => %{"containers" => %{"image" => "nginx"}}
  }
}
Link to this function

put_status(api_version, kind, opts \\ []) 
put_status(binary(), binary(), options() | nil) :: operation_or_error()

Returns a PUT operation for a resource's status by version, kind, name, and optionally namespace.

Examples 

iex> K8s.Client.put_status("apps/v1", "Deployment", namespace: "test", name: "nginx")
%K8s.Client.Operation{
  method: :put,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx/status"
}
Link to this function

replace(resource) 
replace(map()) :: operation_or_error()

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 = %{
...>    "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.replace(deployment)
%K8s.Client.Operation{
  method: :put,
  path: "/apis/apps/v1/namespaces/test/deployments/nginx",
  resource: %{
    "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"
          }
        }
      }
    }
  }
}
Link to this function

run(request, config) 
run(K8s.Client.Operation.t(), K8s.Conf.t()) :: result()

Runs a K8s.Client.Operation.

Examples

Running a list pods operation:

conf = K8s.Conf.from_file "~/.kube/config"
operation = K8s.Client.list("v1", "Pod", namespace: :all)
{:ok, %{"items" => pods}} = K8s.Client.run(operation, conf)

Running a dry-run of a create deployment operation:

conf = K8s.Conf.from_file "~/.kube/config"
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"
        }
      }
    }
  }
}
operation = K8s.Client.create(deployment)

# opts is passed to HTTPoison as opts.
opts = [params: %{"dryRun" => "all"}]
:ok = K8s.Client.run(operation, conf, opts)
Link to this function

run(request, config, opts) 
run(K8s.Client.Operation.t(), K8s.Conf.t(), keyword()) :: result()

See run/2

Link to this function

run(request, config, body, opts \\ []) 
run(K8s.Client.Operation.t(), K8s.Conf.t(), map(), keyword() | nil) :: result()

See run/2

Link to this function

update(resource)

Alias of replace/1