clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-09-06 22:01:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #273 from MCamp859/k8s-tutorial

Browse Source 
Streamlined config & run sections and edited text for clarity.
This commit is contained in:
michael vincerra
2018-10-24 19:44:15 +00:00
committed by GitHub
parent f288e9d6d6 9a03f10c64
commit e25713ab00
1 changed files with 131 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/tutorials/kubernetes.rst
+131 -93
View File
@@ -11,18 +11,23 @@ Kubernetes\* is an open source system for automating deployment, scaling, and
management of containerized applications. It groups containers that make up
an application into logical units for easy management and discovery.
Runc and Kata Containers\* kata-runtime adhere to :abbr:`OCI (Open Container Initiative*)` guidelines and work seamlessly with Kubernetes.
`Kata Containers`_ provide strong isolation for untrusted workloads or
multi-tenant scenarios. Runc and Kata Containers can be allocated on a
per-pod basis so you can mix and match both on the same host
to suit your needs.
Runc and Kata Containers\* kata-runtime adhere to :abbr:`OCI (Open Container Initiative*)`
guidelines and work seamlessly with Kubernetes. `Kata Containers`_ provide
strong isolation for untrusted workloads or multi-tenant scenarios. Runc and
Kata Containers can be allocated on a per-pod basis so you can mix and match
both on the same host to suit your needs.
This tutorial describes the following combinations:
* Kubernetes with Docker and runc
* Kubernetes with CRI-O and kata-runtime
Prerequisites
*************
This tutorial assumes you have installed |CL| and updated to the latest
release on your host system. You can learn about the benefits of having an
up-to-date system for cloud orchestration in the :ref:`swupd-about`
up-to-date system for cloud orchestration on the :ref:`swupd-about`
page. For detailed instructions on installing |CL| on a bare metal system,
follow the :ref:`bare metal installation tutorial<bare-metal-install>`.
@@ -50,7 +55,7 @@ This tutorial uses the basic default Kubernetes configuration for simplicity.
You must define your Kubernetes configuration according to your specific
deployment and your security needs.
#. Enable IP forwarding to avoid "preflight check" errors:
#. Enable IP forwarding to avoid kubeadm `preflight check`_ errors:
Create (or edit if it exists) the file :file:`/etc/sysctl.d/60-k8s.conf`
and include the following line:
@@ -65,7 +70,7 @@ deployment and your security needs.
sudo systemctl restart systemd-sysctl
#. Enable kubelet service:
#. Enable the kubelet service:
.. code-block:: bash
@@ -99,110 +104,120 @@ deployment and your security needs.
On systems with limited resources, some performance degradation may
be observed while swap is disabled.
#. Create (or edit if it exists) the hosts file that kubernetes will read to
locate master's host:
#. Switch to root to modify `hostname`:
.. code-block:: bash
echo "127.0.0.1 localhost `hostname`" >> /etc/hosts
sudo -s
#. Configure the Kubernetes runtime interface, either:
#. Create (or edit if it exists) the hosts file that Kubernetes will read to
locate the master's host:
a) Run Kubernetes with Docker + runc:
.. code-block:: bash
#. Enable docker.service:
echo "127.0.0.1 localhost `hostname`" >> /etc/hosts
.. code-block:: bash
#. Exit root:
sudo systemctl enable docker.service
.. code-block:: bash
#. Create (or edit if it exists) the file
:file:`/etc/systemd/system/docker.service.d/51-runtime.conf` and include the following lines:
exit
.. code-block:: bash
Configure and run Kubernetes
****************************
[Service]
Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime runc"
This section describes how to configure and run Kubernetes with:
#. Create (or edit if it exists) the file :file:`/etc/systemd/system/kubelet.service.d/10-kubeadm.conf` and include the following lines:
* Docker and runc
* CRI-O and kata-runtime
.. code-block:: bash
Configure and run Docker + runc
===============================
[Service]
Environment="KUBELET_EXTRA_ARGS="
#. Enable the Docker service:
#. Restart services:
.. code-block:: bash
.. code-block:: bash
sudo systemctl enable docker.service
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl restart kubelet
#. Create (or edit if it exists) the file
:file:`/etc/systemd/system/docker.service.d/51-runtime.conf` and include the following lines:
or:
.. code-block:: bash
b) Run Kubernetes with CRI-O + your desired runtime. You can use multiple
runtimes with CRI-O, including *runc* and *kata-runtime*. To use
CRI-O + *kata-runtime*:
[Service]
Environment="DOCKER_DEFAULT_RUNTIME=--default-runtime runc"
#. Enable crio.service:
#. Create (or edit if it exists) the file :file:`/etc/systemd/system/kubelet.service.d/10-kubeadm.conf` and include the following lines:
.. code-block:: bash
.. code-block:: bash
sudo systemctl enable crio.service
[Service]
Environment="KUBELET_EXTRA_ARGS="
#. Restart services:
#. Enter the commands:
.. code-block:: bash
.. code-block:: bash
sudo systemctl restart crio
sudo systemctl restart kubelet
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl restart kubelet
Run Kubernetes for the first time
*********************************
#. Initialize the master control plane with the command:
#. Prepare your system to run Kubernetes for the first time with the
following commands, either:
.. code-block:: bash
a) If you are running Kubernetes with Docker + runc:
sudo kubeadm init --ignore-preflight-errors=SystemVerification
.. code-block:: bash
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl restart kubelet
Configure and run CRI-O + kata-runtime
======================================
or:
#. Enable the CRI-O service:
b) If you are running Kubernetes with CRI-O + kata-runtime:
.. code-block:: bash
.. code-block:: bash
sudo systemctl enable crio.service
sudo systemctl daemon-reload
sudo systemctl restart crio
sudo systemctl restart kubelet
#. Enter the commands:
#. Initialize the master control plane with the following command, either:
.. code-block:: bash
a) If you are running Kubernetes with Docker + runc:
sudo systemctl daemon-reload
sudo systemctl restart crio
sudo systemctl restart kubelet
.. code-block:: bash
#. Initialize the master control plane with the command:
sudo -E kubeadm init --pod-network-cidr 10.244.0.0/16 --ignore-preflight-errors=SystemVerification
.. code-block:: bash
or:
sudo kubeadm init --cri-socket=/run/crio/crio.sock
b) If you are running Kubernetes with CRI-O + kata-runtime:
.. code-block:: bash
Install pod network add-on
**************************
sudo -E kubeadm init --pod-network-cidr 10.244.0.0/16 --cri-socket=/run/crio/crio.sock
You must choose and install a `pod network add-on`_ to allow your pods to
communicate.
Once your master control is successfully initialized, instructions on how to
use your cluster and its *IP*, *token*, and *hash* values are displayed. It
is important that you note these cluster values because they will be needed
when joining worker nodes to the cluster and some of them have a valid
Check whether or not your add-on requires special flags when you initialize
the master control plane. For example, if you choose the `flannel` add-on,
then you must add :command:`--pod-network-cidr 10.244.0.0/16` to the `kubeadm
init` command.
Similarly, if you choose the `weave` add-on, then you must change the CNI
add-on directory parameter because the weave plugin installs itself in the
:file:`/opt/cni/bin` directory.
Use your cluster
****************
Once your master control plane is successfully initialized, instructions on
how to use your cluster and its *IP*, *token*, and *hash* values are
displayed. It is important that you record the cluster values because they are
needed when joining worker nodes to the cluster. Some values have a valid
period. The values are presented in a format similar to:
.. code-block:: bash
@@ -212,12 +227,12 @@ period. The values are presented in a format similar to:
**Congratulations!**
You've successfully installed and set up Kubernetes in |CL| using Docker and
runc or CRI-O and kata-runtime. You are now ready to follow on-screen
instructions to deploy a pod network to the cluster and join worker nodes
You've successfully installed and set up Kubernetes in |CL| using Docker and
runc or CRI-O and kata-runtime. You are now ready to follow on-screen
instructions to deploy a pod network to the cluster and join worker nodes
with the displayed token and IP information.
Related Topics
Related topics
**************
Read the Kubernetes documentation to learn more about:
@@ -226,11 +241,11 @@ Read the Kubernetes documentation to learn more about:
* `Deploying an application to your cluster`_
* `Installing a pod network add-on`_
* Installing a `pod network add-on`_
* `Joining your nodes`_
Package configuration customization in |CL| (Optional)
Package configuration customization in |CL| (optional)
******************************************************
|CL| is a stateless system that looks for user-defined package configuration
@@ -238,12 +253,12 @@ files in the :file:`/etc/<package-name>` directory to be used as default. If
user-defined files are not found, |CL| uses the distribution-provided
configuration files for each package.
If you customize any of the default package configuration files, you *must*
If you customize any of the default package configuration files, you **must**
store the customized files in the :file:`/etc/` directory. If you edit any of
the distribution-provided default files, your changes will be lost in the
next system update.
For example, to customize CRI-O configuration in your system you can run the
For example, to customize CRI-O configuration in your system, run the
following commands:
.. code-block:: bash
@@ -283,35 +298,56 @@ commands as a shell script to configure all of these services in one step:
Troubleshooting
***************
* <HOSTNAME> not found in <IP> message.
* <HOSTNAME> not found in <IP> message.
Your DNS server may not be appropriately configured. You can try adding
an entry to the :file:`/etc/hosts` file with your host's IP and Name. Use
the commands *hostname* and *hostname -I* to retrieve them.
For example: 100.200.50.20 myhost
Your DNS server may not be appropriately configured. Try adding an
entry to the :file:`/etc/hosts` file with your host's IP and Name.
For example: 100.200.50.20 myhost
* Images cannot be pulled.
Use the commands :command:`hostname` and :command:`hostname -I` to retrieve them.
You may be behind a proxy server. Try configuring your proxy settings,
* Images cannot be pulled.
You may be behind a proxy server. Try configuring your proxy settings,
using the environment variables *HTTP_PROXY*, *HTTPS_PROXY*, and *NO_PROXY*
as required in your environment.
* Connection refused error.
* Connection refused error.
If you are behind a proxy server, you may need to add the master's IP to
the environment variable *NO_PROXY*.
* Connection timed-out or Access Refused errors.
You must ensure that the appropriate proxy settings are available from the
same terminal where you will initialize the control plane. To verify the
proxy settings that kubernetes will actually use, run the commands:
You must ensure that the appropriate proxy settings are available from the
same terminal where you will initialize the control plane. To verify the
proxy settings that Kubernetes will actually use, run the commands:
* *"echo $HTTP_PROXY"*
* *"echo $HTTPS_PROXY"*
* *"echo $NO_PROXY"*
.. code-block:: bash
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY
If the displayed proxy values are different from your assigned values, the
cluster initialization will fail. Contact your IT support team to learn how
to set the proxy variables permanently, and how to make them available for
all the types of access that you will use, such as remote SSH access.
* Missing environment variables.
If you are behind a proxy server, pass environment variables by adding *-E*
to the command that initializes the master control plane.
.. code-block:: bash
/* Kubernetes with Docker + runc */
sudo -E kubeadm init --ignore-preflight-errors=SystemVerification
/* Kubernetes with CRI-O + kata-runtime */
sudo -E kubeadm init --cri-socket=/run/crio/crio.sock
If the displayed proxy values are different from your assigned values, the cluster initialization will fail. Contact your IT support team to learn the appropriate procedure to set the proxy variables permanently, and make them available for all the access forms that you will use (for example: remote ssh access).
.. _Kubernetes container orchestration system: https://kubernetes.io/
@@ -321,11 +357,13 @@ Troubleshooting
.. _cloud-native-basic: https://github.com/clearlinux/clr-bundles/blob/master/bundles/cloud-native-basic
.. _preflight check: https://kubernetes.io/docs/reference/setup-tools/kubeadm/implementation-details/#preflight-checks
.. _Understanding basic Kubernetes architecture: https://kubernetes.io/docs/user-journeys/users/application-developer/foundational/#section-3
.. _Deploying an application to your cluster: https://kubernetes.io/docs/user-journeys/users/application-developer/foundational/#section-2
.. _Installing a pod network add-on: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network
.. _pod network add-on: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#pod-network
.. _Joining your nodes: https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/#join-nodes