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