Skip to content

Commit fcba34e

Browse files
shu-mutouk8s-ci-robot
authored andcommitted
Migrate documentation for installation (#4220)
Migrate Wiki pages for Installation and Certificate Management into `docs`.
1 parent 2fb062b commit fcba34e

File tree

2 files changed

+103
-2
lines changed

2 files changed

+103
-2
lines changed

docs/user/certificate-management.md

+44-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,49 @@
11
# Certificate management
22

3-
___It will be moved soon, for now you can [visit Wiki](https://github.com/kubernetes/dashboard/wiki/Certificate-management).___
3+
This document describes shortly how to get certificates, that can be used to enable HTTPS in Dashboard. There are two steps required to do it:
4+
5+
1. Generate certificates.
6+
1. [Public trusted CA](#public-trusted-certificate-authority).
7+
2. [Self-signed certificate](#self-signed-certificate).
8+
2. Pass them to Dashboard.
9+
1. In case you are following [Recommended Setup](./installation.md#recommended-setup) to deploy Dashboard just generate certificates and follow it.
10+
2. In any other case you need to alter Dashboard's YAML deploy file and pass --tls-key-file and --tls-cert-file flags to Dashboard. More information about how to mount them into the pods can be found [here](https://kubernetes.io/docs/concepts/storage/volumes/).
11+
12+
## Public trusted Certificate Authority
13+
14+
There are many public and free certificate providers to choose from. One of the best trusted certificate providers is [Let's encrypt](https://letsencrypt.org/). Everything you need to know about how to generate certificates signed by their trusted CA can be found [here](https://letsencrypt.org/getting-started/).
15+
16+
## Self-signed certificate
17+
18+
In case you want to generate certificates on your own you need library like [OpenSSL](https://www.openssl.org/) that will help you do that.
19+
20+
### Generate private key and certificate signing request
21+
22+
A private key and certificate signing request are required to create an SSL certificate. These can be generated with a few simple commands. When the openssl req command asks for a “challenge password”, just press return, leaving the password empty. This password is used by Certificate Authorities to authenticate the certificate owner when they want to revoke their certificate. Since this is a self-signed certificate, there’s no way to revoke it via CRL (Certificate Revocation List).
23+
24+
```
25+
openssl genrsa -des3 -passout pass:x -out dashboard.pass.key 2048
26+
...
27+
openssl rsa -passin pass:x -in dashboard.pass.key -out dashboard.key
28+
# Writing RSA key
29+
rm dashboard.pass.key
30+
openssl req -new -key dashboard.key -out dashboard.csr
31+
...
32+
Country Name (2 letter code) [AU]: US
33+
...
34+
A challenge password []:
35+
...
36+
```
37+
38+
### Generate SSL certificate
39+
40+
The self-signed SSL certificate is generated from the `dashboard.key` private key and `dashboard.csr` files.
41+
42+
```
43+
openssl x509 -req -sha256 -days 365 -in dashboard.csr -signkey dashboard.key -out dashboard.crt
44+
```
45+
46+
The `dashboard.crt` file is your certificate suitable for use with Dashboard along with the `dashboard.key` private key.
447

548
----
649
_Copyright 2019 [The Kubernetes Dashboard Authors](https://github.com/kubernetes/dashboard/graphs/contributors)_

docs/user/installation.md

+59-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,64 @@
11
# Installation
22

3-
___It will be moved soon, for now you can [visit Wiki](https://github.com/kubernetes/dashboard/wiki/Installation).___
3+
## Official release
4+
5+
**IMPORTANT:** Before upgrading from older version of Dashboard to 1.7+ make sure to delete Cluster Role Binding for `kubernetes-dashboard` Service Account, otherwise Dashboard will have full admin access to the cluster.
6+
7+
### Quick setup
8+
9+
The fastest way of deploying Dashboard has been described in our [README](../../README.md). It is destined for people that are new to Kubernetes and want to quickly start using Dashboard. Other possible setups for more experienced users, that want to know more about our deployment procedure can be found below.
10+
11+
### Recommended setup
12+
13+
To access Dashboard directly (without `kubectl proxy`) valid certificates should be used to establish a secure HTTPS connection. They can be generated using public trusted Certificate Authorities like [Let's Encrypt](https://letsencrypt.org/). Use them to replace the auto-generated certificates from Dashboard.
14+
15+
By default self-signed certificates are generated and stored in-memory. In case you would like to use your custom certificates follow the below steps, otherwise skip directly to the Dashboard deploy part.
16+
17+
Custom certificates have to be stored in a secret named `kubernetes-dashboard-certs` in the same namespace as Kubernetes Dashboard. Assuming that you have `dashboard.crt` and `dashboard.key` files stored under `$HOME/certs` directory, you should create secret with contents of these files:
18+
19+
```
20+
kubectl create secret generic kubernetes-dashboard-certs --from-file=$HOME/certs -n kubernetes-dashboard
21+
```
22+
23+
Afterwards, you are ready to deploy Dashboard using the following command:
24+
25+
```
26+
kubectl create -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta3/aio/deploy/recommended.yaml
27+
```
28+
29+
### Alternative setup
30+
31+
This setup is not fully secure. Certificates are not used and Dashboard is exposed only over HTTP. In this setup access control can be ensured only by using [Authorization Header](./access-control/README.md#authorization-header) feature.
32+
33+
To deploy Dashboard execute following command:
34+
35+
```
36+
kubectl create -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta3/aio/deploy/alternative.yaml
37+
```
38+
39+
## Development release
40+
41+
Besides official releases, there are also development releases, that are pushed after every successful master build. It is not advised to use them on production environment as they are less stable than the official ones. Following sections describe installation and discovery of development releases.
42+
43+
### Installation
44+
45+
In most of the use cases you need to execute the following command to deploy latest development release:
46+
47+
```
48+
$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta3/aio/deploy/head.yaml
49+
```
50+
51+
### Update
52+
53+
Once installed, the deployment is not automatically updated. In order to update it you need to delete the deployment's pods and wait for it to be recreated. After recreation, it should use the latest image.
54+
55+
Delete all Dashboard pods (assuming that Dashboard is deployed in kubernetes-dashboard namespace):
56+
57+
```
58+
kubectl -n kubernetes-dashboard delete $(kubectl -n kubernetes-dashboard get pod -o name | grep dashboard)
59+
pod "dashboard-metrics-scraper-fb986f88d-gnfnk" deleted
60+
pod "kubernetes-dashboard-7d8b9cc8d-npljm" deleted
61+
```
462

563
----
664
_Copyright 2019 [The Kubernetes Dashboard Authors](https://github.com/kubernetes/dashboard/graphs/contributors)_

0 commit comments

Comments
 (0)