[WIP] Update documentation for single/multi tenant configurations #2074

floreks · 2017-06-29T09:53:15Z

Closes #2045. Related to discussion started in #574.

First we have to state what we will support. What I think we should do is:

Provide good documentation for latest supported kubernetes release (currently 1.6).
Provide option to deploy on older clusters but leave advanced configuration up to the users. Only basic yaml without RBAC configuration.
Split deployment into 2 parts: dashboard, rbac configuration
Document details about single/multi tenant approach that our proposed configuration supports.
For multi-tenant setup describe how to authorize users using authorization header and tokens but without specific examples as we don't have enough people to maintain them well.
Simplify head releases and support only latest kubernetes versions with full access to the cluster (by providing yaml file). Of course we will add information about that to warn potential users.
Remove other arch yaml files and just document what architectures we support with example that in order to deploy for different arch user can use this command curl -sSL <dashboard_url> | sed "s/amd64/arm64/g" | kubectl create -f -
State that kubectl proxy is not the right way to authorize users for multi-tenant configurations.

I have updated documentation a bit and if we agree on required changes I will update yamls and remaining docs.

Calling everyone involved in discussion.

@bryk @cheld @rf232 @liggitt @maciaszczykm

maciaszczykm · 2017-06-29T09:57:25Z

README.md

@@ -13,26 +13,51 @@ itself.
 ![Dashboard UI workloads page](docs/dashboard-ui.png)

 ## Deployment
-It is likely that the Dashboard is already installed on your cluster. Check with the following command:
+Provided instructions are compliant with kubernetes 1.6+. If you plan to deploy dashboard on older kubernetes version please


s/dashboard/Dashboard
s/kubernetes/Kubernetes

cheld · 2017-06-29T10:34:02Z

README.md

+TODO multi-tenant SA, Role deployment
+```
+
+### Single-tenant configuration


The deployment section is the single tenant documentation, right?

cheld · 2017-06-29T10:35:34Z

README.md

@@ -13,26 +13,51 @@ itself.
 ![Dashboard UI workloads page](docs/dashboard-ui.png)

 ## Deployment
-It is likely that the Dashboard is already installed on your cluster. Check with the following command:
+Provided instructions are compliant with kubernetes 1.6+. If you plan to deploy dashboard on older kubernetes version please
+follow [these instructions](#older-kubernetes-versions).


I like this idea, but I would move to separate page. The landing page should be as easy as possible
You could do similar with multi-tenant setup

I didn't want to force user to open another page just to copy command in order to deploy rbac configuration. Single-tenant description is also very simple. There is not much more to add so keeping 1 sentence and 1 command on separate page seems unnecessary.

Do we want to force users to open another page just to set up RBACs for dashboard? Usually all commands required to run application are present on a landing page.

Landing Page should describe getting started steps. Everything advanced to subpages

cheld · 2017-06-29T10:36:08Z

README.md

+TODO single-tenant SA, Role deployment
+```
+
+### Older kubernetes versions


move to separate page

I agree here. We can move this information to a separate page.

cheld

I don't like the current structure. Structure should be cleaner and also simpified. We can talk directly

cheld · 2017-06-30T10:59:18Z

My comments on the questions:

Hope so
We must support the current version and the version before. At least this was the rule in kube-deploy.
No, leave as it is. It will become deployment for single tenant.
ok
Yes, please. In addition, you can also add links to issues with detailed discussions
Yes. (Do we need Head at all? Replace by regex?)
Hmm..not sure. I think it is ok
Yes, as part of the multi-tenant setup

floreks · 2017-06-30T11:32:33Z

No, leave as it is. It will become deployment for single tenant.

As we discussed in #574 single-tenant(full dashboard access to the cluster) approach is overall not a secure approach, therefore I'd not make it our default and suggested configuration. I think information about both configurations have to be stated loud and clear on the same level without making one of them more prominent. This way user will have to choose in the beginning configuration he preffers and we will not suggest that he should use one or another.

Either we leave both options with short description on landing page or we only list links to pages with information about second deployment step, i.e.

Deploy dashboard using the following command:
$ ...
Set dashboard privileges by choosing one of the configurations:
link to single-tenant doc
link to multi-tenant doc

maciaszczykm · 2017-06-30T11:59:19Z

Multi/single-tenant is not easy to understand for new users. We have to let beginners, what it is (secure setup or a setup with everything unlocked, which is super dangerous). I would change this name or at least add (secure setup) and (insecure setup) information.

@bryk @rf232 @liggitt

cheld · 2017-06-30T11:59:52Z

If we don't want to provide a default kind of deployment and want to force the user to make a decission than we provide just 2 links on landing page:

link to single-tenant doc
link to multi-tenant doc

