.. _namespace:

Namespace
---------

Namespaces give you a way to organize your work on Kubernetes.  What happens in one namespace, doesn't affect
other namespaces (usually).  You can use them for anything.  Perhaps you are learning Kubernetes, you can create a
namespace for yourself and start building deployments, services, etc. without affecting other people's
namespaces.

The most common use of namespace is to separate the work of different teams and projects.  Typically you'll
create a separate namespace for each project and environment.  For example, if you have a project named
"my-project" and you want to have separate development, test and production environments, you would have
the namespaces **my-project-dev**, **my-project-test** and **my-project-prd**.  Most objects are specific to
a namespace.  There are some things that will apply to all namespaces on the same cluster, such as
**cluster roles**, roles that are globally recognized across the entire cluster.

While you can specify the namespace in most of the functions provided in this library, it is optional.  The best
way to work is to set a default namespace so you don't have to specify the namespace on every function call.  You
can even set the default namespace before creating a namespace.

Example:

.. code-block:: python

    from k9.helper import (
        set_default_namespace,
        create_namespace,
        delete_namespace
    )
    import pprint

    try:
        pp = pprint.PrettyPrinter(indent=2)

        # Create a deveopment namespace for "myproject"
        ns = "myproject-dev"
        set_default_namespace(ns)

        result = create_namespace()
        pp.pprint(result)

    finally:
        # Typically, you would want to keep your namespace
        # unless this was part of a unit test where you
        # create a temporary namespace and tear it down
        # after testing.
        delete_namespace()

Example Output::

    {'api_version': 'v1',
     'kind': 'Namespace',
     'metadata': {'annotations': None,
                  'cluster_name': None,
                  'creation_timestamp': datetime.datetime(2019, 10, 23, 19, 22, 7, tzinfo=tzutc()),
                  'deletion_grace_period_seconds': None,
                  'deletion_timestamp': None,
                  'finalizers': None,
                  'generate_name': None,
                  'generation': None,
                  'initializers': None,
                  'labels': None,
                  'managed_fields': None,
                  'name': 'myproject-dev',
                  'namespace': None,
                  'owner_references': None,
                  'resource_version': '2849463',
                  'self_link': '/api/v1/namespaces/myproject-dev',
                  'uid': '673ee6f0-f5ca-11e9-aa89-025000000001'},
     'spec': {'finalizers': ['kubernetes']},
     'status': {'phase': 'Active'}}

.. autofunction:: k9.core.set_default_namespace
.. autofunction:: k9.core.get_default_namespace
.. autofunction:: k9.core.list_namespaces
.. autofunction:: k9.core.get_namespace
.. autofunction:: k9.core.namespace_exists
.. autofunction:: k9.core.create_namespace
.. autofunction:: k9.core.delete_namespace