doc: add doc for using the instance hw spec flags

anjannath · adrianriobo · commit b9f1dc9d9903 · 2024-12-12T11:21:25.000+01:00
this also updates the command help o/p in the existing docs
so that it includes the `--cpus`, `--memory`, `--arch`  and
`--nested-virt` flags
diff --git a/docs/aws/fedora.md b/docs/aws/fedora.md
@@ -11,16 +11,23 @@ create
 
 Usage:
   mapt aws fedora create [flags]
-
 Flags:
-      --airgap                       if this flag is set the host will be created as airgap machine. Access will done through a bastion
-      --arch string                  architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
-      --conn-details-output string   path to export host connection information (host, username and privateKey)
-  -h, --help                         help for create
-      --spot                         if this flag is set the host will be created only on the region set by the AWS Env (AWS_DEFAULT_REGION)
-      --tags stringToString          tags to add on each resource (--tags name1=value1,name2=value2) (default [])
-      --version string               version for the Fedora Cloud OS (default "40")
-      --vm-types strings             set an specific set of vm-types. Note vm-type should match requested arch. Also if --spot flag is used set at least 3 types
+      --airgap                            if this flag is set the host will be created as airgap machine. Access will done through a bastion
+      --arch string                       architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
+      --conn-details-output string        path to export host connection information (host, username and privateKey)
+      --cpus int32                        Number of CPUs for the cloud instance (default 8)
+      --ghactions-runner-labels strings   List of labels separated by comma to be added to the self-hosted runner
+      --ghactions-runner-name string      Name for the Github Actions Runner
+      --ghactions-runner-repo string      Full URL of the repository where the Github Actions Runner should be registered
+      --ghactions-runner-token string     Token needed for registering the Github Actions Runner token
+  -h, --help                              help for create
+      --install-ghactions-runner          Install and setup Github Actions runner in the instance
+      --memory int32                      Amount of RAM for the cloud instance in GiB (default 64)
+      --nested-virt                       Use cloud instance that has nested virtualization support
+      --spot                              if this flag is set the host will be created only on the region set by the AWS Env (AWS_DEFAULT_REGION)
+      --tags stringToString               tags to add on each resource (--tags name1=value1,name2=value2) (default [])
+      --version string                    version for the Fedora Cloud OS (default "40")
+      --vm-types strings                  set an specific set of vm-types and ignore any CPUs, Memory, Arch parameters set. Note vm-type should match requested arch. Also if --spot flag is used set at least 3 types.
 
 Global Flags:
       --backed-url string     backed for stack state. Can be a local path with format file:///path/subpath or s3 s3://existing-bucket
@@ -54,4 +61,4 @@ podman run -d --name mapt-rhel \
             --project-name mapt-fedora \
             --backed-url file:///workspace \
             --conn-details-output /workspace
-```
+```
diff --git a/docs/aws/rhel.md b/docs/aws/rhel.md
@@ -18,13 +18,22 @@ Flags:
       --airgap                            if this flag is set the host will be created as airgap machine. Access will done through a bastion
       --arch string                       architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
       --conn-details-output string        path to export host connection information (host, username and privateKey)
+      --cpus int32                        Number of CPUs for the cloud instance (default 8)
+      --ghactions-runner-labels strings   List of labels separated by comma to be added to the self-hosted runner
+      --ghactions-runner-name string      Name for the Github Actions Runner
+      --ghactions-runner-repo string      Full URL of the repository where the Github Actions Runner should be registered
+      --ghactions-runner-token string     Token needed for registering the Github Actions Runner token
   -h, --help                              help for create
+      --install-ghactions-runner          Install and setup Github Actions runner in the instance
+      --memory int32                      Amount of RAM for the cloud instance in GiB (default 64)
+      --nested-virt                       Use cloud instance that has nested virtualization support
       --rh-subscription-password string   password to register the subscription
       --rh-subscription-username string   username to register the subscription
       --snc                               if this flag is set the RHEL will be setup with SNC profile. Setting up all requirements to run https://github.com/crc-org/snc
       --spot                              if this flag is set the host will be created only on the region set by the AWS Env (AWS_DEFAULT_REGION)
       --tags stringToString               tags to add on each resource (--tags name1=value1,name2=value2) (default [])
       --version string                    version for the RHEL OS (default "9.4")
+      --vm-types strings                  set an specific set of vm-types and ignore any CPUs, Memory, Arch parameters set. Note vm-type should match requested arch. Also if --spot flag is used set at least 3 types.
 
 Global Flags:
       --backed-url string     backed for stack state. Can be a local path with format file:///path/subpath or s3 s3://existing-bucket
@@ -75,4 +84,4 @@ podman run -d --name mapt-rhel \
             --rh-subscription-password XXXX \
             --rh-subscription-username XXXXX \
             --conn-details-output /workspace
