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 mariadb 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 MARIADB_AKRAINO_PASSWORD, the desired mariadb akraino user password, this variable is required
 104 UI_ADMIN_PASSWORD, the desired Blueprint Validation UI password for the admin user, this variable is required
 105 UI_AKRAINO_PASSWORD, the desired Blueprint Validation UI password for the akraino user, this variable is required
 106 REGISTRY, registry of the mariadb image, default value is akraino
 107 NAME, name of the mariadb image, default value is validation
 108 TAG_PRE, first part of the image version, default value is mariadb
 109 TAG_VER, last part of the image version, default value is latest
 110 MARIADB_HOST_PORT, port on which mariadb is exposed on host, default value is 3307
 111
 112 In order to deploy the container, this script can be executed with the appropriate parameters.
 113
 114 Example (assuming the default variables have been utilized for building the image using the make command):
 115
 116 .. code-block:: console
 117
 118     cd validation/docker/mariadb
 119     ./deploy.sh MARIADB_ROOT_PASSWORD=root_password MARIADB_AKRAINO_PASSWORD=akraino_password UI_ADMIN_PASSWORD=admin UI_AKRAINO_PASSWORD=akraino
 120
 121 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.
 122
 123 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:
 124
 125 CONTAINER_NAME, the name of the container, default value is akraino-validation-mariadb
 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
 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_IP_PORT, the IP and port of the maridb instance, this variable is required
 167 MARIADB_AKRAINO_PASSWORD, the mariadb akraino 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 (http or https must be defined), 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_IP_PORT=172.17.0.3:3306 MARIADB_AKRAINO_PASSWORD=akraino_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 openstack container
 279 =======================
 280
 281 Building and pushing the container
 282 ----------------------------------
 283
 284 To build just the openstack container, use the command:
 285
 286 .. code-block:: console
 287
 288     make openstack-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 openstack [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 295
 296 Using the container
 297 -------------------
 298
 299 The openstack image is meant to be ran from a server that has access to the
 300 openstack deployment (jenkins slave, jumpserver, etc).
 301
 302 Before running the image, copy openstack deployment environment variables
 303 (openrc) to a local folder (e.g. /root/openrc).
 304
 305 Container needs to be started with the openrc file mounted. Optionally, test
 306 cases can be excluded from execution via a mounted blacklist file.
 307
 308 The results folder can be mounted as well; this way the logs are
 309 stored on the local server.
 310
 311 .. code-block:: console
 312
 313     docker run -ti -v /home/jenkins/openrc:/root/openrc \
 314     -v /home/jenkins/blacklist.txt:/opt/akraino/validation/tests/openstack/tempest/blacklist.txt \
 315     -v /home/jenkins/openstack_results:/opt/akraino/results/ \
 316     akraino/validation:openstack-latest
 317
 318 The helm container
 319 ==================
 320
 321 Building and pushing the container
 322 ----------------------------------
 323
 324 To build just the helm container, use the command:
 325
 326 .. code-block:: console
 327
 328     make helm-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 329
 330 To both build and push the container, use the command:
 331
 332 .. code-block:: console
 333
 334     make helm [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 335
 336 Using the container
 337 -------------------
 338
 339 Container needs to be started with the SSH key file mounted. Users
 340 credentials can be provided via a mounted variables.yaml file.
 341
 342 The results folder can be mounted as well; this way the logs are
 343 stored on the local server.
 344
 345 .. code-block:: console
 346
 347     docker run -ti -v /home/jenkins/openrc:/root/openrc \
 348     -v /home/foobar/.ssh/id_rsa:/root/.ssh/id_rsa \
 349     -v /home/foobar/variables.yaml:/opt/akraino/validation/tests/variables.yaml \
 350     -v /home/foobar/helm_results:/opt/akraino/results/ \
 351     akraino/validation:helm-latest