docs: Add installation option description #11735

qudtjs0753 · 2023-09-03T15:52:03Z

Fixes #7838

Motivation

To give clarity about namespace install and managed namespace install description in operator manual

Modifications

I update content in warning message(namespace install vs managed namespace install)

Verification

.

Signed-off-by: KBS <qudtjs0753@naver.com>

agilgur5

I've only used a cluster-scoped install, so this looks like a nice addition to me!

Made some copy-edits below

agilgur5 · 2023-09-04T00:26:08Z

docs/installation.md

@@ -30,6 +30,12 @@ Determine your base installation option.
 * A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
 * A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).

+!!! Warning "namespace install vs. managed namespace install"


Suggested change

!!! Warning "namespace install vs. managed namespace install"

!!! Info "namespace install vs. managed namespace install"

I think info makes more sense here as opposed to a warning. There is nothing to warn about, this is just descriptive

agilgur5 · 2023-09-04T00:37:57Z

docs/installation.md

@@ -30,6 +30,12 @@ Determine your base installation option.
 * A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
 * A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).

+!!! Warning "namespace install vs. managed namespace install"
+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  


Suggested change

A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.

A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed.

A managed namespace install allows Workflows to run only in one namespace _other than_ the one where Argo Workflows is installed.

You can use a managed namespace install if you want some users or services to run Workflows without granting them privileges in the namespace where Argo Workflows is installed.

Use simpler & more direct language

"processes" -> "services", so as to not confuse folks with Unix processes. "Service" as in "ServiceAccount" fits better in k8s

tiny formatting changes

The last sentence here can be moved to managed-namespace.md. Could put it in the same paragraph as the example that is to be moved.

The first two sentences I think are redundant with managed-namespace.md

agilgur5 · 2023-09-04T00:45:10Z

docs/installation.md

+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  
+
+    For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.
+    To configure a managed namespace install, edit the workflow-controller and argo-server Deployments to pass the --managed-namespace argument.


Suggested change

To configure a managed namespace install, edit the workflow-controller and argo-server Deployments to pass the --managed-namespace argument.

To configure a managed namespace install, edit the `workflow-controller` and `argo-server` Deployments to pass the `--managed-namespace` flag.

add backticks around naming

"argument" -> "flag"

managed-namespace.md describes this better with a YAML code block, so I don't this is needed

agilgur5 · 2023-09-04T00:47:12Z

docs/installation.md

+!!! Warning "namespace install vs. managed namespace install"
+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  
+
+    For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.


Suggested change

For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.

For example, if you only run CI/CD Workflows that are maintained by the same team that manages the Argo Workflows installation, you may want a namespace install.

But if all the Workflows are run by a separate data science team, you may want to give them a "data-science-workflows" namespace and use a managed namespace install of Argo Workflows in another namespace.

Use simpler & more direct language

"managed namespace install" is not quoted anywhere else, so remove quotes there. instead quote "data-science-workflows"

tiny formatting changes

Let's move this to managed-namespace.md instead

agilgur5 · 2023-09-04T00:55:41Z

Oh, this is pretty much a verbatim copy+paste of Crenshaw's SO Answer linked in #7838. That would have been good to make clear & credit. Some of the formatting I added above is also present in the SO Answer

agilgur5

Upon second glance, this documentation already exists in the above linked managed-namespace.md: https://argoproj.github.io/argo-workflows/managed-namespace/.
There is a more detailed configuration description there as well.

As a result, I think much of this is redundant, but we can make the link clearer and move the usage example to managed-namespace.md

agilgur5 · 2023-09-04T01:07:17Z

docs/installation.md

+!!! Warning "namespace install vs. managed namespace install"
+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  
+
+    For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.


Let's move this to managed-namespace.md instead

agilgur5 · 2023-09-04T01:08:28Z

docs/installation.md

+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  
+
+    For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.
+    To configure a managed namespace install, edit the workflow-controller and argo-server Deployments to pass the --managed-namespace argument.


managed-namespace.md describes this better with a YAML code block, so I don't this is needed

agilgur5 · 2023-09-04T01:09:53Z

docs/installation.md

@@ -30,6 +30,12 @@ Determine your base installation option.
 * A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
 * A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).

+!!! Warning "namespace install vs. managed namespace install"
+    A namespace install allows Workflows to run only in the namespace where Argo Workflows is installed. A managed namespace install allows Workflows to run only in one namespace besides the one where Argo Workflows is installed. Using a managed namespace install might make sense if you want some users/processes to be able to run Workflows without granting them any privileges in the namespace where Argo Workflows is installed.  


The last sentence here can be moved to managed-namespace.md. Could put it in the same paragraph as the example that is to be moved.

The first two sentences I think are redundant with managed-namespace.md

agilgur5 · 2023-09-04T01:11:58Z

docs/installation.md

@@ -30,6 +30,12 @@ Determine your base installation option.
 * A **namespace install** only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
 * A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).


Suggested change

* A **managed namespace install**: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).

* A **managed namespace install**: only executes workflows in a separate namespace from the one it is installed in. See [Managed Namespace](managed-namespace.md) for more details.

