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 ENCRYPTION_KEY, the key that should be used by the AES algorithm for encrypting passwords stored in database, this variable is required
 112
 113 In order to deploy the container, this script can be executed with the appropriate parameters.
 114
 115 Example (assuming the default variables have been utilized for building the image using the make command):
 116
 117 .. code-block:: console
 118
 119     cd validation/docker/mariadb
 120     ./deploy.sh MARIADB_ROOT_PASSWORD=root_password MARIADB_AKRAINO_PASSWORD=akraino_password UI_ADMIN_PASSWORD=admin UI_AKRAINO_PASSWORD=akraino ENCRYPTION_KEY=key
 121
 122 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.
 123
 124 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:
 125
 126 CONTAINER_NAME, the name of the container, default value is akraino-validation-mariadb
 127 REGISTRY, the registry of the mariadb image, default value is akraino
 128 NAME, the name of the mariadb image, default value is validation
 129 TAG_PRE, the first part of the image version, default value is mariadb
 130 TAG_VER, the last part of the image version, default value is latest
 131 MARIADB_HOST_PORT, the port on which mariadb is exposed on host, default value is 3307
 132
 133 In order to deploy the container, this script can be executed with the appropriate parameters.
 134
 135 Example (assuming the default variables have been utilized for building the image using the make command):
 136
 137 .. code-block:: console
 138
 139     cd validation/docker/mariadb
 140     ./deploy_with_existing_persistent_storage.sh
 141
 142 More info can be found at the UI README file.
 143
 144 The ui container
 145 ================
 146
 147 Building and pushing the container
 148 ----------------------------------
 149
 150 To build just the UI container, use the command:
 151
 152 .. code-block:: console
 153
 154     make ui-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 155
 156 To both build and push the container, use the command:
 157
 158 .. code-block:: console
 159
 160     make ui [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 161
 162 Using the container
 163 -------------------
 164 In order for the container to be easily created, the deploy.sh script has been developed. This script accepts the following as input parameters:
 165
 166 CONTAINER_NAME, the name of the contaner, default value is akraino-validation-ui
 167 DB_IP_PORT, the IP and port of the maridb instance, this variable is required
 168 MARIADB_AKRAINO_PASSWORD, the mariadb akraino user password, this variable is required
 169 REGISTRY, the registry of the mariadb image, default value is akraino
 170 NAME, the name of the mariadb image, default value is validation
 171 TAG_PRE, the first part of the image version, default value is ui
 172 TAG_VER, the last part of the image version, default value is latest
 173 JENKINS_URL, the URL of the Jenkins instance (http or https must be defined), the default value is 'https://jenkins.akraino.org/'
 174 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)
 175 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)
 176 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)
 177 NEXUS_PROXY, the needed proxy in order for the Nexus server to be reachable, default value is none
 178 JENKINS_PROXY, the needed proxy in order for the Jenkins server to be reachable, default value is none
 179 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
 180 ENCRYPTION_KEY, the key that should be used by the AES algorithm for encrypting passwords stored in database, this variable is required
 181
 182 Note that, for a functional UI, the following prerequisites are needed:
 183
 184 - The mariadb container in up and running state
 185 - A Jenkins instance capable of running the blueprint validation test (this is optional and is needed only for UI full control loop mode)
 186 - A Nexus repo in which all the test results are stored.
 187
 188 More info can be found at the UI README file.
 189
 190 In order to deploy the container, the aforementioned script can be executed with the appropriate parameters.
 191
 192 Example (assuming the default variables have been utilized for building the image using the make command):
 193
 194 .. code-block:: console
 195
 196     cd validation/docker/ui
 197     ./deploy.sh DB_IP_PORT=172.17.0.3:3306 MARIADB_AKRAINO_PASSWORD=akraino_password ENCRYPTION_KEY=key
 198
 199 The kube-conformance container
 200 ==============================
 201
 202 Building and pushing the container
 203 ----------------------------------
 204
 205 To build just the kube-conformance container, use the command:
 206
 207 .. code-block:: console
 208
 209     make kube-conformance-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 210
 211 To both build and push the container, use the command:
 212
 213 .. code-block:: console
 214
 215     make kube-conformance [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 216
 217 Using the container
 218 -------------------
 219
 220 This is a standalone container able to launch Kubernetes end-to-end tests,
 221 for the purposes of conformance testing.
 222
 223 It is a thin wrapper around the `e2e.test` binary in the upstream Kubernetes
 224 distribution, which drops results in a predetermined location for use as a
 225 [Heptio Sonobuoy](https://github.com/heptio/sonobuoy) plugin.
 226
 227 To learn more about conformance testing and its Sonobuoy integration, read the
 228 [conformance guide](https://github.com/heptio/sonobuoy/blob/master/docs/conformance-testing.md).
 229
 230 Example:
 231
 232 .. code-block:: console
 233
 234     docker run -ti akraino/validation:kube-conformance-v1.15
 235
 236 By default, the container will run the `run_e2e.sh` script. If you want to
 237 enter the container, add */bin/sh* at the end of the command above
 238
 239 Normally, this conainer is not used directly, but instead leveraged via
 240 sonobuoy.
 241
 242 The sonobuoy-plugin-systemd-logs container
 243 ==========================================
 244
 245 Building and pushing the container
 246 ----------------------------------
 247
 248 To build just the sonobuoy-plugin-systemd-logs container, use the command:
 249
 250 .. code-block:: console
 251
 252     make sonobuoy-plugin-systemd-logs-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 253
 254 To both build and push the container, use the command:
 255
 256 .. code-block:: console
 257
 258     make sonobuoy-plugin-systemd-logs [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 259
 260 Using the container
 261 -------------------
 262
 263 This is a simple standalone container that gathers log information from
 264 systemd, by chrooting into the node's filesystem and running `journalctl`.
 265
 266 This container is used by [Heptio Sonobuoy](https://github.com/heptio/sonobuoy)
 267 for gathering host logs in a Kubernetes cluster.
 268
 269 Example:
 270
 271 .. code-block:: console
 272
 273     docker run -ti akraino/validation:sonobuoy-plugin-systemd-logs-latest
 274
 275 By default, the container will run the `get_systemd_logs.sh` script. If you
 276 want to enter the container, add */bin/sh* at the end of the command above.
 277
 278 Normally, this conainer is not used directly, but instead leveraged via
 279 sonobuoy.
 280
 281 The openstack container
 282 =======================
 283
 284 Building and pushing the container
 285 ----------------------------------
 286
 287 To build just the openstack container, use the command:
 288
 289 .. code-block:: console
 290
 291     make openstack-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 292
 293 To both build and push the container, use the command:
 294
 295 .. code-block:: console
 296
 297     make openstack [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 298
 299 Using the container
 300 -------------------
 301
 302 The openstack image is meant to be ran from a server that has access to the
 303 openstack deployment (jenkins slave, jumpserver, etc).
 304
 305 Before running the image, copy openstack deployment environment variables
 306 (openrc) to a local folder (e.g. /root/openrc).
 307
 308 Container needs to be started with the openrc file mounted. Optionally, test
 309 cases can be excluded from execution via a mounted blacklist file.
 310
 311 The results folder can be mounted as well; this way the logs are
 312 stored on the local server.
 313
 314 .. code-block:: console
 315
 316     docker run -ti -v /home/jenkins/openrc:/root/openrc \
 317     -v /home/jenkins/blacklist.txt:/opt/akraino/validation/tests/openstack/tempest/blacklist.txt \
 318     -v /home/jenkins/openstack_results:/opt/akraino/results/ \
 319     akraino/validation:openstack-latest
 320
 321 The helm container
 322 ==================
 323
 324 Building and pushing the container
 325 ----------------------------------
 326
 327 To build just the helm container, use the command:
 328
 329 .. code-block:: console
 330
 331     make helm-build [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 332
 333 To both build and push the container, use the command:
 334
 335 .. code-block:: console
 336
 337     make helm [ REGISTRY=<dockerhub_registry> NAME=<image_name>]
 338
 339 Using the container
 340 -------------------
 341
 342 Container needs to be started with the SSH key file mounted. Users
 343 credentials can be provided via a mounted variables.yaml file.
 344
 345 The results folder can be mounted as well; this way the logs are
 346 stored on the local server.
 347
 348 .. code-block:: console
 349
 350     docker run -ti -v /home/jenkins/openrc:/root/openrc \
 351     -v /home/foobar/.ssh/id_rsa:/root/.ssh/id_rsa \
 352     -v /home/foobar/variables.yaml:/opt/akraino/validation/tests/variables.yaml \
 353     -v /home/foobar/helm_results:/opt/akraino/results/ \
 354     akraino/validation:helm-latest