Browse Source

Merge pull request #37 from iron-io/doc-updates

doc updates
Derek Schultz 2 years ago
parent
commit
45af81accb
5 changed files with 121 additions and 261 deletions
  1. 20
    35
      README.md
  2. 93
    0
      TESTING.md
  3. 8
    18
      devstack/README.md
  4. 0
    96
      examples/hello-lambda.sh
  5. 0
    112
      testing.md

+ 20
- 35
README.md View File

@@ -1,4 +1,6 @@
1
-# Picasso: Functions-as-a-Service (FaaS) on OpenStack
1
+# Picasso
2
+
3
+Functions-as-a-Service (FaaS) on OpenStack
2 4
 
3 5
 ## Mission
4 6
 
@@ -37,13 +39,13 @@ then the benefits are different, but related.
37 39
   * Scaling is simply adding more IronFunctions nodes
38 40
 
39 41
 
40
-### System requirements
42
+## System requirements
41 43
 
42 44
 * Operating system: Linux/MacOS
43 45
 * Python version: 3.5 or greater
44 46
 * Database: MySQL 5.7 or greater
45 47
 
46
-### Quick-start guide
48
+## Quick-start guide
47 49
 
48 50
 * Install DevStack with [IronFunctions enabled](https://github.com/iron-io/picasso/blob/master/devstack/README.rst)
49 51
 * Clone the [Picasso source](https://github.com/iron-io/picasso)
@@ -53,7 +55,7 @@ Create a Python3.5 virtualenv
53 55
     $ virtualenv -p python3.5 .venv
54 56
     $ source .venv/bin/activate
55 57
 
56
-Install dependencies
58
+Install Picasso dependencies
57 59
 
58 60
     $ pip install -r requirements.txt -r test-requirements.txt
59 61
 
@@ -72,7 +74,7 @@ set the following environment variable:
72 74
 
73 75
     export PICASSO_MIGRATIONS_DB=mysql+pymysql://root:root@localhost/functions
74 76
 
75
-Use `alembic` to apply the migrations:
77
+Then use `alembic` to apply the migrations
76 78
 
77 79
     $ alembic upgrade head
78 80
 
@@ -103,22 +105,21 @@ The following are the minimum required options to start the Picasso API service:
103 105
 
104 106
 ### Building and Running Picasso in Docker
105 107
 
106
-From the Picasso repo, build a Docker image:
108
+Install [Docker engine](https://docs.docker.com/engine/installation/) if you haven't already.
109
+
110
+From the Picasso repo, build a Docker image using the following commands:
107 111
 
108 112
     export DOCKER_HOST=tcp://<docker-host>:<docker-port>
109 113
     docker build -t picasso-api -f Dockerfile .
110 114
 
111
-To start the container, pass in the required env vars, by
112
-
113
-`--env-file` example [Dockerfile.env](Dockerfile.env.example)
114
-
115
-     docker run -d -p 10001:10001 --env-file Dockerfile.env picasso-api
115
+To start the container, pass in the required env vars with `--env-file` or by entering all required
116
+values in `-e <KEY>=<VALUE>` format to the `docker run` command.
116 117
 
117
-or by entering all values in `-e <KEY>=<VALUE>` format.
118
+Example [Dockerfile.env](Dockerfile.env.example)
118 119
 
119
-Once the container is started, check if the service in running:
120
+    docker run -d -p 10001:10001 --env-file Dockerfile.env picasso-api
120 121
 
121
-In your web browser navigate to:
122
+Once the container is started, check if the service in running. In your web browser navigate to:
122 123
 
123 124
     <docker-host>:10001/api
124 125
 
@@ -126,32 +127,16 @@ or using the CLI:
126 127
 
127 128
     curl -X GET http://<docker-host>:10001/api/swagger.json | python -mjson.tool
128 129
 
129
-### Examining the API
130
-
131
-In [examples](examples/) folder you can find a script that examines available API endpoints.
132
-
133
-Note that this script depends on the following env vars:
134
-
135
-* `PICASSO_API_URL` - Picasso API endpoint
136
-* `OS_AUTH_URL` - OpenStack Auth URL
137
-* `OS_PROJECT_ID` - it can be found in OpenStack Dashboard or in CLI
138
-* `OS_USERNAME` - OpenStack project-aligned username
139
-* `OS_PASSWORD` - OpenStack project-aligned user password
140
-* `OS_DOMAIN` - OpenStack project domain name
141
-* `OS_PROJECT_NAME` - OpenStack project name
142
-
143
-To run the script:
144
-
145
-    OS_AUTH_URL=http://192.168.0.112:5000/v3 OS_PROJECT_ID=8fb76785313a4500ac5367eb44a31677 OS_USERNAME=admin OS_PASSWORD=root OS_DOMAIN=default OS_PROJECT_NAME=admin ./examples/hello-lambda.sh
146
-
147
-Please note that values provided are project-specific, so they can't be reused.
148
-
149 130
 ### API docs
150 131
 
151 132
 API docs are discoverable via Swagger. Just launch the Picasso API and browse to:
152 133
 
153 134
     http://<picasso-host>:<picasso-port>/api
154 135
 
136
+### Testing Picasso
137
+
138
+See [Testing.md](TESTING.md)
139
+
155 140
 ### Support
156 141
 
157
-Join us on [Slack](https://open-iron.herokuapp.com/)!
142
+Join us on [Slack](https://open-iron.slack.com/)!

+ 93
- 0
TESTING.md View File

@@ -0,0 +1,93 @@
1
+# Testing
2
+
3
+## Requirements
4
+
5
+* Install `Tox`
6
+
7
+        $ pip install tox
8
+
9
+* MySQL instance with database migrations applied (refer to quick start guide)
10
+
11
+        $ export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
12
+
13
+### PEP8 style checks
14
+
15
+    $ tox -e pep8
16
+
17
+
18
+### Functional testing
19
+
20
+    $ tox -e py35-functional
21
+
22
+Pros:
23
+
24
+* lightweight (controllers and DB models testing)
25
+* no OpenStack required
26
+* no IronFunctions required
27
+
28
+Cons:
29
+
30
+* MySQL server required
31
+* OpenStack authentication is not tested
32
+* IronFunctions API stubbed with fake implementation
33
+
34
+### Integration tests
35
+
36
+The following env variables are required:
37
+
38
+* TEST_DB_URI - similar to functional tests, database endpoint
39
+* FUNCTIONS_API_URL - IronFunctions API URL (default value - `http://localhost:8080/v1`)
40
+* OS_AUTH_URL - OpenStack Identity endpoint
41
+* OS_PROJECT_NAME - OpenStack user-specific project name
42
+* OS_USERNAME - OpenStack user name
43
+* OS_PASSWORD - OpenStack user user password
44
+
45
+```bash
46
+export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
47
+export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
48
+export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
49
+export OS_PROJECT_NAME=<project-name>
50
+export OS_USERNAME=<project-name>
51
+export OS_PASSWORD=<project-name>
52
+tox -epy35-integration
53
+```
54
+
55
+### Testing: Docker-build
56
+
57
+The following operations are performed:
58
+
59
+* builds an image
60
+* deletes all artifacts (Python3.5 image and recently built image)
61
+
62
+```bash
63
+export DOCKER_HOST=tcp://<docker-host>:<docker-port>>
64
+export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
65
+export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
66
+export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
67
+tox -e docker-build
68
+```
69
+
70
+### Testing Docker-full
71
+
72
+The following operations are performed:
73
+
74
+* build container from source code
75
+* run container with exposed ports
76
+* request Swagger API doc to see if API is responsive
77
+* destroy running container
78
+
79
+```bash
80
+export DOCKER_HOST=tcp://<docker-host>:<docker-port>>
81
+export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
82
+export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
83
+export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
84
+tox -e docker-full
85
+```
86
+
87
+### Coverage regression testing
88
+
89
+    $ tox -e py35-functional-regression
90
+
91
+### Static code analysis with Bandit
92
+
93
+    $ tox -e bandit

devstack/README.rst → devstack/README.md View File

@@ -1,28 +1,21 @@
1
-Enabling Picasso (Functions-as-a-Service) in DevStack
2
-=====================================================
1
+# Enabling Picasso (Functions-as-a-Service) in DevStack
3 2
 
4
-Installing Glide
5
-================
3
+## Install Glide
6 4
 
7
-Note that your machine should have Glide installed.
5
+It is required to install Glide on the system in which you plan to run DevStack on, as
6
+the Functions service is written in Go and we must fetch dependencies during install.
8 7
 See more info at https://github.com/Masterminds/glide
9 8
 
10 9
 
11
-Download DevStack
12
-=================
13
-
14
-.. sourcecode:: bash
10
+## Download DevStack
15 11
 
16 12
     export DEVSTACK_DIR=~/devstack
17 13
     git clone git://git.openstack.org/openstack-dev/devstack.git $DEVSTACK_DIR
18 14
 
19
-Enable the FaaS plugin
20
-======================
15
+## Enable the Functions plugin
21 16
 
22 17
 Enable the plugin by adding the following section to ``$DEVSTACK_DIR/local.conf``
23 18
 
24
-.. sourcecode:: bash
25
-
26 19
     [[local|localrc]]
27 20
 
28 21
     enable_plugin picasso git@github.com:iron-io/picasso.git
@@ -40,7 +33,7 @@ Enable the plugin by adding the following section to ``$DEVSTACK_DIR/local.conf`
40 33
     PICASSO_CLIENT_DIR=${PICASSO_CLIENT_DIR:-${DEST}/python-picassoclient}
41 34
     PICASSO_CLIENT_BRANCH=${PICASSO_CLIENT_BRANCH:-master}
42 35
 
43
-    # IronFunctions parameters
36
+    # Functions parameters
44 37
     FUNCTIONS_REPO=${FUNCTIONS_REPO:-git@github.com:iron-io/functions.git}
45 38
     FUNCTIONS_BRANCH=${FUNCTIONS_BRANCH:-master}
46 39
     FUNCTIONS_PORT=${FUNCTIONS_PORT:-10501}
@@ -50,10 +43,7 @@ Enable the plugin by adding the following section to ``$DEVSTACK_DIR/local.conf`
50 43
 
51 44
     DOCKERD_OPTS=${DOCKERD_OPTS:---dns 8.8.8.8 --dns 8.8.4.4 --storage-driver=overlay2 -H fd://}
52 45
 
53
-Run the DevStack utility
54
-========================
55
-
56
-.. sourcecode:: bash
46
+## Run the DevStack utility
57 47
 
58 48
      cd $DEVSTACK_DIR
59 49
      ./stack.sh

+ 0
- 96
examples/hello-lambda.sh View File

@@ -1,96 +0,0 @@
1
-#!/usr/bin/env bash
2
-
3
-set +x
4
-set +e
5
-
6
-export LAOS_API_URL=${LAOS_API_URL:-http://localhost:10001}
7
-
8
-export OS_AUTH_URL=${OS_AUTH_URL:-http://localhost:5000/v3}
9
-export OS_USERNAME=${OS_USERNAME:-admin}
10
-export OS_PASSOWRD=${OS_PASSWORD:-root}
11
-export OS_DOMAIN=${OS_DOMAIN:-default}
12
-export OS_PROJECT_ID=${OS_PROJECT_ID:-"dummy_project_id"}
13
-
14
-
15
-rm -fr examples/token_request.json
16
-echo -e "{
17
-  \"auth\": {
18
-    \"identity\": {
19
-      \"methods\": [\"password\"],
20
-      \"password\": {
21
-        \"user\": {
22
-          \"name\": \"${OS_USERNAME:-admin}\",
23
-          \"domain\": { \"id\": \"${OS_DOMAIN:-default}\" },
24
-          \"password\": \"${OS_PASSWORD:-root}\"
25
-        }
26
-      }
27
-    },
28
-    \"scope\": {
29
-      \"project\": {
30
-        \"name\": \"${OS_PROJECT_NAME:-admin}\",
31
-        \"domain\": {\"id\": \"${OS_DOMAIN:-default}\" }
32
-      }
33
-    }
34
-  }
35
-}" >> examples/token_request.json
36
-
37
-
38
-export OS_TOKEN=`curl -si -d @examples/token_request.json -H "Content-type: application/json" ${OS_AUTH_URL}/auth/tokens | awk '/X-Subject-Token/ {print $2}'`
39
-
40
-echo -e "Listing apps\n"
41
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
42
-
43
-echo -e "Creating app\n"
44
-curl -X POST -d '{"app":{"name": "testapp"}}' ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
45
-
46
-echo -e "Listing apps\n"
47
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
48
-
49
-echo -e "Showing app info\n"
50
-export raw_app_info=`curl localhost:10001/v1/${OS_PROJECT_ID}/apps -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool | grep name | awk '{print $2}'`
51
-export app_name=${raw_app_info:1:30}
52
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name} -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
53
-
54
-echo -e "Listing app routes\n"
55
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
56
-
57
-echo -e "Creating app sync private route\n"
58
-curl -X POST -d '{"route":{"type": "sync", "path": "/hello-sync-private", "image": "iron/hello", "is_public": "false" }}' ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${APP_NAME}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
59
-
60
-echo -e "Creating app sync public route\n"
61
-curl -X POST -d '{"route":{"type": "sync", "path": "/hello-sync-public", "image": "iron/hello", "is_public": "true" }}' ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${APP_NAME}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
62
-
63
-echo -e "Listing app routes\n"
64
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
65
-
66
-echo -e "Show app private route\n"
67
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes/hello-sync-private -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
68
-
69
-echo -e "Show app public route\n"
70
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes/hello-sync-public -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
71
-
72
-echo -e "Running app sync private route\n"
73
-curl -X POST -d '{"name": "Johnny"}' ${LAOS_API_URL}/v1/r/${OS_PROJECT_ID}/${app_name}/hello-sync-private -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
74
-
75
-echo -e "Running app sync public route\n"
76
-curl -X POST -d '{"name": "Johnny"}' ${LAOS_API_URL}/r/${app_name}/hello-sync-public -H "Content-Type: application/json" | python3 -mjson.tool
77
-
78
-echo -e "Creating app async route\n"
79
-curl -X POST -d '{"route":{"type": "async", "path": "/hello-async-private", "image": "iron/hello", "is_public": "false"}}' ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
80
-
81
-echo -e "Running app async route\n"
82
-curl -X POST -d '{"name": "Johnny"}' ${LAOS_API_URL}/v1/r/${OS_PROJECT_ID}/${app_name}/hello-async-private -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
83
-
84
-echo -e "Deleting app route\n"
85
-curl -X DELETE ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes/hello-sync-public -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
86
-curl -X DELETE ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes/hello-sync-private -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
87
-curl -X DELETE ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes/hello-async-private -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
88
-
89
-echo -e "Listing app routes\n"
90
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name}/routes -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
91
-
92
-echo -e "Deleting app\n"
93
-curl -X DELETE ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps/${app_name} -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool
94
-
95
-echo -e "Listing apps\n"
96
-curl ${LAOS_API_URL}/v1/${OS_PROJECT_ID}/apps -H "X-Auth-Token:${OS_TOKEN}" -H "Content-Type: application/json" | python3 -mjson.tool

