github.com/cloudwan/edgelq-sdk@v1.15.4/README.md (about)

     1  # EdgeLQ SDK
     2  
     3  ## Overview
     4  EdgeLQ is a development platform and environment of reusable, generic microservices, which enables rapid application
     5  development. Each EdgeLQ service utilizes Goten framework, but its API is gRPC/REST compatible.
     6  
     7  Microservices available in EdgeLQ:
     8  * Identity and Access Management (IAM) - provides access to users/service account, role management and permission checks.
     9    It is used by other microservices for authorization.
    10  * Audit - Generic service that provides view into any activity by any user or service account. Any interesting API call
    11    to any EdgeLQ based service is reported to Audit - including calls to Audit itself.
    12  * Monitoring - Provides generic time-series endpoint, allowing various application to store any timestamp based data
    13    conforming to registered (by the same applications) descriptors.
    14  * Devices - Provides device management (physical or virtual machines). It also enables connecting into devices.
    15  * Applications - It is generic service managing (any) applications installed on devices.
    16  * Proxies - Provides generic proxy feature for easy tunneling.
    17  * Secrets - Manages secrets, that can be used by other services (like Applications).
    18  * Meta - provides information about state of deployment (like list of regions and endpoints).
    19  
    20  EdgeLQ SDK provides:
    21  * Set of proto files for each mentioned above service. They can be used to learn about API and can help in
    22    generating client library in practically any programming language.
    23  * Dedicated Golang client libraries for all the services. They were generated using proto files by dedicated protoc
    24    compilers from Goten.
    25  * Docs in HTML format located [here](./docs/apis), with API reference for each service.
    26  * [Examples](./examples/cmd) - they use our Golang libraries.
    27  
    28  In simple words, EdgeLQ SDK provides code for client-based applications talking to EdgeLQ services.
    29  
    30  ## Repository structure
    31  
    32  [goten sdk]: https://github.com/cloudwan/goten-sdk
    33  Each service contains its own directory in this repo. Internal structure is practically same everywhere, as Goten
    34  enforces some common standards. All the components reference [Goten SDK] library.
    35  
    36  
    37  Code organization within single service has following pattern:
    38  
    39  ### \<service-name\>/proto/\<version\>
    40  Provides description of APIs, resources and other objects in protobuf format. Files there can be used to learn about service
    41  or be used in order to generate client libraries in other programming languages.
    42  
    43  Separation of APIs and resources into subpackages allows building more light-weight applications.
    44  
    45  ### \<service-name\>/resources/\<version\>/\<resource-name\>
    46  Golang module for single resource. Contains definition of it and all helper objects - dedicated Filter, FieldMask,
    47  set of FieldPaths etc.
    48  
    49  ### \<service-name\>/client/\<version\>/\<api-name\>
    50  Contains basic (almost like raw, but type safe) client for communication with RPC API and definitions for most
    51  request/response objects.
    52  
    53  ### \<service-name\>/client/\<version\>/\<service-name\>
    54  Contains sum of all clients for given service. May not be recommended if we want to minimize size of application runtime.
    55  
    56  ### \<service-name\>/access/\<version\>/\<resource-name\>
    57  Contains high-level client-based components like Watcher - dedicated for each resource.
    58  
    59  ## How to use
    60  EdgeLQ utilizes [Goten SDK], which contains basic instructions. It does not require much
    61  extra - in order to develop Golang application with this SDK, you need to install Go and include SDK in your list of dependencies.
    62  You can use [examples](./examples) provided in this repository as a help.
    63  
    64  In order to generate SDK in other language, you need to follow steps regarding protoc installation, as described in Goten
    65  SDK. The only extra thing to do, is to include directory with this repository (on your machine) as additional include proto
    66  path.
    67  
    68  ## Notes about examples
    69  Examples provided in this repository, in order to be executed, require access to some currently running service. You
    70  need user or service account ready on hand. This user/service account needs to have a granted permission in a project where
    71  you want to execute the examples. It is assumed that, at the very least, you have all of those, otherwise you would not be
    72  able to use cuttle or UI dashboard. SDK gives an access on the code-level, so one step further. Here you just need some additional,
    73  extra information on how to execute examples properly.
    74  
    75  ### Endpoint
    76  Endpoint should contain domain with service name and port number, for example "devices.stg01b.edgelq.com:443".
    77  
    78  ### Authentication & Authorization
    79  Every action requires authentication and authorization. For this reason, example has to be executed as user or service
    80  account. If you want to execute example as user, you need to get access token. For service account, you need to get a
    81  file with service account key. Every example requires one or another to work.
    82  
    83  #### Getting Access Token
    84  In order to get fresh access token for user, login to any dashboard like Squid. Open developer tools, find HTTP headers for
    85  any request dashboards sends to edgeLQ service (devices, iam, applications...). Find "authorization" header. It should have
    86  a format "Bearer $VALUE". This VALUE will be your access token. You can copy it and use it with example.
    87  
    88  Of course, this token has limited value, so it will need to be checked again in some near future.
    89  
    90  Same token could be obtained from cuttle credentials (in ~/.config/goten.cuttle.json as default path). You need to find
    91  your user entry and access token.
    92  
    93  #### Service account key file
    94  This is JSON file with email, key ID, private key value. File format can be found [here](./examples/files/service_account_credentials_template.json).
    95  
    96  If you dont have private key for any service account, but you have user, then you can create your own, its simple. This
    97  is how you can make with cuttle:
    98  
    99  First, List your projects:
   100  ```shell
   101  cuttle iam list-my projects
   102  ```
   103  
   104  Chose some project ID, taken from "name" field. Of course, strip "projects/" prefix. Now, I assume that your user
   105  can create service accounts. In that case, make some (with key):
   106  
   107  ```shell
   108  cuttle iam create service-account my-test-svcacc-for-examples [--region $REGION_ID] --project $PROJECT_ID
   109  ```
   110  
   111  Of course, "my-test-svcacc-for-examples" is $SERVICE_ACCOUNT_ID. You can replace with any value you like. You can specify
   112  REGION if you like, but you can skip. If you do, it will create in the nearest available region, which is fine. You need
   113  to look at response object. You will see fully qualified name with REGION_ID assigned. You will also have now EMAIL value,
   114  which is exactly what you need to have in service account key credentials file!
   115  
   116  Now, you can create service account key. With cuttle help, it will automatically create service account key file for you,
   117  so you dont need template really:
   118  
   119  ```shell
   120  cuttle iam create service-account-key --project $PROJECT_ID --region $REGION_ID --service-account $SERVICE_ACCOUNT_ID \
   121    --algorithm RSA_4096 --credentials-output-file my-service-account-key-file.json
   122  ```
   123  
   124  As you may have noticed, this command will create file for you.
   125  If you want to create private key on your own machine, its also possible (see cuttle iam create service-account-key --help).
   126  
   127  Service account created in this way will not be functional without role bindings. If you want to allow this
   128  account to do something useful, you need to create role binding. For example, this will allow service account to do
   129  anything it likes in devices service:
   130  ```shell
   131  cuttle iam create role-binding --project $PROJECT_ID --role 'roles/devices-admin' --member 'serviceAccount:$EMAIL'
   132  ```
   133  
   134  Value EMAIL must be same as in service account key file.