diff options
author | WuKong <rebirthmonkey@gmail.com> | 2017-12-23 21:49:35 +0100 |
---|---|---|
committer | WuKong <rebirthmonkey@gmail.com> | 2017-12-23 21:49:58 +0100 |
commit | 1100c66ce03a059ebe7ece9734e799b49b3a5a9e (patch) | |
tree | a057e7e7511f6675a9327b79e6919f07c5f89f07 /README.md | |
parent | 7a4dfdde6314476ae2a1a1c881ff1e3c430f790e (diff) |
moonv4 cleanup
Change-Id: Icef927f3236d985ac13ff7376f6ce6314b2b39b0
Signed-off-by: WuKong <rebirthmonkey@gmail.com>
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 00000000..ba3604d6 --- /dev/null +++ b/README.md @@ -0,0 +1,381 @@ +# Moon +__Version 4.3__ + +This directory contains all the modules for running the Moon platform. + +## Installation +### kubeadm +You must follow those explanations to install `kubeadm`: +> https://kubernetes.io/docs/setup/independent/install-kubeadm/ + +To summarize, you must install `docker`: +```bash +apt update +apt install -y docker.io +``` + +And then, install `kubeadm`: +```bash +apt update && apt install -y apt-transport-https +curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - +cat <<EOF >/etc/apt/sources.list.d/kubernetes.list +deb http://apt.kubernetes.io/ kubernetes-xenial main +EOF +apt update +apt install -y kubelet kubeadm kubectl +``` + +### Moon +The Moon code is not necessary to start the platform but you need +Kubernetes configuration files from the GIT repository. + +The easy way is to clone the Moon code: +```bash +git clone https://git.opnfv.org/moon +cd moon/moonv4 +export MOON=$(pwd) +``` + +### OpenStack +You must have the following OpenStack components installed somewhere: +- nova, see [Nova install](https://docs.openstack.org/mitaka/install-guide-ubuntu/nova-controller-install.html) +- glance, see [Glance install](https://docs.openstack.org/glance/pike/install/) + +A Keystone component is automatically installed and configured in the Moon platform. +After the Moon platform installation, the Keystone server will be available +at: `http://localhost:30005 or http://\<servername\>:30005` + +You can also use your own Keystone server if you want. + +## Initialisation +### kubeadm +The `kubeadm` platform can be initialized with the following shell script: +```bash +sh kubernetes/init_k8s.sh +``` + +Wait until all the kubeadm containers are in the `running` state: +```bash +watch kubectl get po --namespace=kube-system +``` + +You must see something like this: + + $ kubectl get po --namespace=kube-system + NAME READY STATUS RESTARTS AGE + calico-etcd-7qgjb 1/1 Running 0 1h + calico-node-f8zvm 2/2 Running 1 1h + calico-policy-controller-59fc4f7888-ns9kv 1/1 Running 0 1h + etcd-varuna 1/1 Running 0 1h + kube-apiserver-varuna 1/1 Running 0 1h + kube-controller-manager-varuna 1/1 Running 0 1h + kube-dns-bfbb49cd7-rgqxn 3/3 Running 0 1h + kube-proxy-x88wg 1/1 Running 0 1h + kube-scheduler-varuna 1/1 Running 0 1h + +### Moon +The Moon platform is composed on the following components: +* `consul`: a Consul configuration server +* `db`: a MySQL database server +* `keystone`: a Keystone authentication server +* `gui`: a Moon web interface +* `manager`: the Moon manager for the database +* `orchestrator`: the Moon component that manage pods in te K8S platform +* `wrapper`: the Moon endpoint where OpenStack component connect to. + +At this point, you must choose one of the following options: +* Specific configuration +* Generic configuration + +#### Specific Configuration +Why using a specific configuration: +1. The `db` and `keystone` can be installed by yourself but you must configure the +Moon platform to use them. +2. You want to change the default passwords in the Moon platform + +Use the following commands: `TODO` + +#### Generic Configuration +Why using a specific configuration: +1. You just want to test the platform +2. You want to develop on the Moon platform + +The `Moon` platform can be initialized with the following shell script: +```bash +sh kubernetes/start_moon.sh +``` + +Wait until all the Moon containers are in the `running` state: +```bash +watch kubectl get po --namespace=moon +``` + +You must see something like this: + + $ kubectl get po --namespace=moon + NAME READY STATUS RESTARTS AGE + consul-57b6d66975-9qnfx 1/1 Running 0 52m + db-867f9c6666-bq8cf 1/1 Running 0 52m + gui-bc9878b58-q288x 1/1 Running 0 51m + keystone-7d9cdbb69f-bl6ln 1/1 Running 0 52m + manager-5bfbb96988-2nvhd 1/1 Running 0 51m + manager-5bfbb96988-fg8vj 1/1 Running 0 51m + manager-5bfbb96988-w9wnk 1/1 Running 0 51m + orchestrator-65d8fb4574-tnfx2 1/1 Running 0 51m + wrapper-astonishing-748b7dcc4f-ngsvp 1/1 Running 0 51m + +## Configuration +### Moon +#### Introduction +The Moon platform is already configured after the installation. +If you want to see or modify the configuration, go with a web browser +to the following page: + +> http://localhost:30006 + +This is a consul server, you can update the configuration in the `KEY/VALUE` tab. +There are some configuration items, lots of them are only read when a new K8S pod is started +and not during its life cycle. + +**WARNING: some confidential information are put here in clear text. +This is a known security issue.** + +#### Keystone +If you have your own Keystone server, you can point Moon to your server in the +`openstack/keystone` element or through the link: +> http://localhost:30005/ui/#/dc1/kv/openstack/keystone/edit + +This configuration element is read every time Moon need it, specially when adding users. + +#### Database +The database can also be modified here: +> http://varuna:30005/ui/#/dc1/kv/database/edit + +**WARNING: the password is in clear text, this is a known security issue.** + +If you want to use your own database server, change the configuration: + + {"url": "mysql+pymysql://my_user:my_secret_password@my_server/moon", "driver": "sql"} + +Then you have to rebuild the database before using it. +This can be done with the following commands: + + cd $MOON + kubectl delete -f kubernetes/templates/moon_configuration.yaml + kubectl create -f kubernetes/templates/moon_configuration.yaml + + +### OpenStack +Before updating the configuration of the OpenStack platform, check that the platform +is working without Moon, use the following commands: +```bash +# set authentication +openstack endpoint list +openstack user list +openstack server list +``` + +In order to connect the OpenStack platform with the Moon platform, you must update some +configuration files in Nova and Glance: +* `/etc/nova/policy.json` +* `/etc/glance/policy.json` + +In some installed platform, the `/etc/nova/policy.json` can be absent so you have +to create one. You can find example files in those directory: +> ${MOON}/moonv4/templates/nova/policy.json +> ${MOON}/moonv4/templates/glance/policy.json + +Each line is mapped to an OpenStack API interface, for example, the following line +allows the user to get details for every virtual machines in the cloud +(the corresponding shell command is `openstack server list`): + + "os_compute_api:servers:detail": "", + +This lines indicates that there is no special authorisation to use this API, +every users can use it. If you want that the Moon platform handles that authorisation, +update this line with: + + "os_compute_api:servers:detail": "http://my_hostname:31001/authz" + +1) by replacing `my_hostname` with the hostname (od the IP address) of the Moon platform. +2) by updating the TCP port (default: 31001) with the good one. + +To find this TCP port, use the following command: + + $ kubectl get services -n moon | grep wrapper | cut -d ":" -f 2 | cut -d " " -f 1 + 31002/TCP + +### Moon +The Moon platform comes with a graphical user interface which can be used with +a web browser at this URL: +> http://$MOON_HOST:30002 + +You will be asked to put a login and password. Those elements are the login and password +of the Keystone server, if you didn't modify the Keystone server, you will find the +login and password here: +> http://$MOON_HOST:30005/ui/#/dc1/kv/openstack/keystone/edit + +**WARNING: the password is in clear text, this is a known security issue.** + +The Moon platform can also be requested through its API: +> http://$MOON_HOST:30001 + +**WARNING: By default, no login/password will be needed because of +the configuration which is in DEV mode.** + +If you want more security, you have to update the configuration of the Keystone server here: +> http://$MOON_HOST:30005/ui/#/dc1/kv/openstack/keystone/edit + +by modifying the `check_token` argument to `yes`. +If you write this modification, your requests to Moon API must always include a valid token +taken from the Keystone server. This token must be place in the header of the request +(`X-Auth-Token`). + +## usage +### tests the platform +In order to know if the platform is healthy, here are some commands you can use. +1) Check that all the K8S pods in the Moon namespace are in running state: +`kubectl get pods -n moon` + +2) Check if the Manager API is running: +```bash +curl http://$MOON_HOST:30001 +curl http://$MOON_HOST:30001/pdp +curl http://$MOON_HOST:30001/policies +``` + +If you configured the authentication in the Moon platform: +```bash +curl -i \ + -H "Content-Type: application/json" \ + -d ' +{ "auth": { + "identity": { + "methods": ["password"], + "password": { + "user": { + "name": "admin", + "domain": { "id": "default" }, + "password": "<set_your_password_here>" + } + } + }, + "scope": { + "project": { + "name": "admin", + "domain": { "id": "default" } + } + } + } +}' \ + "http://moon_hostname:30006/v3/auth/tokens" ; echo + +curl --header "X-Auth-Token: <token_retrieve_from_keystone>" http://moon_hostname:30001 +curl --header "X-Auth-Token: <token_retrieve_from_keystone>" http://moon_hostname:30001/pdp +curl --header "X-Auth-Token: <token_retrieve_from_keystone>" http://moon_hostname:30001/policies +``` + +3) Use a web browser to navigate to the GUI and enter the login and password of the keystone service: +`firefox http://$MOON_HOST:30002` + +4) Use tests Python Scripts +check firstly the Consul service for *Components/Manager*, e.g. +```json +{ + "port": 8082, + "bind": "0.0.0.0", + "hostname": "manager", + "container": "wukongsun/moon_manager:v4.3.1", + "external": { + "port": 30001, + "hostname": "$MOON_HOST" + } +} +``` +*OpenStack/Keystone*: e.g. +```json +{ + "url": "http://keystone:5000/v3", + "user": "admin", + "password": "p4ssw0rd", + "domain": "default", + "project": "admin", + "check_token": false, + "certificate": false, + "external": { + "url": "http://$MOON_HOST:30006/v3" + } +} +``` + +```bash +python3 populate_default_values.py --consul-host=$MOON_HOST --consul-port=30005 -v scenario/rbac_large.py +python3 send_authz.py --consul-host=$MOON_HOST --consul-port=30005 --authz-host=$MOON_HOST --authz-port=31002 -v scenario/rbac_large.py +``` + +### GUI usage +After authentication, you will see 4 tabs: Project, Models, Policies, PDP: + +* *Projects*: configure mapping between Keystone projects and PDP (Policy Decision Point) +* *Models*: configure templates of policies (for example RBAC or MLS) +* *Policies*: applied models or instantiated models ; +on one policy, you map a authorisation model and set subject, objects and action that will +rely on that model +* *PDP*: Policy Decision Point, this is the link between Policies and Keystone Project + +In the following paragraphs, we will add a new user in OpenStack and allow her to list +all VM on the OpenStack platform. + +First, add a new user and a new project in the OpenStack platform: + + openstack user create --password-prompt demo_user + openstack project create demo + DEMO_USER=$(openstack user list | grep demo_user | cut -d " " -f 2) + DEMO_PROJECT=$(openstack project list | grep demo | cut -d " " -f 2) + openstack role add --user $DEMO_USER --project $DEMO_PROJECT admin + +You have to add the same user in the Moon interface: + +1. go to the `Projects` tab in the Moon interface +1. go to the line corresponding to the new project and click to the `Map to a PDP` link +1. select in the combobox the MLS PDP and click `OK` +1. in the Moon interface, go to the `Policy` tab +1. go to the line corresponding to the MLS policy and click on the `actions->edit` button +1. scroll to the `Perimeters` line and click on the `show` link to show the perimeter configuration +1. go to the `Add a subject` line and click on `Add a new perimeter` +1. set the name of that subject to `demo_user` (*the name must be strictly identical*) +1. in the combobox named `Policy list` select the `MLS` policy and click on the `+` button +1. click on the yellow `Add Perimeter` button +1. go to the `Assignment` line and click on the `show` button +1. under the `Add a Assignments Subject` select the MLS policy, +the new user (`demo_user`), the category `subject_category_level` +1. in the `Select a Data` line, choose the `High` scope and click on the `+` link +1. click on the yellow `Create Assignments` button +1. if you go to the OpenStack platform, the `demo_user` is now allow to connect +to the Nova component (test with `openstack server list` connected with the `demo_user`) + + +## Annexes + +### connect to the OpenStack platform + +Here is a shell script to authenticate to the OpenStack platform as `admin`: + + export OS_USERNAME=admin + export OS_PASSWORD=p4ssw0rd + export OS_REGION_NAME=Orange + export OS_TENANT_NAME=admin + export OS_AUTH_URL=http://moon_hostname:30006/v3 + export OS_DOMAIN_NAME=Default + export OS_IDENTITY_API_VERSION=3 + +For the `demo_user`, use: + + export OS_USERNAME=demo_user + export OS_PASSWORD=your_secret_password + export OS_REGION_NAME=Orange + export OS_TENANT_NAME=demo + export OS_AUTH_URL=http://moon_hostname:30006/v3 + export OS_DOMAIN_NAME=Default + export OS_IDENTITY_API_VERSION=3 + |