==========
Kubeconfig
==========

The ``kubectl`` command determines which cluster on which to operate
from the *kubeconfig* (see [kubeconfig-01]_). (*kubeconfig* is a generic term
to refer to kubernetes configuration files, the default is *~/.kube/config*)

In many cases the *kubeconfig* is created/edited by the tools provided by the
cloud provider (so the user does not need to care too much about it).
For example, with a non-existent *~/.kube/config* I ran the following Google Cloud
CLI command to create a cluster:

.. code-block:: fish

    > gcloud container clusters create mon-cluster

and this command automagically populated the *~/.kube/config* so that the
``kubectl`` knows which cluster to use:

.. code-block:: none

    > kubectl get nodes
    NAME                                         STATUS   ROLES    AGE   VERSION
    gke-mon-cluster-default-pool-737805c2-1762   Ready    <none>   58s   v1.10.9-gke.5
    gke-mon-cluster-default-pool-737805c2-d2gt   Ready    <none>   49s   v1.10.9-gke.5
    gke-mon-cluster-default-pool-737805c2-r1r8   Ready    <none>   48s   v1.10.9-gke.5

    > kubectl config view
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: DATA+OMITTED
        server: https://<SOME_IP_ADDRESS>
    name: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
    contexts:
    - context:
        cluster: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
        user: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
    name: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
    current-context: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
    kind: Config
    preferences: {}
    users:
    - name: gke_linear-aviary-193922_northamerica-northeast1-a_mon-cluster
    user:
        auth-provider:
        config:
            cmd-args: config config-helper --format=json
            cmd-path: /Users/hector/google-cloud-sdk/bin/gcloud
            expiry-key: '{.credential.token_expiry}'
            token-key: '{.credential.access_token}'
        name: gcp

When using other cloud providers you may need to adjust the *kubeconfig* manually.
For example when provisioning a cluster in Digital Ocean Kubernetes (DOK8s), it provides
guidance to download a configuration file, that must be specified when running
``kubectl``. For example if this config file was saved in *$HOME/.kube* as
*sites-cluster-kubeconfig.yaml*:

.. code-block:: fish

    > kubectl --kubeconfig=="$HOME/.kube/sites-cluster-kubeconfig.yaml" get nodes

To avoid the need of specifying kubeconfig for every invocation, export the environment
variable `KUBECONFIG` (see [kubeconfig-02]_). For example in fish:

.. code-block:: fish

    > set -x KUBECONFIG "$KUBECONFIG:$HOME/.kube/config:$HOME/.kube/sites-cluster-kubeconfig.yaml"

    > kubectl config view
    (configuration result of merging files specified in the KUBECONFIG var)

The you can use ``kubectl config use-context`` to switch between clusters:

.. code-block:: fish

    > kubectl get nodes
    NAME                                         STATUS   ROLES    AGE   VERSION
    gke-mon-cluster-default-pool-737805c2-1762   Ready    <none>   1h    v1.10.9-gke.5
    gke-mon-cluster-default-pool-737805c2-d2gt   Ready    <none>   1h    v1.10.9-gke.5
    gke-mon-cluster-default-pool-737805c2-r1r8   Ready    <none>   1h    v1.10.9-gke.5

    > kubectl config use-context do-nyc1-sites-cluster
    Switched to context "do-nyc1-sites-cluster".

    > kubectl get nodes
    NAME                STATUS   ROLES    AGE    VERSION
    silly-wright-32ya   Ready    <none>   124m   v1.12.3
    silly-wright-32ye   Ready    <none>   124m   v1.12.3
    silly-wright-32yg   Ready    <none>   124m   v1.12.3

----------
References
----------

.. [kubeconfig-01] `Organizing Cluster Access Using kubeconfig Files (Kubernetes Documentation)
   <https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/>`_
   (Retrieved 2018-12-13)

.. [kubeconfig-02] `Configure Access to Multiple Clusters (Kubernetes Documentation)
   <https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/>`_
   (Retrieved 2018-12-13)