Merge "Add Robot test for validating Helm charts"
[validation.git] / docker / README.rst
1 .. ############################################################################
2 .. Copyright (c) 2019 AT&T, ENEA AB, Nokia and others                         #
3 ..                                                                            #
4 .. Licensed under the Apache License, Version 2.0 (the "License");            #
5 .. you maynot use this file except in compliance with the License.            #
6 ..                                                                            #
7 .. You may obtain a copy of the License at                                    #
8 ..       http://www.apache.org/licenses/LICENSE-2.0                           #
9 ..                                                                            #
10 .. Unless required by applicable law or agreed to in writing, software        #
11 .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT  #
12 .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.           #
13 .. See the License for the specific language governing permissions and        #
14 .. limitations under the License.                                             #
15 .. ############################################################################
16
17
18 Overview
19 ========
20
21 The Makefile in this directory is used to build and push all
22 the validation containers. The default registry is **akraino** on
23 dockerhub, but only CI jenkins slaves are authorized to push
24 images to that registry. If you want to push to your own test registry, set
25 the REGISTRY variables as in the commands below.
26
27 To build and push the images:
28
29 .. code-block:: console
30
31     make all [ REGISTRY=<dockerhub_registry> ]
32
33 To just build the containers, use the command:
34
35 .. code-block:: console
36
37     make build-all [ REGISTRY=<dockerhub_registry> ]
38
39 The k8s container
40 =================
41
42 Building and pushing the container
43 ----------------------------------
44
45 To build just the k8s container, use the command:
46
47 .. code-block:: console
48
49     make k8s-build [ REGISTRY=<dockerhub_registry> ]
50
51 To both build and push the container, use the command:
52
53 .. code-block:: console
54
55     make k8s [ REGISTRY=<dockerhub_registry> ]
56
57 Using the container
58 -------------------
59
60 The k8s image is meant to be ran from a server that has access to the
61 kubernetes cluster (jenkins slave, jumpserver, etc).
62
63 Before running the image, copy the folder ~/.kube from your kubernetes
64 master node to a local folder (e.g. /home/jenkins/k8s_access).
65
66 Container needs to be started with the kubernetes access folder mounted.
67 Optionally, the results folder can be mounted as well; this way the logs are
68 stored on the local server.
69
70 .. code-block:: console
71
72     docker run -ti -v /home/jenkins/k8s_access:/root/.kube/ \
73     -v /home/jenkins/k8s_results:/opt/akraino/results/ \
74     akraino/validation:k8s-latest
75
76 By default, the container will run the k8s conformance test. If you want to
77 enter the container, add */bin/sh* at the end of the command above
78
79 The mariadb container
80 =====================
81
82 Building and pushing the container
83 ----------------------------------
84
85 To build just the postgresql container, use the command:
86
87 .. code-block:: console
88
89    make mariadb-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
90
91 To both build and push the container, use the command:
92
93 .. code-block:: console
94
95    make mariadb [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
96
97 Using the container
98 -------------------
99 In order for the container to be easily created, the deploy.sh script has been developed. This script accepts the following as input parameters:
100
101 CONTAINER_NAME, name of the container, default value is akraino-validation-mariadb
102 MARIADB_ROOT_PASSWORD, the desired mariadb root user password, this variable is required
103 UI_ADMIN_PASSWORD, the desired Blueprint Validation UI password for the admin user, this variable is required
104 UI_AKRAINO_PASSWORD, the desired Blueprint Validation UI password for the akraino user, this variable is required
105 REGISTRY, registry of the mariadb image, default value is akraino
106 NAME, name of the mariadb image, default value is validation
107 TAG_PRE, first part of the image version, default value is mariadb
108 TAG_VER, last part of the image version, default value is latest
109 MARIADB_HOST_PORT, port on which mariadb is exposed on host, default value is 3307
110
111 In order to deploy the container, this script can be executed with the appropriate parameters.
112
113 Example (assuming the default variables have been utilized for building the image using the make command):
114
115 .. code-block:: console
116
117     cd validation/docker/mariadb
118     ./deploy.sh MARIADB_ROOT_PASSWORD=password UI_ADMIN_PASSWORD=admin UI_AKRAINO_PASSWORD=akraino
119
120 Also, in order to re-deploy the database (it is assumed that the corresponding mariadb container has been stopped and deleted) while the persistent storage already exists (currently, the directory /var/lib/mariadb of the host is used), a different approach should be used after the image build process.
121
122 To this end, another script has been developed, namely deploy_with_existing_storage.sh which easily deploys the container. This script accepts the following items as input parameters:
123
124 CONTAINER_NAME, the name of the container, default value is akraino-validation-mariadb
125 MARIADB_ROOT_PASSWORD, the desired mariadb root user password, this variable is required
126 REGISTRY, the registry of the mariadb image, default value is akraino
127 NAME, the name of the mariadb image, default value is validation
128 TAG_PRE, the first part of the image version, default value is mariadb
129 TAG_VER, the last part of the image version, default value is latest
130 MARIADB_HOST_PORT, the port on which mariadb is exposed on host, default value is 3307
131
132 In order to deploy the container, this script can be executed with the appropriate parameters.
133
134 Example (assuming the default variables have been utilized for building the image using the make command):
135
136 .. code-block:: console
137
138     cd validation/docker/mariadb
139     ./deploy_with_existing_persistent_storage.sh MARIADB_ROOT_PASSWORD=password
140
141 More info can be found at the UI README file.
142
143 The ui container
144 ================
145
146 Building and pushing the container
147 ----------------------------------
148
149 To build just the UI container, use the command:
150
151 .. code-block:: console
152
153     make ui-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
154
155 To both build and push the container, use the command:
156
157 .. code-block:: console
158
159     make ui [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
160
161 Using the container
162 -------------------
163 In order for the container to be easily created, the deploy.sh script has been developed. This script accepts the following as input parameters:
164
165 CONTAINER_NAME, the name of the contaner, default value is akraino-validation-ui
166 DB_CONNECTION_URL, the URL connection with the akraino database of the maridb instance, this variable is required
167 MARIADB_ROOT_PASSWORD, the mariadb root user password, this variable is required
168 REGISTRY, the registry of the mariadb image, default value is akraino
169 NAME, the name of the mariadb image, default value is validation
170 TAG_PRE, the first part of the image version, default value is ui
171 TAG_VER, the last part of the image version, default value is latest
172 JENKINS_URL, the URL of the Jenkins instance, this variable is required
173 JENKINS_USERNAME, the Jenkins user name, this variable is required
174 JENKINS_USER_PASSWORD, the Jenkins user password, this variable is required
175 JENKINS_JOB_NAME, the name of Jenkins job capable of executing the blueprint validation tests, this variable is required
176 NEXUS_PROXY, the needed proxy in order for the Nexus server to be reachable, default value is none
177 JENKINS_PROXY, the needed proxy in order for the Jenkins server to be reachable, default value is none
178
179 Note that, for a functional UI, the following prerequisites are needed:
180
181 - The mariadb container in up and running state
182 - A Jenkins instance capable of running the blueprint validation test
183 - A Nexus repo in which all the test results are stored.
184
185 More info can be found at the UI README file.
186
187 In order to deploy the container, the aforementioned script can be executed with the appropriate parameters.
188
189 Example (assuming the default variables have been utilized for building the image using the make command):
190
191 .. code-block:: console
192
193     cd validation/docker/ui
194     ./deploy.sh DB_CONNECTION_URL=172.17.0.3:3306/akraino MARIADB_ROOT_PASSWORD=password JENKINS_URL=http://192.168.2.2:8080 JENKINS_USERNAME=name JENKINS_USER_PASSWORD=jenkins_pwd JENKINS_JOB_NAME=job1
195
196 The kube-conformance container
197 ==============================
198
199 Building and pushing the container
200 ----------------------------------
201
202 To build just the kube-conformance container, use the command:
203
204 .. code-block:: console
205
206     make kube-conformance-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
207
208 To both build and push the container, use the command:
209
210 .. code-block:: console
211
212     make kube-conformance [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
213
214 Using the container
215 -------------------
216
217 This is a standalone container able to launch Kubernetes end-to-end tests,
218 for the purposes of conformance testing.
219
220 It is a thin wrapper around the `e2e.test` binary in the upstream Kubernetes
221 distribution, which drops results in a predetermined location for use as a
222 [Heptio Sonobuoy](https://github.com/heptio/sonobuoy) plugin.
223
224 To learn more about conformance testing and its Sonobuoy integration, read the
225 [conformance guide](https://github.com/heptio/sonobuoy/blob/master/docs/conformance-testing.md).
226
227 Example:
228
229 .. code-block:: console
230
231     docker run -ti akraino/validation:kube-conformance-v1.15
232
233 By default, the container will run the `run_e2e.sh` script. If you want to
234 enter the container, add */bin/sh* at the end of the command above
235
236 Normally, this conainer is not used directly, but instead leveraged via
237 sonobuoy.
238
239 The sonobuoy-plugin-systemd-logs container
240 ==========================================
241
242 Building and pushing the container
243 ----------------------------------
244
245 To build just the sonobuoy-plugin-systemd-logs container, use the command:
246
247 .. code-block:: console
248
249     make sonobuoy-plugin-systemd-logs-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
250
251 To both build and push the container, use the command:
252
253 .. code-block:: console
254
255     make sonobuoy-plugin-systemd-logs [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
256
257 Using the container
258 -------------------
259
260 This is a simple standalone container that gathers log information from
261 systemd, by chrooting into the node's filesystem and running `journalctl`.
262
263 This container is used by [Heptio Sonobuoy](https://github.com/heptio/sonobuoy)
264 for gathering host logs in a Kubernetes cluster.
265
266 Example:
267
268 .. code-block:: console
269
270     docker run -ti akraino/validation:sonobuoy-plugin-systemd-logs-latest
271
272 By default, the container will run the `get_systemd_logs.sh` script. If you
273 want to enter the container, add */bin/sh* at the end of the command above.
274
275 Normally, this conainer is not used directly, but instead leveraged via
276 sonobuoy.
277
278 The helm container
279 ==================
280
281 Building and pushing the container
282 ----------------------------------
283
284 To build just the helm container, use the command:
285
286 .. code-block:: console
287
288     make helm-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
289
290 To both build and push the container, use the command:
291
292 .. code-block:: console
293
294     make helm [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
295
296 Using the container
297 -------------------
298
299 Container needs to be started with the SSH key file mounted. Users
300 credentials can be provided via a mounted variables.yaml file.
301
302 The results folder can be mounted as well; this way the logs are
303 stored on the local server.
304
305 .. code-block:: console
306
307     docker run -ti -v /home/jenkins/openrc:/root/openrc \
308     -v /home/foobar/.ssh/id_rsa:/root/.ssh/id_rsa \
309     -v /home/foobar/variables.yaml:/opt/akraino/validation/tests/variables.yaml \
310     -v /home/foobar/helm_results:/opt/akraino/results/ \
311     akraino/validation:helm-latest