+ 0
- 112
testing.md View File

@@ -1,112 +0,0 @@
1
-Testing
2
--------
3
-
4
-In order to run tests you need to install `Tox`:
5
-
6
-    $ pip install tox
7
-
8
-Also, you will need a running MySQL instance with the database migrations applied from the previous step.
9
-Tests are dependent on pre-created MySQL database for persistence.
10
-Please set env var
11
-
12
-    $ export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
13
-
14
-PEP8 style checks
15
------------------
16
-
17
-In order to run `PEP8` style checks run following command:
18
-
19
-    $ tox -e pep8
20
-
21
-
22
-Functional testing
23
-------------------
24
-
25
-In order to run `functional` tests run following command:
26
-
27
-    $ tox -e py35-functional
28
-
29
-Pros:
30
-
31
-* lightweight (controllers and DB models testing)
32
-* no OpenStack required
33
-* no IronFunctions required
34
-
35
-Cons:
36
-
37
-* MySQL server required
38
-* OpenStack authentication is not tested
39
-* IronFunctions API stubbed with fake implementation
40
-
41
-Integration integrations
42
-------------------------
43
-
44
-Integration tests are dependent on following env variables:
45
-
46
-* TEST_DB_URI - similar to functional tests, database endpoint
47
-* FUNCTIONS_API_URL - IronFunctions API URL (default value - `http://localhost:8080/v1`)
48
-* OS_AUTH_URL - OpenStack Identity endpoint
49
-* OS_PROJECT_NAME - OpenStack user-specific project name
50
-* OS_USERNAME - OpenStack user name
51
-* OS_PASSWORD - OpenStack user user password
52
-
53
-To run tests use following command:
54
-
55
-    export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
56
-    export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
57
-    export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
58
-    export OS_PROJECT_NAME=<project-name>
59
-    export OS_USERNAME=<project-name>
60
-    export OS_PASSWORD=<project-name>
61
-    tox -epy35-integration
62
-
63
-Testing: Docker-build
64
----------------------
65
-
66
-This type of testing allows to ensure if code can be build inside docker container with no problems.
67
-In order to run this check use following commands::
68
-
69
-    export DOCKER_HOST=tcp://<docker-host>:<docker-port>>
70
-    export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
71
-    export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
72
-    export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
73
-    tox -e docker-build
74
-
75
-During this check Tox:
76
-
77
-* builds an image
78
-* deletes all artifacts (Python3.5 image and recently built image)
79
-
80
-Testing Docker-full
81
--------------------
82
-
83
-This type of testing allows to ensure if code code can be build and run successfully inside docker container with no problems.
84
-In order to run this check use following commands::
85
-
86
-    export DOCKER_HOST=tcp://<docker-host>:<docker-port>>
87
-    export TEST_DB_URI=mysql://<your-user>:<your-user-password>@<mysql-host>:<mysql-port>/<functions-db>
88
-    export FUNCTIONS_API_URL=<functions-api-protocol>://<functions-host>:<functions-port>/<functions-api-version>
89
-    export OS_AUTH_URL=<identity-api-protocol>://<identity-host>:<identity-port>/<identity-api-version>
90
-    tox -e docker-full
91
-
92
-During this check following operations are performed::
93
-
94
-* build container from source code
95
-* run container with exposed ports
96
-* request Swagger API doc to see if API is responsive
97
-* tear-down running container
98
-
99
-
100
-Coverage regression testing
101
----------------------------
102
-
103
-In order to build quality software it is necessary to keep test coverage at its highest point.
104
-So, as part of `Tox` testing new check was added - functional test coverage regression.
105
-In order to run it use following command:
106
-
107
-    $ tox -e py35-functional-regression
108
-
109
-Static code analysis with Bandit
110
-================================
111
-
112
-    $ tox -e bandit

Loading…
Cancel
Save