success

docs/source/index.rst

@@ -25,6 +25,20 @@ Welcome to AppMesh's documentation!
    USER_ROLE.md
    Coverity.md
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Success:
+   :numbered: 0
+
+
+   success/build_powerful_monitor_system_with_Grafana_Prometheus_Loki.md
+   success/customize_app_startup_behavior.md
+   success/manage_cluster_level_microservice_applications.md
+   success/open_service_broker_support_local_pv_for_K8S.md
+   success/promote_native_app_to_microservice_app.md
+   success/secure_REST_file_server.md
+   success/standalone_JWT_server.md
+
 Indices and tables
 ==================
 

docs/source/success/build_powerful_monitor_system_with_Grafana_Prometheus_Loki.md

@@ -0,0 +1,90 @@
+# Build powerful monitor system with Grafana/Prometheus/Loki
+App Mesh can manage all app applications running on Linux and provide build-in Prometheus exporter the metrics can be used to monitor hosted application detail running behavior. Loki can be used to collect all applications and App Mesh logs.
+
+Grafana can be used as Prometheus and Loki web portal, with those components, we can build a runtime metrics and log aggregate system with a flexible GUI.
+<div align=center><img src="https://raw.githubusercontent.com/laoshanxi/app-mesh/main/doc/diagram.png" width=600 height=400 align=center /></div>
+
+## Deploy all component by docker compose
+
+### install docker-compose
+```
+sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+sudo chmod +x /usr/local/bin/docker-compose
+```
+
+### Clone App Mesh source files
+```
+git clone --depth=1 https://github.com/laoshanxi/app-mesh.git
+cd app-mesh
+```
+
+### Deploy all in one YAML
+```
+cd app-mesh/script
+$ docker-compose -f docker-compose-all-in-one.yaml up -d
+Creating script_prometheus_1    ... done
+Creating script_loki_1          ... done
+Creating script_consul_1        ... done
+Creating script_grafana_1       ... done
+Creating script_node_exporter_1 ... done
+Creating script_alertmanager_1  ... done
+Creating script_promtail_1      ... done
+Creating script_appmesh_1       ... done
+Creating script_appmesh-ui_1    ... done
+
+```
+
+Then you can access App Mesh UI (https://192.168.3.24/) with initial user (admin/Admin123).
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/appmesh/1.png" />
+
+Monitor system: Grafana, Prometheus, Node Exporter, promtail, Alert Manager
+
+<img src="https://prometheus.io/assets/architecture.png" />
+
+## Login Grafana
+Open target host http://192.168.3.24:3000/
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/01.png" />
+
+Input initial password admin/admin and change a new password for Grafana
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/02.png" />
+
+Add Prometheus Data Source with default address(http://localhost:9090/)
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/03.png" />
+
+In Grafana Explorer page, you can query App Mesh metrics
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/04.png" />
+
+Add Loki Data Source with default address(http://localhost:3100/)
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/05.png" />
+
+In Grafana Exploere page, you can query all app stdout of App Mesh managed applications and App Mesh logs
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/06.png" />
+
+## Prometheus UI (alertmanager)
+Open Prometheus WEB portal at http://192.168.3.24:9090/
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/prometheus01.png" />
+
+Query metrics: appmesh_prom_process_memory_gauge
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/prometheus02.png" />
+
+Stop node exporter to trigger alertmanager, you will get bellow email:
+```
+$ docker stop script_node_exporter_1
+```
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/email.png" />
+
+### Clean docker compose started containers
+```
+$ cd app-mesh/script
+$ docker-compose -f docker-compose-all-in-one.yaml stop
+$ docker-compose -f docker-compose-all-in-one.yaml rm -f
+```

docs/source/success/customize_app_startup_behavior.md

@@ -0,0 +1,18 @@
+# Customize application start behavior
+App Mesh can be used as a daemon application used to monitor and launch other applications on Linux, it is most like crontab and supervisor but much simple and powerful.
+For application deployment, application startup behavior can be managed by App Mesh on local host to get High Available benefit.
+
+## Solution
+App Mesh support monitor both long running and short running applications, for more details, refer to [CommandLine](https://github.com/laoshanxi/app-mesh/blob/main/doc/CLI.md)
+
+## Register an existing application to App Mesh
+By default you can register your application simply by specify start command:
+```
+appc reg -n myapp--perm 11  -c 'sh /root/data/deploy/myapp.sh'
+```
+
+### Integrate to application installation script
+If your application package was pack yourself, you can add the startup behavior to post-installation script, with this, you app will be monitor and started automatically without any missing.
+```
+appc reg -n mysql--perm 11  -c 'mysqld'
+```

docs/source/success/manage_cluster_level_microservice_applications.md

@@ -0,0 +1,24 @@
+# Manage cluster level microservice applications
+Multiple App Mesh instances can connect as a cluster with [Consul](https://github.com/laoshanxi/app-mesh/blob/main/doc/CONSUL.md) and schedule cluster level micro-service applications. Cluster level application can get the benefit of cluster level HA, and the application will be schedule among the cluster with resource requirement consideration.
+
+## Configuration
+
+In cluster environment, an App Mesh instance can be a `main` (leader candidates) node or `worker` node, All main nodes and worker nodes should connect to the same Consul URL to perform a cluster, we can configure from App Mesh UI:
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/07.png" />
+
+### Add cloud application
+
+We can register Cloud cloud application in Cloud menu.
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/08.png" />
+
+cloud application can have bellow content:
+1. application definition JSON body
+2. application replication number (App Mesh will schedule and start according instance)
+3. application service port (this will be register to Consul service for service discovering)
+4. application schedule preference (node select with labels, support wildcards)
+
+### App Schedule
+App Mesh leader node will schedule cloud application to perfected nodes, and cloud app will have cloud icon from UI:
+
+<img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/09.png" />

docs/source/success/open_service_broker_support_local_pv_for_K8S.md

@@ -0,0 +1,15 @@
+# Open service broker support local PV for Kubernetes
+Currently, we are moving more and move applications to Kubernetes, but for Data Base applications which depend on IO performance, will get bad experience using shared storage like GlusterFS, Ceph. even Kubernetes support local PV storage class, but still does not support dynamic provision for persistent volume.
+
+## Solution
+With the ability of remote execute commands by App Mesh, we can design a real local PV for docker container, this will improve container IO performance and gain the local storage performance.
+
+We usually manage applications on Kubernetes follow [Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker), and implement `Service Broker` for each kind of applications, the the application launch process will be handled in `Service Broker`.
+<div align=center><img src="https://raw.githubusercontent.com/laoshanxi/picture/master/wiki/localpv.png" /></div>
+
+1. Service Broker accept a instance create request with requested resource
+2. Service Broker schedule a dummy YAML with request requirement (plus local PV node label)
+3. When Kubernetes finished schedule dummy YAML, create corresponding Local PV remotely
+4. Service Broker create real multiple Application YAML with `Daemon Set` to make sure new container schedule to local PV node
+5. Delete dummy YAML
+6. When broker instance destroying, clean remote PV accordingly

docs/source/success/promote_native_app_to_microservice_app.md

@@ -0,0 +1,34 @@
+# Promote native application to microservice application
+App Mesh is designed for manage micro service applications, for a native application without any refactor and adapt, can promote as a micro service application with App Mesh, other app can use HTTP request to call this native application.
+
+## Solution
+App Mesh support POST [/appmesh/app/run] API used to run a command remotely, with this feature, we can launch native app in server side and get result via REST response, App Mesh framework will guarantee the security and permission. 
+
+The interactive with native application can use std input, App Mesh support pass text (json) data to application process.
+
+## Deploy App Mesh by Docker container
+* Assume native app is `/usr/share/myapp.py`, mount native app binary to container.
+* Expose 6060 for App Mesh service port
+* Start Docker container in backend:
+```
+docker run -d -m 8g --restart=always -v /usr/share/myapp.py:/usr/share/myapp.py:ro --name=myapp -p 6060:6060 -v /var/run/docker.sock:/var/run/docker.sock laoshanxi/appmesh
+```
+* If we have any special configuration changes for App Mesh container, we can add `-v /opt/user/appsvc.json:/opt/appmesh/appsvc.json:ro`.
+* mount docker.sock to container so that App Mesh will also support manage container app.
+
+## Use native application
+### Security
+App Mesh by default enable JWT authentication for all REST requests, we need get JWT token:
+```
+curl -X POST -k -H "username:$(echo -n admin | base64)" -H "password:$(echo -n Admin123 | base64)" https://localhost:6060/appmesh/login
+``` 
+BTW, the admin user password can be changed by appsvc.json or override with container(laoshanxi/appmesh) startup environment like `-e APPMESH_Security_Users_admin_key=MyNewPwd`
+
+### Call micro service
+With JWT token, you can call native app by App Mesh REST now, the body can include you remote application start command and metadata for stdin:
+```
+curl -X POST -k -H "Authorization:Bearer $JWT_TOKEN" \
+-d '{ "command" : "python3 /usr/share/myapp.py", "metadata": "std input text data" }' \
+https://appmesh-host:6060/appmesh/app/syncrun?timeout=30
+```
+You will get result by REST response.

docs/source/success/secure_REST_file_server.md

@@ -0,0 +1,12 @@
+# Secure REST file server
+App Mesh provide file download/upload REST APIs, also those APIs can be authenticated by JWT.
+
+## Solution
+Use below API to manage file:
+Method | URI | Body/Headers | Desc
+---|---|---|---
+GET | /appmesh/file/download | Header: <br> FilePath=/opt/remote/filename | Download a file from REST server and grant permission
+POST| /appmesh/file/upload | Header: <br> FilePath=/opt/remote/filename <br> Body: <br> file steam | Upload a file to REST server and grant permission
+
+* The simple way is use [Python SDK](https://github.com/laoshanxi/app-mesh/blob/main/src/sdk/python/appmesh_client.py)
+* Use appmesh cli is also fine: `appc put -l /opt/appmesh/log/appsvc.log -r /tmp/1.log`

docs/source/success/standalone_JWT_server.md

@@ -0,0 +1,38 @@
+# Standalone JWT server
+JWT authentication is a popular authentication method for HTTP service and client, App Mesh implemented a JWT Server with RBAC (role based access control) and this service can be used to build a JWT server for other systems. detail design refer to [JWT Design](https://github.com/laoshanxi/app-mesh/blob/main/doc/JWT_DESC.md)
+
+## Solution
+### App Mesh can manage bellow concepts:
+1. Users
+2. Roles
+3. Groups
+4. Permissions
+
+### Bellow APIs for security:
+
+Index | Method | URI | Body/Headers | Desc
+---|---|---|---|---
+1 |POST| /appmesh/login | UserName=base64(uname) <br> Password=base64(passwd) <br> Optional: <br> ExpireSeconds=600 | JWT authenticate login
+2 |POST| /appmesh/auth | curl -X POST -k -H "Authorization:Bearer ZWrrpKI" https://127.0.0.1:6060/appmesh/auth <br> Optional: <br> AuthPermission=permission_id | JWT token and permission authenticate
+3 |POST| /appmesh/user/admin/passwd | NewPassword=base64(passwd) | Change user password
+4 |POST| /appmesh/user/usera/lock | | admin user to lock usera
+5 |POST| /appmesh/user/usera/unlock | | admin user to unlock usera
+6 |PUT | /appmesh/user/usera | | Add usera to Users
+7 |DEL | /appmesh/user/usera | | Delete usera
+8 |GET | /appmesh/users | | Get user list
+9 |GET | /appmesh/roles | | Get role list
+10 |POST| /appmesh/role/roleA | | Update roleA with defined permissions
+11 |DELETE| /appmesh/role/roleA | | Delete roleA
+12 |GET | /appmesh/user/permissions |  | Get user self permissions, user token is required in header
+13 |GET | /appmesh/permissions |  | Get all permissions
+14 |GET | /appmesh/user/groups |  | Get all user groups
+
+
+### Manage
+Other system can call the 10th API to define `Roles` and `Permissions`, and call 6th API to define user with corrospanding role.
+
+### Authenticate
+System login and permission can all forward to App Mesh 1st and 2nd API to do the authentication.
+
+### UI
+All those management API can be operated by [UI](https://github.com/laoshanxi/app-mesh-ui)