From 09f05d570224dfc0888ff2e4e8b06827875ecf4b Mon Sep 17 00:00:00 2001 From: Flyte Bot Date: Tue, 15 Mar 2022 08:34:37 -0700 Subject: [PATCH] Update documentation (#293) Signed-off-by: Flyte-Bot Co-authored-by: samhita-alla --- docs/source/gen/flytectl.rst | 2 +- ...lytectl_delete_execution-cluster-label.rst | 20 ++++++------ ...tectl_delete_execution-queue-attribute.rst | 16 ++++------ .../gen/flytectl_delete_plugin-override.rst | 17 +++++----- ...lytectl_delete_task-resource-attribute.rst | 18 +++++------ ...tectl_delete_workflow-execution-config.rst | 18 +++++------ docs/source/gen/flytectl_get.rst | 2 +- .../flytectl_get_execution-cluster-label.rst | 6 ++-- docs/source/gen/flytectl_get_launchplan.rst | 2 +- ...flytectl_get_workflow-execution-config.rst | 2 +- docs/source/gen/flytectl_register_files.rst | 32 +++++++++++-------- docs/source/gen/flytectl_sandbox.rst | 29 ++++++++--------- docs/source/gen/flytectl_sandbox_exec.rst | 7 ++-- docs/source/gen/flytectl_sandbox_start.rst | 13 ++++---- docs/source/gen/flytectl_sandbox_status.rst | 6 ++-- docs/source/gen/flytectl_sandbox_teardown.rst | 2 +- 16 files changed, 95 insertions(+), 97 deletions(-) diff --git a/docs/source/gen/flytectl.rst b/docs/source/gen/flytectl.rst index 6d7693e09a..03357644e9 100644 --- a/docs/source/gen/flytectl.rst +++ b/docs/source/gen/flytectl.rst @@ -67,7 +67,7 @@ SEE ALSO * :doc:`flytectl_delete` - Terminates/deletes various Flyte resources such as tasks, workflows, launch plans, executions, and projects. * :doc:`flytectl_get` - Fetches various Flyte resources such as tasks, workflows, launch plans, executions, and projects. * :doc:`flytectl_register` - Registers tasks, workflows, and launch plans from a list of generated serialized files. -* :doc:`flytectl_sandbox` - Helps with Sandbox interactions like start, teardown, status, and exec. +* :doc:`flytectl_sandbox` - Helps with sandbox interactions like start, teardown, status, and exec. * :doc:`flytectl_update` - Update Flyte resources e.g., project. * :doc:`flytectl_upgrade` - Upgrades/rollbacks to a Flyte version. * :doc:`flytectl_version` - Fetches Flyte version diff --git a/docs/source/gen/flytectl_delete_execution-cluster-label.rst b/docs/source/gen/flytectl_delete_execution-cluster-label.rst index 889e09a6fa..e83edad12e 100644 --- a/docs/source/gen/flytectl_delete_execution-cluster-label.rst +++ b/docs/source/gen/flytectl_delete_execution-cluster-label.rst @@ -10,32 +10,30 @@ Synopsis -Deletes execution cluster label for a given project and domain combination or additionally the workflow name. +Delete execution cluster label for a given project and domain, in combination with the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: - flytectl delete execution-cluster-label -p flytectldemo -d development + flytectl delete execution-cluster-label -p flytectldemo -d development - -Delete execution cluster label using the config file that was used to create it. -Here, the config file is written to ecl.yaml. -Value is optional in the file as it is unread during the delete command, but it can be retained since the same file can be used for 'get', 'update' or 'delete' commands. -Example: content of ecl.yaml: +To delete execution cluster label using the config file that was used to create it, run: :: flytectl delete execution-cluster-label --attrFile ecl.yaml +For example, here's the config file ecl.yaml: .. code-block:: yaml - + domain: development project: flytectldemo value: foo -Delete execution cluster label for a workflow. -For the workflow 'core.control_flow.run_merge_sort.merge_sort': +Value is optional in the file as it is unread during the delete command, but it can be retained since the same file can be used for 'get', 'update' and 'delete' commands. + +To delete the execution cluster label of the workflow 'core.control_flow.run_merge_sort.merge_sort', run the following: :: diff --git a/docs/source/gen/flytectl_delete_execution-queue-attribute.rst b/docs/source/gen/flytectl_delete_execution-queue-attribute.rst index 9909792dbe..710e8e7f10 100644 --- a/docs/source/gen/flytectl_delete_execution-queue-attribute.rst +++ b/docs/source/gen/flytectl_delete_execution-queue-attribute.rst @@ -10,23 +10,20 @@ Synopsis -Delete execution queue attributes for the given project and domain combination or additionally the workflow name. +Delete execution queue attributes for the given project and domain, in combination with the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: - flytectl delete execution-queue-attribute -p flytectldemo -d development - + flytectl delete execution-queue-attribute -p flytectldemo -d development Delete execution queue attribute using the config file which was used to create it. -Here, the config file is written to era.yaml. -Value is optional in the file as it is unread during the delete command but it can be retained since the same file can be used for get, update or delete commands. -Example: content of era.yaml: :: flytectl delete execution-queue-attribute --attrFile era.yaml +For example, here's the config file era.yaml: .. code-block:: yaml @@ -38,8 +35,9 @@ Example: content of era.yaml: - buzz - lightyear -Delete execution queue attribute for a workflow. -For the workflow 'core.control_flow.run_merge_sort.merge_sort': +Value is optional in the file as it is unread during the delete command but it can be retained since the same file can be used for get, update and delete commands. + +To delete the execution queue attribute for the workflow 'core.control_flow.run_merge_sort.merge_sort', run the following command: :: diff --git a/docs/source/gen/flytectl_delete_plugin-override.rst b/docs/source/gen/flytectl_delete_plugin-override.rst index 9933f2c072..f3b01a02c9 100644 --- a/docs/source/gen/flytectl_delete_plugin-override.rst +++ b/docs/source/gen/flytectl_delete_plugin-override.rst @@ -10,22 +10,20 @@ Synopsis -Delete plugin override for the given project and domain combination or additionally the workflow name. +Delete plugin override for the given project and domain, in combination with the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: - flytectl delete plugin-override -p flytectldemo -d development + flytectl delete plugin-override -p flytectldemo -d development -Delete plugin override using the config file which was used to create it. -Here, the config file is written to po.yaml. -Overrides are optional in the file as they are unread during the delete command but can be retained since the same file can be used for get, update or delete commands. -Example: content of po.yaml: +To delete plugin override using the config file which was used to create it, run: :: flytectl delete plugin-override --attrFile po.yaml +For example, here's the config file po.yaml: .. code-block:: yaml @@ -38,8 +36,9 @@ Example: content of po.yaml: - plugin_override2 missing_plugin_behavior: 1 # Behavior when no specified plugin_id has an associated handler. 0 : FAIL , 1: DEFAULT -Delete plugin override for a workflow. -For the workflow 'core.control_flow.run_merge_sort.merge_sort': +Overrides are optional in the file as they are unread during the delete command but can be retained since the same file can be used for get, update and delete commands. + +To delete plugin override for the workflow 'core.control_flow.run_merge_sort.merge_sort', run the following command: :: diff --git a/docs/source/gen/flytectl_delete_task-resource-attribute.rst b/docs/source/gen/flytectl_delete_task-resource-attribute.rst index 8664c34035..ac26e320de 100644 --- a/docs/source/gen/flytectl_delete_task-resource-attribute.rst +++ b/docs/source/gen/flytectl_delete_task-resource-attribute.rst @@ -10,23 +10,20 @@ Synopsis -Deletes task resource attributes for the given project and domain combination, or additionally the workflow name. +Delete task resource attributes for the given project and domain, in combination with the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: - flytectl delete task-resource-attribute -p flytectldemo -d development + flytectl delete task-resource-attribute -p flytectldemo -d development - -Deletes task resource attribute using config file which was used to create it. -Here, the config file is written to tra.yaml. -The defaults/limits are optional in the file as they are unread during the delete command, but can be retained since the same file can be used for 'get', 'update' or 'delete' commands. -Example: content of tra.yaml: +To delete task resource attribute using the config file which was used to create it, run: :: flytectl delete task-resource-attribute --attrFile tra.yaml +For example, here's the config file tra.yaml: .. code-block:: yaml @@ -39,8 +36,9 @@ Example: content of tra.yaml: cpu: "2" memory: "450Mi" -Delete task resource attribute for a workflow. -For the workflow 'core.control_flow.run_merge_sort.merge_sort': +The defaults/limits are optional in the file as they are unread during the delete command, but can be retained since the same file can be used for 'get', 'update' and 'delete' commands. + +To delete task resource attribute for the workflow 'core.control_flow.run_merge_sort.merge_sort', run the following command: :: diff --git a/docs/source/gen/flytectl_delete_workflow-execution-config.rst b/docs/source/gen/flytectl_delete_workflow-execution-config.rst index b584343e6f..0f36d5dd7a 100644 --- a/docs/source/gen/flytectl_delete_workflow-execution-config.rst +++ b/docs/source/gen/flytectl_delete_workflow-execution-config.rst @@ -12,30 +12,28 @@ Synopsis Delete workflow execution config for the given project and domain combination or additionally the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: - flytectl delete workflow-execution-config -p flytectldemo -d development + flytectl delete workflow-execution-config -p flytectldemo -d development - -Deletes workflow execution config using config file which was used to create it. -Here, the config file is written to wec.yaml. -Max_parallelism is optional in the file as it is unread during the delete command but can be retained since the same file can be used for get, update or delete commands. -Example: content of wec.yaml: +To delete workflow execution config using the config file which was used to create it, run: :: flytectl delete workflow-execution-config --attrFile wec.yaml +For example, here's the config file wec.yaml: .. code-block:: yaml - + domain: development project: flytectldemo max_parallelism: 5 -Deletes workflow execution config for a workflow. -For the workflow 'core.control_flow.run_merge_sort.merge_sort': +Max_parallelism is optional in the file as it is unread during the delete command but can be retained since the same file can be used for get, update and delete commands. + +To delete workflow execution config for the workflow 'core.control_flow.run_merge_sort.merge_sort', run: :: diff --git a/docs/source/gen/flytectl_get.rst b/docs/source/gen/flytectl_get.rst index a61c75323c..0be6546db4 100644 --- a/docs/source/gen/flytectl_get.rst +++ b/docs/source/gen/flytectl_get.rst @@ -10,7 +10,7 @@ Synopsis -Fetch Flyte resource; if a project: +To fetch a project, use the following command: :: flytectl get project diff --git a/docs/source/gen/flytectl_get_execution-cluster-label.rst b/docs/source/gen/flytectl_get_execution-cluster-label.rst index 47309bf44f..c8eed6cbb6 100644 --- a/docs/source/gen/flytectl_get_execution-cluster-label.rst +++ b/docs/source/gen/flytectl_get_execution-cluster-label.rst @@ -10,14 +10,14 @@ Synopsis -Retrieve the execution cluster label for a given project and domain, combination or additionally the workflow name. +Retrieve the execution cluster label for a given project and domain, in combination with the workflow name. -For project flytectldemo and development domain: +For project flytectldemo and development domain, run: :: flytectl get execution-cluster-label -p flytectldemo -d development -Example: output from the command: +The output would look like: .. code-block:: json diff --git a/docs/source/gen/flytectl_get_launchplan.rst b/docs/source/gen/flytectl_get_launchplan.rst index 53c95cff78..2d47156ba8 100644 --- a/docs/source/gen/flytectl_get_launchplan.rst +++ b/docs/source/gen/flytectl_get_launchplan.rst @@ -16,7 +16,7 @@ Retrieve all launch plans within the project and domain: flytectl get launchplan -p flytesnacks -d development .. note:: - The terms launch plan/launch plans are interchangeable in these commands. + The terms launchplan/launchplans are interchangeable in these commands. Retrieve a launch plan by name within the project and domain: diff --git a/docs/source/gen/flytectl_get_workflow-execution-config.rst b/docs/source/gen/flytectl_get_workflow-execution-config.rst index 85ce34f3b9..ce38e4be29 100644 --- a/docs/source/gen/flytectl_get_workflow-execution-config.rst +++ b/docs/source/gen/flytectl_get_workflow-execution-config.rst @@ -10,7 +10,7 @@ Synopsis -Retrieve workflow execution config for the given project and domain combination or additionally the workflow name. +Retrieve workflow execution config for the given project and domain, in combination with the workflow name. For project flytectldemo and development domain: diff --git a/docs/source/gen/flytectl_register_files.rst b/docs/source/gen/flytectl_register_files.rst index e052e181be..7c20d694bb 100644 --- a/docs/source/gen/flytectl_register_files.rst +++ b/docs/source/gen/flytectl_register_files.rst @@ -11,30 +11,36 @@ Synopsis Registers all the serialized protobuf files including tasks, workflows and launch plans with default v1 version. + If previously registered entities with v1 version are present, the command will fail immediately on the first such encounter. :: flytectl register file _pb_output/* -d development -p flytesnacks - -Registration and fast registration mean the same. In fast registration, the input provided by the user is fast serialized proto generated by pyflyte. -If Flytectl finds any source code in users' input, it considers the registration as fast registration. -Flytectl finds input file by searching an archive file whose name starts with fast and has .tar.gz extension. When the user runs pyflyte with --fast flag then pyflyte creates serialize proto and it also creates source code archive file in the same directory. -SourceUploadPath is an optional flag. By default, Flytectl will create SourceUploadPath from your storage config. In case of s3 Flytectl will upload code base in s3://{{DEFINE_BUCKET_IN_STORAGE_CONFIG}}/fast/{{VERSION}}-fast{{MD5_CREATED_BY_PYFLYTE}.tar.gz}. + +As per Flytectl, registration and fast registration mean the same! + +In fast registration, the input provided by the user is fast serialized proto generated by pyflyte. +When the user runs pyflyte with --fast flag, then pyflyte creates serialized proto and the source code archive file in the same directory. +Flytectl finds the input file by searching for an archive file whose name starts with "fast" and has .tar.gz extension. +If Flytectl finds any source code in users' input, it considers the registration as fast registration. + +SourceUploadPath is an optional flag. By default, Flytectl will create SourceUploadPath from your storage config. +If s3, Flytectl will upload the code base to s3://{{DEFINE_BUCKET_IN_STORAGE_CONFIG}}/fast/{{VERSION}}-fast{{MD5_CREATED_BY_PYFLYTE}.tar.gz}. :: - flytectl register file _pb_output/* -d development -p flytesnacks --version v2 - -In case of fast registration, if the SourceUploadPath flag is defined, Flytectl will not use the default directory to upload the source code. Instead, it will override the destination path on the registration. + flytectl register file _pb_output/* -d development -p flytesnacks --version v2 + +In case of fast registration, if the SourceUploadPath flag is defined, Flytectl will not use the default directory to upload the source code. +Instead, it will override the destination path on the registration. :: - flytectl register file _pb_output/* -d development -p flytesnacks --version v2 --SourceUploadPath="s3://dummy/fast" - -Using archive file. Currently supported extensions are .tgz and .tar. They can be local or remote files served through http/https. -Use --archive flag: + flytectl register file _pb_output/* -d development -p flytesnacks --version v2 --SourceUploadPath="s3://dummy/fast" + +To register a .tgz or .tar file, use the --archive flag. They can be local or remote files served through http/https. :: - flytectl register files http://localhost:8080/_pb_output.tar -d development -p flytesnacks --archive + flytectl register files http://localhost:8080/_pb_output.tar -d development -p flytesnacks --archive Using local tgz file: diff --git a/docs/source/gen/flytectl_sandbox.rst b/docs/source/gen/flytectl_sandbox.rst index 43e7816f51..dcc3f886cd 100644 --- a/docs/source/gen/flytectl_sandbox.rst +++ b/docs/source/gen/flytectl_sandbox.rst @@ -3,33 +3,32 @@ flytectl sandbox ---------------- -Helps with Sandbox interactions like start, teardown, status, and exec. +Helps with sandbox interactions like start, teardown, status, and exec. Synopsis ~~~~~~~~ -Flyte Sandbox is a fully standalone minimal environment for running Flyte. It provides a simplified way of running Flyte Sandbox as a single Docker container locally. +Flyte Sandbox is a fully standalone minimal environment for running Flyte. +It provides a simplified way of running Flyte sandbox as a single Docker container locally. -Creates Sandbox cluster: +To create a sandbox cluster, run: :: flytectl sandbox start - - -Removes Sandbox cluster: + +To remove a sandbox cluster, run: :: - flytectl sandbox teardown - + flytectl sandbox teardown -Checks the status of the Sandbox container: +To check the status of the sandbox container, run: :: - flytectl sandbox status - -Executes commands inside the Sandbox container: + flytectl sandbox status + +To execute commands inside the sandbox container, use exec: :: flytectl sandbox exec -- pwd @@ -92,8 +91,8 @@ SEE ALSO ~~~~~~~~ * :doc:`flytectl` - Flytectl CLI tool -* :doc:`flytectl_sandbox_exec` - Executes non-interactive command inside the Sandbox container -* :doc:`flytectl_sandbox_start` - Starts the Flyte Sandbox cluster. -* :doc:`flytectl_sandbox_status` - Gets the status of the Sandbox environment. +* :doc:`flytectl_sandbox_exec` - Executes non-interactive command inside the sandbox container +* :doc:`flytectl_sandbox_start` - Starts the Flyte sandbox cluster. +* :doc:`flytectl_sandbox_status` - Gets the status of the sandbox environment. * :doc:`flytectl_sandbox_teardown` - Cleans up the sandbox environment diff --git a/docs/source/gen/flytectl_sandbox_exec.rst b/docs/source/gen/flytectl_sandbox_exec.rst index e030242b1d..ebe3141dda 100644 --- a/docs/source/gen/flytectl_sandbox_exec.rst +++ b/docs/source/gen/flytectl_sandbox_exec.rst @@ -3,14 +3,15 @@ flytectl sandbox exec --------------------- -Executes non-interactive command inside the Sandbox container +Executes non-interactive command inside the sandbox container Synopsis ~~~~~~~~ -Runs non-interactive commands inside the Sandbox container and immediately returns the output. By default, "flytectl exec" is present in the /root directory inside the Sandbox container. +Run non-interactive commands inside the sandbox container and immediately return the output. +By default, "flytectl exec" is present in the /root directory inside the sandbox container. :: @@ -78,5 +79,5 @@ Options inherited from parent commands SEE ALSO ~~~~~~~~ -* :doc:`flytectl_sandbox` - Helps with Sandbox interactions like start, teardown, status, and exec. +* :doc:`flytectl_sandbox` - Helps with sandbox interactions like start, teardown, status, and exec. diff --git a/docs/source/gen/flytectl_sandbox_start.rst b/docs/source/gen/flytectl_sandbox_start.rst index c7a87d2ed1..75169d7cec 100644 --- a/docs/source/gen/flytectl_sandbox_start.rst +++ b/docs/source/gen/flytectl_sandbox_start.rst @@ -3,26 +3,27 @@ flytectl sandbox start ---------------------- -Starts the Flyte Sandbox cluster. +Starts the Flyte sandbox cluster. Synopsis ~~~~~~~~ -Flyte Sandbox is a fully standalone minimal environment for running Flyte. It provides a simplified way of running Flyte Sandbox as a single Docker container locally. +Flyte sandbox is a fully standalone minimal environment for running Flyte. +It provides a simplified way of running Flyte sandbox as a single Docker container locally. -Starts the Sandbox cluster without any source code: +Starts the sandbox cluster without any source code: :: flytectl sandbox start -Mounts your source code repository inside the Sandbox: +Mounts your source code repository inside the sandbox: :: flytectl sandbox start --source=$HOME/flyteorg/flytesnacks -Runs a specific version of Flyte. Flytectl Sandbox only supports Flyte version available in the Github release, https://github.com/flyteorg/flyte/tags. +Runs a specific version of Flyte. Flytectl sandbox only supports Flyte version available in the Github release, https://github.com/flyteorg/flyte/tags. :: flytectl sandbox start --version=v0.14.0 @@ -139,5 +140,5 @@ Options inherited from parent commands SEE ALSO ~~~~~~~~ -* :doc:`flytectl_sandbox` - Helps with Sandbox interactions like start, teardown, status, and exec. +* :doc:`flytectl_sandbox` - Helps with sandbox interactions like start, teardown, status, and exec. diff --git a/docs/source/gen/flytectl_sandbox_status.rst b/docs/source/gen/flytectl_sandbox_status.rst index a7a8e1e372..41b13a1307 100644 --- a/docs/source/gen/flytectl_sandbox_status.rst +++ b/docs/source/gen/flytectl_sandbox_status.rst @@ -3,14 +3,14 @@ flytectl sandbox status ----------------------- -Gets the status of the Sandbox environment. +Gets the status of the sandbox environment. Synopsis ~~~~~~~~ -Retrieves the status of the Sandbox environment. Currently, Flyte Sandbox runs as a local Docker container. +Retrieves the status of the sandbox environment. Currently, Flyte sandbox runs as a local Docker container. Usage :: @@ -79,5 +79,5 @@ Options inherited from parent commands SEE ALSO ~~~~~~~~ -* :doc:`flytectl_sandbox` - Helps with Sandbox interactions like start, teardown, status, and exec. +* :doc:`flytectl_sandbox` - Helps with sandbox interactions like start, teardown, status, and exec. diff --git a/docs/source/gen/flytectl_sandbox_teardown.rst b/docs/source/gen/flytectl_sandbox_teardown.rst index 31280b2511..18a97a7fb8 100644 --- a/docs/source/gen/flytectl_sandbox_teardown.rst +++ b/docs/source/gen/flytectl_sandbox_teardown.rst @@ -79,5 +79,5 @@ Options inherited from parent commands SEE ALSO ~~~~~~~~ -* :doc:`flytectl_sandbox` - Helps with Sandbox interactions like start, teardown, status, and exec. +* :doc:`flytectl_sandbox` - Helps with sandbox interactions like start, teardown, status, and exec.