1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216 | = Local Stamp User Guide
== Introduction
_LocalStamp_ is a solution that facilitates the development and testing of
components and services for the `ECloud` framework.
This solution runs an `ECloud` stamp in a single machine. With this solution
you will be able to emulate locally a real `ECloud` stamp. Thus, you can deploy
service applications resulting in a service running instance and access it for
development and testing purposes. As a real `ECloud` stamp it makes use of
Docker containers technology.
The main difference of _LocalSTamp_ in regard to a real stamp is that it will
not scale up and down the number of role instances of the service according to
its workload variations. Therefore, _LocalStamp_ is not intended for real
production scenarios.
Moreover, as it is run in a single machine take care not to overload a
_LocalStamp_ instance with many service application deployments or large
service applications.
Next section provides you some basic information for understanding _LocalStamp_.
== _LocalStamp_ in a Nutshell
As said _LocalStamp_ allows emulating an `ECloud` stamp locally but without
scaling capabilities.
In the same machine you can have several running instances of _LocalStamp_,
having each one of them a unique identifier. Although possible it is not
recommended. For short the term _stamp_ will be used in this document for
referring to a running instance of _LocalStamp_.
When a _LocalStamp_ is launched and executed a folder is created in the '/tmp/'
folder of the computer naming it with the stamp identifier: '/tmp/<stamp_id>'.
Inside this folder is placed all the information used during its execution.
Thus, if the computer running a stamp crashes or shuts down all this
information is lost. Among this information has to be highlighted role instance
information.
As already commented several service application deployments can be performed
in a stamp. So, if you use this characteristic take care of not running out of
resources (remember that you are executing it locally).
Now, once you know some basic hints of _LocalStamp_ the following sections will
show you different ways of using _LocalStamp_.
== Local Stamp Service
This section explains how to use _LocalStamp_ as a service running in a Docker
container instance.
=== Launch Local Stamp
In order to use it execute the `local-stamp-start.sh` script that will launch a _stamp_.
_Usage_:
./local-stamp-start.sh
If everything goes fine the system will return:
----
Local Stamp log in /tmp/local-stamp.log
Local Stamp workdir in /tmp/local-stamp
Local Stamp Started
Listening on port 8090
----
As it can be seen it informs that an instance of _LocalStamp_ is up and running
accepting requests in port `8090`.
=== Deploying Services (Bundle)
Once the _LocalStamp_ instance is up and running services can be deployed (and
undeployed) sending bundles to its _Admission_ REST API, more specifically its
method `admission/bundles`. In order to do so use the `curl` command line tool.
Accepted bundle types are: _test_ and _deployment_ bundles.
_Usage_:
curl http://localhost:8090/admission/bundles -F bundlesZip=@PATH_TO_BUNDLE.zip
Once executed _LocalStamp_ returns the response of trying to deploy the
service(s). Here is shown an example of answer.
[source,json]
----
{
"data": {
"deployments": {
"successful": [
{
"volumes": {},
"portMapping": [ // <1>
{
"port": 9000,
"role": "clock",
"iid": "clock-1"
}
],
"roles": {
"clock": {
"instances": [
"clock-1"
]
},
"acs": {
"instances": [
"acs-2"
]
}
},
"deploymentURN": "slap://javaexample.examples.ecloud/deployments/20161014_111704/48e7b155" // <2>
}
],
"errors": []
},
"errors": [],
"successful": [
"Registered element: eslap://javaexample.examples.ecloud/components/acs/0_5_0",
"Registered element: eslap://javaexample.examples.ecloud/components/simpleclock/0_5_0",
"Registered element: eslap://javaexample.examples.ecloud/services/clock/0_5_0"
]
},
"message": "Bundle registration finished with no errors.", // <3>
"success": true
}
----
From this answer have to be highlighted the following fields:
<1> _portMapping_ field specifies the port where the service is listening. In
this case specifies that _clock_ role is receiving requests in port `9000`.
<2> _deploymentURN_ field is the identifier of the service deployment. This
value is used for performing management operations over the service, as
undeploying it.
<3> _message_ field will detail if any problem arose during the installation.
This is the answer returned when using a _deployment_ bundle. In case of using
a _test_ bundle some extra fields are added (`testToken` and `tests`).
=== Accessing a Deployed Service
Once a service is properly deployed in _LocalStamp_ it can be accessed through
the roles that have a mapped port.
In the previous example the deployed service can be accessed through port
`9000`. Thus, assuming that the component of the role _clock_ offers a REST API
method named `clock` requiring two parameters `username` and `password`:
curl http://localhost:9000/clock?username=me&password=me
And it will be returned the expected answer.
=== Listing Deployed Services
Request the `admission/deployments` _Admission_ REST API method at any time you
need to check the current list of deployments in the _LocalStamp_:
_Usage_:
curl -s http://localhost:8090/admission/deployments
Its execution will return a json file with the current listed deployments in
the _LocalStamp_.
=== Undeploying Services
There are two ways of undeploying services in a _LocalStamp_: the official (and
pretty) and the rude (and easy) ones.
The official one makes use of the _Admission_ REST API method for undeploying
services: `admission/undeploy`.
_Usage_:
curl http://localhost:8090/admission/undeploy?deploymentURN=DEPLOYMENTURN_OF_THE_SERVICE
As it can be seen it is necessary to pass as parameter the _deploymentURN_ of
the service to be undeployed.
The rude way just consists to stop the _LocalStamp_ execution. This can be done
considering that this is a testing and local environment. In order to do so
just execute `Ctrl+C` in the console where the _LocalStamp_ has been launched.
[NOTE]
.Resource consumption
======
Please take into account that if you start deploying services in a running
_LocalStamp_ instance without undeploying previous ones at the end you can end
up out of resources.
======
=== Relevant Folder and Logs
When using the _LocalStamp_ instance launched as a service relevant information
is stored in `/tmp/`. Most relevant files and folders are:
* _/tmp/local-stamp.log_: this log contains information about the execution of
the _LocalStamp_ instance.
* _/tmp/local-stamp/_: inside this folder will be created several folders,
being the most important ones from a service testing point of view the
folders that are created for each _role_ in each deployed _service_.
* _/tmp/local-stamp/<role>/_: those folders contain the information necessary
for each role, including also the log resulting of its execution.
* _/tmp/local-stamp/<role>/slap.log_: this file contains the logging generated
during the role execution.
|