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 mysql container
  80 =====================
  81
  82 Building and pushing the container
  83 ----------------------------------
  84
  85 To build just the mysql container, use the command:
  86
  87 .. code-block:: console
  88
  89    make mysql-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 mysql [ 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-mysql
 102 MYSQL_ROOT_PASSWORD, the desired mysql root user password, this variable is required
 103 MYSQL_AKRAINO_PASSWORD, the desired mysql akraino user password, this variable is required
 104 REGISTRY, registry of the mysql image, default value is akraino
 105 NAME, name of the mysql image, default value is validation
 106 TAG_PRE, first part of the image version, default value is mysql
 107 TAG_VER, last part of the image version, default value is latest
 108 MYSQL_HOST_PORT, port on which mysql is exposed on host, default value is 3307
 109
 110 In order to deploy the container, this script can be executed with the appropriate parameters.
 111
 112 Example (assuming the default variables have been utilized for building the image using the make command):
 113
 114 .. code-block:: console
 115
 116     cd validation/docker/mysql
 117     ./deploy.sh MYSQL_ROOT_PASSWORD=root_password MYSQL_AKRAINO_PASSWORD=akraino_password
 118
 119 Also, in order to re-deploy the database (it is assumed that the corresponding mysql container has been stopped and deleted) while the persistent storage already exists (currently, the 'akraino-validation-mysql' docker volume is used), a different approach should be used after the image building process.
 120
 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:
 122
 123 CONTAINER_NAME, the name of the container, default value is akraino-validation-mysql
 124 REGISTRY, the registry of the mysql image, default value is akraino
 125 NAME, the name of the mysql image, default value is validation
 126 TAG_PRE, the first part of the image version, default value is mysql
 127 TAG_VER, the last part of the image version, default value is latest
 128 MYSQL_HOST_PORT, the port on which mysql is exposed on host, default value is 3307
 129
 130 In order to deploy the container, this script can be executed with the appropriate parameters.
 131
 132 Example (assuming the default variables have been utilized for building the image using the make command):
 133
 134 .. code-block:: console
 135
 136     cd validation/docker/mysql
 137     ./deploy_with_existing_persistent_storage.sh
 138
 139 More info can be found at the UI README file.
 140
 141 The ui container
 142 ================
 143
 144 Building and pushing the container
 145 ----------------------------------
 146
 147 To build just the UI container, use the command:
 148
 149 .. code-block:: console
 150
 151     make ui-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 152
 153 To both build and push the container, use the command:
 154
 155 .. code-block:: console
 156
 157     make ui [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 158
 159 Using the container
 160 -------------------
 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:
 162
 163 CONTAINER_NAME, the name of the contaner, default value is akraino-validation-ui
 164 DB_IP_PORT, the IP and port of the mysql instance, this variable is required
 165 MYSQL_AKRAINO_PASSWORD, the mysql akraino user password, this variable is required
 166 REGISTRY, the registry of the mysql image, default value is akraino
 167 NAME, the name of the mysql 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
 180
 181 Note that, for a functional UI, the following prerequisites are needed:
 182
 183 - The mysql 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.
 186
 187 More info can be found at the UI README file.
 188
 189 In order to deploy the container, the aforementioned script can be executed with the appropriate parameters.
 190
 191 Example (assuming the default variables have been utilized for building the image using the make command):
 192
 193 .. code-block:: console
 194
 195     cd validation/docker/ui
 196     ./deploy.sh DB_IP_PORT=172.17.0.3:3306 MYSQL_AKRAINO_PASSWORD=akraino_password ENCRYPTION_KEY=AGADdG4D04BKm2IxIWEr8o== UI_ADMIN_PASSWORD=admin UI_AKRAINO_PASSWORD=akraino
 197
 198 The kube-conformance container
 199 ==============================
 200
 201 Building and pushing the container
 202 ----------------------------------
 203
 204 To build just the kube-conformance container, use the command:
 205
 206 .. code-block:: console
 207
 208     make kube-conformance-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 209
 210 To both build and push the container, use the command:
 211
 212 .. code-block:: console
 213
 214     make kube-conformance [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 215
 216 Using the container
 217 -------------------
 218
 219 This is a standalone container able to launch Kubernetes end-to-end tests,
 220 for the purposes of conformance testing.
 221
 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.
 225
 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).
 228
 229 Example:
 230
 231 .. code-block:: console
 232
 233     docker run -ti akraino/validation:kube-conformance-v1.15
 234
 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
 237
 238 Normally, this conainer is not used directly, but instead leveraged via
 239 sonobuoy.
 240
 241 The sonobuoy-plugin-systemd-logs container
 242 ==========================================
 243
 244 Building and pushing the container
 245 ----------------------------------
 246
 247 To build just the sonobuoy-plugin-systemd-logs container, use the command:
 248
 249 .. code-block:: console
 250
 251     make sonobuoy-plugin-systemd-logs-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 252
 253 To both build and push the container, use the command:
 254
 255 .. code-block:: console
 256
 257     make sonobuoy-plugin-systemd-logs [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 258
 259 Using the container
 260 -------------------
 261
 262 This is a simple standalone container that gathers log information from
 263 systemd, by chrooting into the node's filesystem and running `journalctl`.
 264
 265 This container is used by [Heptio Sonobuoy](https://github.com/heptio/sonobuoy)
 266 for gathering host logs in a Kubernetes cluster.
 267
 268 Example:
 269
 270 .. code-block:: console
 271
 272     docker run -ti akraino/validation:sonobuoy-plugin-systemd-logs-latest
 273
 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.
 276
 277 Normally, this conainer is not used directly, but instead leveraged via
 278 sonobuoy.
 279
 280 The openstack container
 281 =======================
 282
 283 Building and pushing the container
 284 ----------------------------------
 285
 286 To build just the openstack container, use the command:
 287
 288 .. code-block:: console
 289
 290     make openstack-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 291
 292 To both build and push the container, use the command:
 293
 294 .. code-block:: console
 295
 296     make openstack [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 297
 298 Using the container
 299 -------------------
 300
 301 The openstack image is meant to be ran from a server that has access to the
 302 openstack deployment (jenkins slave, jumpserver, etc).
 303
 304 Before running the image, copy openstack deployment environment variables
 305 (openrc) to a local folder (e.g. /root/openrc).
 306
 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.
 309
 310 The results folder can be mounted as well; this way the logs are
 311 stored on the local server.
 312
 313 .. code-block:: console
 314
 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
 319
 320 The helm container
 321 ==================
 322
 323 Building and pushing the container
 324 ----------------------------------
 325
 326 To build just the helm container, use the command:
 327
 328 .. code-block:: console
 329
 330     make helm-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 331
 332 To both build and push the container, use the command:
 333
 334 .. code-block:: console
 335
 336     make helm [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 337
 338 Using the container
 339 -------------------
 340
 341 Container needs to be started with the SSH key file mounted. Users
 342 credentials can be provided via a mounted variables.yaml file.
 343
 344 The results folder can be mounted as well; this way the logs are
 345 stored on the local server.
 346
 347 .. code-block:: console
 348
 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