deployment/aks/README.md

   1 # ONAP on AKS
   2
   3 ## License
   4
   5 Copyright 2019 AT&T Intellectual Property. All rights reserved.
   6
   7 This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
   8
   9 Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
  10
  11
  12 ## About
  13
  14 ONAP on AKS will orchestrate an Azure Kubernetes Service (AKS) deployment, a DevStack deployment, an ONAP + NFS deployment, as well as configuration to link the Azure resources together. After ONAP is installed, a cloud region will also be added to ONAP with the new DevStack details that can be used to instantiate a VNF.
  15
  16
  17 ### Pre-Reqs
  18
  19 The following software is required to be installed:
  20
  21 - bash
  22 - [helm](https://helm.sh/docs/using_helm/)
  23 - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
  24 - [azure command line](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-apt?view=azure-cli-latest)
  25 - make, openjdk-8-jdk, openjdk-8-jre (``apt-get update && apt-get install make openjdk-8-jre openjdk-8-jdk``)
  26
  27 Check the [OOM Cloud Setup Guide](https://docs.onap.org/en/latest/submodules/oom.git/docs/oom_cloud_setup_guide.html#cloud-setup-guide-label) for the versions of kubectl and helm to use.
  28
  29 After installing the above software, run ``az login`` and follow the instructions to finalize the azure command line installation. **You'll need to be either an owner or co-owner of the azure subscription, or some of the deployment steps may not complete successfully**. If you have multiple azure subscriptions, use ``az account set --subscription <subscription name>`` prior to running ``az login`` so that resources are deployed to the correct subscription. See [the azure docs](https://docs.microsoft.com/en-us/cli/azure/get-started-with-azure-cli?view=azure-cli-latest) for more details on using the azure command line.
  30
  31
  32 ### The following resources will be created in Azure
  33
  34 - Kubernetes cluster via AKS (Azure Kubernetes Service)
  35 - VM running NFS server application
  36 - VM running latest DevStack version
  37
  38
  39 ## Usage
  40
  41
  42 ### cloud.sh
  43
  44
  45 ``cloud.sh`` is the main driver script, and deploys a Kubernetes Cluster (AKS), DevStack, NFS, and bootstraps ONAP with configuration needed to instantiate a VNF. The script creates ONAP in "about" an hour.
  46
  47 ```
  48
  49 $ ./cloud.sh --help
  50 ./cloud.sh [options]
  51
  52
  53 options:
  54 -f, --no-prompt           executes with no prompt for confirmation
  55 -n, --no-install          don't install ONAP
  56 -o, --override            create integration override for robot configuration
  57 -d, --no-validate         dont validate pre-reqs before executing deployment
  58 -p, --post-install        execute post-install scripts
  59 -h, --help                provide brief overview of script
  60
  61 This script deploys a cloud environment in Azure.
  62 It:
  63 - Uses Azure Kubernetes Service (AKS) to bootstrap a kubernetes cluster.
  64 - Creates a VM to be used as NFS storage.
  65 - Creates a VM and installs DevStack, to be used with ONAP.
  66 - Creates an openstack cli pod that can be used for cli access to devstack
  67 - Creates an integration-override.yaml file to configure robot
  68 - Launches ONAP onto the AKS Cluster via OOM.
  69 - Configures Networking, SSH Access, and Security Group Rules
  70
  71 ```
  72
  73 #### Example
  74
  75 ```
  76 $ ./cloud.sh --override
  77 ```
  78
  79
  80 ### cloud.conf
  81
  82
  83 This file contains the parameters that will be used when executing ``cloud.sh``. The parameter ``BUILD`` will be generated at runtime.
  84
  85 For an example with all of the parameters filled out, check [here](./cloud.conf.example). You can copy this and modify to suit your deployment. The parameters that MUST be modified from ``cloud.conf.example`` are ``USER_PUBLIC_IP_PREFIX`` and ``BUILD_DIR``.
  86
  87 All other parameters will work out of the box, however you can also customize them to suit your own deployment. See below for a description of the available parameters and how they're used.
  88
  89
  90 ```
  91
  92 # The variable $BUILD will be generated dynamically when this file is sourced
  93
  94 RANDOM_STRING=`cat /dev/urandom | env LC_CTYPE=C tr -cd 'a-zA-Z0-9' | head -c 4`
  95 BUILD=                     This is just a helper variable to create a random string to assign to various resources. Look at cloud.conf.example to see how it can be used.
  96
  97 # GLOBAL PARAMS
  98 LOCATION=                  Location in Azure to deploy resources
  99 USER_PUBLIC_IP_PREFIX=     Space delimited list of ip addresses/CIDR blocks that will be added to azure secuirty groups for access. Add the CIDR blocks to grant access for ssh, ONAP portal, and DevStack horizon access.
 100 BUILD_DIR=                 /path/to/directory where build files, artifacts, and other files will be created.
 101
 102 # AKS PARAMS
 103 AKS_RESOURCE_GROUP_NAME=   Name of resource group in azure that will be created for the AKS resource. Must not already exist.
 104 AKS_NAME=                  Name of AKS resource.
 105 AKS_K8_VERSION=            Kubernetes version, use az aks get-versions --location <location> to see available versions.
 106 AKS_NODE_COUNT=            Number of nodes that will comprise the AKS cluster.
 107 AKS_NODE_SIZE=             Flavor to use for AKS nodes.
 108 AKS_VNET_NAME=             Name of VNET that AKS nodes will attach to.
 109 AKS_DNS_PREFIX=            DNS prefix that will be used by kubernetes dns service.
 110 AKS_POD_CIDR=              CIDR used for pod ip allocation.
 111 AKS_NODE_CIDR=             CIDR used for node ip allocation.
 112 AKS_SERVICE_CIDR=          CIDR used for kubernetes service allocation.
 113 AKS_DNS_IP=                IP address to assign to kubernetes dns service. Should be from AKS_SERVICE_CIDR range.
 114 AKS_ADMIN_USER=            User name that will be created on AKS nodes. Use this user to ssh into AKS nodes if needed.
 115
 116 # NFS PARAMS
 117 NFS_NAME=                  Name of NFS VM created in Azure.
 118 NFS_RG=                    Name of resource group that will be created in Azure for the NFS VM. Must not already exist.
 119 NFS_VM_SIZE=               Flavor to use for NFS VM.
 120 NFS_LOCATION=              Azure location to deploy NFS VM.
 121 NFS_CIDR=                  CIDR for NFS VNET.
 122 NFS_ADMIN_USER=            User name that will be created on NFS VM. Use this to ssh to NFS VM if needed.
 123 NFS_VNET_NAME=             Name of VNET that NFS VM will attach to.
 124 NFS_SUBNET_NAME=           Name of SUBNET attached to NFS_VNET_NAME.
 125 NFS_DISK_SIZE=             Size of OS Disk for NFS VM.
 126
 127 # DEVSTACK PARAMS
 128 DEVSTACK_NAME=             Name of DevStack VM created in Azure.
 129 DEVSTACK_RG=               Name of resource group that will be created in Azure for the DevStack VM. Must not already exist.
 130 DEVSTACK_VM_SIZE=          Flavor to use for DevStack VM.
 131 DEVSTACK_LOCATION=         Azure location to deploy DevStack VM.
 132 DEVSTACK_CIDR=             CIDR for DevStack VNET.
 133 DEVSTACK_PRIVATE_IP=       IP to allocate to DevStack VM. This should be from DEVSTACK_CIDR range, and will be used to communicate with DevStack from ONAP.
 134 DEVSTACK_ADMIN_USER=       User name that will be created on DevStack VM. Use this to ssh to DevStack VM if needed.
 135 DEVSTACK_VNET_NAME=        Name of VNET that DevStack VM will attach to.
 136 DEVSTACK_SUBNET_NAME=      Name of SUBNET attached to DEVSTACK_VNET_NAME.
 137 DEVSTACK_DISK_SIZE=        Size of OS Disk for DevStack VM.
 138 OPENSTACK_USER=            User name that will be added to OpenStack after devstack has finished installing. This is also the username that will be used to create a cloud site in ONAP SO.
 139 OPENSTACK_PASS=            Password to use for OPENSTACK_USER.
 140 OPENSTACK_TENANT=          Tenant name that will be added to OpenStack after devstack has finished installing. This is also the username that will be used to create a cloud site in ONAP SO.
 141 OPENSTACK_REGION=          Only allows RegionOne for now, future enhancements will be added to allow multi-region.
 142 IMAGE_LIST=                Space delimited list of image urls to add to DevStack. Not required.
 143
 144 # ONAP PARAMS
 145 CLLI=                      Name of CLLI to be created in AAI.
 146 CLOUD_OWNER=               Name of Cloud Owner to be created in AAI.
 147 CLOUD_REGION=              Name of Cloud Region to be created in AAI.
 148 CUSTOMER=                  Name of Customer to be created in AAI.
 149 SUBSCRIBER=                Name of Subscriber to be created in AAI.
 150 SERVICE_TYPE=              Name of Service Type to be created in AAI.
 151 AZ=                        Name of Availability Zone to be created in AAI.
 152 OE=                        Name of Owning Entity to be created in VID.
 153 LOB=                       Name of Line of Business to be created in VID.
 154 PROJECT=                   Name of Project to be created in VID.
 155 PLATFORM=                  Name of Platform to be created in VID.
 156 OS_ID=                     Primary key to be used when adding cloud site to mariadb pod.
 157 OS_TENANT_ROLE=            Only supports admin for now.
 158 OS_KEYSTONE=               Use KEYSTONE_V3 for now.
 159 OOM_BRANCH=                Branch of OOM to clone and use to install ONAP.
 160 CHART_VERSION=             Version of charts to use for ONAP install. This is needed in case multiple versions of the onap helm charts are present on the machine being used for the install.
 161 OOM_OVERRIDES=             Command line overrides to use when running helm deploy. --set <override value>, etc...
 162 DOCKER_REPOSITORY=         Image repository url to pull ONAP images to use for installation.
 163
 164 ```
 165
 166 ### Integration Override
 167
 168 When you execute ``cloud.sh``, you have the option to create an ``integration-override.yaml`` file that will be used during ``helm deploy ...`` to install ONAP. This is done by passing the ``--override`` flag to cloud.sh.
 169
 170 The template used to create the override file is ``./util/integration-override.template``, and is invoked by ``./util/create_robot_config.sh``. It's very possible this isn't complete or sufficient for how you'd like to customize your deployment. You can update the template file and/or the script to provide additional customization for your ONAP install.
 171
 172
 173 ### OOM Overrides
 174
 175 In ``cloud.conf``, there's a parameter ``OOM_OVERRIDES`` available that's used to provide command line overrides to ``helm deploy``. This uses the standard helm syntax, so if you're using it the value should look like ``OOM_OVERRIDES="--set vid.enabled=false,so.image=abc"``. If you don't want to override anything, just set this value to an empty string.
 176
 177
 178 ### Pre Install
 179
 180 When you run ``cloud.sh`` it will execute ``pre_install.sh`` first, which checks a few things:
 181
 182 - It checks you have the correct pre-reqs installed. So, it'll make sure you have kubectl, azure cli, helm, etc...
 183 - It checks that the version of kubernetes in ``cloud.conf`` is available in Azure.
 184 - It checks the version of azure cli is >= to the baselined version (you can check this version by looking at the top of ``pre_install.sh``). The Azure cli is introduced changes in minor versions that aren't backwards compatible.
 185 - It checks that the version of kubectl installed is at **MOST** 1 minor version different than the version of kubernetes in ``cloud.conf``.
 186
 187 If you would like to skip ``pre_install.sh`` and run the deployment anyways, pass the flag ``--no-validate`` to ``cloud.sh``, like this:
 188
 189 ```
 190 $ ./cloud.sh --no-validate
 191
 192 ```
 193
 194
 195 ### Post Install
 196
 197 After ONAP is deployed, you have the option of executing an arbitrary set of post-install scripts. This is enabled by passing the ``--post-install`` flag to ``cloud.sh``, like this:
 198
 199 ```
 200 $ ./cloud.sh --post-install
 201
 202 ```
 203
 204 These post-install scripts need to be executable from the command line, and will be provided two parameters that they can use to perform their function:
 205
 206 - /path/to/onap.conf : This is created during the deployment, and has various ONAP and OpenStack parameters.
 207 - /path/to/cloud.conf : this is the same ``cloud.conf`` that's used during the original deployment.
 208
 209
 210 Your post-install scripts can disregard these parameters, or source them and use the parameters as-needed.
 211
 212 Included with this repo is one post-install script (``000_bootstrap_onap.sh``)that bootstraps AAI, VID, and SO with cloud and customer details so that ONAP is ready to model and instantiate a VNF.
 213
 214 In order to include other custom post-install scripts, simply put them in the ``post-install`` directory, and make sure to set its mode to executable. They are executed in alphabetical order.
 215
 216
 217 ## Post Deployment
 218
 219 After ONAP and DevStack are deployed, there will be a ``deployment.notes`` file with instructions on how to access the various components. The ``BUILD_DIR`` specified in ``cloud.conf`` will contain a new ssh key, kubeconfig, and other deployment artifacts as well.
 220
 221 All of the access information below will be in ``deployment.notes``.
 222
 223
 224 ### Kubernetes Access
 225
 226 To access the Kubernetes dashboard:
 227
 228 ``az aks browse --resource-group $AKS_RESOURCE_GROUP_NAME --name $AKS_NAME``
 229
 230 To use kubectl:
 231 ```
 232
 233 export KUBECONFIG=$BUILD_DIR/kubeconfig
 234 kubectl ...
 235
 236 ```
 237
 238 ### Devstack Access
 239
 240 To access Horizon:
 241
 242 Find the public IP address via the Azure portal, and go to
 243 ``http://$DEVSTACK_PUBLIC_IP``
 244
 245 SSH access to DevStack node:
 246
 247 ``ssh -i $BUILD_DIR/id_rsa ${DEVSTACK_ADMIN_USER}@${DEVSTACK_PUBLIC_IP}``
 248
 249 OpenStack cli access:
 250
 251 There's an openstack cli pod that's created in the default kubernetes default namespace. To use it, run:
 252
 253 ``kubectl exec $OPENSTACK_CLI_POD -- sh -lc "<openstack command>"``
 254
 255
 256 ### NFS Access
 257
 258 ``ssh -i $BUILD_DIR/id_rsa ${NFS_ADMIN_USER}@${NFS_PUBLIC_IP}``
 259
 260
 261 ## Deleting the deployment
 262
 263 After deployment, there will be a script named ``$BUILD_DIR/clean.sh`` that can be used to delete the resource groups that were created during deployment. This script is not required; you can always just navigate to the Azure portal to delete the resource groups manually.
 264
 265
 266 ## Running the scripts separately
 267
 268 Below are instructions for how to create DevStack, NFS, or AKS cluster separately if you don't want to create everything all at once.
 269
 270 **NOTE: The configuration to link components together (network peering, route table modification, NFS setup, etc...) and the onap-bootstrap will not occur if you run the scripts separately**
 271
 272
 273 ### DevStack creation
 274
 275 ```
 276
 277 $ ./create_devstack.sh --help
 278 ./create_devstack.sh [options]
 279
 280
 281 required:
 282 --public-key                public key to add for admin user [required]
 283 --user-public-ip            public ip that will be granted access to VM [required]
 284 -l, --location              location to deploy VM [required]
 285 -u, --admin-user            admin user to create on VM [required]
 286
 287 additional options:
 288 -f, --no-prompt             executes with no prompt for confirmation
 289 -h, --help                  provide brief overview of script
 290 -n, --name                  VM name [optional]
 291 -g, --resource-group        provide brief overview of script [optional]
 292 -s, --size                  Azure flavor size for VM [optional]
 293 -c, --cidr                  cidr for VNET to create for VM [optional]. If provided, must also provide --devstack-private-ip from same range.
 294 -d, --directory             directory to store cloud config data [optional]
 295 --vnet-name                 name of Vnet to create for VM [optional]
 296 --image-list                space delimited list of image urls that will be added to devstack [optional]
 297 --devstack-private-ip       private ip assigned to VM [optional]. If provided, this value must come from the CIDR range of VNET.
 298 --devstack-subnet-name      subnet name created on VNET [optional]
 299 --devstack-disk-size        size of OS disk to be allocated [optional]
 300 --openstack-username        default user name for openstack [optional]
 301 --openstack-password        default password for openstack [optional]
 302 --openstack-tenant          default tenant name for openstack [optional]
 303
 304 ```
 305
 306
 307 ### NFS Creation
 308
 309 ```
 310
 311 $ ./create_nfs.sh --help
 312 ./create_nfs.sh [options]
 313
 314
 315 required:
 316 --public-key                public key to add for admin user [required]
 317 --user-public-ip            public ip that will be granted access to VM [required]
 318 -l, --location              location to deploy VM [required]
 319 -u, --admin-user            admin user to create on VM [required]
 320 --aks-node-cidr             CIDR for Kubernetes nodes [required]. This is used during the NFS deploy to grant access to the NFS server from Kubernetes.
 321
 322 additional options:
 323 -f, --no-prompt             executes with no prompt for confirmation
 324 -h, --help                  provide brief overview of script
 325 -n, --name                  VM name [optional]
 326 -g, --resource-group        resource group that will be created [optional]
 327 -s, --size                  Azure flavor size for VM [optional]
 328 -c, --cidr                  cidr for VNET to create for VM [optional].
 329 -d, --directory             directory to store cloud config data [optional]
 330 --vnet-name                 name of Vnet to create for VM [optional]
 331 --nfs-subnet-name           subnet name created on VNET [optional]
 332 --nfs-disk-size             size of external disk to be mounted on NFS VM [optional]
 333
 334 ```
 335
 336
 337 ### AKS Creation
 338
 339 ```
 340
 341 $ ./create_aks.sh --help
 342 ./create_aks.sh [options]
 343
 344
 345 required:
 346 --user-public-ip            public ip that will be granted access to AKS [required]
 347 --admin-user                admin user created on AKS nodes [required]
 348 --public-key                public key added for admin user [required]
 349 -l, --location              location to deploy AKS [required]
 350
 351 additional options:
 352 -f, --no-prompt             executes with no prompt for confirmation
 353 -h, --help                  provide brief overview of script
 354 -n, --name                  AKS name [optional]
 355 -g, --resource-group        name of resource group that will be created [optional]
 356 -s, --size                  azure flavor size for Kube nodes [optional]
 357 -v, --kube-version          version of Kubernetes for cluster [optional]
 358 -c, --node-count            number of nodes for cluster [optional]
 359 --service-cidr              cidr for Kuberenetes services [optional].
 360 --dns-ip                    IP for Kuberenetes dns service [optional]. This should be from --service-cidr.
 361 --pod-cidr                  cidr for Kuberenetes pods [optional].
 362 --node-cidr                 cidr for Kuberenetes nodes [optional].
 363 --vnet-name                 name of Vnet to create for Kubernetes Cluster [optional]
 364
 365 ```