ENDOC-492 ent CLI troubleshooting and versioning from Notions #504

Lyd1aCla1r3 · 2022-04-27T19:23:01Z

extensive page rework to improve flow and formatting

jyunmitch

Not to make more work, but it might be nice to have a separate page with all the cli commands and their various forms, like a cheatsheet as a quick reference that links back to this page. Just a thought

jyunmitch · 2022-04-27T20:49:19Z

vuepress/docs/next/docs/reference/entando-cli.md

 ```sh
 ent prj get-bundle-id --auto
 ```

-A unique identifier will also be calculated for each microservice plugin in your project. You can determine this identifier with the command 
+Determine the microservice plugin identifier:


nothing wrong but it can be called plugin ID too. in other tutorials, it's been called plugin ID often. I'm used to it being called that.

jyunmitch · 2022-04-27T20:52:53Z

vuepress/docs/next/docs/reference/entando-cli.md


-To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).
+### Custom Resource Wrapper
+Entando supports a series of `ent ecr` commands to facilitate custom resource operations. 


support >> provides seems more accurate

jyunmitch · 2022-04-27T20:58:21Z

vuepress/docs/next/docs/reference/entando-cli.md

-This sets the minimal profile data and explains next steps.
+#### Determine Custom Resource Identifiers
+
+The helpers `get-bundle-id` and `get-plugin-id` have been added to `ent ecr` to calculate and display unique identifiers related to custom resources. This provides additional security controls around bundle-specific and microservice plugin resources.


is this the same or different from the get-bundle-id or get-plugin-id from above in projects? It sounds different but looks the same so confusing

they are different commands relating to different things. i modified the text right above the commands to emphasize that.

jyunmitch · 2022-04-27T21:03:11Z

vuepress/docs/next/docs/reference/entando-cli.md

@@ -93,10 +93,23 @@ Use `ent help` to review the list of available commands
 ```
 Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. For general configuration options related to ent itself, see `ent --help`.


question, should we use "ent" when it's not part of a command. I feel like we should capitalize a reference to "Ent", the cli when just talking about it, but it's not a strong opinion. thoughts?

i think we should keep it lowercase. it's either referred to as "ent" or ent elsewhere in the documentation. i prefer "ent" because it doesn't represent a command or entity; "ent" is the abbreviation for the Entando CLI, and a capital E looks off, as does all caps.

Agreed, usually if you reference a command you use the exact name. Linux is case-sensitive so it definitely matters here.

jyunmitch · 2022-04-27T21:08:46Z

vuepress/docs/next/docs/reference/entando-cli.md


-This sets the minimal profile data and explains next steps.
+#### Determine Custom Resource Identifiers


this confused me, Custom resource IDs?

yes. per the text right beneath the header.

Let's discuss this language a bit. Custom resource is a very general term and the ecr commands here are specifically and only for bundles. When you use ent ecr deploy, ent ecr deploy, etc. you are only dealing with a bundle which is single kind of custom resource, the EntandoDeBundle.

jyunmitch · 2022-04-27T21:15:28Z

vuepress/docs/next/docs/reference/entando-cli.md

+ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL
+```
+### Profile Management
+To manage and switch between different ent configurations, use `ent profile`. To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).


ent configuration >> ent profile configuration?? not sure but ent configuration can refer to how and what version your ent is configured?And here we are talking more about profiles?

i think it's implied we're talking about profiles here ?? pretty sure an ent configuration is a profile.

ent configuration is confusing. What we're doing here is switching between different profiles which help us connect to different Entando Applications. Maybe just change it to "Entando configurations" to avoid confusion with the ent command.

The clause "To switch between different Entando Applications, even if they are in different clusters," can be removed since the first sentence explains it.

jyunmitch · 2022-04-27T21:22:17Z

vuepress/docs/next/docs/reference/entando-cli.md

+The CLI is a useful debug tool to identify and correct issues with an Entando instance. 
+
+#### Error Location
+Zero in on error messages in the EntandoApp pods:


zero in >> find or retrieve? a little confusing what zero in means

"find" is a bit too passive and loose, and idk if you're actually retrieving anything - that would imply something is excerpted or returned. i like zero in on but maybe that would confuse a non-native speaker... i guess "locate" is the best choice, even though it's also kind of passive and boring...

jyunmitch · 2022-04-27T21:25:52Z

vuepress/docs/next/docs/reference/entando-cli.md

+#### Extraction Error
+To resolve the error "Unable to extract the application client secret":
+
+1. Verify that the current profile namespace and application name are correct match the output of the following command


and application name are correct match the output >> and application name match the output with the following command??

what is it correcting? a little unclear

typo! correct and match

nshaw · 2022-04-28T12:30:10Z

Please remove the NVM dependency from the prerequisites. It's no longer used on Windows.

nshaw

Overall the structure looks good. Biggest issue to sort out is the "Custom Resource" section which we can discuss,

nshaw · 2022-04-28T12:24:07Z

vuepress/docs/next/docs/reference/entando-cli.md

@@ -93,10 +93,23 @@ Use `ent help` to review the list of available commands
 ```
 Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. For general configuration options related to ent itself, see `ent --help`.


Agreed, usually if you reference a command you use the exact name. Linux is case-sensitive so it definitely matters here.

nshaw · 2022-04-28T12:32:59Z

vuepress/docs/next/docs/reference/entando-cli.md

-### Project Setup
+For example, to reuse an existing VM:
+``` sh
+ent quickstart --vm-reuse[=YOUR-EXISTING-VM]


no brackets here.

nshaw · 2022-04-28T12:36:47Z

vuepress/docs/next/docs/reference/entando-cli.md


-To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).
+### Custom Resource Wrapper