-```
+```
diff --git a/docs/aws/windows.md b/docs/aws/windows.md
@@ -76,4 +76,4 @@ podman run -d --name mapt-rhel \
             --project-name mapt-windows \
             --backed-url file:///workspace \
             --conn-details-output /workspace
-```
+```
diff --git a/docs/azure/fedora.md b/docs/azure/fedora.md
@@ -33,7 +33,7 @@ Flags:
       --spot-eviction-tolerance string   if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
       --tags stringToString              tags to add on each resource (--tags name1=value1,name2=value2) (default [])
       --username string                  username for general user. SSH accessible + rdp with generated password (default "rhqp")
-      --version string                   linux version. Version should be formated as X.Y (Major.minor)
+      --version string                   linux version. Version should be formated as X.Y (Major.minor) (default "40.0")
       --vmsize strings                   set specific size for the VM and ignore any CPUs, Memory and Arch parameters set. Type requires to allow nested virtualization
 
 Global Flags:
diff --git a/docs/azure/rhel.md b/docs/azure/rhel.md
@@ -22,18 +22,28 @@ create
 
 Usage:
   mapt azure rhel create [flags]
-
 Flags:
-      --arch string                      architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
-      --conn-details-output string       path to export host connection information (host, username and privateKey)
-  -h, --help                             help for create
-      --location string                  If spot is passed location will be calculated based on spot results. Otherwise localtion will be used to create resources. (default "West US")
-      --spot                             if spot is set the spot prices across all regions will be cheked and machine will be started on best spot option (price / eviction)
-      --spot-eviction-tolerance string   if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
-      --tags stringToString              tags to add on each resource (--tags name1=value1,name2=value2) (default [])
-      --username string                  username for general user. SSH accessible + rdp with generated password (default "rhqp")
-      --version string                   linux version. Version should be formmated as X.Y (Major.minor) (default "9.4")
-      --vmsize string                    size for the VM. Type requires to allow nested virtualization (default "Standard_D8as_v5")
+      --arch string                       architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
+      --conn-details-output string        path to export host connection information (host, username and privateKey)
+      --cpus int32                        Number of CPUs for the cloud instance (default 8)
+      --ghactions-runner-labels strings   List of labels separated by comma to be added to the self-hosted runner
+      --ghactions-runner-name string      Name for the Github Actions Runner
+      --ghactions-runner-repo string      Full URL of the repository where the Github Actions Runner should be registered
+      --ghactions-runner-token string     Token needed for registering the Github Actions Runner token
+  -h, --help                              help for create
+      --install-ghactions-runner          Install and setup Github Actions runner in the instance
+      --location string                   If spot is passed location will be calculated based on spot results. Otherwise localtion will be used to create resources. (default "West US")
+      --memory int32                      Amount of RAM for the cloud instance in GiB (default 64)
+      --nested-virt                       Use cloud instance that has nested virtualization support
+      --rh-subscription-password string   password to register the subscription
+      --rh-subscription-username string   username to register the subscription
+      --snc                               if this flag is set the RHEL will be setup with SNC profile. Setting up all requirements to run https://github.com/crc-org/snc
+      --spot                              if spot is set the spot prices across all regions will be cheked and machine will be started on best spot option (price / eviction)
+      --spot-eviction-tolerance string    if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
+      --tags stringToString               tags to add on each resource (--tags name1=value1,name2=value2) (default [])
+      --username string                   username for general user. SSH accessible + rdp with generated password (default "rhqp")
+      --version string                    linux version. Version should be formated as X.Y (Major.minor) (default "9.4")
+      --vmsize strings                    set specific size for the VM and ignore any CPUs, Memory and Arch parameters set. Type requires to allow nested virtualization
 
 Global Flags:
       --backed-url string     backed for stack state. Can be a local path with format file:///path/subpath or s3 s3://existing-bucket
diff --git a/docs/azure/ubuntu.md b/docs/azure/ubuntu.md
@@ -22,17 +22,20 @@ create
 
 Usage:
   mapt azure ubuntu create [flags]
-
 Flags:
+      --arch string                      architecture for the machine. Allowed x86_64 or arm64 (default "x86_64")
       --conn-details-output string       path to export host connection information (host, username and privateKey)
+      --cpus int32                       Number of CPUs for the cloud instance (default 8)
   -h, --help                             help for create
       --location string                  If spot is passed location will be calculated based on spot results. Otherwise localtion will be used to create resources. (default "West US")
+      --memory int32                     Amount of RAM for the cloud instance in GiB (default 64)
+      --nested-virt                      Use cloud instance that has nested virtualization support
       --spot                             if spot is set the spot prices across all regions will be cheked and machine will be started on best spot option (price / eviction)
       --spot-eviction-tolerance string   if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
       --tags stringToString              tags to add on each resource (--tags name1=value1,name2=value2) (default [])
       --username string                  username for general user. SSH accessible + rdp with generated password (default "rhqp")
-      --version string                   ubunutu version. Tore info at https://documentation.ubuntu.com/azure/en/latest/azure-how-to/instances/find-ubuntu-images (default "24_04")
-      --vmsize string                    size for the VM. Type requires to allow nested virtualization (default "Standard_D8as_v5")
+      --version string                   linux version. Version should be formated as X.Y (Major.minor) (default "24.04")
+      --vmsize strings                   set specific size for the VM and ignore any CPUs, Memory and Arch parameters set. Type requires to allow nested virtualization
 
 Global Flags:
       --backed-url string     backed for stack state. Can be a local path with format file:///path/subpath or s3 s3://existing-bucket
diff --git a/docs/azure/windows.md b/docs/azure/windows.md
@@ -35,20 +35,27 @@ create
 
 Usage:
   mapt azure windows create [flags]
-
 Flags:
-      --admin-username string            username for admin user. Only rdp accessible within generated password (default "rhqpadmin")
-      --conn-details-output string       path to export host connection information (host, username and privateKey)
-  -h, --help                             help for create
-      --location string                  If spot is passed location will be calculated based on spot results. Otherwise localtion will be used to create resources. (default "West US")
-      --profile strings                  comma seperated list of profiles to apply on the target machine. Profiles available: crc
-      --spot                             if spot is set the spot prices across all regions will be cheked and machine will be started on best spot option (price / eviction)
-      --spot-eviction-tolerance string   if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
-      --tags stringToString              tags to add on each resource (--tags name1=value1,name2=value2) (default [])
-      --username string                  username for general user. SSH accessible + rdp with generated password (default "rhqp")
-      --vmsize string                    size for the VM. Type requires to allow nested virtualization (default "Standard_D8s_v5")
-      --windows-featurepack string       windows feature pack (default "23h2-pro")
-      --windows-version string           Major version for windows desktop 10 or 11 (default "11")
+      --admin-username string             username for admin user. Only rdp accessible within generated password (default "rhqpadmin")
+      --conn-details-output string        path to export host connection information (host, username and privateKey)
+      --cpus int32                        Number of CPUs for the cloud instance (default 8)
+      --ghactions-runner-labels strings   List of labels separated by comma to be added to the self-hosted runner
+      --ghactions-runner-name string      Name for the Github Actions Runner
+      --ghactions-runner-repo string      Full URL of the repository where the Github Actions Runner should be registered
+      --ghactions-runner-token string     Token needed for registering the Github Actions Runner token
+  -h, --help                              help for create
+      --install-ghactions-runner          Install and setup Github Actions runner in the instance
+      --location string                   If spot is passed location will be calculated based on spot results. Otherwise localtion will be used to create resources. (default "West US")
+      --memory int32                      Amount of RAM for the cloud instance in GiB (default 64)
+      --nested-virt                       Use cloud instance that has nested virtualization support
+      --profile strings                   comma seperated list of profiles to apply on the target machine. Profiles available: crc
+      --spot                              if spot is set the spot prices across all regions will be cheked and machine will be started on best spot option (price / eviction)
+      --spot-eviction-tolerance string    if spot is enable we can define the minimum tolerance level of eviction. Allowed value are: lowest, low, medium, high or highest (default "lowest")
+      --tags stringToString               tags to add on each resource (--tags name1=value1,name2=value2) (default [])
+      --username string                   username for general user. SSH accessible + rdp with generated password (default "rhqp")
+      --vmsize strings                    set specific size for the VM and ignore any CPUs, Memory and Arch parameters set. Type requires to allow nested virtualization
+      --windows-featurepack string        windows feature pack (default "23h2-pro")
+      --windows-version string            Major version for windows desktop 10 or 11 (default "11")
 
 Global Flags:
       --backed-url string     backed for stack state. Can be a local path with format file:///path/subpath or s3 s3://existing-bucket
diff --git a/docs/instance-selection.md b/docs/instance-selection.md
@@ -0,0 +1,24 @@
+# Instance Selection based on hardware specification
+
+## Overview
+
+With `mapt` users can select the type of instance to create on the cloud provider by providing its specification, i.e CPUs count, CPU architecture, Memory size
+and support for nested virtualization.
+
+There are flags `--cpus`, `--memory`, `--arch` and `--nested-virt` for most of the `mapt <provider> <profile | os> create` with exception of `mac` and `windows` OS for AWS
+and `aks` profile for Azure.
+
+The flags also have sensible default values, if an instance type satisfying the requested hardware specs is not offered by the provider, it'll use the default
+values to create a machine.
+
+## Creating a fedora VM on AWS with user provided specs
+
+As an example we can use the `--cpus`, `--arch` and `--memory` flags with the `mapt aws fedora create` command to create an arm machine with 8 cpus and 64GB of RAM:
+```
+$ mapt aws fedora create --spot \
+    --arch arm64 \
+    --cpus 8 --memory 64 \
+    --project-name aws-mapt-fedora-test \
+    --backed-url file:///home/mapt/workspace \
+    --conn-details-output /tmp/fedora
+```