In the single tenant doc we provide the current yaml and the current documentation. I don't like to split up the deployment for single tenant in two steps.

maciaszczykm · 2017-06-30T12:01:38Z

@cheld We have to let users know, that installation process has two steps to do it like this I believe.

cheld · 2017-06-30T12:23:08Z

In any case the documentation must explain the decision the user has to take.

The options secure/insecure could work in other scenarios, but in our it does not make sense. So, why would someone want an insecure setup? So every user would follow the secure setup and then fail, because it is far too complicated. Then you have to explain that the insure setup is actually secure for single tenant environments. So, the actual choice for the user is single tenant/multi-tenant. There is no escape. It has to be explained.

cheld · 2017-06-30T12:35:57Z

We have to let users know, that installation process has two steps to do it like this I believe.

In the multi-tenant case that certainly is ok. In the single tenant case, I wonder if there is any benefit.

Maybe you name the yaml something like "grant-full-access-to-dashboard.yaml", but there has to be some benefit...

floreks · 2017-06-30T12:42:23Z

Actually this single-tenant approach could still be insecure even if there is only 1 person that manages the cluster. In example if you deploy ubuntu and decide to give user access to this "virtualized system". Even so user is not aware that underneath kubernetes is used then privilege escalation is possible thanks to pod-to-pod communication because you have deployed single-tenant configuration and dashboard has full access to the cluster.

IMHO single-tenant will always be insecure by default and exposed to potential security breaches. Multi-tenant on the other side will be secure by default.

codecov · 2017-06-30T12:43:27Z

Codecov Report

Merging #2074 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2074   +/-   ##
=======================================
  Coverage   59.35%   59.35%           
=======================================
  Files         545      545           
  Lines       11556    11556           
=======================================
  Hits         6859     6859           
  Misses       4524     4524           
  Partials      173      173

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e42a910...9836bdd. Read the comment docs.

cheld · 2017-06-30T12:52:53Z

@gertipoppel will help to bring it into proper shape. But please provide all the required steps and yaml

floreks · 2017-06-30T13:04:53Z

I can't provide any steps or yamls until we agree how it should look like. Anyway yamls are not required. I can prepare them once everything is documented.

@bryk @rf232 could you share your opinion?

cheld · 2017-06-30T13:37:38Z

I think we agree that there is no point in documenting a setup for production and defining it as insecure by default and a gate for security breaches. In this case we should not document it at all and only document the secure setup, but then in all details.

On the other hand this architectual problem is known since the beginning. So far we considered it secure enough for single tenant usage and securing multi tenant usage as an ongoing process.

floreks · 2017-07-03T07:57:24Z

I think that we can still document this setup but we are obligated to warn users about potential security issues and maybe suggest some steps to avoid it, i.e. by setting up network policies and blocking traffic from other pods/namespaces.

I only wouldn't default to single setup but rather present both configurations as equal and let user choose what he needs. We only need to describe pros and cons of both configurations. Then we can just point people to our documentation if there are some issues caused by not reading it and close them.

liggitt · 2017-07-04T03:37:44Z

On the other hand this architectual problem is known since the beginning. So far we considered it secure enough for single tenant usage

I strongly disagree. Private pod and service networks should not be assumed, even in single-tenant setups.

I think that we can still document this setup but we are obligated to warn users about potential security issues and maybe suggest some steps to avoid it, i.e. by setting up network policies and blocking traffic from other pods/namespaces.

Yes, I'd expect a clear explanation of the exposure and a list of the aspects that must be secured to avoid letting unintended actors make use of that exposure

bryk · 2017-07-05T13:38:23Z

@floreks @maciaszczykm

Can we go with the secure/insecure wording? Or insecure/default? And explain why someone would use insecure (for onboarding and stuff). I believe that multi-single tenant wording hides away the important piece of security information that we want to convey.

bryk · 2017-07-05T13:49:13Z

README.md

