CNV-2705 Creating and exposing a VM-backed service

modules/virt-creating-a-service-from-a-virtual-machine.adoc

@@ -0,0 +1,232 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc
+
+[id="virt-creating-a-service-from-a-virtual-machine_{context}"]
+
+= Creating a service from a virtual machine
+
+Create a service from a running virtual machine by first creating a `Service` object to expose the virtual machine.
+
+The `ClusterIP` service type exposes the virtual machine internally, within the cluster. The `NodePort` or `LoadBalancer` service types expose the virtual machine externally, outside of the cluster.
+
+This procedure presents an example of how to create, connect to, and expose a `Service` object of `type: ClusterIP` as a virtual machine-backed service.
+
+[NOTE]
+====
+`ClusterIP` is the default service `type`, if the service `type` is not specified.
+====
+
+.Procedure
+
+. Edit the virtual machine YAML as follows:
++
+
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1alpha3
+kind: VirtualMachine
+metadata:
+  name: vm-ephemeral
+  namespace: example-namespace
+spec:
+  running: false
+  template:
+    metadata:
+      labels:
+        special: key <1>
+    spec:
+      domain:
+        devices:
+          disks:
+            - name: containerdisk
+              disk:
+                bus: virtio
+            - name: cloudinitdisk
+              disk:
+                bus: virtio
+          interfaces:
+          - masquerade: {}
+            name: default
+        resources:
+          requests:
+            memory: 1024M
+      networks:
+        - name: default
+          pod: {}
+      volumes:
+        - name: containerdisk
+          containerDisk:
+            image: kubevirt/fedora-cloud-container-disk-demo
+        - name: cloudinitdisk
+          cloudInitNoCloud:
+            userData: |
+              #!/bin/bash
+              echo "fedora" | passwd fedora --stdin
+----
+<1> Add the label `special: key` in the `spec.template.metadata.labels` section.
++
+
+[NOTE]
+====
+Labels on a virtual machine are passed through to the pod. The labels on
+the `VirtualMachine`, for example `special: key`, must match the labels in
+the `Service` YAML `selector` attribute, which you create later
+in this procedure.
+====
+
+. Save the virtual machine YAML to apply your changes.
+
+. Edit the `Service` YAML to configure the settings necessary to create and expose the `Service` object:
++
+
+[source,yaml]
+----
+apiVersion: v1
+kind: Service
+metadata:
+  name: vmservice <1>
+  namespace: example-namespace <2>
+spec:
+  ports:
+  - port: 27017
+    protocol: TCP
+    targetPort: 22 <3>
+  selector:
+    special: key <4>
+  type: ClusterIP <5>
+----
+<1> Specify the `name` of the service you are creating and exposing.
+<2> Specify `namespace` in the `metadata` section of the `Service` YAML that corresponds to the `namespace` you specify in the virtual machine YAML.
+<3> Add `targetPort: 22`, exposing the service on SSH port `22`.
+<4> In the `spec` section of the `Service` YAML, add `special: key` to the `selector` attribute, which corresponds to the `labels` you added in the virtual machine YAML configuration file.
+<5> In the `spec` section of the `Service` YAML, add `type: ClusterIP` for a
+ClusterIP service. To create and expose other types of services externally, outside of the cluster, such as `NodePort` and `LoadBalancer`, replace
+`type: ClusterIP` with `type: NodePort` or `type: LoadBalancer`, as appropriate.
++
+
+. Save the `Service` YAML to store the service configuration.
+. Create the `ClusterIP` service:
++
+
+[source,terminal]
+----
+$ oc create -f <service_name>.yaml
+----
+
++
+. Start the virtual machine. If the virtual machine is already running, restart it.
++
+
++
+. Query the `Service` object to verify it is available and is configured with type `ClusterIP`.
++
+
+.Verification steps
+* Run the `oc get service` command, specifying the `namespace` that you reference in the virtual machine and `Service` YAML files.
++
+
+[source, terminal]
+----
+$ oc get service -n example-namespace
+----
++
+
+.Example output
+[source, terminal]
+----
+NAME        TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)     AGE
+vmservice   ClusterIP   172.30.3.149   <none>        27017/TCP   2m
+----
++
+
+** As shown from the output, `vmservice` is running.
+** The `TYPE` displays as `ClusterIP`, as you specified in the `Service` YAML.
+
+. Establish a connection to the virtual machine that you want to use to back your service. Connect from an object inside the cluster, such as another virtual machine.
++
+
+.. Edit the virtual machine YAML as follows:
++
+
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1alpha3
+kind: VirtualMachine
+metadata:
+  name: vm-connect
+  namespace: example-namespace
+spec:
+  running: false
+  template:
+    spec:
+      domain:
+        devices:
+          disks:
+            - name: containerdisk
+              disk:
+                bus: virtio
+            - name: cloudinitdisk
+              disk:
+                bus: virtio
+          interfaces:
+          - masquerade: {}
+            name: default
+        resources:
+          requests:
+            memory: 1024M
+      networks:
+        - name: default
+          pod: {}
+      volumes:
+        - name: containerdisk
+          containerDisk:
+            image: kubevirt/fedora-cloud-container-disk-demo
+        - name: cloudinitdisk
+          cloudInitNoCloud:
+            userData: |
+              #!/bin/bash
+              echo "fedora" | passwd fedora --stdin
+----
++
+
+.. Run the `oc create` command to create a second virtual machine, where `file.yaml` is the name of the virtual machine YAML:
++
+
+[source,terminal]
+----
+$ oc create -f <file.yaml>
+----
++
+
+.. Start the virtual machine.
+
+.. Connect to the virtual machine by running the following `virtctl` command:
++
+
+[source,terminal]
+----
+$ virtctl -n example-namespace console <new-vm-name>
+----
++
+
+[NOTE]
+====
+For service type `LoadBalancer`, use the `vinagre` client to connect your
+virtual machine by using the public IP and port.
+External ports are dynamically allocated when using service type
+`LoadBalancer`.
+====
++
+
+.. Run the `ssh` command to authenticate the connection, where `172.30.3.149` is the ClusterIP of the service and `fedora` is the user name of the virtual machine:
++
+
+[source,terminal]
+----
+$ ssh fedora@172.30.3.149 -p 27017
+----
++
+
+.Verification steps
+* You receive the command prompt of the virtual machine backing the service you want to expose. You now have a service backed by a running virtual machine.

virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc

@@ -30,3 +30,7 @@ include::modules/virt-networking-wizard-fields-web.adoc[leveloffset=+2]
 include::modules/virt-template-vm-config.adoc[leveloffset=+2]
 
 include::modules/virt-template-windows-vmi.adoc[leveloffset=+2]
+
+include::modules/virt-creating-a-service-from-a-virtual-machine.adoc[leveloffset=+1]
+.Additional resources
+* xref:../../../networking/configuring_ingress_cluster_traffic/configuring-externalip.adoc#configuring-externalip[Configuring external IPs]