From 13b09fb9783375a52523ecaa0f92817be94be0d2 Mon Sep 17 00:00:00 2001 From: Abhijeet Chatterjee Date: Mon, 8 Nov 2021 19:02:51 +0530 Subject: [PATCH] [Docs] Flytectl docs cleanup (#210) * Docs Fix flytectl.rst Signed-off-by: abhijeet007rocks8 * Doc fix config.go Signed-off-by: abhijeet007rocks8 * Docs Update get/Execution.go Signed-off-by: abhijeet007rocks8 * Docs Update get/Execution.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * docs update get/launch_plan.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Docs fix get/matchable_cluster_resource_attribute.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Docs Update matchable_execution_cluster_label.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Docs Update matchable_execution_queue_attribute.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Docs Update matchable_plugin_override.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Docs Fix matchable_task_resource_attribute.go Signed-off-by: Abhijeet Chatterjee Signed-off-by: abhijeet007rocks8 * Applied Suggestion Signed-off-by: abhijeet007rocks8 * Apply suggestions from code review Co-authored-by: Samhita Alla Signed-off-by: abhijeet007rocks8 * Apply suggestions from code review Co-authored-by: Samhita Alla Signed-off-by: abhijeet007rocks8 * Applied Suggestion Signed-off-by: abhijeet007rocks8 * Applied Suggestion Signed-off-by: abhijeet007rocks8 * Applied Suggestion Signed-off-by: abhijeet007rocks8 Co-authored-by: Samhita Alla --- flytectl/cmd/config/config.go | 4 +- flytectl/cmd/get/execution.go | 20 ++++----- flytectl/cmd/get/launch_plan.go | 16 +++---- .../matchable_cluster_resource_attribute.go | 16 ++++--- .../get/matchable_execution_cluster_label.go | 16 +++---- .../matchable_execution_queue_attribute.go | 20 ++++----- flytectl/cmd/get/matchable_plugin_override.go | 16 ++++--- .../get/matchable_task_resource_attribute.go | 18 ++++---- flytectl/docs/source/gen/flytectl.rst | 42 +++++++++---------- 9 files changed, 80 insertions(+), 88 deletions(-) diff --git a/flytectl/cmd/config/config.go b/flytectl/cmd/config/config.go index c20f2bc2ef..0283313f24 100644 --- a/flytectl/cmd/config/config.go +++ b/flytectl/cmd/config/config.go @@ -20,8 +20,8 @@ var ( // Config hold configration for flytectl flag type Config struct { Project string `json:"project" pflag:",Specifies the project to work on."` - Domain string `json:"domain" pflag:",Specified the domain to work on."` - Output string `json:"output" pflag:",Specified the output type."` + Domain string `json:"domain" pflag:",Specifies the domain to work on."` + Output string `json:"output" pflag:",Specifies the output type."` } // OutputFormat will return output formate diff --git a/flytectl/cmd/get/execution.go b/flytectl/cmd/get/execution.go index 45ce3d9b69..3cda9d4925 100644 --- a/flytectl/cmd/get/execution.go +++ b/flytectl/cmd/get/execution.go @@ -17,12 +17,12 @@ import ( const ( executionShort = "Gets execution resources" executionLong = ` -Retrieves all the executions within project and domain.(execution,executions can be used interchangeably in these commands) +Retrieve all executions within the project and domain (execution, executions can be used interchangeably). :: bin/flytectl get execution -p flytesnacks -d development -Retrieves execution by name within project and domain. +Retrieves executions by name within the project and domain. :: @@ -34,44 +34,44 @@ Retrieves all the executions with filters. bin/flytectl get execution -p flytesnacks -d development --filter.fieldSelector="execution.phase in (FAILED;SUCCEEDED),execution.duration<200" -Retrieves all the execution with limit and sorting. +Retrieve executions as per the specified limit and sorting parameters. :: bin/flytectl get execution -p flytesnacks -d development --filter.sortBy=created_at --filter.limit=1 --filter.asc -Retrieves all the execution within project and domain in yaml format +Retrieve executions within the project and domain in YAML format. :: bin/flytectl get execution -p flytesnacks -d development -o yaml -Retrieves all the execution within project and domain in json format. +Retrieve executions within the project and domain in JSON format. :: bin/flytectl get execution -p flytesnacks -d development -o json -Get more details for the execution using --details flag which shows node executions along with task executions on them. Default view is tree view and TABLE format is not supported on this view +Get more details of the execution using the --details flag, which shows node and task executions. The default view is a tree view, and the TABLE view format is not supported on this view. :: bin/flytectl get execution -p flytesnacks -d development oeh94k9r2r --details -Using yaml view for the details. In this view only node details are available. For task details pass --nodeID flag +Fetch execution details in YAML format. In this view, only node details are available. For task, send the --nodeID flag. :: bin/flytectl get execution -p flytesnacks -d development oeh94k9r2r --details -o yaml -Using --nodeID flag to get task executions on a specific node. Use the nodeID attribute from node details view +Fetch task executions on a specific node using the --nodeID flag. Use the nodeID attribute given by the node details view. :: - bin/flytectl get execution -p flytesnacks -d development oeh94k9r2r --nodID n0 + bin/flytectl get execution -p flytesnacks -d development oeh94k9r2r --nodeID n0 -Task execution view is also available in yaml/json format. Below example shows yaml. This also contains inputs/outputs data for each node +Task execution view is also available in YAML/JSON format. The following example showcases YAML, where the output also contains input and output data of each node. :: diff --git a/flytectl/cmd/get/launch_plan.go b/flytectl/cmd/get/launch_plan.go index 6ef85d6cb3..79aa4822b3 100644 --- a/flytectl/cmd/get/launch_plan.go +++ b/flytectl/cmd/get/launch_plan.go @@ -16,25 +16,25 @@ import ( const ( launchPlanShort = "Gets launch plan resources" launchPlanLong = ` -Retrieves all the launch plans within project and domain.(launchplan,launchplans can be used interchangeably in these commands) +Retrieve all launch plans within the project and domain (launchplan, launchplans can be used interchangeably). :: flytectl get launchplan -p flytesnacks -d development -Retrieves launch plan by name within project and domain. + Retrieve a launch plan by name within the project and domain. :: flytectl get launchplan -p flytesnacks -d development core.basic.lp.go_greet -Retrieves latest version of task by name within project and domain. +Retrieve the latest version of the task by name within the project and domain. :: flytectl get launchplan -p flytesnacks -d development core.basic.lp.go_greet --latest -Retrieves particular version of launchplan by name within project and domain. +Retrieves a particular version of the launch plan by name within the project and domain. :: @@ -57,25 +57,25 @@ Retrieves all the launch plans with limit and sorting. bin/flytectl get launchplan -p flytesnacks -d development --filter.sortBy=created_at --filter.limit=1 --filter.asc -Retrieves all the launchplan within project and domain in yaml format. +Retrieves all launch plans within the project and domain in YAML format. :: flytectl get launchplan -p flytesnacks -d development -o yaml -Retrieves all the launchplan within project and domain in json format +Retrieves all launch plans the within the project and domain in JSON format. :: flytectl get launchplan -p flytesnacks -d development -o json -Retrieves a launch plans within project and domain for a version and generate the execution spec file for it to be used for launching the execution using create execution. +Retrieve a launch plan within the project and domain as per a version and generate the execution spec file; the file can be used to launch the execution using the 'create execution' command. :: flytectl get launchplan -d development -p flytectldemo core.advanced.run_merge_sort.merge_sort --execFile execution_spec.yaml -The generated file would look similar to this +The generated file would look similar to this: .. code-block:: yaml diff --git a/flytectl/cmd/get/matchable_cluster_resource_attribute.go b/flytectl/cmd/get/matchable_cluster_resource_attribute.go index e29f61d5a1..7750a30ee2 100644 --- a/flytectl/cmd/get/matchable_cluster_resource_attribute.go +++ b/flytectl/cmd/get/matchable_cluster_resource_attribute.go @@ -11,12 +11,10 @@ import ( ) const ( - clusterResourceAttributesShort = "Gets matchable resources of cluster resource attributes" + clusterResourceAttributesShort = "Gets matchable resources of cluster resource attributes." clusterResourceAttributesLong = ` -Retrieves cluster resource attributes for given project and domain combination or additionally with workflow name. - -Retrieves cluster resource attribute for project and domain -Here the command get cluster resource attributes for project flytectldemo and development domain. +Retrieve cluster resource attributes for the given project and domain. +Here, the command gets cluster resource attributes for the project flytectldemo and development domain. :: flytectl get cluster-resource-attribute -p flytectldemo -d development @@ -27,8 +25,8 @@ eg : output from the command {"project":"flytectldemo","domain":"development","attributes":{"buzz":"lightyear","foo":"bar"}} -Retrieves cluster resource attribute for project and domain and workflow -Here the command get cluster resource attributes for project flytectldemo, development domain and workflow core.control_flow.run_merge_sort.merge_sort +Retrieve cluster resource attributes for the given project, domain, and workflow. +Here, the command gets cluster resource attributes for the project flytectldemo, development domain, and workflow 'core.control_flow.run_merge_sort.merge_sort'. :: flytectl get cluster-resource-attribute -p flytectldemo -d development core.control_flow.run_merge_sort.merge_sort @@ -39,8 +37,8 @@ eg : output from the command {"project":"flytectldemo","domain":"development","workflow":"core.control_flow.run_merge_sort.merge_sort","attributes":{"buzz":"lightyear","foo":"bar"}} -Writing the cluster resource attribute to a file. If there are no cluster resource attributes , command would return an error. -Here the command gets task resource attributes and writes the config file to cra.yaml +Writes the cluster resource attributes to a file. If there are no cluster resource attributes,the command throws an error. +Here, the command gets the task resource attributes and writes the config file to cra.yaml file. eg: content of cra.yaml :: diff --git a/flytectl/cmd/get/matchable_execution_cluster_label.go b/flytectl/cmd/get/matchable_execution_cluster_label.go index 56e9e7b94c..8a5227d736 100644 --- a/flytectl/cmd/get/matchable_execution_cluster_label.go +++ b/flytectl/cmd/get/matchable_execution_cluster_label.go @@ -11,24 +11,24 @@ import ( ) const ( - executionClusterLabelShort = "Gets matchable resources of execution cluster label" + executionClusterLabelShort = "Gets matchable resources of execution cluster label." executionClusterLabelLong = ` -Retrieves execution cluster label for given project and domain combination or additionally with workflow name. +// Retrieves the execution cluster label for a given project and domain, combination or additionally with workflow name. -Retrieves execution cluster label for project and domain +Retrieve the execution cluster label for the given project and domain. Here the command get execution cluster label for project flytectldemo and development domain. :: flytectl get execution-cluster-label -p flytectldemo -d development -eg : output from the command +e.g. : output from the command .. code-block:: json {"project":"flytectldemo","domain":"development","value":"foo"} -Retrieves execution cluster label for project and domain and workflow -Here the command get execution cluster label for project flytectldemo, development domain and workflow core.control_flow.run_merge_sort.merge_sort +Retrieve the execution cluster label for the given project, domain and workflow. +Here, the command gets the execution cluster label for the project flytectldemo, development domain, and workflow 'core.control_flow.run_merge_sort.merge_sort'. :: flytectl get execution-cluster-label -p flytectldemo -d development core.control_flow.run_merge_sort.merge_sort @@ -39,8 +39,8 @@ eg : output from the command {"project":"flytectldemo","domain":"development","workflow":"core.control_flow.run_merge_sort.merge_sort","value":"foo"} -Writing the execution cluster label to a file. If there are no execution cluster label, command would return an error. -Here the command gets execution cluster label and writes the config file to ecl.yaml +Writes the execution cluster label to a file. If there is no execution cluster label, command throws an error. +Here, the command gets the execution cluster label and writes the config file to ecl.yaml file. eg: content of ecl.yaml :: diff --git a/flytectl/cmd/get/matchable_execution_queue_attribute.go b/flytectl/cmd/get/matchable_execution_queue_attribute.go index b51517e595..0fea10ee56 100644 --- a/flytectl/cmd/get/matchable_execution_queue_attribute.go +++ b/flytectl/cmd/get/matchable_execution_queue_attribute.go @@ -13,35 +13,33 @@ import ( const ( executionQueueAttributesShort = "Gets matchable resources of execution queue attributes" executionQueueAttributesLong = ` -Retrieves execution queue attributes for given project and domain combination or additionally with workflow name. - -Retrieves execution queue attribute for project and domain -Here the command get execution queue attributes for project flytectldemo and development domain. +Retrieve the execution queue attribute for the given project and domain. +Here, the command gets execution queue attributes for the project flytectldemo and development domain. :: flytectl get execution-queue-attribute -p flytectldemo -d development -eg : output from the command +e.g. : output from the command .. code-block:: json {"project":"flytectldemo","domain":"development","tags":["foo", "bar"]} -Retrieves execution queue attribute for project and domain and workflow -Here the command get execution queue attributes for project flytectldemo, development domain and workflow core.control_flow.run_merge_sort.merge_sort +Retrieve the execution queue attribute for the given project, domain, and workflow. +Here, the command gets execution queue attributes for the project flytectldemo, development domain, and workflow 'core.control_flow.run_merge_sort.merge_sort'. :: flytectl get execution-queue-attribute -p flytectldemo -d development core.control_flow.run_merge_sort.merge_sort -eg : output from the command +e.g. : output from the command .. code-block:: json {"project":"flytectldemo","domain":"development","workflow":"core.control_flow.run_merge_sort.merge_sort","tags":["foo", "bar"]} -Writing the execution queue attribute to a file. If there are no execution queue attributes, command would return an error. -Here the command gets execution queue attributes and writes the config file to era.yaml -eg: content of era.yaml +Write the execution queue attribute to a file. If there are no execution queue attributes, the command throws an error. +Here, the command gets the execution queue attributes and writes the config to era.yaml file. +e.g. : content of era.yaml :: diff --git a/flytectl/cmd/get/matchable_plugin_override.go b/flytectl/cmd/get/matchable_plugin_override.go index 7c42a35219..8c8f5986dc 100644 --- a/flytectl/cmd/get/matchable_plugin_override.go +++ b/flytectl/cmd/get/matchable_plugin_override.go @@ -13,16 +13,14 @@ import ( const ( pluginOverrideShort = "Gets matchable resources of plugin override" pluginOverrideLong = ` -Retrieves plugin overrides for given project and domain combination or additionally with workflow name. - -Retrieves plugin overrides for project and domain -Here the command get plugin override for project flytectldemo and development domain. +Retrieve the plugin overrides for the given project and domain. +Here, the command gets the plugin overrides for the project flytectldemo and development domain. :: flytectl get plugin-override -p flytectldemo -d development -eg : output from the command +e.g. : output from the command .. code-block:: json @@ -36,14 +34,14 @@ eg : output from the command }] } -Retrieves plugin override for project and domain and workflow -Here the command get plugin override for project flytectldemo ,development domain and workflow core.control_flow.run_merge_sort.merge_sort +Retrieves the plugin overrides for project, domain and workflow +Here the command gets the plugin overrides for project flytectldemo, development domain and workflow core.control_flow.run_merge_sort.merge_sort :: flytectl get plugin-override -p flytectldemo -d development core.control_flow.run_merge_sort.merge_sort -eg : output from the command +e.g. : output from the command .. code-block:: json @@ -58,7 +56,7 @@ eg : output from the command }] } -Writing the plugin override to a file. If there are no plugin overrides, command would return an error. +Writing the plugin overrides to a file. If there are no plugin overrides, command would return an error. Here the command gets plugin overrides and writes the config file to po.yaml eg: content of po.yaml diff --git a/flytectl/cmd/get/matchable_task_resource_attribute.go b/flytectl/cmd/get/matchable_task_resource_attribute.go index 74c8a9a99d..2c27bb6f46 100644 --- a/flytectl/cmd/get/matchable_task_resource_attribute.go +++ b/flytectl/cmd/get/matchable_task_resource_attribute.go @@ -13,36 +13,34 @@ import ( const ( taskResourceAttributesShort = "Gets matchable resources of task attributes" taskResourceAttributesLong = ` -Retrieves task resource attributes for given project,domain combination or additionally with workflow name. - -Retrieves task resource attribute for project and domain -Here the command get task resource attributes for project flytectldemo and development domain. +Retrieve task resource attributes for the given project and domain. +Here, the command gets the task resource attributes for the project flytectldemo and development domain. :: flytectl get task-resource-attribute -p flytectldemo -d development -eg : output from the command +e.g. : output from the command .. code-block:: json {"project":"flytectldemo","domain":"development","workflow":"","defaults":{"cpu":"1","memory":"150Mi"},"limits":{"cpu":"2","memory":"450Mi"}} -Retrieves task resource attribute for project and domain and workflow -Here the command get task resource attributes for project flytectldemo, development domain and workflow core.control_flow.run_merge_sort.merge_sort +Retrieve task resource attributes for the given project, domain, and workflow. +Here, the command gets task resource attributes for the project flytectldemo, development domain, and workflow 'core.control_flow.run_merge_sort.merge_sort'. :: flytectl get task-resource-attribute -p flytectldemo -d development core.control_flow.run_merge_sort.merge_sort -eg : output from the command +e.g. : output from the command .. code-block:: json {"project":"flytectldemo","domain":"development","workflow":"core.control_flow.run_merge_sort.merge_sort","defaults":{"cpu":"1","memory":"150Mi"},"limits":{"cpu":"2","memory":"450Mi"}} -Writing the task resource attribute to a file. If there are no task resource attributes a file would be written with basic data populated. +Write the task resource attributes to a file. If there are no task resource attributes, a file would be populated with the basic data. Here the command gets task resource attributes and writes the config file to tra.yaml -eg: content of tra.yaml +e.g. : content of tra.yaml :: diff --git a/flytectl/docs/source/gen/flytectl.rst b/flytectl/docs/source/gen/flytectl.rst index d56aa0fca5..73fc3d1770 100644 --- a/flytectl/docs/source/gen/flytectl.rst +++ b/flytectl/docs/source/gen/flytectl.rst @@ -3,44 +3,44 @@ flytectl -------- -flyetcl CLI tool +**flyetcl** CLI tool Synopsis ~~~~~~~~ -flytectl is CLI tool written in go to interact with flyteadmin service +**flytectl** is CLI tool written in go to interact with flyteadmin service. Options ~~~~~~~ :: - --admin.authorizationHeader string Custom metadata header to pass JWT - --admin.authorizationServerUrl string This is the URL to your IdP's authorization server. It'll default to Endpoint - --admin.clientId string Client ID (default "flytepropeller") - --admin.clientSecretLocation string File containing the client secret (default "/etc/secrets/client_secret") - --admin.endpoint string For admin types, specify where the uri of the service is located. + --admin.authorizationHeader string Custom metadata header to pass JWT. + --admin.authorizationServerUrl string This is the URL to your IdP's authorization server. It'll default to Endpoint. + --admin.clientId string Client ID. (default "flytepropeller") + --admin.clientSecretLocation string File containing the client secret. (default "/etc/secrets/client_secret") + --admin.endpoint string For admin types, specify where the URI of the service is located. --admin.insecure Use insecure connection. - --admin.insecureSkipVerify InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name. Caution : shouldn't be use for production usecases' - --admin.maxBackoffDelay string Max delay for grpc backoff (default "8s") - --admin.maxRetries int Max number of gRPC retries (default 4) - --admin.perRetryTimeout string gRPC per retry timeout (default "15s") + --admin.insecureSkipVerify InsecureSkipVerify controls whether a client verifies the server's certificate chain and host name. Caution :shouldn't be use for production usecases'. + --admin.maxBackoffDelay string Max delay for gRPC backoff. (default "8s") + --admin.maxRetries int Max number of gRPC retries. (default 4) + --admin.perRetryTimeout string gRPC per retry timeout. (default "15s") --admin.pkceConfig.refreshTime string (default "5m0s") --admin.pkceConfig.timeout string (default "15s") - --admin.scopes strings List of scopes to request + --admin.scopes strings List of scopes to request. --admin.tokenUrl string OPTIONAL: Your IdP's token endpoint. It'll be discovered from flyte admin's OAuth Metadata endpoint if not provided. --admin.useAuth Deprecated: Auth will be enabled/disabled based on admin's dynamically discovered information. - -c, --config string config file (default is $HOME/.flyte/config.yaml) + -c, --config string config file. (default is $HOME/.flyte/config.yaml) -d, --domain string Specifies the Flyte project's domain. - -h, --help help for flytectl + -h, --help Help for flytectl. --logger.formatter.type string Sets logging format type. (default "json") --logger.level int Sets the minimum logging level. (default 4) --logger.mute Mutes all logs regardless of severity. Intended for benchmarks/tests only. --logger.show-source Includes source code location in logs. -o, --output string Specifies the output type - supported formats [TABLE JSON YAML DOT DOTURL]. NOTE: dot, doturl are only supported for Workflow (default "TABLE") -p, --project string Specifies the Flyte project. - --storage.cache.max_size_mbs int Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0, cache is not used + --storage.cache.max_size_mbs int Maximum size of the cache where the Blob store data is cached in-memory. If not specified or set to 0, cache is not used. --storage.cache.target_gc_percent int Sets the garbage collection target percentage. --storage.connection.access-key string Access key to use. Only required when authtype is set to accesskey. --storage.connection.auth-type string Auth Type to use [iam, accesskey]. (default "iam") @@ -48,9 +48,9 @@ Options --storage.connection.endpoint string URL for storage client to connect to. --storage.connection.region string Region to connect to. (default "us-east-1") --storage.connection.secret-key string Secret to use when accesskey is set. - --storage.container string Initial container (in s3 a bucket) to create -if it doesn't exist-.' + --storage.container string Initial container (in s3 a bucket) to create -if it doesn't exist. --storage.defaultHttpClient.timeout string Sets time out on the http client. (default "0s") - --storage.enable-multicontainer If this is true, then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered + --storage.enable-multicontainer If this is true, then the container argument is overlooked and redundant. This config will automatically open new connections to new containers/buckets as they are encountered. --storage.limits.maxDownloadMBs int Maximum allowed download size (in MBs) per call. (default 2) --storage.stow.config stringToString Configuration for stow backend. Refer to github/graymeta/stow (default []) --storage.stow.kind string Kind of Stow backend to use. Refer to github/graymeta/stow @@ -59,12 +59,12 @@ Options SEE ALSO ~~~~~~~~ -* :doc:`flytectl_completion` - Generate completion script -* :doc:`flytectl_config` - Runs various config commands, look at the help of this command to get a list of available commands.. +* :doc:`flytectl_completion` - Generates completion script. +* :doc:`flytectl_config` - Runs various config commands, look at the help of this command to get a list of available commands. * :doc:`flytectl_create` - Used for creating various flyte resources including tasks/workflows/launchplans/executions/project. * :doc:`flytectl_delete` - Used for terminating/deleting various flyte resources including tasks/workflows/launchplans/executions/project. -* :doc:`flytectl_get` - Used for fetching various flyte resources including tasks/workflows/launchplans/executions/project. -* :doc:`flytectl_register` - Registers tasks/workflows/launchplans from list of generated serialized files. +* :doc:`flytectl_get` - Used for fetching various flyte resources including tasks/workflows/launchplans/executions/project. +* :doc:`flytectl_register` - Registers the tasks/workflows/launchplans from list of generated serialized files. * :doc:`flytectl_sandbox` - Used for sandbox interactions like start/teardown/status/exec. * :doc:`flytectl_update` - Used for updating flyte resources eg: project. * :doc:`flytectl_upgrade` - Used for upgrade/rollback flyte version