Better instructions to 'add resources to a task' (#2585)

* Add instructions to package the workflow

Slack conversation: https://flyte-org.slack.com/archives/CP2HDHKE1/p1653126470767129
Add instructions to package and register the workflow
Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Slack conversation: https://flyte-org.slack.com/archives/CP2HDHKE1/p1653126470767129
Signed-off-by: SmritiSatyanV [email protected]

* Updated index.rst

Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Changes based on comments
Signed-off-by: SmritiSatyanV <[email protected]>

* Updated index.rst

Changes based on review
Signed-off-by: SmritiSatyanV <[email protected]>

* Better instructions to 'add resources to a task' 

Slack conversation: https://flyte-org.slack.com/archives/C02HARLSW30/p1653436394626289
Improve the documentation for adding resources (such as memory, cpu) that a task can use in Flyte.
Signed-off-by: SmritiSatyanV <[email protected]>

* Changes based on commets

Signed-off-by: SmritiSatyanV <[email protected]>

* Updated general.rst

Changes based on comments
Signed-off-by: SmritiSatyanV <[email protected]>

* Updated general.rst

Signed-off-by: SmritiSatyanV <[email protected]>

rsts/deployment/cluster_config/general.rst

@@ -7,24 +7,24 @@ Configuring Custom K8s Resources
 Configurable Resource Types
 ***************************
 
-Many platform specifications such as task resource defaults, project namespace Kubernetes quota, and more can all be
+Many platform specifications such as task resource defaults, project namespace Kubernetes quota, and more can be
 assigned using default values or custom overrides. Defaults are specified in the FlyteAdmin config and
-overrides for specific projects can be registered with the FlyteAdmin service.
+overrides for specific projects are registered with the FlyteAdmin service.
 
-Specifically, flyte allows these custom settings along increasing levels of specificity:
+You can customize these settings along increasing levels of specificity with Flyte:
 
 - domain
 - project and domain
 - project, domain, and workflow name
 - project, domain, workflow name and launch plan name
 
-Please see the :ref:`concepts/control_plane:control plane` document to get to know about projects and domains.
+See :ref:`concepts/control_plane:control plane` to understand projects and domains.
 Along these dimensions, the following settings are configurable:
 
 Task Resources
 ==============
 Configuring task resources includes setting default values for unspecified task requests and limits.
-Task resources also include limits which specify the maximum value either a task request or limit can have.
+Task resources also include limits which specify the maximum value that a task request or a limit can have.
 
 - cpu
 - gpu
@@ -38,7 +38,7 @@ in the FlyteAdmin config are used.
 
 The override values from the database are assigned at execution, rather than registration time.
 
-To update individual project-domain attributes, first define a ``tra.yaml`` file with your overrides:
+To customize resources for project-domain attributes, define a ``tra.yaml`` file with your overrides:
 
 .. code-block:: yaml
 
@@ -51,15 +51,15 @@ To update individual project-domain attributes, first define a ``tra.yaml`` file
     project: flyteexamples
     domain: development
 
-Then, use the following command for your reference.
+Update the task resource attributes for a project-domain combination:
 
 .. prompt:: bash
 
     flytectl update task-resource-attribute --attrFile tra.yaml
 
 Refer to the :ref:`docs <flytectl:flytectl_update_task-resource-attribute>` to learn more about the command and its supported flag(s).
 
-To fetch and verify the individual project-domain attributes, similarly you can run:
+To fetch and verify the individual project-domain attributes:
 
 .. prompt:: bash
 
@@ -71,20 +71,18 @@ You can view all custom task-resource-attributes by visiting ``protocol://<host/
 
 Cluster Resources
 =================
-These are free-form key-value pairs used when filling the templates that the admin feeds into the cluster manager, the process that syncs kubernetes resources.
+These are free-form key-value pairs used when filling the templates that the admin feeds into the cluster manager; the process that syncs Kubernetes resources.
 
 The keys represent templatized variables in `cluster resource template YAML <https://github.com/flyteorg/flyte/blob/1e3d515550cb338c2edb3919d79c6fa1f0da5a19/charts/flyte-core/values.yaml#L737,L760>`__ and the values are what you want to see filled in.
 
-
-In the absence of custom override values, ``templateData`` from the `FlyteAdmin config <https://github.com/flyteorg/flyte/blob/1e3d515550cb338c2edb3919d79c6fa1f0da5a19/charts/flyte-core/values.yaml#L719,L734>`__
-is used as a default. Note, these defaults are specified by domain but will be applied to every project-domain namespace combination.
+In the absence of custom override values, you can use ``templateData`` from the `FlyteAdmin config <https://github.com/flyteorg/flyte/blob/1e3d515550cb338c2edb3919d79c6fa1f0da5a19/charts/flyte-core/values.yaml#L719,L734>`__ as a default. Flyte specifies these defaults by domain and applies them to every project-domain namespace combination.
 
 .. note::
-    The above-referenced settings can only take on domain, project, and domain specificity.
-    Since Flyte has not tied in the notion of a workflow or a launch plan to any Kubernetes constructs, specifying a workflow or launch plan name doesn't make any sense.
+    The settings above can be specified on domain, and project-and-domain.
+    Since Flyte hasn't tied the notion of a workflow or a launch plan to any Kubernetes construct, specifying a workflow or launch plan name doesn't make sense.
     This is a departure from the usual hierarchy for customizable resources.
 
-Define an attributes file like the the following in ``cra.yaml``
+Define an attributes file, ``cra.yaml``:
 
 .. code-block:: yaml
 
@@ -94,7 +92,7 @@ Define an attributes file like the the following in ``cra.yaml``
     domain: development
     project: flyteexamples
 
-Then run the below command to ensure that when the admin fills in cluster resource templates, the Kubernetes namespace ``flyteexamples-development`` will have a resource quota of 1000 CPU cores and 5TB of memory.
+To ensure that the overrides reflect in the Kubernetes namespace ``flyteexamples-development`` (that is, the namespace has a resource quota of 1000 CPU cores and 5TB of memory) when the admin fills in cluster resource templates:
 
 .. prompt:: bash
 
@@ -103,21 +101,21 @@ Then run the below command to ensure that when the admin fills in cluster resour
 Refer to the :ref:`docs <flytectl:flytectl_update_cluster-resource-attribute>` to learn more about the command and its supported flag(s).
 
 
-To fetch and verify the individual project-domain attributes, similarly you can run:
+To fetch and verify the individual project-domain attributes:
 
 .. prompt:: bash
 
     flytectl get cluster-resource-attribute -p flyteexamples -d development
 
 Refer to the :ref:`docs <flytectl:flytectl_get_task-resource-attribute>` to learn more about the command and its supported flag(s).
 
-The above-updated values will, in turn, be used to fill in the template fields for the flyteexamples-development namespace.
+Flyte uses these updated values to fill the template fields for the flyteexamples-development namespace.
 
 For other namespaces, the `platform defaults <https://github.com/flyteorg/flyte/blob/1e3d515550cb338c2edb3919d79c6fa1f0da5a19/charts/flyte-core/values.yaml#L719,L734>`__ apply.
 
 .. note::
-    The template values, e.g. ``projectQuotaCpu`` or ``projectQuotaMemory`` are freeform strings.
-    You must ensure that they match the template placeholders in your `template file <https://github.com/flyteorg/flyte/blob/master/kustomize/base/single_cluster/headless/config/clusterresource-templates/ab_project-resource-quota.yaml>`__
+    The template values, for example, ``projectQuotaCpu`` or ``projectQuotaMemory`` are free-form strings.
+    Ensure that they match the template placeholders in your `template file <https://github.com/flyteorg/flyte/blob/master/kustomize/base/single_cluster/headless/config/clusterresource-templates/ab_project-resource-quota.yaml>`__
     for your changes to take effect and custom values to be substituted.
 
 You can view all custom cluster-resource-attributes by visiting ``protocol://<host/api/v1/matchable_attributes?resource_type=1>`` and substitute the protocol and host appropriately.
@@ -126,23 +124,23 @@ Execution Cluster Label
 =======================
 This allows forcing a matching execution to consistently execute on a specific Kubernetes cluster for multi-cluster Flyte deployment set-up.
 
-Define an attributes file like so in `ec.yaml`:
+Define an attributes file in `ec.yaml`:
 
 .. code-block:: yaml
 
     value: mycluster
     domain: development
     project: flyteexamples
 
-Then run the below command to ensure that admin places executions in the flyteexamples project and development domain onto ``mycluster``.
+Ensure that admin places executions in the flyteexamples project and development domain onto ``mycluster``:
 
 .. prompt:: bash
 
    flytectl update execution-cluster-label --attrFile ec.yaml
 
 Refer to the :ref:`docs <flytectl:flytectl_update_execution-cluster-label>` to learn more about the command and its supported flag(s).
 
-To fetch and verify the individual project-domain attributes, similarly you can run:
+To fetch and verify the individual project-domain attributes:
 
 .. prompt:: bash
 
@@ -154,12 +152,11 @@ You can view all custom execution cluster attributes by visiting ``protocol://<h
 
 Execution Queues
 ================
-Execution queues themselves are currently defined in the
+Execution queues are defined in
 `flyteadmin config <https://github.com/flyteorg/flyteadmin/blob/6a64f00315f8ffeb0472ae96cbc2031b338c5840/flyteadmin_config.yaml#L97,L106>`__.
 These are used for execution placement for constructs like AWS Batch.
 
-The **attributes** associated with an execution queue must match the **tags** for workflow executions. The tags are associated with configurable resources
-stored in the admin database.
+The **attributes** associated with an execution queue must match the **tags** for workflow executions. The tags associated with configurable resources are stored in the admin database.
 
 .. prompt:: bash
 
@@ -172,7 +169,7 @@ You can view existing attributes for which tags can be assigned by visiting ``pr
 *********
 Hierarchy
 *********
-Increasing specificity defines how matchable resource attributes get applied. The available configurations, in order of decreasing specifity, are:
+Increasing specificity defines how matchable resource attributes get applied. The available configurations, in order of decreasing specifity are:
 
 #. Domain, project, workflow name, and launch plan.