Config Qinling with existing Kubernetes cluster¶

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.

[kubernetes]
kube_host = http://127.0.0.1:8001
use_api_certificate = True
ssl_ca_cert = /etc/qinling/pki/kubernetes/ca.crt
cert_file = /etc/qinling/pki/kubernetes/qinling.crt
key_file = /etc/qinling/pki/kubernetes/qinling.key

For now, just update the kube_host to the URI which the Kubernetes API serves for HTTPS connections with authentication and authorization, for example, kube_host = https://kube-api.example.com:6443. We will cover the other options in the following sections.

Authentication and Authorization¶

The access to the Kubernetes API is controlled by several modules, refer to Controlling Access to the Kubernetes API for more details.

By default, Qinling engine is configured to access the Kubernetes API with a client certificate for authentication(use_api_certificate is set to True), so make sure that the Kubernetes API server is running with the --client-ca-file=SOMEFILE option for client certificate authentication to be enabled. The common name of the subject in the client certificate is used as the user name for the requests that Qinling engine makes to the Kubernetes API 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.

Generate Client Certificate for Qinling¶

See Managing Certificates for how to generate a client cert. We use cfssl as the example here.

1. Download and prepare the command line tools.

   curl -L https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 -o /tmp/cfssl
   chmod +x /tmp/cfssl
   curl -L https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64 -o /tmp/cfssljson
   chmod +x /tmp/cfssljson
   

2. Generate the client ceritificate for Qinling. Note that the common name of the subject is set to qinling in the example CSR located at example/kubernetes/cfssl-client-csr.json.

   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_FOLDER/example/kubernetes/cfssl-ca-config.json \
       -profile=client \
       QINLING_SOURCE_FOLDER/example/kubernetes/cfssl-client-csr.json | /tmp/cfssljson -bare client
   

3. 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.

   Note

   Remember to backup the existing files in /etc/qinling/pki/kubernetes folder first.

   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

   Make sure both /etc/qinling/pki/kubernetes and /etc/qinling/pki belong to Qinling service user. You can set the permissions with chown -R qinling:qinling /etc/qinling/pki

Create Role and RoleBinding in Kubernetes¶

If RBAC Authorization is enabled, we can limit the permissions that Qinling access the Kubernetes API. Before you procceed the steps in this section, make sure that the Kubernetes API server is running with the --authorization-mode=RBAC option.

Qinling provides a single file located at example/kubernetes/k8s_qinling_role.yaml for users to create a Role and a ClusterRole with the permissions that Qinling needs, and bind the roles to the user named qinling, which is from 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.

curl -sSL https://raw.githubusercontent.com/openstack/qinling/master/example/kubernetes/k8s_qinling_role.yaml | kubectl apply -f -

Restart Qinling Engine¶

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. The requests that Qinling makes to the Kubernetes API are also authorized.

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 should be used for testing purpose only.

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.