+
+For security reasons installation has been split into two parts:
+[Deployment](#deployment) and [Configuration](#configuration). Deployment part will deploy Dashboard on your
+cluster without any privileges. It will only work if RBACs are disabled on your cluster.


Without any privileges? I think this is actually "with administrator privileges open to anyone with access to the UI". Is this correct?

This is the current behavior but my proposal is to split installation and privileges configuration into 2 parts so simple kubectl create -f <dashboard_link> would deploy dashboard but without cluster role or service account with admin privileges.

Then as a second step we'd deploy privileges configuration based on chosen configuration: minimal or full.

maciaszczykm · 2017-07-05T14:31:43Z

@floreks @maciaszczykm

Can we go with the secure/insecure wording? Or insecure/default?

I suggested same thing in #2074 (comment).

floreks · 2017-07-05T14:45:16Z

Can we go with the secure/insecure wording? Or insecure/default?

Yes, I'd also go with this wording. We have to make sure that when dashboard is deployed with kubernetes then its' default configuration will not cause any security issues. That is currently the case.

cheld · 2017-07-05T17:48:19Z

Or insecure/default?

I am fine with that (or something else). Of course, it would be bizzar if the "default" installation document is not complete and only usefull for experts...Anyway lets wait and see how the document will look like.

bryk · 2017-07-25T09:39:50Z

Any progress here? It'd be great to have this for 1.6.2.

floreks · 2017-07-25T09:41:28Z

It's on hold for now as I'm working on implementing log in mechanism for dashboard. Once it's done we will fallback to secure by default and rely on it.

bryk · 2017-07-25T09:41:52Z

Awesome, thanks!

maciaszczykm · 2017-09-25T09:18:08Z

Already done in a different way.

floreks self-assigned this Jun 29, 2017

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jun 29, 2017

maciaszczykm reviewed Jun 29, 2017

View reviewed changes

cheld reviewed Jun 29, 2017

View reviewed changes

cheld suggested changes Jun 30, 2017

View reviewed changes

floreks added 2 commits June 30, 2017 14:33

Update documentation

2b2257f

Update documentation

9836bdd

floreks force-pushed the update-documentation branch from 3d4fab9 to 9836bdd Compare June 30, 2017 12:33

bryk reviewed Jul 5, 2017

View reviewed changes

maciaszczykm closed this Sep 25, 2017

floreks deleted the update-documentation branch November 22, 2017 15:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Update documentation for single/multi tenant configurations #2074

[WIP] Update documentation for single/multi tenant configurations #2074

floreks commented Jun 29, 2017 •

edited

Loading

maciaszczykm Jun 29, 2017

cheld Jun 29, 2017

cheld Jun 29, 2017

floreks Jun 29, 2017

cheld Jun 29, 2017

cheld Jun 29, 2017

floreks Jun 29, 2017

cheld left a comment

cheld commented Jun 30, 2017 •

edited

Loading

floreks commented Jun 30, 2017

maciaszczykm commented Jun 30, 2017

cheld commented Jun 30, 2017

maciaszczykm commented Jun 30, 2017

cheld commented Jun 30, 2017 •

edited

Loading

cheld commented Jun 30, 2017 •

edited

Loading

floreks commented Jun 30, 2017

codecov bot commented Jun 30, 2017 •

edited

Loading

cheld commented Jun 30, 2017

floreks commented Jun 30, 2017

cheld commented Jun 30, 2017

floreks commented Jul 3, 2017

liggitt commented Jul 4, 2017

bryk commented Jul 5, 2017

bryk Jul 5, 2017

floreks Jul 5, 2017 •

edited

Loading

maciaszczykm commented Jul 5, 2017

floreks commented Jul 5, 2017

cheld commented Jul 5, 2017 •

edited

Loading

bryk commented Jul 25, 2017

floreks commented Jul 25, 2017

bryk commented Jul 25, 2017

maciaszczykm commented Sep 25, 2017

[WIP] Update documentation for single/multi tenant configurations #2074

[WIP] Update documentation for single/multi tenant configurations #2074

Conversation

floreks commented Jun 29, 2017 • edited Loading

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

cheld left a comment

Choose a reason for hiding this comment

cheld commented Jun 30, 2017 • edited Loading

floreks commented Jun 30, 2017

maciaszczykm commented Jun 30, 2017

cheld commented Jun 30, 2017

maciaszczykm commented Jun 30, 2017

cheld commented Jun 30, 2017 • edited Loading

cheld commented Jun 30, 2017 • edited Loading

floreks commented Jun 30, 2017

codecov bot commented Jun 30, 2017 • edited Loading

Codecov Report

cheld commented Jun 30, 2017

floreks commented Jun 30, 2017

cheld commented Jun 30, 2017

floreks commented Jul 3, 2017

liggitt commented Jul 4, 2017

bryk commented Jul 5, 2017

Choose a reason for hiding this comment

floreks Jul 5, 2017 • edited Loading

Choose a reason for hiding this comment

maciaszczykm commented Jul 5, 2017

floreks commented Jul 5, 2017

cheld commented Jul 5, 2017 • edited Loading

bryk commented Jul 25, 2017

floreks commented Jul 25, 2017

bryk commented Jul 25, 2017

maciaszczykm commented Sep 25, 2017

floreks commented Jun 29, 2017 •

edited

Loading

cheld commented Jun 30, 2017 •

edited

Loading

cheld commented Jun 30, 2017 •

edited

Loading

cheld commented Jun 30, 2017 •

edited

Loading

codecov bot commented Jun 30, 2017 •

edited

Loading

floreks Jul 5, 2017 •

edited

Loading

cheld commented Jul 5, 2017 •

edited

Loading