Merge pull request #466 from gabriel-samfira/update-docs-and-defaults

Update docs and deprecate the --all flag

Author: gabriel-samfira

README.md

@@ -48,9 +48,11 @@ Here is a brief architectural diagram of how pools work and how GARM reacts to w
 
 **Scale sets** work differently. While pools (as they are defined in GARM) rely on webhooks to know when a job was started and GARM needs to internally make the right decission in terms of which pool should handle that runner, scale sets have a lot of the scheduling and decission making logic done in GitHub itself.
 
-:warning: **Important note**: The README and documentation in the `main` branch are relevant to the not yet released code that is present in `main`. Following the documentation from the `main` branch for a stable release of GARM, may lead to errors. To view the documentation for the latest stable release, please switch to the appropriate tag. For information about setting up `v0.1.5`, please refer to the [v0.1.5 tag](https://github.com/cloudbase/garm/tree/v0.1.5).
+> [!IMPORTANT]
+> The README and documentation in the `main` branch are relevant to the not yet released code that is present in `main`. Following the documentation from the `main` branch for a stable release of GARM, may lead to errors. To view the documentation for the latest stable release, please switch to the appropriate tag. For information about setting up `v0.1.6`, please refer to the [v0.1.6 tag](https://github.com/cloudbase/garm/tree/v0.1.6).
 
-:warning: **Important note**: The `main` branch holds the latest code and is not guaranteed to be stable. If you are looking for a stable release, please check the releases page. If you plan to use the `main` branch, please do so on a new instance. Do not upgrade from a stable release to `main`.
+> [!CAUTION]
+> The `main` branch holds the latest code and is not guaranteed to be stable. If you are looking for a stable release, please check the releases page. If you plan to use the `main` branch, please do so on a new instance. Do not upgrade from a stable release to `main`.
 
 ## Join us on slack
 

cmd/garm-cli/cmd/pool.go

@@ -128,12 +128,9 @@ Example:
 				listEnterprisePoolsReq := apiClientEnterprises.NewListEnterprisePoolsParams()
 				listEnterprisePoolsReq.EnterpriseID = poolEnterprise
 				response, err = apiCli.Enterprises.ListEnterprisePools(listEnterprisePoolsReq, authToken)
-			} else if cmd.Flags().Changed("all") {
+			} else {
 				listPoolsReq := apiClientPools.NewListPoolsParams()
 				response, err = apiCli.Pools.ListPools(listPoolsReq, authToken)
-			} else {
-				cmd.Help() //nolint
-				os.Exit(0)
 			}
 		default:
 			cmd.Help() //nolint
@@ -409,11 +406,12 @@ func init() {
 	poolListCmd.Flags().StringVarP(&poolRepository, "repo", "r", "", "List all pools within this repository.")
 	poolListCmd.Flags().StringVarP(&poolOrganization, "org", "o", "", "List all pools within this organization.")
 	poolListCmd.Flags().StringVarP(&poolEnterprise, "enterprise", "e", "", "List all pools within this enterprise.")
-	poolListCmd.Flags().BoolVarP(&poolAll, "all", "a", false, "List all pools, regardless of org or repo.")
+	poolListCmd.Flags().BoolVarP(&poolAll, "all", "a", true, "List all pools, regardless of org or repo.")
 	poolListCmd.Flags().BoolVarP(&long, "long", "l", false, "Include additional info.")
 	poolListCmd.Flags().StringVar(&endpointName, "endpoint", "", "When using the name of an entity, the endpoint must be specified when multiple entities with the same name exist.")
 
-	poolListCmd.MarkFlagsMutuallyExclusive("repo", "org", "all", "enterprise")
+	poolListCmd.Flags().MarkDeprecated("all", "all pools are listed by default in the absence of --repo, --org or --enterprise.")
+	poolListCmd.MarkFlagsMutuallyExclusive("repo", "org", "enterprise", "all")
 
 	poolUpdateCmd.Flags().StringVar(&poolImage, "image", "", "The provider-specific image name to use for runners in this pool.")
 	poolUpdateCmd.Flags().UintVar(&priority, "priority", 0, "When multiple pools match the same labels, priority dictates the order by which they are returned, in descending order.")

cmd/garm-cli/cmd/runner.go

@@ -104,23 +104,32 @@ Example:
 			response, err = apiCli.Instances.ListPoolInstances(listPoolInstancesReq, authToken)
 		case 0:
 			if cmd.Flags().Changed("repo") {
+				runnerRepo, resErr := resolveRepository(runnerRepository, endpointName)
+				if resErr != nil {
+					return resErr
+				}
 				listRepoInstancesReq := apiClientRepos.NewListRepoInstancesParams()
-				listRepoInstancesReq.RepoID = runnerRepository
+				listRepoInstancesReq.RepoID = runnerRepo
 				response, err = apiCli.Repositories.ListRepoInstances(listRepoInstancesReq, authToken)
 			} else if cmd.Flags().Changed("org") {
+				runnerOrg, resErr := resolveOrganization(runnerOrganization, endpointName)
+				if resErr != nil {
+					return resErr
+				}
 				listOrgInstancesReq := apiClientOrgs.NewListOrgInstancesParams()
-				listOrgInstancesReq.OrgID = runnerOrganization
+				listOrgInstancesReq.OrgID = runnerOrg
 				response, err = apiCli.Organizations.ListOrgInstances(listOrgInstancesReq, authToken)
 			} else if cmd.Flags().Changed("enterprise") {
+				runnerEnt, resErr := resolveEnterprise(runnerEnterprise, endpointName)
+				if resErr != nil {
+					return resErr
+				}
 				listEnterpriseInstancesReq := apiClientEnterprises.NewListEnterpriseInstancesParams()
-				listEnterpriseInstancesReq.EnterpriseID = runnerEnterprise
+				listEnterpriseInstancesReq.EnterpriseID = runnerEnt
 				response, err = apiCli.Enterprises.ListEnterpriseInstances(listEnterpriseInstancesReq, authToken)
-			} else if cmd.Flags().Changed("all") {
+			} else {
 				listInstancesReq := apiClientInstances.NewListInstancesParams()
 				response, err = apiCli.Instances.ListInstances(listInstancesReq, authToken)
-			} else {
-				cmd.Help() //nolint
-				os.Exit(0)
 			}
 		default:
 			cmd.Help() //nolint
@@ -205,9 +214,12 @@ func init() {
 	runnerListCmd.Flags().StringVarP(&runnerRepository, "repo", "r", "", "List all runners from all pools within this repository.")
 	runnerListCmd.Flags().StringVarP(&runnerOrganization, "org", "o", "", "List all runners from all pools within this organization.")
 	runnerListCmd.Flags().StringVarP(&runnerEnterprise, "enterprise", "e", "", "List all runners from all pools within this enterprise.")
-	runnerListCmd.Flags().BoolVarP(&runnerAll, "all", "a", false, "List all runners, regardless of org or repo.")
+	runnerListCmd.Flags().BoolVarP(&runnerAll, "all", "a", true, "List all runners, regardless of org or repo. (deprecated)")
 	runnerListCmd.Flags().BoolVarP(&long, "long", "l", false, "Include additional info.")
 	runnerListCmd.MarkFlagsMutuallyExclusive("repo", "org", "enterprise", "all")
+	runnerListCmd.Flags().StringVar(&endpointName, "endpoint", "", "When using the name of an entity, the endpoint must be specified when multiple entities with the same name exist.")
+
+	runnerListCmd.Flags().MarkDeprecated("all", "all runners are listed by default in the absence of --repo, --org or --enterprise.")
 
 	runnerDeleteCmd.Flags().BoolVarP(&forceRemove, "force-remove-runner", "f", false, "Forcefully remove a runner. If set to true, GARM will ignore provider errors when removing the runner.")
 	runnerDeleteCmd.Flags().BoolVarP(&bypassGHUnauthorized, "bypass-github-unauthorized", "b", false, "Ignore Unauthorized errors from GitHub and proceed with removing runner from provider and DB. This is useful when credentials are no longer valid and you want to remove your runners. Warning, this has the potential to leave orphaned runners in GitHub. You will need to update your credentials to properly consolidate.")

doc/gitea.md

@@ -346,7 +346,7 @@ garm-cli pool add \
 You should now see 1 runner being spun up in LXD. You can check the status of the pool by doing:
 
 ```bash
-garm-cli runner ls -a
+garm-cli runner ls
 ```
 
 To get more details about the runner, run:

doc/quickstart.md

@@ -133,7 +133,7 @@ docker run -d \
   -p 80:80 \
   -v /etc/garm:/etc/garm:rw \
   -v /var/snap/lxd/common/lxd/unix.socket:/var/snap/lxd/common/lxd/unix.socket:rw \
-  ghcr.io/cloudbase/garm:v0.1.4
+  ghcr.io/cloudbase/garm:v0.1.6
 ```
 
 You will notice that we also mounted the LXD unix socket from the host inside the container where the config you pasted expects to find it. If you plan to use an external provider that does not need to connect to LXD over a unix socket, feel free to remove that mount.
@@ -166,7 +166,7 @@ Adding the `garm` user to the LXD group will allow it to connect to the LXD unix
 Next, download the latest release from the [releases page](https://github.com/cloudbase/garm/releases).
 
 ```bash
-wget -q -O - https://github.com/cloudbase/garm/releases/download/v0.1.5/garm-linux-amd64.tgz |  tar xzf - -C /usr/local/bin/
+wget -q -O - https://github.com/cloudbase/garm/releases/download/v0.1.6/garm-linux-amd64.tgz |  tar xzf - -C /usr/local/bin/
 ```
 
 We'll be running under an unprivileged user. If we want to be able to listen on any port under `1024`, we'll have to set some capabilities on the binary:
@@ -199,7 +199,7 @@ Copy the sample `systemd` service file:
 
 ```bash
 wget -O /etc/systemd/system/garm.service \
-  https://raw.githubusercontent.com/cloudbase/garm/v0.1.5/contrib/garm.service
+  https://raw.githubusercontent.com/cloudbase/garm/v0.1.6/contrib/garm.service
 ```
 
 Reload the `systemd` daemon and start the service:
@@ -234,7 +234,7 @@ Before we can start using GARM, we need initialize it. This will create the `adm
 To initialize GARM, we'll use the `garm-cli` tool. You can download the latest release from the [releases page](https://github.com/cloudbase/garm/releases):
 
 ```bash
-wget -q -O - https://github.com/cloudbase/garm/releases/download/v0.1.5/garm-cli-linux-amd64.tgz |  tar xzf - -C /usr/local/bin/
+wget -q -O - https://github.com/cloudbase/garm/releases/download/v0.1.6/garm-cli-linux-amd64.tgz |  tar xzf - -C /usr/local/bin/
 ```
 
 Now we can initialize GARM:
@@ -502,7 +502,7 @@ gabriel@rossak:~$ garm-cli pool add \
 If we list the pool we should see it:
 
 ```bash
-gabriel@rock:~$ garm-cli pool ls -a
+gabriel@rock:~$ garm-cli pool ls
 +--------------------------------------+---------------------------+--------------+-----------------+------------------+-------+---------+---------------+----------+
 | ID                                   | IMAGE                     | FLAVOR       | TAGS            | BELONGS TO       | LEVEL | ENABLED | RUNNER PREFIX | PRIORITY |
 +--------------------------------------+---------------------------+--------------+-----------------+------------------+-------+---------+---------------+----------+
@@ -517,7 +517,7 @@ For the purposes of this guide, we'll increase it to 1 so we have a runner creat
 First, list current runners:
 
 ```bash
-gabriel@rossak:~$ garm-cli runner ls -a
+gabriel@rossak:~$ garm-cli runner ls
 +----+------+--------+---------------+---------+
 | NR | NAME | STATUS | RUNNER STATUS | POOL ID |
 +----+------+--------+---------------+---------+
@@ -554,7 +554,7 @@ gabriel@rossak:~$ garm-cli pool update 344e4a72-2035-4a18-a3d5-87bd3874b56c --mi
 Now if we list the runners:
 
 ```bash
-gabriel@rossak:~$ garm-cli runner ls -a
+gabriel@rossak:~$ garm-cli runner ls
 +----+-------------------+----------------+---------------+--------------------------------------+
 | NR | NAME              | STATUS         | RUNNER STATUS | POOL ID                              |
 +----+-------------------+----------------+---------------+--------------------------------------+

doc/using_garm.md

@@ -66,7 +66,7 @@ garm-cli controller show
 | Webhook Base URL        | https://garm.example.com/webhooks                                          |
 | Controller Webhook URL  | https://garm.example.com/webhooks/a4dd5f41-8e1e-42a7-af53-c0ba5ff6b0b3     |
 | Minimum Job Age Backoff | 30                                                                         |
-| Version                 | v0.1.5                                                                     |
+| Version                 | v0.1.6                                                                     |
 +-------------------------+----------------------------------------------------------------------------+
 ```
 
@@ -567,10 +567,10 @@ ubuntu@garm:~$ garm-cli pool list --repo=be3a0673-56af-4395-9ebf-4521fea67567
 
 If you want to list pools for an organization or enterprise, you can use the `--org` or `--enterprise` options respectively.
 
-You can also list **all** pools from all configureg github entities by using the `--all` option.
+In the absence or the `--repo`, `--org` or `--enterprise` options, the command will list all pools in GARM, regardless of the entity they belong to.
 
 ```bash
-ubuntu@garm:~/garm$ garm-cli pool list --all
+ubuntu@garm:~/garm$ garm-cli pool list
 +--------------------------------------+---------------------------+--------------+-----------------------------------------+------------------+-------+---------+---------------+----------+
 | ID                                   | IMAGE                     | FLAVOR       | TAGS                                    | BELONGS TO       | LEVEL | ENABLED | RUNNER PREFIX | PRIORITY |
 +--------------------------------------+---------------------------+--------------+-----------------------------------------+------------------+-------+---------+---------------+----------+
@@ -705,7 +705,7 @@ Awesome! This runner will be able to pick up jobs that match the labels we've se
 You can list runners for a pool, for a repository, organization or enterprise, or for all of them. To list all runners, you can run:
 
 ```bash
-ubuntu@garm:~$ garm-cli runner list --all
+ubuntu@garm:~$ garm-cli runner list
 +----+---------------------+---------+---------------+--------------------------------------+
 | NR | NAME                | STATUS  | RUNNER STATUS | POOL ID                              |
 +----+---------------------+---------+---------------+--------------------------------------+