Add a virtual machine to the mesh
This guide shows you how to manually add a virtual machine to a workload, using the analytics-v1
workload of the Service Mesh Manager demo application as an example.
If you already understand the procedure and want to configure your virtual machine to be automatically added to the mesh, see Autoscaling VM groups.
Prerequisites
- You already have a virtual machine available.
- You have root access to the virtual machine.
- You have completed the Prerequisites.
- If you are using the different network approach make sure to set up your firewall.
- If you want to exactly replicate the steps of this guide for testing purposes, install the Service Mesh Manager demo application on your cluster, and the jq tool on your computer.
If you are performing this procedure on a clean installation of the Service Mesh Manager demo application, the topology view of the smm-demo
namespace should look similar to this:
Scale down the analytics service
Note: If you are not using the demo application to test VM integration, skip this step. You can install the demo application on your Service Mesh Manager cluster by running
smm demoapp install
This step and the examples in other steps of this guide rely on the analytics-v1
workload of the Service Mesh Manager demo application.
-
Scale it down to have zero replicas:
kubectl scale deploy -n smm-demo analytics-v1 --replicas=0
-
Verify that there are no pods belonging to the analytics deployment. The following command should return an empty response:
kubectl get pods -n smm-demo | grep analytics
Add an external workload to the mesh
The attached machines will behave as Kubernetes workloads. This means that it will have a set of labels assigned that could be used by Services
to match the machine. All Kubernetes Pods have a service account assigned (usually the default
one in the namespace if not specified otherwise). The machine uses this service account to authenticate to the Istio control plane.
To add an external workload to the mesh, create a WorkloadGroup
in the namespace where the machine will be attached to. This object represents a group of machines serving the same service. This is analogous to the Kubernetes concept of a Deployment
.
For example, to add a virtual machine serving the analytics
traffic in the demo application, use the following object:
apiVersion: networking.istio.io/v1alpha3
kind: WorkloadGroup
metadata:
labels:
app: analytics
version: v0
name: analytics-v0
namespace: smm-demo
spec:
metadata:
labels:
app: analytics
version: v0
probe:
httpGet:
path: /
host: 127.0.0.1
port: 8080
scheme: HTTP
template:
network: vm-network-1
ports:
http: 8080
grpc: 8082
tcp: 8083
serviceAccount: default
For details on these settings, see Exposing the Dashboard.
mTLS settings (optional)
After Istio is started on the virtual machine, Istio takes over the service ports defined in the WorkloadGroup
resource. Depending on your settings, it will also start enforcing mTLS on those service ports.
If external (non-mesh) services communicate with the virtual machine, ensure that communication without encryption is permitted on the service ports. To do so, create a PeerAuthentication
object in the smm-demo
namespace. Make sure that the matchLabels
selector only matches the WorkloadGroup
, and not any other Kubernetes deployment, to avoid permitting unencrypted communication where it’s not needed. In the following example, the matchLabels
selector includes both the app and the version labels.
apiVersion: security.istio.io/v1beta1
kind: PeerAuthentication
metadata:
name: analytics
namespace: smm-demo
spec:
mtls:
mode: PERMISSIVE
selector:
matchLabels:
app: analytics
version: v0
We recommend setting the mTLS mode to PERMISSIVE
as it allows unencrypted traffic. The in-mesh traffic will use mTLS.
Note: In case of any compatibility issues, you can set the mode to
DISABLE
, but it this case all traffic will be un-encrypted.
Set up the virtual machine
Required packages on the virtual machines
In addition to the OS package dependencies prerequisites, this example requires python3
. To install the python3
package, run the following command:
-
On Ubuntu:
apt-get update && apt-get install -y python3
-
On RHEL:
yum install -y python3
Executing the Example VM-based Service Workload
Before you can register the virtual machine, the workload must already be running on the VM. The following instructions start an example HTTP server workload on the virtual machine.
In the example using the demo application, open a terminal on the machine (for example, using SSH), and start a simple web server serving files from the empty-dir (the demo application requires only the availability of http://<pod-id>:8080/**
).
Note: The
nohup
shell command keepspython3
andhttp.server
running when the shell is logged out.
mkdir -p empty-dir
cd empty-dir
nohup python3 -m http.server 8080 &
Collect the required data
To attach the VM to the mesh, you’ll need the following information:
- The URL of the dashboard
- The namespace and name of the
WorkloadGroup
(smm-demo.analytics-v1
in the example) - The bearer token of the service account referenced in the
.spec.template.serviceAccount
of theWorkloadGroup
- (Optional) The IP address that the clusters in the service mesh can use to access the VM. If this is the same as the IP the public internet sees for the VM, then Service Mesh Manager detects the VM’s IP automatically.
To acquire the bearer token of the ServiceAccount
, complete the following steps.
-
On Kubernetes 1.24 and newer, the token secrets for service accounts are not created automatically. Create the token manually. For details, see the Kubernetes documentation.
-
Download and run the following script. This script fetches the bearer token for the service account in namespace
SA_NAMESPACE
with the name ofSA_SERVICEACCOUNT
and saves it into the~/bearer-token
file.Note: If you are running the script on a OpenShift ROSA cluster, at line 13 in the script, please replace the ‘jq’ output string with
'.items[1].data.token | @base64d'
Prepare the virtual machine
To prepare the virtual machine to be attached to the mesh, complete the following steps.
-
Open a terminal (for example, SSH) to the virtual machine.
-
Install
smm-agent
on the virtual machine. The agent ensures that the machine’s Istio configuration is always up-to-date. Run the following command as the root user:curl http://<dashboard-url>/get/smm-agent | bash
The output should be similar to:
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 1883 100 1883 0 0 13744 0 --:--:-- --:--:-- --:--:-- 13744 Detecting host properties: - OS: linux - CPU: amd64 - Packager: deb - SMM Base URL: http://a6bc8072e26154e5c9084e0d7f5a9c92-2016650592.eu-north-1.elb.amazonaws.com % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 20.3M 0 20.3M 0 0 22.2M 0 --:--:-- --:--:-- --:--:-- 22.2M Selecting previously unselected package smm-agent. (Reading database ... 63895 files and directories currently installed.) Preparing to unpack /tmp/smm-agent-package ... Unpacking smm-agent (1.9.1~snapshot.202203311042-SNAPSHOT-ab2e8684a) ... Setting up smm-agent (1.9.1~snapshot.202203311042-SNAPSHOT-ab2e8684a) ... Created symlink /etc/systemd/system/multi-user.target.wants/smm-agent.service → /lib/systemd/system/smm-agent.service. ✓ dashboard url set url=<dashboard-url>
-
Specify which
WorkloadGroup
and namespace you want to attach the machine to by running the following command:smm-agent set workload-group <namespace> <workloadgroup>
For example:
smm-agent set workload-group smm-demo analytics-v0
The output should be similar to:
✓ target workload group set namespace=smm-demo, name=analytics-v0
-
Specify the bearer token you have acquired in a previous step (replace <token> with the actual token, not the filename):
smm-agent set bearer-token <token>
The output should be similar to:
✓ bearer token set
-
(Optional) Set the IP address the service mesh should use to access the VM.
smm-agent set node-ip <VM's IP>
The output should be similar to:
✓ node-ip is set ip=<VM's IP>
-
Validate the configuration of smm-agent by running the following command. If the configuration is invalid an error is shown.
smm-agent show-config
The output should be similar to:
✓ dashboard url=http://a6bc8072e26154e5c9084e0d7f5a9c92-2016650592.eu-north-1.elb.amazonaws.com ✓ target workload-group namespace=smm-demo, name=analytics-v0 ✓ no additional labels set ✓ bearer token set ✓ node-ip is set ✓ configuration is valid
Attach the virtual machine to the mesh
Now that you have started the workload (HTTP server) and configured smm-agent, you can attach the VM to the mesh. To do so, run a reconciliation on this host. This step will:
- configure and start Istio, so the virtual machine becomes part of the mesh
- ensure that the cluster configuration is properly set
- start smm-agent in the background so that the system is always up-to-date
Run the following command:
smm-agent reconcile
The output should be similar to:
✓ reconciling host operating system
✓ configuration loaded config=/etc/smm/agent.yaml
✓ install-pilot-agent ❯ downloading and installing OS package component=pilot-agent, platform={linux amd64 deb 0xc00000c168}
✓ install-pilot-agent ❯ downloader reconciles with exponential backoff downloader={pilot-agent {linux amd64 deb 0xc00000c168} true 0xc0002725b0}
...
✓ systemd-ensure-smm-agent-running/systemctl ❯ starting service args=[smm-agent]
✓ systemd-ensure-smm-agent-running/systemctl/start ❯ executing command command=systemctl, args=[start smm-agent], timeout=5m0s
✓ systemd-ensure-smm-agent-running/systemctl/start ❯ command executed successfully command=systemctl, args=[start smm-agent], stdout=, stderr=
✓ changes were made to the host operating system
✓ reconciled host operating system
Verify connectivity
If the attachment was successful, a new WorkloadEntry has been created for the new node in the namespace of the WorkloadGroup (if you followed the examples, in the smm-demo
namespace). Verify it by completing the following steps.
-
Check that the new WorkloadEntry exists:
kubectl get workloadentries -n smm-demo
The output should be similar to:
NAME AGE ADDRESS analytics-v0-3.68.232.96-vm-network-1 2m40s 3.68.232.96
-
Check the healthiness of the service:
kubectl describe workloadentries analytics-v0-3.68.232.96-vm-network-1 -n smm-demo
The output should be similar to:
Name: analytics-v0-3.68.232.96-vm-network-1 Namespace: smm-demo Labels: app=analytics ... Status: Conditions: Last Probe Time: 2022-04-01T05:47:47.472143851Z Last Transition Time: 2022-04-01T05:47:47.472144917Z Status: True Type: Healthy
-
On the Service Mesh Manager dashboard, navigate to MENU > TOPOLOGY and verify that the VM is visible and that it is getting traffic. If you have performed this procedure on a clean installation of the Service Mesh Manager demo application, the difference on the topology view of the smm-demo namespace is that the analytics-v1 workload is now running on a virtual machine (indicated by the blue icon on the workload), and should look similar to this: