Update the examples folder (#733)

* add documentation for rhel os and kubevirt cloud provider
Signed-off-by: Moath Qasim <[email protected]>

Signed-off-by: Moath Qasim <[email protected]>

* addressing PR review
Signed-off-by: Moath Qasim <[email protected]>

Signed-off-by: Moath Qasim <[email protected]>

* updating machine-deployment manifests
Signed-off-by: Moath Qasim <[email protected]>

Signed-off-by: Moath Qasim <[email protected]>

Author: moadqassem

docs/kubevirt.md

@@ -8,7 +8,29 @@ are some things you need to keep in mind:
 
 * The machine-controller will create `VMIs` that have the same name as the underlying `machine`. To
 avoid collisions, use one namespace per cluster that runs the `machine-controller`
-* Service CIDR range: The CIDR ranges of the cluster that runs Kubevirt and the cluster that hosts the machine-controller must not overlap, otherwise routing of services that run in the kubevirt cluster
- wont work anymore. THis is especially important for the DNS ClusterIP.
-* In order to create VirtualMachineInstances deployed with CoreOS, you should use `coreos_production_qemu_image.img.bz2`, which can be found in the stable releases
-[here](https://stable.release.core-os.net/amd64-usr/).
+* Service CIDR range: The CIDR ranges of the cluster that runs Kubevirt and the cluster that hosts the machine-controller must not overlap,
+otherwise routing of services that run in the kubevirt cluster wont work anymore. This is especially important for the DNS ClusterIP.
+* In order to create VirtualMachineInstances deployed with CoreOS, you should use `coreos_production_qemu_image.img.bz2`, which can be found in 
+the stable releases [here](https://stable.release.core-os.net/amd64-usr/).
+
+## Serving Supported Images
+
+For KubeVirt clusters, we use Containerized Data Importer (CDI), which is is a utility to import, upload and clone 
+Virtual Machine images for use with KubeVirt. At a high level, a persistent volume claim (PVC), which defines VM-suitable 
+storage via a storage class, is created.
+
+The Containerized Data Importer is capable of performing certain functions that streamline its use with KubeVirt. It automatically 
+decompresses gzip and xz files, and un-tar’s tar archives. Also, qcow2 images are converted into the raw format which is required by KubeVirt, 
+resulting in the final file being a simple .img file.
+
+Supported file formats are:
+
+- Tar archive
+- Gzip compressed file
+- XZ compressed file
+- Raw image data
+- ISO image data
+- Qemu qcow2 image data
+
+KubeVirt reads those images from an http endpoint which is passed to the `MachineDeployment` spec. The field that should be used 
+for to import those images is `sourceURL`.

docs/rhel-custom-image.md

@@ -0,0 +1,55 @@
+# RedHat Enterprise Linux
+
+Cloud providers which are listed below, support using rhel as an operating system option: 
+
+- AWS 
+- Azure
+- GCE
+- KubeVirt
+- Openstack
+- vSphere
+
+####  AWS:
+For amazon web service cloud provider, First of all the RHEL gold image AMIs have to be enabled from the 
+[RedHat Customer Portal](https://access.redhat.com/public-cloud/aws) (this requires a [cloud-provider subscription](https://access.redhat.com/public-cloud)).
+.Afterwards, new images will be added to the aws account under EC2-> Images-> AMIs-> Private Images. Once the images are available in the aws account, 
+the image id for rhel(at the moment we only support 8.x.x versions) should be then added to the `MachineDeployment` spec to the field `ami`.
+
+####  Azure
+RedHat provides images for Azure, [documentation](https://access.redhat.com/articles/uploading-rhel-image-to-azure) is available on RH customer portal.
+The `MachineDeployment` field `.spec.template.spec.providerSpec.value.cloudProviderSpec.imageID` should reference the ID of the uploaded VM.
+
+**Note:** 
+Azure rhel images starting from 7.6.x don't support cloud-init as their documentation states [here](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/using-cloud-init#rhel).
+Thus, custom images can be used with a cloud-init pre-installed to solve this issue. Follow this [documentation](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/cloudinit-prepare-custom-image)
+to prepare an image with cloud-init support.
+ 
+####  GCE
+RedHat also provides Gold Access Image for GCE and those can be fetched just like aws and azure. The `MachineDeployment` field `.spec.template.spec.providerSpec.value.cloudProviderSpec.customImage` should reference the ID of the used image.
+
+**Note:** 
+Same as for Azure, rhel images in GCE don't support cloud-init. Thus, custom images can be used with a cloud-init pre-installed
+to solve this issue. Follow this [documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/deploying_red_hat_enterprise_linux_8_on_public_cloud_platforms/assembly_deploying-a-rhel-image-as-a-compute-engine-instance-on-google-cloud-platform_deploying-a-virtual-machine-on-aws) to upload custom rhel
+images in order to use it for running rhel instances.
+
+####  KubeVirt
+In order to create machines which run rhel as an operating system in KubeVirt cloud provider, the image should be available and fetched
+via an endpoint. This endpoint should be then added to the `MachineDeployment` field `.spec.template.spec.providerSpec.value.cloudProviderSpec.sourceURL`. For more information about 
+the supported images please refer to this documentation from KubeVirt CDI [here](https://kubevirt.io/2018/containerized-data-importer.html)
+
+####  Openstack
+Once RHEL images(e.g: Red Hat Enterprise Linux 8.x KVM Guest Image) is uploaded to openstack, the image name should be used in 
+the `MachineDeployment` field `.spec.template.spec.providerSpec.value.cloudProviderSpec.image`.
+
+####  vSphere
+To rhel os for vSphere instance, a template for the rhel machine should be created or a clone from a rhel machine. To upload rhel 
+image to vSphere, follow these steps to create instances from a cloned machine:
+
+- Download Red Hat Enterprise Linux 8.x KVM Guest Image from Red Hat Customer Portal.
+- The image has the format `qcow2` thus should be converted to `vmdk` by running the command: `qemu-img convert -f qcow2 rhel.qcow2 -O vmdk newRHEL.vmdk`
+- Run `vmkfstools -i myImage.vmdk outputName.vmdk -d thin To ensure that the` to ensure that, the `vmdk` is ESXi compatible.
+- Upload the image to vSphere Datastore. Preferably use [`govc`](https://github.com/vmware/govmomi/blob/master/govc/USAGE.md#datastoreupload)
+- Once the image is uploaded create a new instance using that image. During the machine creation process, at the `Customize Hardware`
+step, press on ADD NEW DEVICE and select Existing Hard Disk. 
+- In the Existing Hard Disk wizard select the rhel image file and then create the instance.
+- Use the instance name to clone rhel machine by updating the `MachineDeployment` field `.spec.template.spec.providerSpec.value.cloudProviderSpec.templateVMName`.

examples/alibaba-machinedeployment.yaml

@@ -51,12 +51,15 @@ spec:
                 key: accessKeySecret
             instanceType: "ecs.t1.xsmall"
             instanceName: "alibaba-instance"
+            internetMaxBandwidthOut: 10
             regionID: eu-central-1
-            imageID: "aliyun_2_1903_64_20G_alibase_20190829.vhd"
+            vSwitchID: "vswitchID"
+            zoneID: eu-central-1a
             diskType: "cloud_efficiency"
             diskSize: "40"
           operatingSystem: "ubuntu"
           operatingSystemSpec:
             distUpgradeOnBoot: false
+            disableAutoUpdate: true
       versions:
         kubelet: 1.13.1

examples/aws-machinedeployment.yaml

@@ -59,16 +59,18 @@ spec:
             diskSize: 50
             diskType: "gp2"
             ebsVolumeEncrypted: false
+            ami: "my-custom-ami"
             ## Only application if diskType = io1
             diskIops: 500
             # Assign a public IP to this instance. Default: true
             assignPublicIP: false
             tags:
               "KubernetesCluster": "6qsm86c2d"
-          # Can be 'ubuntu', 'coreos' ,'centos' or 'sles'
+          # Can be 'ubuntu', 'coreos' ,'centos', `rhel` or 'sles'
           operatingSystem: "coreos"
           operatingSystemSpec:
             disableAutoUpdate: true
+            distUpgradeOnBoot: false
             # 'rhelSubscriptionManagerUser' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_USER`
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`

examples/azure-machinedeployment.yaml

@@ -64,18 +64,21 @@ spec:
                 key: subscriptionID
             location: "westeurope"
             resourceGroup: "<< YOUR_RESOURCE_GROUP >>"
-            vmSize: "Standard_B1ms"
+            vmSize: "Standard_F2"
             # optional disk size values in GB. If not set, the defaults for the vmSize will be used.
             osDiskSize: 30
             dataDiskSize: 30
             vnetName: "<< VNET_NAME >>"
             subnetName: "<< SUBNET_NAME >>"
             routeTableName: "<< ROUTE_TABLE_NAME >>"
+            imageID: "myImageID"
             assignPublicIP: false
             securityGroupName: my-security-group
+          # Can be 'ubuntu', 'coreos' ,'centos' or 'rhel'
           operatingSystem: "coreos"
           operatingSystemSpec:
             distUpgradeOnBoot: false
+            disableAutoUpdate: true
             # 'rhelSubscriptionManagerUser' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_USER`
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`

examples/gce-machinedeployment.yaml

@@ -62,7 +62,8 @@ spec:
               "kubernetes_cluster": "my-cluster"
             # Whether to assign a public IP Address. Required for Internet access
             assignPublicIPAddress: true
-          # Can be 'ubuntu' or 'coreos'
+            customImage: "myCustomImage"
+          # Can be 'ubuntu' 'rhel' or 'coreos'
           operatingSystem: "coreos"
           operatingSystemSpec:
             disableAutoUpdate: true

examples/openstack-machinedeployment.yaml

@@ -112,6 +112,7 @@ spec:
           operatingSystem: "ubuntu"
           operatingSystemSpec:
             distUpgradeOnBoot: true
+            disableAutoUpdate: true
             # 'rhelSubscriptionManagerUser' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_USER`
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`

examples/vsphere-datastore-cluster-machinedeployment.yaml

@@ -66,6 +66,7 @@ spec:
           operatingSystem: "ubuntu"
           operatingSystemSpec:
             distUpgradeOnBoot: false
+            disableAutoUpdate: true
             # 'rhelSubscriptionManagerUser' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_USER`
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`

examples/vsphere-machinedeployment.yaml

@@ -66,6 +66,7 @@ spec:
           operatingSystem: "ubuntu"
           operatingSystemSpec:
             distUpgradeOnBoot: false
+            disableAutoUpdate: true
             # 'rhelSubscriptionManagerUser' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_USER`
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`

test/e2e/provisioning/testdata/machinedeployment-vsphere-datastore-cluster.yaml

@@ -45,5 +45,8 @@ spec:
             rhelSubscriptionManagerUser: "<< RHEL_SUBSCRIPTION_MANAGER_USER >>"
             # 'rhelSubscriptionManagerPassword' is only used for rhel os and can be set via env var `RHEL_SUBSCRIPTION_MANAGER_PASSWORD`
             rhelSubscriptionManagerPassword: "<< RHEL_SUBSCRIPTION_MANAGER_PASSWORD >>"
+            # 'rhsmOfflineToken' if it was provided red hat systems subscriptions will be removed upon machines deletions, and if wasn't
+            # provided the rhsm will be disabled and any created subscription won't be removed automatically
+            rhsmOfflineToken: "<< REDHAT_SUBSCRIPTIONS_OFFLINE_TOKEN >>"
       versions:
         kubelet: "<< KUBERNETES_VERSION >>"