github.com/jbking/gohan@v0.0.0-20151217002006-b41ccf1c2a96/README.md (about) 1 # Gohan # 2 3 Project Site: http://gohan.cloudwan.io/ 4 5 Gohan is an REST API framework which has 6 7 - Schema: Gohan makes REST-based api server, db backend, CLI ,and WebUI from JSON schema. 8 - Exension: Gohan supports custom logic using Go, JavaScript or Gohan DSL. 9 - Policy: Gohan supports RBAC-based policy enforcement for your API. 10 - Integration: Gohan can integrated with 3rd party system using Sync (etcd) and OpenStack Keystone 11 12 [![gohan demo](https://github.com/cloudwan/gohan_website/raw/master/gohan_demo.gif)](https://www.youtube.com/watch?v=cwI44wQcxHU) 13 14 [![Join the chat at https://gitter.im/cloudwan/gohan](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/cloudwan/gohan?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 15 16 [![GoDoc](https://godoc.org/github.com/cloudwan/gohan?status.svg)](https://godoc.org/github.com/cloudwan/gohan) 17 18 [![wercker status](https://app.wercker.com/status/cab137b4bfdd05c97cfface7ac12c039/m "wercker status")](https://app.wercker.com/project/bykey/cab137b4bfdd05c97cfface7ac12c039) 19 20 # Getting started # 21 22 You can do step1 and step2 on Heroku using this button. 23 24 ## Setup ## 25 26 [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/cloudwan/gohan.git) 27 28 or 29 30 * Download Gohan binary + sample configuraion https://github.com/cloudwan/ansible-gohan/releases 31 32 * Start server 33 34 ``` 35 ./gohan server --config-file etc/gohan.yaml 36 ``` 37 38 ## WebUI client ## 39 40 ``` 41 https://localhost:9443/webui/ (or https://$APPNAME.herokuapp.com/webui/ ) 42 ``` 43 44 login with this ID/Password 45 46 ``` 47 ID: admin 48 Password: gohan 49 ``` 50 51 You can also access schema editing webui by adding "?type=metaschema" on URL. 52 53 ``` 54 https://localhost:9443/webui/?type=metaschema 55 ``` 56 57 ## Try CLI client ## 58 59 ``` 60 export GOHAN_SCHEMA_URL=/gohan/v0.1/schemas 61 export GOHAN_REGION=RegionOne 62 export GOHAN_SERVICE_NAME=gohan 63 export OS_PASSWORD=gohan 64 export OS_USERNAME=admin 65 export GOHAN_CACHE_SCHEMAS=true 66 export GOHAN_CACHE_TIMEOUT=5m 67 export GOHAN_CACHE_PATH=~/.cached-gohan-schemas 68 export OS_AUTH_URL=https://localhost:9443/v2.0 69 70 ./gohan client 71 ``` 72 73 For Heroku 74 75 ``` 76 export GOHAN_SCHEMA_URL=/gohan/v0.1/schemas 77 export GOHAN_REGION=RegionOne 78 export GOHAN_SERVICE_NAME=gohan 79 export OS_PASSWORD=gohan 80 export OS_USERNAME=admin 81 export GOHAN_CACHE_SCHEMAS=true 82 export GOHAN_CACHE_TIMEOUT=5m 83 export GOHAN_CACHE_PATH=~/.cached-gohan-schemas 84 export OS_AUTH_URL=https://$APPNAME.herokuapp.com/v2.0 85 export GOHAN_ENDPOINT_URL=https://$APPNAME.herokuapp.com 86 87 ./gohan client 88 ``` 89 90 # Example # 91 92 ## Define your resource model ## 93 94 You can define your resource model using JSON schema. 95 You can use YAML format as described in this example. 96 97 ```yaml 98 schemas: 99 - id: network 100 plural: networks 101 prefix: /v2.0 102 schema: 103 properties: 104 description: 105 default: "" 106 permission: 107 - create 108 - update 109 title: Description 110 type: string 111 unique: false 112 id: 113 format: uuid 114 permission: 115 - create 116 title: ID 117 type: string 118 unique: false 119 name: 120 permission: 121 - create 122 - update 123 title: Name 124 type: string 125 unique: false 126 tenant_id: 127 format: uuid 128 permission: 129 - create 130 title: Tenant 131 type: string 132 unique: false 133 propertiesOrder: 134 - id 135 - name 136 - description 137 - tenant_id 138 type: object 139 singular: network 140 title: Network 141 ``` 142 143 ## Define your application policy ## 144 145 Gohan can use OpenStack Keystone as Identity management system. 146 You can configure API access policy based on role information on Keystone. 147 148 Policy has following properties. 149 150 - id : Identitfy of the policy 151 - principal : Keystone Role 152 - action: one of `create`, `read`, `update`, `delete` for CRUD operations 153 on resource or any custom actions defined by schema performed on a 154 resource or `*` for all actions 155 - effect : Allow api access or not 156 - resource : target resource 157 you can specify target resource using "path" and "properties" 158 - condition : addtional condition (see below) 159 - tenant_id : regexp matching the tenant, defaults to ``.*`` 160 161 162 ```yaml 163 policies: 164 - action: '*' 165 effect: allow 166 id: admin_statement 167 principal: admin 168 resource: 169 path: .* 170 ``` 171 172 ## Implement custom logic ## 173 174 you can add your custom logic for each CRUD event. 175 176 Javascript 177 178 ```yaml 179 extensions: 180 - code: | 181 gohan_register_handler("pre_create", function (context){ 182 console.log("Hello world") 183 }); 184 event: list 185 id: test 186 path: /v2.0/network.* 187 ``` 188 189 [Experimental] Donburi (Ansible inspired Gohan DSL) 190 191 ```yaml 192 extensions: 193 - id: network 194 code_type: donburi 195 code: | 196 tasks: 197 - contrail: 198 schema: "virtual-network" 199 allow_update: [] 200 id: "{{ .resource.contrail_virtual_network }}" 201 properties: 202 parent_type: "project" 203 fq_name: 204 - default-domain 205 - "{{ .tenant_name }}" 206 - "{{ .resource.id }}" 207 register: network_response 208 - vars: 209 status: "ACTIVE" 210 when: network_response.status_code == 200 211 else: 212 - vars: 213 status: "ERROR" 214 - vars: 215 response_code: 409 216 when: network_response.status_code != 404 && event_type == "pre_delete" 217 - update: 218 schema: "network" 219 properties: 220 id: "{{ .resource.id }}" 221 contrail_virtual_network: '{{ index .network_response "data" "virtual-network" "uuid" }}' 222 status: "{{ .status }}" 223 path: "/v2.0/network.*" 224 ``` 225 226 You can also find an example for Go based extension in here 227 https://github.com/cloudwan/gohan/tree/master/exampleapp 228 229 see more description in doc 230 231 ## Integrate Gohan with your system ## 232 233 Every CRUD event will be pushed to sync layer (currently etcd is supproted), so your worker can be syncroniced. 234 235 You can also use Gohan as a worker. 236 Gohan support AMQP (OpenStack notification), SNMP (experimental) and CRON, and execute extension. 237 238 ```yaml 239 # Watch etcd and execute extension 240 - id: sync_notification 241 code_type: donburi 242 path: "sync://v2.0/servers/" 243 code: | 244 tasks: 245 - debug: "synced {{ .action }} " 246 # Watch RabbitMQ 247 - id: amqp_notification 248 code_type: donburi 249 path: "amqp://orchestration.stack" 250 code: | 251 tasks: 252 - vars: 253 stack_id: "{{ .event.payload.stack_name }}" 254 state: "{{ .event.payload.state }}" 255 - eval: "stack_id = stack_id.slice(7)" 256 - vars: 257 state: "ACTIVE" 258 when: state == "CREATE_COMPLETE" 259 - update: 260 schema: "server" 261 properties: 262 id: "{{ .stack_id }}" 263 status: "{{ .state }}" 264 rescue: 265 - debug: "{{ .error }}" 266 # Watch SNMP 267 - id: snmp 268 code_type: donburi 269 path: "snmp://" 270 code: | 271 tasks: 272 - debug: "remote host: {{ .remote }} {{ .trap }} " 273 - debug: "traps: {{ .item.key }} {{ .item.value }} " 274 with_dict: "trap" 275 # CRON Job 276 - id: cron_job 277 code_type: donburi 278 path: "cron://cron_job_sample" 279 code: | 280 tasks: 281 - debug: "cron job" 282 ``` 283 284 # More examples # 285 286 see more on https://github.com/cloudwan/gohan_apps 287 288 # Development # 289 290 - Setup Go env 291 - Install development tools 292 293 ``` 294 go get github.com/tools/godep 295 go get github.com/golang/lint/golint 296 go get github.com/coreos/etcd 297 go get golang.org/x/tools/cmd/cover 298 go get golang.org/x/tools/cmd/vet 299 ``` 300 301 - make & make install 302 303 ``` 304 make 305 make install 306 ``` 307 308 - Send a pull request for github 309 310 # Why Gohan? # 311 312 - Gohan is a REST-based api server to evolve your cloud service very rapidly and enable painless operation 313 314 - Gohan makes your system architeture simple 315 316 - Gohan enables you to create / modify new service very rapidly with minimum coding 317 318 - Gohan can be easiliy integrated to your system using sync layer and custom extension 319 320 ## SINGLE PROCESS for REST based "micro" services ## 321 322 Traditional “fat” services are difficult to manage: subsystems become tightly coupled making it hard to introduce changes. Micro-service based architectures are meant to solve this issue; however they come with additional problems such as process management and orchestration. (see Criticism on https://en.wikipedia.org/wiki/Microservices) 323 324 Gohan enables you to define many "micro" services within single unified process, so that you can keep your system architecture and deployment model simple. Moreover, Gohan supports transactional management for microservices orchestration. 325 326 ## SCHEMA-DRIVEN Service Develoment ## 327 328 Similar structure code everywhere. 329 Typical Schema-driven development tools reduces number of code lines by automatic code generation. Down side of the code generation method is adding complexity to the code management. 330 331 In Gohan project, we are challenging to have powerful schema-driven development without those complexity. 332 333 ## SINGLE PLACE to keep Service related poilcy, config and code ## 334 335 Cloud service management is not simple. 336 Typical cloud architecutre has three layers, i.e. Controller, Communication and Agent layer. When you develop a new service on this archtecutre, configurations and codes will be distributed across three layers. This makes hard to diagnose issue and manage services. 337 338 In Gohan, each layer can understand service definition file, so that you can unify service related configuraion and code on one place. 339 340 # License # 341 342 Apache2 343 344 # Docs # 345 346 see more docs http://gohan.cloudwan.io/gohan/