Skip to content

Improve role query command documentation and fix proto docs build #637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
teo merged 3 commits into from
Nov 27, 2024
Merged

Improve role query command documentation and fix proto docs build #637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66b7c46
[coconut] Improve role query command documentation
teo Nov 26, 2024
5ec3a0c
[build] Fix protoc call for o2control.proto docs generation
teo Nov 27, 2024
1eadcc2
[build] Regenerate apidocs
teo Nov 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -314,7 +314,7 @@ docs/coconut:
docs/grpc:
@echo -e "generating gRPC API documentation \033[1;33m==>\033[0m \033[1;34m./docs\033[0m"
@cd apricot/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_apricot.md "apricot.proto"
@cd core/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_aliecs.md "o2control.proto"
@cd core/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc -I=. -I=../../common --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_aliecs.md "o2control.proto"
@cd occ/protos && PATH="$(ROOT_DIR)/tools:$$PATH" protoc --doc_out="$(ROOT_DIR)/docs" --doc_opt=markdown,apidocs_occ.md "occ.proto"

docs/swaggo:
Expand Down
23 changes: 20 additions & 3 deletions coconut/cmd/role_query.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,26 @@ var roleQueryCmd = &cobra.Command{
Use: "query [environment id] [query path]",
Aliases: []string{"query", "q"},
Short: "query O² roles",
Long: `The role query command returns one or more role trees.`,
Run: control.WrapCall(control.QueryRoles),
Args: cobra.ExactArgs(2),
Long: `The role query command returns one or more role subtrees within a given environment.

It allows the user to inspect the environment's workflow at runtime, after template processing operations, including
iterator expansion, just-in-time subworkflow inclusion, and variable substitution, have taken place.

For the target role or roles, it also prints the locally defined variables, as well as the consolidated variable
stack from the point of view of that role.

The role query command accepts two arguments: the environment ID and the query path. The query path is a dot-separated
walk through the role tree of the given environment, starting from the root role. Wildcard expressions are allowed, as
per https://github.com/gobwas/glob syntax.

Examples:
* ` + "`coconut role query 2rE9AV3m1HL readout-dataflow`" + ` - queries the role ` + "`readout-dataflow`" + ` in environment ` + "`2rE9AV3m1HL`" + `, prints the full tree, along with the variables defined in the root role
* ` + "`coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab102`" + ` - queries the role ` + "`readout-dataflow.host-aido2-bld4-lab102`" + `, prints the subtree of that role, along with the variables defined in it
* ` + "`coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab102.data-distribution.stfs`" + ` - queries the role at the given path, it is a task role so there is no subtree, prints the variables defined in that role
* ` + "`coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab*`" + ` - queries the roles matching the given glob expression, prints all the subtrees and variables
* ` + "`coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab*.data-distribution.*`" + ` - queries the task roles matching the given glob expression, prints all the variables`,
Run: control.WrapCall(control.QueryRoles),
Args: cobra.ExactArgs(2),
}