ECR actually references Entando Component Repository - although some of the new options do have more to do with custom resources. Maybe change line 233 "to facilitate custom resource operations" -> "for interaction with the Entando Component Repository". The section title should probably change too.

Side note, the ECR is likely to change to Local Hub in 7.1 but this API likely won't change so we'll need to watch for that.

nshaw · 2022-04-28T12:38:23Z

vuepress/docs/next/docs/reference/entando-cli.md

+ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL
+```
+### Profile Management
+To manage and switch between different ent configurations, use `ent profile`. To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).


ent configuration is confusing. What we're doing here is switching between different profiles which help us connect to different Entando Applications. Maybe just change it to "Entando configurations" to avoid confusion with the ent command.

nshaw · 2022-04-28T12:39:27Z

vuepress/docs/next/docs/reference/entando-cli.md

+ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL
+```
+### Profile Management
+To manage and switch between different ent configurations, use `ent profile`. To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).


The clause "To switch between different Entando Applications, even if they are in different clusters," can be removed since the first sentence explains it.

nshaw · 2022-04-28T12:42:10Z

vuepress/docs/next/docs/reference/entando-cli.md

+### Profile Management
+To manage and switch between different ent configurations, use `ent profile`. To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).
+
+It is common practice for the vendor tool that connects to a cloud Kubernetes to create a Kubernetes context that must be linked to the profile. An overview of the current connection and profile information is provided via `ent status`.


Passive voice is weird on the first sentence. Change to "Cloud Kubernetes tools typically create a Kubernetes context which can be linked to an Entando profile."

nshaw · 2022-04-28T12:53:02Z

vuepress/docs/next/docs/reference/entando-cli.md


-This sets the minimal profile data and explains next steps.
+#### Determine Custom Resource Identifiers


Let's discuss this language a bit. Custom resource is a very general term and the ecr commands here are specifically and only for bundles. When you use ent ecr deploy, ent ecr deploy, etc. you are only dealing with a bundle which is single kind of custom resource, the EntandoDeBundle.

nshaw · 2022-04-28T12:54:06Z

vuepress/docs/next/docs/reference/entando-cli.md

 ```
 ent pro link [contextName]
 ```
-This instructs ent how to connect to the Kubernetes containing the Entando Application.
+This instructs ent to connect to the Kubernetes containing the Entando Application.


Needs better wording, but it only tells ent how. It doesn't actually make a connection until you issue the actual commands. Ent profile just sets up the configuration so you can do it.

jyunmitch · 2022-04-29T15:04:08Z

vuepress/docs/next/docs/reference/entando-cli.md


-To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).
+#### ECR Wrapper
+Entando provides a series of `ent ecr` commands for interaction with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). The following commands apply specifically and only to bundles.


above in line 72(could not leave comment there), 'ECR' appears without the full name which may confuse beginners. It would be good to have the full name there too since this document is not necessarily used in a linear fashion.

jyunmitch · 2022-04-29T15:10:00Z

vuepress/docs/next/docs/reference/entando-cli.md


 ```
 > Collected diagdata available under "~/.entando/reports/entando-diagdata-2020-11-19T02:58:47+0000" for consultation
 > Collected diagdata available in archive "~/.entando/reports/entando-diagdata-2020-11-19T02:58:47+0000.tgz"
 ```
+### Troubleshooting
+The CLI is a useful debug tool to identify and correct issues with an Entando instance. 


debug >> debugging

this is a fine point... "debugging tool" is understood to refer to programs developed exclusively for that purpose. i think it depends on your frame of reference, but "debug" is a widely used term.

ENDOC-492

05fc279

Lyd1aCla1r3 requested review from nshaw and jyunmitch April 27, 2022 19:23

jyunmitch reviewed Apr 27, 2022

View reviewed changes

ENDOC-492 PR feedback

30ab83b

nshaw requested changes Apr 28, 2022

View reviewed changes

ENDOC-492 Reorg and fixes

1bb1611

nshaw approved these changes Apr 28, 2022

View reviewed changes

jyunmitch reviewed Apr 29, 2022

View reviewed changes

ENDOC-492 Last tweaks

3259430

jyunmitch approved these changes May 2, 2022

View reviewed changes

nshaw merged commit 33140ac into main May 2, 2022

nshaw deleted the ENDOC-492 branch May 2, 2022 16:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-492 ent CLI troubleshooting and versioning from Notions #504

ENDOC-492 ent CLI troubleshooting and versioning from Notions #504

Lyd1aCla1r3 commented Apr 27, 2022

jyunmitch left a comment

jyunmitch Apr 27, 2022

jyunmitch Apr 27, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

nshaw Apr 28, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

nshaw Apr 28, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

jyunmitch Apr 27, 2022

Lyd1aCla1r3 Apr 27, 2022

nshaw commented Apr 28, 2022

nshaw left a comment

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

nshaw Apr 28, 2022

jyunmitch Apr 29, 2022

jyunmitch Apr 29, 2022

Lyd1aCla1r3 Apr 29, 2022

		@@ -93,10 +93,23 @@ Use `ent help` to review the list of available commands
		```
		Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. For general configuration options related to ent itself, see `ent --help`.


		This sets the minimal profile data and explains next steps.
		#### Determine Custom Resource Identifiers


		To switch between different Entando Applications, even if they are in different clusters, `ent profile` uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`).
		### Custom Resource Wrapper

ENDOC-492 ent CLI troubleshooting and versioning from Notions #504

ENDOC-492 ent CLI troubleshooting and versioning from Notions #504

Conversation

Lyd1aCla1r3 commented Apr 27, 2022

jyunmitch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nshaw commented Apr 28, 2022

nshaw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment