1 .. ############################################################################
2 .. Copyright (c) 2019 AT&T, ENEA AB, Nokia and others #
4 .. Licensed under the Apache License, Version 2.0 (the "License"); #
5 .. you maynot use this file except in compliance with the License. #
7 .. You may obtain a copy of the License at #
8 .. http://www.apache.org/licenses/LICENSE-2.0 #
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 .. ############################################################################
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.
27 To build and push the images:
29 .. code-block:: console
31 make all [ REGISTRY=<dockerhub_registry> ]
33 To just build the containers, use the command:
35 .. code-block:: console
37 make build-all [ REGISTRY=<dockerhub_registry> ]
42 Building and pushing the container
43 ----------------------------------
45 To build just the k8s container, use the command:
47 .. code-block:: console
49 make k8s-build [ REGISTRY=<dockerhub_registry> ]
51 To both build and push the container, use the command:
53 .. code-block:: console
55 make k8s [ REGISTRY=<dockerhub_registry> ]
60 The k8s image is meant to be ran from a server that has access to the
61 kubernetes cluster (jenkins slave, jumpserver, etc).
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).
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.
70 .. code-block:: console
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
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
82 Building and pushing the container
83 ----------------------------------
85 To build just the mariadb container, use the command:
87 .. code-block:: console
89 make mariadb-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
91 To both build and push the container, use the command:
93 .. code-block:: console
95 make mariadb [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
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:
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 MARIADB_AKRAINO_PASSWORD, the desired mariadb akraino user password, this variable is required
104 REGISTRY, registry of the mariadb image, default value is akraino
105 NAME, name of the mariadb image, default value is validation
106 TAG_PRE, first part of the image version, default value is mariadb
107 TAG_VER, last part of the image version, default value is latest
108 MARIADB_HOST_PORT, port on which mariadb is exposed on host, default value is 3307
110 In order to deploy the container, this script can be executed with the appropriate parameters.
112 Example (assuming the default variables have been utilized for building the image using the make command):
114 .. code-block:: console
116 cd validation/docker/mariadb
117 ./deploy.sh MARIADB_ROOT_PASSWORD=root_password MARIADB_AKRAINO_PASSWORD=akraino_password
119 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 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 CONTAINER_NAME, the name of the container, default value is akraino-validation-mariadb
124 REGISTRY, the registry of the mariadb image, default value is akraino
125 NAME, the name of the mariadb image, default value is validation
126 TAG_PRE, the first part of the image version, default value is mariadb
127 TAG_VER, the last part of the image version, default value is latest
128 MARIADB_HOST_PORT, the port on which mariadb is exposed on host, default value is 3307
130 In order to deploy the container, this script can be executed with the appropriate parameters.
132 Example (assuming the default variables have been utilized for building the image using the make command):
134 .. code-block:: console
136 cd validation/docker/mariadb
137 ./deploy_with_existing_persistent_storage.sh
139 More info can be found at the UI README file.
144 Building and pushing the container
145 ----------------------------------
147 To build just the UI container, use the command:
149 .. code-block:: console
151 make ui-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
153 To both build and push the container, use the command:
155 .. code-block:: console
157 make ui [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
161 In order for the container to be easily created, the deploy.sh script has been developed. This script accepts the following as input parameters:
163 CONTAINER_NAME, the name of the contaner, default value is akraino-validation-ui
164 DB_IP_PORT, the IP and port of the maridb instance, this variable is required
165 MARIADB_AKRAINO_PASSWORD, the mariadb akraino user password, this variable is required
166 REGISTRY, the registry of the mariadb image, default value is akraino
167 NAME, the name of the mariadb image, default value is validation
168 TAG_PRE, the first part of the image version, default value is ui
169 TAG_VER, the last part of the image version, default value is latest
170 JENKINS_URL, the URL of the Jenkins instance (http or https must be defined), the default value is 'https://jenkins.akraino.org/'
171 JENKINS_USERNAME, the Jenkins user name, the default value is 'demo' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins user)
172 JENKINS_USER_PASSWORD, the Jenkins user password, the default value is 'demo' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins user password)
173 JENKINS_JOB_NAME, the name of Jenkins job capable of executing the blueprint validation tests, the default value is 'validation' (in the context of UI full control loop mode, this parameter must be changed to include a real Jenkins job name)
174 NEXUS_PROXY, the needed proxy in order for the Nexus server to be reachable, default value is none
175 JENKINS_PROXY, the needed proxy in order for the Jenkins server to be reachable, default value is none
176 CERTDIR, the directory where the SSL certificates can be found, default value is the working directory where self signed certificates exist only for demo purposes
177 ENCRYPTION_KEY, the key that should be used by the AES algorithm for encrypting passwords stored in database, this variable is required
178 UI_ADMIN_PASSWORD, the desired Blueprint Validation UI password for the admin user, this variable is required
179 UI_AKRAINO_PASSWORD, the desired Blueprint Validation UI password for the akraino user, this variable is required
181 Note that, for a functional UI, the following prerequisites are needed:
183 - The mariadb container in up and running state
184 - A Jenkins instance capable of running the blueprint validation test (this is optional and is needed only for UI full control loop mode)
185 - A Nexus repo in which all the test results are stored.
187 More info can be found at the UI README file.
189 In order to deploy the container, the aforementioned script can be executed with the appropriate parameters.
191 Example (assuming the default variables have been utilized for building the image using the make command):
193 .. code-block:: console
195 cd validation/docker/ui
196 ./deploy.sh DB_IP_PORT=172.17.0.3:3306 MARIADB_AKRAINO_PASSWORD=akraino_password ENCRYPTION_KEY=AGADdG4D04BKm2IxIWEr8o== UI_ADMIN_PASSWORD=admin UI_AKRAINO_PASSWORD=akraino
198 The kube-conformance container
199 ==============================
201 Building and pushing the container
202 ----------------------------------
204 To build just the kube-conformance container, use the command:
206 .. code-block:: console
208 make kube-conformance-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
210 To both build and push the container, use the command:
212 .. code-block:: console
214 make kube-conformance [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
219 This is a standalone container able to launch Kubernetes end-to-end tests,
220 for the purposes of conformance testing.
222 It is a thin wrapper around the `e2e.test` binary in the upstream Kubernetes
223 distribution, which drops results in a predetermined location for use as a
224 [Heptio Sonobuoy](https://github.com/heptio/sonobuoy) plugin.
226 To learn more about conformance testing and its Sonobuoy integration, read the
227 [conformance guide](https://github.com/heptio/sonobuoy/blob/master/docs/conformance-testing.md).
231 .. code-block:: console
233 docker run -ti akraino/validation:kube-conformance-v1.15
235 By default, the container will run the `run_e2e.sh` script. If you want to
236 enter the container, add */bin/sh* at the end of the command above
238 Normally, this conainer is not used directly, but instead leveraged via
241 The sonobuoy-plugin-systemd-logs container
242 ==========================================
244 Building and pushing the container
245 ----------------------------------
247 To build just the sonobuoy-plugin-systemd-logs container, use the command:
249 .. code-block:: console
251 make sonobuoy-plugin-systemd-logs-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
253 To both build and push the container, use the command:
255 .. code-block:: console
257 make sonobuoy-plugin-systemd-logs [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
262 This is a simple standalone container that gathers log information from
263 systemd, by chrooting into the node's filesystem and running `journalctl`.
265 This container is used by [Heptio Sonobuoy](https://github.com/heptio/sonobuoy)
266 for gathering host logs in a Kubernetes cluster.
270 .. code-block:: console
272 docker run -ti akraino/validation:sonobuoy-plugin-systemd-logs-latest
274 By default, the container will run the `get_systemd_logs.sh` script. If you
275 want to enter the container, add */bin/sh* at the end of the command above.
277 Normally, this conainer is not used directly, but instead leveraged via
280 The openstack container
281 =======================
283 Building and pushing the container
284 ----------------------------------
286 To build just the openstack container, use the command:
288 .. code-block:: console
290 make openstack-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
292 To both build and push the container, use the command:
294 .. code-block:: console
296 make openstack [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
301 The openstack image is meant to be ran from a server that has access to the
302 openstack deployment (jenkins slave, jumpserver, etc).
304 Before running the image, copy openstack deployment environment variables
305 (openrc) to a local folder (e.g. /root/openrc).
307 Container needs to be started with the openrc file mounted. Optionally, test
308 cases can be excluded from execution via a mounted blacklist file.
310 The results folder can be mounted as well; this way the logs are
311 stored on the local server.
313 .. code-block:: console
315 docker run -ti -v /home/jenkins/openrc:/root/openrc \
316 -v /home/jenkins/blacklist.txt:/opt/akraino/validation/tests/openstack/tempest/blacklist.txt \
317 -v /home/jenkins/openstack_results:/opt/akraino/results/ \
318 akraino/validation:openstack-latest
323 Building and pushing the container
324 ----------------------------------
326 To build just the helm container, use the command:
328 .. code-block:: console
330 make helm-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
332 To both build and push the container, use the command:
334 .. code-block:: console
336 make helm [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
341 Container needs to be started with the SSH key file mounted. Users
342 credentials can be provided via a mounted variables.yaml file.
344 The results folder can be mounted as well; this way the logs are
345 stored on the local server.
347 .. code-block:: console
349 docker run -ti -v /home/jenkins/openrc:/root/openrc \
350 -v /home/foobar/.ssh/id_rsa:/root/.ssh/id_rsa \
351 -v /home/foobar/variables.yaml:/opt/akraino/validation/tests/variables.yaml \
352 -v /home/foobar/helm_results:/opt/akraino/results/ \
353 akraino/validation:helm-latest