func init() {
Expand Down
2 changes: 1 addition & 1 deletion coconut/doc/coconut.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,4 @@ For more information on the available commands, see the individual documentation
* [coconut task](coconut_task.md) - manage active tasks
* [coconut template](coconut_template.md) - query available workflow templates in configuration repositories

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ coconut about [flags]

* [coconut](coconut.md) - O² Control and Configuration Utility

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
3 changes: 1 addition & 2 deletions coconut/doc/coconut_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,8 @@ configuration store.

* [coconut](coconut.md) - O² Control and Configuration Utility
* [coconut configuration dump](coconut_configuration_dump.md) - dump configuration subtree
* [coconut configuration history](coconut_configuration_history.md) - List all existing entries with timestamps of a specified component in Consul
* [coconut configuration import](coconut_configuration_import.md) - Import a configuration file for the specified component and entry
* [coconut configuration list](coconut_configuration_list.md) - List all existing O² components in Consul
* [coconut configuration show](coconut_configuration_show.md) - Show configuration for the component and entry specified

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_configuration_dump.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,4 @@ coconut configuration dump [key] [flags]

* [coconut configuration](coconut_configuration.md) - view or modify O² configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
6 changes: 3 additions & 3 deletions coconut/doc/coconut_configuration_import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Import a configuration file for the specified component and entry
### Synopsis

The configuration import command generates a timestamp and saves
the configuration file to Consul under the <component>/<entry>/<timestamp> path.
the configuration file to Consul under the <component>/<entry> path.
Supported configuration file types are JSON, YAML, TOML and INI,
and their file extensions are recognized automatically.

Expand All @@ -21,7 +21,7 @@ coconut conf import <component>/<run type>/<machine role>/<entry> <file_path>
coconut conf import <component> <entry> <file_path> --new-component
coconut conf import <component>/<run type>/<machine role>/<entry> <file_path> --format=json
coconut conf import <component> <entry> <file_path>.json
coconut conf import <component> <entry> <file_path>
coconut conf import <component> <entry> <file_path>
coconut conf import <component> <entry> <file_path> --new-component

```
Expand Down Expand Up @@ -51,4 +51,4 @@ coconut conf import <component> <entry> <file_path> --new-component

* [coconut configuration](coconut_configuration.md) - view or modify O² configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_configuration_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,4 +42,4 @@ coconut conf list <component> -t

* [coconut configuration](coconut_configuration.md) - view or modify O² configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
8 changes: 6 additions & 2 deletions coconut/doc/coconut_configuration_show.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Show configuration for the component and entry specified

The configuration show command returns the most recent
configuration revision for the specified component and entry.
It can also return a specific revision, requested with the --timestamp/-t flag

```
coconut configuration show <component> <entry> [flags]
Expand All @@ -17,7 +18,9 @@ coconut configuration show <component> <entry> [flags]
coconut conf show <component> <entry>
coconut conf show <component> <entry> -t <timestamp>
coconut conf show <component>/<run type>/<machine role>/<entry>
coconut conf show <component> <entry> -r <run type> -l <machine role>'
coconut conf show <component>/<run type>/<machine role>/<entry> -t <timestamp>
coconut conf show <component>/<run type>/<machine role>/<entry>@<timestamp>
coconut conf show <component> <entry> -r <run type> -l <machine role> -t <timestamp>'
coconut conf show <component> <entry> -s -e '{"key1": "value1", "key2": "value2"}'
```

Expand All @@ -29,6 +32,7 @@ coconut conf show <component> <entry> -s -e '{"key1": "value1", "key2": "value2"
-l, --role string request configuration for this O² machine role
-r, --runtype string request configuration for this run type (e.g. PHYSICS, TECHNICAL, etc.)
-s, --simulate simulate runtime template processing on the configuration payload
-t, --timestamp string request configuration for this timestamp
Copy link
Collaborator

@knopers8 knopers8 Nov 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well, actually... how come this reappeared? I though i removed timestamp support for good...

Copy link
Member Author

@teo teo Nov 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think so too, I have no idea. Maybe we missed it in the show command?

Copy link
Collaborator

@knopers8 knopers8 Nov 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indeed, you're right, it's still there. i will create a ticket for myself to remove it.

```

### Options inherited from parent commands
Expand All @@ -46,4 +50,4 @@ coconut conf show <component> <entry> -s -e '{"key1": "value1", "key2": "value2"

* [coconut configuration](coconut_configuration.md) - view or modify O² configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,4 +53,4 @@ For more information on the behavior of coconut environments, see the subcommand
* [coconut environment list](coconut_environment_list.md) - list environments
* [coconut environment show](coconut_environment_show.md) - show environment information

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_environment_control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ coconut environment control [environment id] [flags]

* [coconut environment](coconut_environment.md) - create, destroy and manage AliECS environments

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
3 changes: 2 additions & 1 deletion coconut/doc/coconut_environment_create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ coconut environment create [flags]
### Options

```
-y, --asynchronous use asynchronous mode for environment creation
-a, --auto create an autorun environment
-c, --configuration string high-level configuration payload to be loaded for the new environment
-e, --extra-vars key1=val1,key2=val2 values passed using key=value CSV or JSON syntax, interpreted as strings key1=val1,key2=val2 or `{"key1": "value1", "key2": "value2"}`
Expand All @@ -53,4 +54,4 @@ coconut environment create [flags]

* [coconut environment](coconut_environment.md) - create, destroy and manage AliECS environments

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_environment_destroy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ coconut environment destroy [environment id] [flags]

* [coconut environment](coconut_environment.md) - create, destroy and manage AliECS environments

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_environment_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ coconut environment list [flags]

* [coconut environment](coconut_environment.md) - create, destroy and manage AliECS environments

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_environment_show.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,4 +35,4 @@ coconut environment show [environment id] [flags]

* [coconut environment](coconut_environment.md) - create, destroy and manage AliECS environments

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_info.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,4 @@ coconut info [flags]

* [coconut](coconut.md) - O² Control and Configuration Utility

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,4 +65,4 @@ Make sure to run `coconut repo refresh` if you make changes to a configuration r
* [coconut repository refresh](coconut_repository_refresh.md) - refresh git repositories
* [coconut repository remove](coconut_repository_remove.md) - remove a git repository

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,4 +56,4 @@ coconut repository add <repo url> [flags]

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_default-revision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,4 +41,4 @@ coconut repository default-revision <global-default-revision | repo-id default-r

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_default.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ coconut repository default <repo id> [flags]

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ coconut repository list [flags]

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_refresh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ coconut repository refresh [repo id] [flags]

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_repository_remove.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ coconut repository remove <repo id> [flags]

* [coconut repository](coconut_repository.md) - manage git repositories for task and workflow configuration

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_role.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ display information on active roles.
* [coconut](coconut.md) - O² Control and Configuration Utility
* [coconut role query](coconut_role_query.md) - query O² roles

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
21 changes: 19 additions & 2 deletions coconut/doc/coconut_role_query.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,24 @@ query O² roles

### Synopsis

The role query command returns one or more role trees.
The role query command returns one or more role subtrees within a given environment.

It allows the user to inspect the environment's workflow at runtime, after template processing operations, including
iterator expansion, just-in-time subworkflow inclusion, and variable substitution, have taken place.

For the target role or roles, it also prints the locally defined variables, as well as the consolidated variable
stack from the point of view of that role.

The role query command accepts two arguments: the environment ID and the query path. The query path is a dot-separated
walk through the role tree of the given environment, starting from the root role. Wildcard expressions are allowed, as
per https://github.com/gobwas/glob syntax.

Examples:
* `coconut role query 2rE9AV3m1HL readout-dataflow` - queries the role `readout-dataflow` in environment `2rE9AV3m1HL`, prints the full tree, along with the variables defined in the root role
* `coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab102` - queries the role `readout-dataflow.host-aido2-bld4-lab102`, prints the subtree of that role, along with the variables defined in it
* `coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab102.data-distribution.stfs` - queries the role at the given path, it is a task role so there is no subtree, prints the variables defined in that role
* `coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab*` - queries the roles matching the given glob expression, prints all the subtrees and variables
* `coconut role query 2rE9AV3m1HL readout-dataflow.host-aido2-bld4-lab*.data-distribution.*` - queries the task roles matching the given glob expression, prints all the variables

```
coconut role query [environment id] [query path] [flags]
Expand All @@ -31,4 +48,4 @@ coconut role query [environment id] [query path] [flags]

* [coconut role](coconut_role.md) - query roles in an environment

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,4 +30,4 @@ manage active tasks.
* [coconut task clean](coconut_task_clean.md) - clean up idle O² tasks
* [coconut task list](coconut_task_list.md) - list O² tasks

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_task_clean.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ coconut task clean [flags]

* [coconut task](coconut_task.md) - manage active tasks

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_task_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,4 @@ coconut task list [flags]

* [coconut task](coconut_task.md) - manage active tasks

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,4 +29,4 @@ display information on available workflow templates.
* [coconut](coconut.md) - O² Control and Configuration Utility
* [coconut template list](coconut_template_list.md) - list available workflow templates

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
2 changes: 1 addition & 1 deletion coconut/doc/coconut_template_list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,4 +57,4 @@ coconut template list [flags]

* [coconut template](coconut_template.md) - query available workflow templates in configuration repositories

###### Auto generated by spf13/cobra on 17-Aug-2023
###### Auto generated by spf13/cobra on 27-Nov-2024
Loading