cmd/bpa-restapi-agent/README.md

   1 ### Running the server
   2 To run the server, follow these simple steps:
   3
   4 Integrated Cloud Native (ICN) RESTful API
   5
   6 This is a Golang application providing a RESTful API to interact with and upload image objects.
   7
   8 The API application source files are in the icn/cmd/bpa-restapi-agent directory.
   9
  10 While the database back-end is extensible, this initial release requires mongodb.
  11
  12 Install
  13
  14 Install and start mongodb. For instructions: https://docs.mongodb.com/manual/installation/
  15
  16 git clone "https://gerrit.akraino.org/r/icn"
  17 cd icn/cmd/bpa-restapi-agent
  18
  19 Run the application
  20 go run main.go
  21
  22 Output without a  config file:
  23
  24 2019/08/22 14:08:41 Error loading config file. Using defaults
  25 2019/08/22 14:08:41 Starting Integrated Cloud Native API
  26
  27 RESTful API usage examples
  28
  29 Sample Post Request
  30
  31 curl -i -F "metadata=<jsonfile;type=application/json" -F file=@/home/<username>/<dir>/jsonfile -X POST http://NODE_IP:9015//baremetalcluster/{owner}/{clustername}/<image_type>
  32
  33 #image type can be binary_image, container_image, or os_image
  34
  35 Example requests and responses:
  36
  37 Create image - POST
  38
  39 #Using a json file called sample.json
  40 #image_length in sample.json can be determined with the command
  41 ls -al <image_file>
  42
  43 Request
  44
  45 curl -i -F "metadata=<sample.json;type=application/json" -F file=@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample.json -X POST http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images
  46
  47 Response
  48
  49 HTTP/1.1 100 Continue
  50
  51 HTTP/1.1 201 Created
  52 Content-Type: application/json
  53 Date: Thu, 22 Aug 2019 22:56:16 GMT
  54 Content-Length: 239
  55
  56 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
  57
  58 #this creates a database entry for the image, and an empty file in the file system
  59
  60 List image - GET
  61
  62 curl -i -X GET http://localhost:9015/v1/baremetalcluster/{owner}/{clustername}/<image_type>/{imgname}
  63
  64
  65 example:
  66 #continuing with our container image from above
  67
  68 Request
  69
  70 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
  71
  72 Response
  73
  74 HTTP/1.1 200 OK
  75 Content-Type: application/json
  76 Date: Thu, 22 Aug 2019 22:57:10 GMT
  77 Content-Length: 239
  78
  79 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
  80
  81 Upload container image - PATCH
  82 Request
  83
  84 curl --request PATCH --data-binary "@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image" http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 0" --header "Expect:" -i
  85
  86
  87 Response
  88
  89 HTTP/1.1 204 No Content
  90 Upload-Offset: 29718177
  91 Date: Thu, 22 Aug 2019 23:19:44 GMT
  92
  93 Check uploaded image - GET
  94
  95 Request
  96
  97 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
  98
  99 Response
 100
 101 HTTP/1.1 200 OK
 102 Content-Type: application/json
 103 Date: Fri, 23 Aug 2019 17:12:07 GMT
 104 Content-Length: 245
 105
 106 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":29718177,"image_length":29718177,"upload_complete":true,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"1"}]}}
 107
 108 #after the upload, the image_offset is now the same as image_length and upload_complete changed to true
 109 #if upload was incomplete
 110
 111 Resumable upload instructions
 112
 113 Resumable upload -PATCH
 114
 115 #this is the current resumable upload mechanism
 116
 117 Request
 118
 119 curl --request PATCH --data-binary "@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image" http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 0" --header "Expect:" -i --limit-rate 200K
 120
 121 #the above request limits transfer for testing purposes
 122 #'ctl c' out after a few seconds, to stop file transfer
 123 #check image_offset with a GET
 124
 125 Check upload - GET
 126
 127 Request
 128
 129 curl -i -X GET http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 130
 131 Response
 132
 133 HTTP/1.1 200 OK
 134 Content-Type: application/json
 135 Date: Sat, 24 Aug 2019 00:30:00 GMT
 136 Content-Length: 245
 137
 138 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":4079616,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"2"}]}}
 139
 140 #from our response you can see that image_offset is still less than image_length and #upload_complete is still false
 141 #next we use the dd command (no limiting this time)
 142
 143 Request
 144
 145 dd if=/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample_image skip=4079616 bs=1 | curl --request PATCH --data-binary @- http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246 --header "Upload-Offset: 4079616" --header "Expect:" -i
 146
 147 #the request skips already uploaded 4079616 bytes of data
 148
 149 Response
 150
 151 25638561+0 records in
 152 25638561+0 records out
 153 25638561 bytes (26 MB, 24 MiB) copied, 207.954 s, 123 kB/s
 154 HTTP/1.1 204 No Content
 155 Upload-Offset: 29718177
 156 Date: Sat, 24 Aug 2019 00:43:18 GMT
 157
 158 Update image description - PUT
 159
 160 # let's change the tag in description from 1 to latest
 161 # once the  change is made in sample.json (or your json file)
 162
 163 Request
 164
 165 curl -i -F "metadata=<sample.json;type=application/json" -F file=@/home/enyi/workspace/icn/cmd/bpa-restapi-agent/sample.json -X PUT http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 166
 167 Response
 168
 169 HTTP/1.1 100 Continue
 170
 171 HTTP/1.1 201 Created
 172 Content-Type: application/json
 173 Date: Fri, 23 Aug 2019 17:21:01 GMT
 174 Content-Length: 239
 175
 176 {"owner":"alpha","cluster_name":"beta","type":"container","image_name":"asdf246","image_offset":0,"image_length":29718177,"upload_complete":false,"description":{"image_records":[{"image_record_name":"iuysdi1234","repo":"icn","tag":"2"}]}}
 177
 178 Delete an image - DELETE
 179
 180 Request
 181
 182 curl -i -X DELETE http://localhost:9015/v1/baremetalcluster/alpha/beta/container_images/asdf246
 183
 184 Response
 185
 186 # Cloud Storage with MinIO
 187
 188 Start MinIO server daemon with docker command before running REST API agent,
 189 default settings in config/config.go.
 190 AccessKeyID: ICN-ACCESSKEYID
 191 SecretAccessKey: ICN-SECRETACCESSKEY
 192 MinIO Port: 9000
 193
 194 You can setup MinIO server my the following command with default credentials.
 195 ```
 196 $ docker run -p 9000:9000 --name minio1 \
 197   -e "MINIO_ACCESS_KEY=ICN-ACCESSKEYID" \
 198   -e "MINIO_SECRET_KEY=ICN-SECRETACCESSKEY" \
 199   -v /mnt/data:/data \
 200   minio/minio server /data
 201 ```
 202 Also there is a Kubernetes deployment for MinIO server in standalone mode.
 203 ```
 204 $ cd deploy/kud-plugin-addons/minio
 205 $ ./install.sh
 206 ```
 207 You can check the status by opening a browser: http://127.0.0.1:9000/
 208
 209 MinIO Client implementation integrated in REST API agent and will automatically
 210 initialize in main.go, and create 3 buckets: binary, container, operatingsystem.
 211 The Upload image will "PUT" to corresponding buckets by HTTP PATCH request url.