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/