Commit 26b2d08f authored by Richard Neill's avatar Richard Neill
Browse files

doc: Update the user guide use-case reproduce instructions



This patch:

  * Uses consistent terms to refer to baremetal and virtualization distribution
    images
  * Adds that the images should be rebooted before running the use-case
    instructions
  * Adds example output for each of the commands, to be clearer about what is
    expected
  * Provides instructions for how to stop application workloads, when
    recommending the reader to do so
  * Sets a name when the the Docker container is created, to support the
    subsequent stop instructions
  * Clarify which commands should be executed on the Control VM, and which
    commands should be executed on the Guest VM, using a consistent format

Issue-Id: SCM-4397
Signed-off-by: Richard Neill's avatarRichard Neill <richard.neill@arm.com>
Change-Id: Ieec1018e2d1c9fe1864161fd48602f220ed71843
parent bb394280
......@@ -640,14 +640,14 @@ Deploying Application Workloads via Docker and K3s
This example use-case is performed on the:
* EWAOL baremetal architecture
* EWAOL virtualization architecture
* Baremetal distribution image
* Virtualization distribution image
This example deploys the |Nginx|_ webserver as an application workload, using
the ``nginx`` container image available from Docker's default image repository.
The deployment can be achieved either via Docker or via K3s, as follows:
1. Boot the image and log-in as ``ewaol`` user.
1. Reboot the image and log-in as the ``ewaol`` user.
On a virtualization distribution image, this will produce a console on the
Control VM.
......@@ -660,7 +660,7 @@ The deployment can be achieved either via Docker or via K3s, as follows:
.. code-block:: console
sudo docker run -p 8082:80 -d nginx
sudo docker run --name nginx_docker_example -p 8082:80 -d nginx
2.2. Confirm the Docker container is running by checking its ``STATUS``
in the container list:
......@@ -669,6 +669,14 @@ The deployment can be achieved either via Docker or via K3s, as follows:
sudo docker container list
The container should appear in the list of running containers, with
the associated name ``nginx_docker_example``. For example:
.. code-block:: console
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
cb7f67053556 nginx "/docker-entrypoint.…" 14 seconds ago Up 13 seconds 0.0.0.0:8082->80/tcp, :::8082->80/tcp nginx_docker_example
* **Deploy via K3s**
2.1. Run the following example command to deploy via K3s:
......@@ -696,6 +704,13 @@ The deployment can be achieved either via Docker or via K3s, as follows:
sudo kubectl get pods -o wide
The output should be similar to the following example output:
.. code-block:: console
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
k3s-nginx-example 1/1 Running 0 28s [IP] n1sdp <none> <none>
3. After the Nginx application workload has been successfully deployed, it can
be interacted with on the network, via for example:
......@@ -703,17 +718,51 @@ The deployment can be achieved either via Docker or via K3s, as follows:
wget localhost:8082
This should download the webserver's default ``index.html`` page and return
a successful exit status, similar to the following example output:
.. code-block:: console
--YYYY-MM-DD HH:mm:ss-- http://localhost:8082/
Resolving localhost (localhost)... ::1, 127.0.0.1
Connecting to localhost (localhost)|::1|:8082... connected.
HTTP request sent, awaiting response... 200 OK
Length: 615 [text/html]
Saving to: ‘index.html’
index.html 100%[===========================================================================>] 615 --.-KB/s in 0s
YYYY-MM-DD HH:mm:ss (189 MB/s) - ‘index.html’ saved [615/615]
.. note::
As both methods deploy a webserver listening on port 8082, the two methods
cannot be run simultaneously and one deployment must be stopped before the
other can start.
To stop the application workload deployed via Docker, use the command:
.. code-block:: console
sudo docker stop nginx_docker_example
The container should then no longer appear in the list of running containers
given by ``sudo docker container list``.
To stop the application workload deployed via K3s, use the command:
.. code-block:: console
sudo kubectl delete pod k3s-nginx-example
The K3s Pod which was running the container should no longer appear in the
list of K3s Pods given by ``sudo kubectl get pods -o wide``.
Orchestrating Resource-Managed and Isolated Application Workloads via K3s and Xen VMs
=====================================================================================
This example use-case is performed on the:
* EWAOL virtualization architecture
* Virtualization distribution image
This example uses the K3s orchestration framework to use the Control VM to
schedule an |Nginx|_ webserver application workload for execution on the Guest
......@@ -726,62 +775,72 @@ Guest VM via K3s orchestration. This example process is as follows:
1. **Log-in to the Control VM**
Boot the virtualization distribution image and log-in as ``ewaol`` user.
Reboot the virtualization distribution image, then log-in as the ``ewaol``
user.
2. **Connect Guest VM K3s Agent**
2.1. Determine the IP address of the Control VM via:
2.1. On the **Control VM**, determine its IP address via:
.. code-block:: console
ifconfig xenbr0
2.2. Determine the node-token for the K3s server on the Control VM via:
2.2. On the **Control VM**, determine the node-token for the K3s server via:
.. code-block:: console
sudo cat /var/lib/rancher/k3s/server/node-token
2.3. Then, log in to the Guest VM as ``ewaol`` user, via:
2.3. On the **Control VM**, log in to the **Guest VM** as the ``ewaol``
user, via:
.. code-block:: console
sudo xl console ewaol-guest-vm1
2.4. Denoting the IP address and node-token as ``[IP]`` and ``[TOKEN]``
respectively, change the ``ExecStart=`` line in
2.4. On the **Guest VM**, and denoting the IP address and node-token as
``[IP]`` and ``[TOKEN]`` respectively, change the ``ExecStart=`` line in
``/lib/systemd/system/k3s-agent.service`` to:
.. code-block:: console
ExecStart=/usr/local/bin/k3s agent --server=https://[IP]:6443 --token=[TOKEN] --node-label=ewaol.node-type=guest-vm
2.5. Start the Guest VM's K3s Agent with these values via:
2.5. On the **Guest VM**, start the K3s Agent with these values via:
.. code-block:: console
sudo systemctl daemon-reload && sudo systemctl start k3s-agent
2.6. Disconnect from the Guest VM and return to the Control VM via:
2.6. On the **Guest VM**, disconnect from it and return to the Control VM
via:
.. code-block:: console
Ctrl+]
2.7. Ensure that the Control VM K3s server and the Guest VM K3s agent are
connected. This can be checked on the Control VM via:
2.7. On the **Control VM**, ensure that the K3s server and the Guest VM's
K3s agent are connected, by running:
.. code-block:: console
sudo kubectl get nodes
The hostname of the Guest VM should appear as a node in the list, with a
``STATUS`` of ``ready``.
The hostname of the Guest VM should appear as a node in the list, with
a ``STATUS`` of ``ready``. The output should be similar to the
following example:
.. code-block:: console
NAME STATUS ROLES AGE VERSION
ewaol-guest-vm1 Ready <none> 22s v1.22.6-k3s1
n1sdp Ready control-plane,master 6m40s v1.22.6-k3s1
3. **Schedule Application Workload**
3.1. Schedule the Nginx application workload to the Guest VM, via the
following example command:
3.1. On the **Control VM**, schedule the Nginx application workload to be
deployed on the Guest VM, by running the following example command:
.. code-block:: console
......@@ -801,23 +860,56 @@ Guest VM via K3s orchestration. This example process is as follows:
ewaol.node-type: guest-vm
EOT
3.2. Confirm that the K3s Pod hosting the container is running on the Guest
VM by checking its ``STATUS`` is ``running``, and its ``NODE`` is the Guest
VM's hostname, using:
3.2. On the **Control VM**, confirm that the K3s Pod (which hosts the
container) was deployed to the Guest VM by checking its ``STATUS`` is
``running`` and its ``NODE`` is the Guest VM's hostname, by running the
following command:
.. code-block:: console
.. code-block:: console
sudo kubectl get pods -o wide
sudo kubectl get pods -o wide
The output should be similar to the following example output:
.. code-block:: console
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
k3s-nginx-example 1/1 Running 0 33s [IP] ewaol-guest-vm1 <none> <none>
4. **Access the Application Workload**
The webserver will then be running on the Guest VM, and can be accessed by
running the following example command on the Guest VM:
The webserver will then be running on the Guest VM. To access the webserver:
4.1. On the **Control VM**, log in to the **Guest VM** as the ``ewaol``
user, via:
.. code-block:: console
sudo xl console ewaol-guest-vm1
4.2. On the **Guest VM**, access the webserver by running the following
example command:
.. code-block:: console
wget localhost:8082
This should download the webserver's default ``index.html`` page and return
a successful exit status, similar to the following example output:
.. code-block:: console
--YYYY-MM-DD HH:mm:ss-- http://localhost:8082/
Resolving localhost (localhost)... ::1, 127.0.0.1
Connecting to localhost (localhost)|::1|:8082... connected.
HTTP request sent, awaiting response... 200 OK
Length: 615 [text/html]
Saving to: ‘index.html’
index.html 100%[===========================================================================>] 615 --.-KB/s in 0s
YYYY-MM-DD HH:mm:ss (189 MB/s) - ‘index.html’ saved [615/615]
While the Guest VM is running this application workload, other deployments may
be carried out (for example) on the Control VM, thus enabling isolation between
application workloads running on resource-managed virtualized hardware.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment