From b3c5bfd2ce13cad54b712aaeaaaf784d5afa6336 Mon Sep 17 00:00:00 2001 From: Lingxian Kong Date: Wed, 25 Jul 2018 23:43:04 +1200 Subject: [PATCH] Improve connecting to existing k8s cluster guide Change-Id: I9ea2798546dfa5638c0c849da88ee8a8e0b38a79 --- .../admin/install/config_kubernetes.rst | 62 +++++++++---------- 1 file changed, 29 insertions(+), 33 deletions(-) diff --git a/doc/source/admin/install/config_kubernetes.rst b/doc/source/admin/install/config_kubernetes.rst index 4fc03202..4686c1d4 100644 --- a/doc/source/admin/install/config_kubernetes.rst +++ b/doc/source/admin/install/config_kubernetes.rst @@ -21,8 +21,8 @@ Qinling. The component which works with Kubernetes cluster in Qinling is the existing Kubernetes cluster, and make Qinling access the Kubernetes API with authentication and authorization. -Configurations -~~~~~~~~~~~~~~ +Qinling Configurations +~~~~~~~~~~~~~~~~~~~~~~ Below are the options that relate to accessing the Kubernetes API in Qinling's configuration file, all of them are under the ``kubernetes`` section. @@ -58,10 +58,10 @@ server. Refer to `Authentication in Kubernetes `_. If `RBAC Authorization `_ -is enabled in the Kubernetes API, we will also have to grant access to resources -in Kubernetes for the specific user that Qinling uses to make requests to the -Kubernetes API. Using RBAC Authorization can ensure that Qinling access the -Kubernetes API with only the permission that it needs. +is enabled in the Kubernetes API, we will also have to grant access to +resources in Kubernetes for the specific user that Qinling uses to make +requests to the Kubernetes API. Using RBAC Authorization can ensure that +Qinling access the Kubernetes API with only the permission that it needs. Generate Client Certificate for Qinling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -84,24 +84,29 @@ for how to generate a client cert. We use ``cfssl`` as the example here. .. code-block:: console - mkdir certs; cd certs + mkdir /tmp/certs; cd /tmp/certs /tmp/cfssl gencert -ca=/path/to/kubernetes_ca_crt \ -ca-key=/path/to/kubernetes_ca_key \ - -config=QINLING_SOURCE/example/kubernetes/cfssl-ca-config.json \ + -config=QINLING_SOURCE_FOLDER/example/kubernetes/cfssl-ca-config.json \ -profile=client \ - QINLING_SOURCE/example/kubernetes/cfssl-client-csr.json | /tmp/cfssljson -bare client + QINLING_SOURCE_FOLDER/example/kubernetes/cfssl-client-csr.json | /tmp/cfssljson -bare client #) Copy the needed files to the locations. The command above generates two files named ``client-key.pem`` and ``client.pem``, the former is the key file of the client certificate, and the latter is the certificate file itself. - .. code-block:: console + .. note:: - mkdir -p /etc/qinling/pki/kubernetes - cp client-key.pem /etc/qinling/pki/kubernetes/qinling.key - cp client.pem /etc/qinling/pki/kubernetes/qinling.crt - cp /path/to/kubernetes_ca_crt /etc/qinling/pki/kubernetes/ca.crt + Remember to backup the existing files in /etc/qinling/pki/kubernetes + folder first. + + .. code-block:: console + + mkdir -p /etc/qinling/pki/kubernetes + mv client-key.pem /etc/qinling/pki/kubernetes/qinling.key + mv client.pem /etc/qinling/pki/kubernetes/qinling.crt + mv /path/to/kubernetes_ca_crt /etc/qinling/pki/kubernetes/ca.crt .. note:: @@ -125,30 +130,21 @@ the common name of the subject in the client certificate. The role is defined within a namespace named ``qinling``, which is the default namespace that Qinling uses and the name is configurable. -#) Grant access to the resources in the Kubernetes cluster for Qinling. The - following command can be running on any host that kubectl is installed - to interact with Kubernetes. +.. code-block:: console - .. code-block:: console + curl -sSL https://raw.githubusercontent.com/openstack/qinling/master/example/kubernetes/k8s_qinling_role.yaml | kubectl apply -f - - curl -sSL https://raw.githubusercontent.com/openstack/qinling/master/example/kubernetes/k8s_qinling_role.yaml | kubectl create -f - -The command above creates a ``ClusterRole`` named ``qinling`` with the -cluster-wide permissions that Qinling needs and binds it to the ``qinling`` -user. It also creates a ``Role`` named ``qinling`` within a newly created -``qinling`` namespace and binds it to the specific user. So the access to -resources within that namespace is also granted. +Restart Qinling Engine +~~~~~~~~~~~~~~~~~~~~~~ -Start Qinling Engine -~~~~~~~~~~~~~~~~~~~~ - -Start the qinling-engine service after the steps above are done. And now +Restart the qinling-engine service after the steps above are done, and now Qinling is accessing the Kubernetes API with itself authenticated by a client -certificate. And the requests that Qinling makes to the Kubernetes API -are also authorized. +certificate. The requests that Qinling makes to the Kubernetes API are also +authorized. -Access the Kubernetes API Insecurely (For Testing ONLY) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Access the Kubernetes API Insecurely (For testing purpose ONLY) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Qinling can also connect to the Kubernetes API insecurely if the Kubernetes API server serves for insecure connections. However this is not recommended and @@ -158,4 +154,4 @@ In the configuration file, under the ``kubernetes`` section, set ``kube_host`` to the URI which the Kubernetes API serves for insecure HTTP connections, for example, ``kube_host = http://localhost:8080``, and set ``use_api_certificate`` to ``False`` to disable Qinling using a client certificate to access the -Kubernetes API. \ No newline at end of file +Kubernetes API.