Thank you for your detailed feedback @agilgur5! I applied your suggestion, so result are as follows.

This is managed-namespace.md

This one is changed description with link of managed-namespace.md in installation.md

Awesome, looks great and thanks for providing the screenshots too!

Move description to managed-namespace.md. Delete obsolete description and use simpler language. Make the link more clearer Signed-off-by: KBS <qudtjs0753@naver.com>

agilgur5

Just one tiny improvement below, otherwise LGTM. Thanks for adding this!

docs/managed-namespace.md

Co-authored-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Signed-off-by: KBS <qudtjs0753@naver.com>

agilgur5 · 2023-09-04T05:56:55Z

CI looks like it's failing on unrelated test flakes 😕 Will need a retry from an admin

qudtjs0753 closed this Sep 3, 2023

qudtjs0753 reopened this Sep 3, 2023

docs: Add managed namespace descrption

81a92ea

Signed-off-by: KBS <qudtjs0753@naver.com>

qudtjs0753 force-pushed the docs-namespace-install branch from 75e48b8 to 81a92ea Compare September 3, 2023 23:13

agilgur5 added the area/docs Incorrect, missing, or mistakes in docs label Sep 4, 2023

agilgur5 reviewed Sep 4, 2023

View reviewed changes

agilgur5 requested changes Sep 4, 2023

View reviewed changes

docs: Correct docs based on feedback

8da3609

Move description to managed-namespace.md. Delete obsolete description and use simpler language. Make the link more clearer Signed-off-by: KBS <qudtjs0753@naver.com>

agilgur5 reviewed Sep 4, 2023

View reviewed changes

docs/managed-namespace.md Outdated Show resolved Hide resolved

Add title to the info block

81b91bf

Co-authored-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com> Signed-off-by: KBS <qudtjs0753@naver.com>

agilgur5 approved these changes Sep 4, 2023

View reviewed changes

agilgur5 requested a review from terrytangyuan September 4, 2023 04:44

terrytangyuan approved these changes Sep 11, 2023

View reviewed changes

terrytangyuan enabled auto-merge (squash) September 11, 2023 00:23

Merge branch 'master' into docs-namespace-install

cec0706

terrytangyuan changed the title ~~docs: Add installation option descrption~~ docs: Add installation option description Sep 13, 2023

terrytangyuan disabled auto-merge September 13, 2023 22:52

terrytangyuan enabled auto-merge (squash) September 13, 2023 22:53

terrytangyuan merged commit ab35c98 into argoproj:master Sep 13, 2023
25 checks passed

agilgur5 mentioned this pull request Sep 14, 2023

docs: improve grammar + wording on Managed NS install #11817

Merged

agilgur5 mentioned this pull request Sep 22, 2023

REQUEST: Promotion to Reviewer for @agilgur5 argoproj/argoproj#242

Closed

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add installation option description #11735

docs: Add installation option description #11735

qudtjs0753 commented Sep 3, 2023 •

edited

agilgur5 left a comment

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 commented Sep 4, 2023

agilgur5 left a comment

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 Sep 4, 2023 •

edited

qudtjs0753 Sep 4, 2023

agilgur5 Sep 4, 2023

agilgur5 left a comment •

edited

agilgur5 commented Sep 4, 2023

	!!! Warning "namespace install vs. managed namespace install"
	!!! Info "namespace install vs. managed namespace install"

	To configure a managed namespace install, edit the workflow-controller and argo-server Deployments to pass the --managed-namespace argument.
	To configure a managed namespace install, edit the `workflow-controller` and `argo-server` Deployments to pass the `--managed-namespace` flag.

	For example, if you only run CI/CD-related Workflows that are maintained by the same team that manages the Argo Workflows installation, it's probably reasonable to use a namespace install. But if all the Workflows are run by a separate data science team, it probably makes sense to give them a data-science-workflows namespace and run a "managed namespace install" of Argo Workflows from another namespace.
	For example, if you only run CI/CD Workflows that are maintained by the same team that manages the Argo Workflows installation, you may want a namespace install.
	But if all the Workflows are run by a separate data science team, you may want to give them a "data-science-workflows" namespace and use a managed namespace install of Argo Workflows in another namespace.

		@@ -30,6 +30,12 @@ Determine your base installation option.
		* A namespace install only executes workflows in the namespace it is installed in (typically `argo`). Look for `namespace-install.yaml` in the [release assets](https://github.com/argoproj/argo-workflows/releases/latest).
		* A managed namespace install: only executes workflows in a specific namespace ([learn more](managed-namespace.md)).

docs: Add installation option description #11735

docs: Add installation option description #11735

Conversation

qudtjs0753 commented Sep 3, 2023 • edited

Motivation

Modifications

Verification

agilgur5 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

agilgur5 commented Sep 4, 2023

agilgur5 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

agilgur5 Sep 4, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agilgur5 left a comment • edited

Choose a reason for hiding this comment

agilgur5 commented Sep 4, 2023

qudtjs0753 commented Sep 3, 2023 •

edited

agilgur5 Sep 4, 2023 •

edited

agilgur5 left a comment •

edited