diff --git a/src/docs/ocean/_media/eks-manage-vngs.png b/src/docs/ocean/_media/eks-manage-vngs.png new file mode 100644 index 0000000000..f5f9398365 Binary files /dev/null and b/src/docs/ocean/_media/eks-manage-vngs.png differ diff --git a/src/docs/ocean/tutorials/manage-virtual-node-groups.md b/src/docs/ocean/tutorials/manage-virtual-node-groups.md index 2470de4807..2eb19618b1 100644 --- a/src/docs/ocean/tutorials/manage-virtual-node-groups.md +++ b/src/docs/ocean/tutorials/manage-virtual-node-groups.md @@ -1,75 +1,100 @@ -# Manage Virtual Node Groups +# Manage AWS Virtual Node Groups -[Virtual Node Groups](ocean/features/launch-specifications.md) (VNGs) provide a single layer of abstraction that enables you to manage different types of workloads on the same cluster. +Cloud service provider relevance: AWS Kubernetes -This tutorial describes how to create, view, edit, and delete VNGs in Ocean. +This topic describes how to work with [virtual node groups (VNGs)](ocean/features/launch-specifications.md) for AWS Kubernetes. -## Relevance - -The following procedures are relevant for users of Ocean Kubernetes on AWS. +Virtual node groups provide a single layer of abstraction that enables you to manage different types of workloads on the same cluster. ## Prerequisites -- An Ocean cluster up and running +An Ocean cluster is up and running. + +## Access the Virtual Node Groups Tab + +1. Click **Ocean > Cloud Clusters** in the left main menu. +2. Select a cluster from the list of clusters. +3. Click the **virtual node groups** tab + +The virtual node groups tab lets you track live data per virtual node group. You can review the resource allocation, number of nodes and pods running, and other information about the virtual node groups. + +![aws_vng-aws-list](https://github.com/user-attachments/assets/6bd98303-54ee-44c4-9f96-4bc89b7faa5f) -## Create a VNG +The virtual node groups Summary List displays the following columns: -This procedure describes how to create a VNG from scratch. +* ID: The identification code of the virtual node group. +* Name: The user-defined name of the virtual node group. (If a virtual node group were defined without a name, it would appear as an Unnamed virtual node group.) +* Resource Allocation: Percent of defined resources (CPU, Memory, and GPU) currently running on nodes from this virtual node group. +* Running Pods: Number of pods the VNG currently uses. +* Max Nodes: The maximum number of nodes defined for the virtual node group. +* Node Count: Number of nodes the VNG currently uses. +* Node Labels: Number of node labels the virtual node group uses. +* Node Taints: Number of taints the virtual node group uses. +* Tags: Number of tags the virtual node group uses. -1. In the console, go to Ocean/Cloud Clusters and click the Ocean Cluster you want to add a VNG to. -2. Click the Virtual Node Groups tab. +> Notes: +> - Click the three dots on the right to select which columns to display in the list. +> - Use the search box to filter items in the list or search for a specific virtual node group. +> - To view the configuration details of a virtual node group, click on its Name. - +## Create a Virtual Node Group -3. Click Create New Virtual Node Group. +1. Click **Create VNG** in the virtual node groups tab. - +![import-or-manual](https://github.com/user-attachments/assets/63cb8805-eb79-449c-858e-dc3d483bb473) -4. Click Configure Manually or choose to import from an existing [Autoscaling Group](ocean/tutorials/manage-virtual-node-groups?id=create-a-vng-from-an-asg) (AWS) or Node Pool (AKS and GKE). -5. Click Continue. +2. Select one of these options: + * Click **Configure Manually** + * For AWS Kubernetes only, select to import from an existing [Autoscaling Group](ocean/tutorials/manage-virtual-node-groups?id=create-a-vng-from-an-asg). + * For EKS only, select to import from an existing node group. +3. Click **Continue**. -When you choose Import, a one-time process occurs. Import copies values from the cloud provider node group entity to the Ocean configuration. Afterwards, there is no active connection between these two entities. Ocean will provision new VMs, not as part of a managed Kubernetes service of node group entities. +When you select Import, a one-time process occurs. Import copies values from the cloud provider node group entity to the Ocean configuration. Later, there is no active connection between these two entities. Ocean will provision new instance types, not as part of a managed Kubernetes service of node group entities. -### New Virtual Node Group Page +4. Review all the virtual node group parameters (listed below) and update if necessary before saving. -1. In the New Virtual Node Group page, enter the VNG parameters you want to customize. Parameters that are left blank use values from the default VNG, as indicated in the illustration below. -2. When you have finished customizing the VNG, click Save. The VNG parameters are described below. +>**Note**: +>- Parameters left blank use values from the default virtual node group. +>- To restore attributes to default (template) virtual node group values, click the **Restore to vng template values** for the field or list. - + ## Configuration Parameters -- Name: The name you assign to the new VNG. -- Image: The Amazon machine image (AMI) used for the VNG. -- Security Groups: The security groups that apply to the VNG. You can choose up to five groups as per the [AWS limitation](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-security-groups). -- Subnets: The subnets that apply to the VNG. You can choose multiple subnets. -- Root Volume Size: The root volume size in GiB. This field and blockDeviceMappings cannot be used in the same VNG. -- Instance Profile: The iamRole object applicable to the instance profile. -- User Data (Startup Script): The user data script to be set in Base64-encoded MIME. +* Name: The name you assign to the new virtual node group. +* Image: The Amazon machine image (AMI) used for the virtual node group. +* Security Groups: These are the security groups that apply to the virtual node group. As per the [AWS limitation](https://docs.aws.amazon.com/vpc/latest/userguide/amazon-vpc-limits.html#vpc-limits-security-groups), you can select up to five groups. +* Subnets: The subnets that apply to the virtual node group. You can choose multiple subnets. +* Root Volume Size: The root volume size in GiB. This field and `blockDeviceMappings` cannot be used in the same VNG. +* Instance Profile: The iamRole object that applies to the instance profile. +* User Data (Startup Script): User data script to set in Base64-encoded MIME. ### Node Selection Parameters -This section enables you to inform Ocean about the labels and taints that are set on the nodes. When they are set, Ocean will use them to choose the right VNG for a pending pod. +This section lets you inform Ocean about the labels and taints set on the nodes. When they are set, Ocean will use them to select the right VNG for a pending pod. -- Node Labels: Key/Value pairs defined on the Kubernetes nodes. -- Node [Taints](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/): Triplets of Key, Value, and Effect defined on the Kubernetes nodes. +* Node Labels: Key/Value pairs defined on the Kubernetes nodes. +* Node [Taints](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/): Triplets of Key, Value, and Effect defined on the Kubernetes nodes. > **Important**: **You must enter custom labels in both the VNG Node Selection configuration and in the VNG User Data (Startup Script) configuration for the labels to take full effect. For Kubernetes user data, see [Create Custom Labels](https://docs.spot.io/ocean/tutorials/create-custom-labels).** ## Advanced Parameters -- Maximum Nodes: The upper limit number of instances that you can scale up to. -- Block Device Mapping: Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the spec at the same time. -- Tags: Key and Value pairs used to apply tags on the EC2 machine. Specific tags can be applied per VNG. -- Headroom: Spare resource capacity management enabling fast assignment of Pods without waiting for new resources to launch. -- Reserve: The number of units to retain as headroom, where each unit has the defined headroom CPU and memory. -- CPU (millicpu): Optionally configure the number of CPUs to allocate to the headroom. CPUs are denoted in millicores, where 1000 millicores = 1 vCPU. -- Memory (MiB): Optionally configure the amount of memory (MiB) to allocate to the headroom. -- GPUs: Optionally configure the number of GPUs to allocate for headroom unit. +* Maximum Nodes: The upper limit number of instances that you can scale up to. +* Minimum Nodes: +* Spot %: The percentage of spot nodes used in the virtual node group. +* Restrict Scale-Down. When turned on, Ocean will not scale down nodes in this virtual node group for bin-packing purposes unless they are empty. +* Block Device Mapping: Block devices that are exposed to the instance. You can specify virtual devices and EBS volumes. This parameter and rootVolumeSize cannot be in the spec simultaneously. +* Tags: Key and Value pairs are used to apply tags to the EC2 machine. Specific tags can be applied per VNG. +* Headroom: Spare resource capacity management enabling fast assignment of Pods without waiting for new resources to launch. + * Reserve: The number of units to retain as headroom, each with the defined headroom CPU and memory. + * CPU (millicpu): You can optionally configure the number of CPUs to allocate to the headroom. CPUs are denoted in millicuries, where 1000 millicuries = 1 vCPU. + * Memory (MiB): You can optionally configure the amount of memory (MiB) to allocate to the headroom. + * GPUs: Optionally configure the number of GPUs to allocate for the headroom unit. ## Example: GPU Instance -If a pod requires a GPU instance, add the relevant GPU image in a VNG. Ocean will spin up instances accordingly. Specific labels are not required in this case. Example: +Add the relevant GPU image in a virtual node group if a pod requires a GPU instance. Ocean will spin up instances accordingly. Specific labels are not required in this case. Example: ``` resources: @@ -77,133 +102,86 @@ resources: nvidia.com/gpu: 1 ``` -You can use a node selector or node affinity that requires your GPU-based pods to select the specific VNG containing the GPU image, based on the custom node label configured in the GPU VNG. - -## Choose Instance Types per VNG - -To choose spot instance types for a specific VNG, do the following: - -1. Go to Clusters in the left menu tree and click the name of the relevant Ocean cluster. -2. Click the Virtual Node Groups tab and click the name of the relevant VNG in the list. - - - -3. In the VNG page, scroll down until you see Instance Types and click Customize Instance Types. - - - -4. Complete the Instance Types configuration as described below and then click Save. - -### Configure Instance Types - -The instance types shown in the default VNG are only the instance types supported in the region that the cluster is configured in. - -In the custom VNGs, Ocean automatically filters out instance types that are not selected in the default VNG and instance types that do not meet the AMI architecture of the custom VNG. - - - -1. Click an arrow to see the available instance options. -2. Unmark the available options, as needed. +You can use a node selector or node affinity that requires your GPU-based pods to select the specific virtual node group containing the GPU image based on the custom node label configured in the GPU virtual node group. -The instance types that are grayed out are disabled for the following reasons: +## Configure Instance Types -- Does not exist in the default VNG. -- Does not fit the AMI architecture. +This section describes selecting instance types and sizes in your cluster per virtual node group (custom or template) according to your application needs. -When you hover the cursor over the instance type, a tooltip appears stating which reason. +1. In the virtual node groups tab, scroll down to the Instance Types panel and select one of the options: -### Use the Sliders + * Automatic: Let Ocean Autoscaler select your instance types and sizes according to your applications' needs. In this case, click **Save** to complete the procedure. + * Manual Selection: You can manually define a list of instance types from which Ocean can scale. See [Configure Instance Types Manually]() + * Advanced Selection: Use multiple filters to optimize instance types and sizes based on your application needs (supports all families available on the [Amazon link](https://aws.amazon.com/ec2/instance-types/) cloud). See [Configure Instance Types Using Advanced Filters](). -Instead of unmarking individual instances, you can use the vCPU, memory, or GPU sliders. When you use these, the instance types that are not in the range will be unmarked automatically. + - +### Configure Instance Types Manually -Above the sliders, Instance Types Selected indicates how many of the available instances you have marked (specifically: number of instances marked/number of instances available). This figure changes automatically when you move the sliders or when click or unclick instances. There are similar indicators in the Types column. For example, the illustration above shows that you have marked two Compute Optimized instances out of four that are available. +![eks-manage-vngs](https://github.com/user-attachments/assets/4443dc84-eb72-4a58-9855-fa597b3776a2) -### Restore to Default +The instance types shown in the default virtual node group are only those supported in the cluster's region. -To restore the instance types in a VNG to the default configuration, click Restore to Default. This behaves as follows: +In other virtual node groups, Ocean automatically grays out instance types that are not selected in the default virtual node group or do not meet AMI architecture requirements for the specific virtual node group. Hover over the instance type to view the reason. -- For a Custom VNG: The instance types are set to all the instance types that are available in the Default VNG. -- For Default VNG: The instance types are set to the default Ocean configuration, which means that all instance types are available. Then Ocean can choose any combination of instance types that best fit the workload requirements. +You can manually configure the instance types as follows: + * Click a down arrow to see the available options and check/uncheck as required. + +>**Note**: When you update the default virtual node group instance types, Ocean updates the Ocean cluster types because these have the same configuration. -Note that when you update the default VNG instance types, Ocean actually updates the Ocean cluster types since these have the same configuration. +### Configure Instance Types Using Advanced Filters - +Before configuring with this option, consider the following limitations: -## Create a VNG from an ASG +* If the default virtual node group (template) is set with `cluster.instanceTypes`.`filters != null` or `cluster.instanceTypes.whitelist/blacklist != null`, you cannot add filters on the custom virtual node group level. The **Advanced Selection** radio button is grayed with a tooltip on hover and a banner indicating the reason. + 1. Click **set to automatic** in the banner or the tooltip. The dialog that appears reflects the current configuration of the Template/Default VNG and the recommended change. + 2. Set the instanceTypes on the template/Default VNG to null and use filters on the custom virtual node group or accept the settings. +* If any custom VNG is set with `launchSpec.instanceTypesFilters!=null`, you cannot add a whitelist or filters on the template/default VNG level. The **Advanced Selection** and **Manual Selection** radio buttons are grayed, with a tooltip on hover and a banner indicating the reason. +need screen here with good example + 1. Click **view details** in the banner or the tooltip. The dialog that appears includes all the custom VNGs set with `launchSpec.instanceTypesFilters != null` + 2. If you want to set filters on the default virtual node group, click the virtual node group name and then configure by either **Manual Selection** or **Automatic Selection**. + + -The following procedure describes how to create a VNG in an Ocean cluster using the configuration from an existing Amazon autoscaling group. This process is referred to as importing a VNG from an ASG. +The Advanced instance types size filtering controls to the right of the instance types selection list let you filter the following attributes: -1. In the console, go to Ocean/Cloud Clusters and click the Cluster Name you want to add a VNG to. -2. In the summary page for the cluster, click Virtual Node Groups. -3. Click Create New Virtual Node Group. -4. Choose Import configurations from an Autoscaling Group, choose the Autoscaling Group in the dropdown list, and click Continue. +* Categories: One of the following: Accelerated_computing, Compute_optimized, General_purpose, Memory_optimized, Storage_optimized". +* Disk Types: NVMe, EBS, SSD, HDD. +* Excude Families: Types that will not be available for scaling (asterisk wildcard is also supported). For example, C* will exclude instance types from these families: c5, c4, c4a, etc. +* Exclude Metal: Metal types will not be available for scaling when set to true. +* Hypervisor TYpes: nitro, xen. +* Include Families: Types that will be available for scaling (asterisk wildcard is also supported). For example, C* will include instance types from these families: c5, c4, c4a, etc. +* Ena Support: Ena support when set to True. +* Max GPU: Maximum total number of GPUs. +* Min. GPUs: Minimum total number of GPUs. +* Max. Memory (GIB): Maximum amount of Memory (GiB). +* Min. Memory (GiBs): Minimum amount of Memory (GiB). +* Max. Network Performance: Maximum Bandwidth in Gib/s of network performance. +* Min. Network Performance: Minimum Bandwidth in Gib/s of network performance. +* Max. vCPU: Maximum number of vCPUs available. +* Min. vCPU: Minimum number of vCPUs available. +* Min. ENIs: Minimum number of network interfaces (ENIs). - +You can also configure these parameters via the [Spot API](https://docs.spot.io/api/#tag/Ocean-AWS/operation/OceanAWSLaunchSpecCreate) -5. When the New Virtual Node Group page appears, you will see the fields populated with the values from the Autoscaling Group you chose. Review all of the parameters and update them if necessary. -6. When you are finished reviewing and updating the imported configuration, click Save. +## Edit a Virtual Node Group -## View VNGs +* Click on the name of the virtual node group in the virtual node groups Summary List. -Ocean provides a dashboard that enables you to track live data per VNG. You can review the resource allocation, number of nodes and pods running, and other information about the VNGs. +### Edit a Virtual Node Group in JSON Format -1. In the console, go to Ocean/Cloud Clusters and click the Cluster you want to add a VNG to. -2. Click the Virtual Node Groups tab. The Virtual Node Groups tab opens and displays a summary of all the VNGs defined in the Ocean cluster. +You can also review and edit the configuration directly in JSON format in the console. This provides more flexibility and enables you to utilize VNG features supported in the API without leaving the Ocean console. (These are usually new features that have been implemented in the API but are not yet accessible in the console.) - +To edit in JSON format: -### VNG Summary Table +1. Click on the name of the virtual node group in the virtual node groups Summary List, and click **JSON** on the upper right. +2. Click **Edit Mode**, edit and save your changes. -The VNG summary table can display the following columns: - -- ID: The identification code of the VNG. -- Name: The user-defined name of the VNG. (If a VNG was defined without a time, it will appear in this column as Unnamed Virtual Node Group.) -- Resource Allocation: Percent of defined resources (CPU, Memory, and GPU) currently used by the VNG. -- Running Pods: Number of pods the VNG currently uses. -- Nodes: Number of nodes the VNG currently uses. -- Node Labels: Number of node labels the VNG uses. -- Node Taints: Number of taints the VNG uses. -- Tags: Number of tags the VNG uses. -- Max Nodes: The maximum number of nodes defined for the VNG. - -You can change the sort order in the table by clicking on the column headings. - -### Choose Columns - -To choose which columns to display in the table, click the three dots on the right. - - - -### Filter List - -Use the search box to filter items in the table or search for a specific VNG. - -### VNG Details - -To see the configuration details of a VNG, click on the Name of the VNG. - -## Edit a VNG - -1. To edit the configuration of a VNG, go to the Virtual Node Groups tab and click on the Name of the VNG. -2. Make the required changes in the configuration and click Save. - -### Edit in JSON Format - -In the console, you can also review and edit the configuration directly in JSON format. This provides more flexibility and enables you to utilize VNG features that are supported in the API without leaving the Ocean console. (These are usually new features that have been implemented in the API, but are not yet accessible in the UI.) - -1. To review and edit a VNG in JSON format, go to the Virtual Node Groups tab and click on the Name of the VNG. -2. Click JSON on the upper right. - - - -In this view, you can see the full JSON configuration of the VNG. If you would like to edit the JSON, just click Edit Mode, make your changes, and click Save. +![json-example-edit-mode](https://github.com/user-attachments/assets/13fd52bb-067b-44ba-a03f-139ef0e7d71b) ## Delete a VNG -1. To delete a VNG, go to the Virtual Node Groups tab. -2. In the VNG summary table, mark the VNG(s) to delete and click Delete. - -Alternatively, if you are already on the configuration page of a VNG, just click Delete VNG at the bottom. +In the virtual node groups summary list, check the virtual node groups to delete and click **Delete**. +OR +If you are already configuring a virtual node group, click **Delete VNG**.