Installation steps

Check requirements

Supported OpenStack versions

Required services with API access

Additional requirements

  • OpenStack project with appropriate quotas
  • An external network with a subnet, that can assign floating IPs
  • Version control system (Git-based)
  • DNS service to register Cloudboostr domains and routes

Computational and network resources and quoates are listed on this page.

Additonaly make sure that you have an admin access account that can be used to create, update and remove resources in OpenStack project. If there is no project created beforehand, make sure the account you use have privilages to create the project.

Prepare local environment

Install and configure OpenStack CLI (python and pip required):

pip install python-openstackclient
pip install python-swiftclient

Python installation

On Mac python can be installed using command brew install python. On Windows download latest installer from the Python official site https://www.python.org/.

Install tools (macOS)

The only mandatory tools are terraform CLI and git client. In most cases git is already preinstalled. If you cannot find the instruction for the operating system you use on this page consult the official documentation.

Without homebrew

# Install terraform (https://www.terraform.io)
wget https://releases.hashicorp.com/terraform/0.11.10/terraform_0.11.10_darwin_amd64.zip
unzip terraform*
chmod +x terraform
sudo mv terraform /usr/bin/terraform

With homebrew

brew install terraform

Additional tools

Optionally install CF, BOSH and Kubernetes CLI:

brew install bosh-cli
brew tap cloudfoundry/tap
brew install kubernetes-cli

Note

Homebrew was used to install some of the tools on macOS: https://brew.sh/. All binaries can be also downloaded and placed in the /usr/bin folder if Homebrew is not available.

Install tools (Windows)

  1. Download binaries for Terraform.

https://www.terraform.io/downloads.html

  1. Place terraform binary in directory available from Path.

  2. Download and install GIT for Windows if

https://git-scm.com/download/win

Hint

GIT Bash available with Git for Windows installation has better support for unix tools than regular Windows command line.

OpenStack CLIs configuraion

OpenStack tools are configured using environment variables. Depending on the installation and configuration not all the fields are required. Fields listed in the snippet below are most commonly required.

Clean configuration:

export OS_USERNAME=
export OS_PASSWORD=
export OS_AUTH_URL=
export OS_USER_DOMAIN_NAME=
export OS_PROJECT_DOMAIN_NAME=
export OS_REGION_NAME=
export OS_PROJECT_NAME=
export OS_TENANT_NAME=
export OS_AUTH_VERSION=3
export OS_IDENTITY_API_VERSION=3

OpenStack environment variables

Comprehensive list of OpenStack client environment variables is available in the official documentation: https://docs.openstack.org/python-openstackclient/pike/cli/man/openstack.html.

Create a project for the deployment

If you don't have yet a project for the deployment you should start with configuring it. The minimal quotas are listed on this page.

Create domain:

openstack domain create --description "OpsControl" opscontrol

Create project (tenant):

openstack project create --domain default --description “Cloudboostr” cloudboostr

Create admin user:

openstack user create --domain default --password-prompt admin

Note

If you are not sure if project already exist consult the infrastructure team. Projects configuration require admin privileges.

Prepare repository

git clone https://grape-up@dev.azure.com/grape-up/cloudboostr/_git/cb-opscontrol
make update_git
maka pull_latest_submodules

Navigate to cb-opscontrol/terraform.

Create container

openstack container create sensitive-data

Output example:

+---------------------------------------+----------------+--------------------------------------------------+
| account                               | container      | x-trans-id                                       |
+---------------------------------------+----------------+--------------------------------------------------+
| AUTH_e9979cc0a89e40acbcf0219ca14f5107 | sensitive-data | tx000000000000000005866-005beaaa53-e4df9-default |
+---------------------------------------+----------------+--------------------------------------------------+

Prepare SSH keys

First step is to prepare SSH keys that will be used for jumpbox and bosh connection. Also GIT key is required for terraform and scripts to download the required repositories.

If SSH keys were prepared before hand or are being created by external tool like Vault skip this and go to the next step.

# Create SSH keys

export EMAIL=[YOUR_EMAIL_HERE]
mkdir keys
ssh-keygen -t rsa -b 4096 -C "$EMAIL" -f ./keys/jumpbox_devops -N '' -m pem
ssh-keygen -t rsa -b 4096 -C "$EMAIL" -f ./keys/bosh_devops -N '' -m pem
ssh-keygen -t rsa -b 4096 -C "$EMAIL" -f ./keys/git_private_key -N '' -m pem

Upload keys

Then keys should be uploaded to the sensitive-data container. Filenames and container name can be changed in configuration if required.

swift upload sensitive-data ./keys/bosh_devops --object-name bosh_devops
swift upload sensitive-data ./keys/bosh_devops.pub --object-name bosh_devops.pub
swift upload sensitive-data ./keys/jumpbox_devops --object-name jumpbox_devops
swift upload sensitive-data ./keys/jumpbox_devops.pub --object-name jumpbox_devops.pub
swift upload sensitive-data ./keys/git_private_key --object-name git_private_key
swift upload sensitive-data ./keys/git_private_key.pub --object-name git_private_key.pub

Output for the command is the name of the object created in the container.

Configure DNS IP address

Create elastic (floating) IP address for dns server deployed within Opscontrol openstack floating ip create ext-net

External network name

Please note ext-net is the name of external network and it can be different on different openstack deployments.

Configure terraform

Create file terraform.tfvars based on terraform.tfvars.example.

Fill the OpsControl configuration

At minimum update the required fields.

Example

### OPENSTACK PROVIDER ####################################################
# Authorization URL for OpenStack    [REQUIRED]
auth_url = "<STRIPPED>"

# Username for the OpenStack account [REQUIRED]
user_name = "<STRIPPED>"

# Password for the OpenStack acconut [REQUIRED]
password = "<STRIPPED>"

# Project name (tenant name)         [REQUIRED]
tenant_name = "<STRIPPED>"

# Project id (tenant id)             [REQUIRED]
tenant_id = "<STRIPPED>"

# OpenStack domain name              [REQUIRED]
domain_name = "<STRIPPED>"

### NETWORK #############################################################
# Network region
region = "Kna1"

storage_region = "Kna1"

### SECURITY GROUPS #####################################################
# IP address or range allowed to access Jumpbox 
jumpbox_whitelist = ["0.0.0.0/0"]

### DNS #################################################################
# DNS domain for externaly accessible services   [REQUIRED]
opscontrol_base_domain = "devops.adko.rnd.grapeup.com"

# Floating IP created manually for the DNS       [REQUIRED]
dns_instance_public_ip = "188.212.108.75"

# Network name for the DNS Floating IP           [REQUIRED]
ext_net_name = "ext-net"

# BOSH Director VM size (openstack flavor list)  [REQUIRED]
bosh_flavor_name = "2C-4GB"

bosh_vm_az = "nova"

cloud_config_azs = ["nova", "nova", "nova"]

jumpbox_flavor_name = "1C-0.5GB"
jumpbox_image_name = "Ubuntu 16.04 Xenial Xerus"

# GIT repository address for the config files    [REQUIRED]
config_repository_url = "git@ssh.dev.azure.com:v3/grape-up/cloudboostr/cb-config"

# GIT repository branch for the config files     [REQUIRED]
config_repository_branch = "cb"

Configure environments

Configure environments for your purposes. To use default configuration clone the cb-config repository and change mandatory fields for infrastructure, Kubernetes, Cloud Foundry and common for all components.

Address and branch of that repository should be correctly filled in the "Fill the OpsControl configuration" step. Also git private key in sensitive-data container must work for that repository.

Run terraform

Start the deployment operation in directory "terraform" in the opscontrol repository:

terraform init
terraform apply

Terraform backend

Terraform can be configured to use external backend instead of local files. To use that feature follow the guide in the official documentation.

The process of deployment may take from 30 minutes to two hours depending on the underlying infrastructure. If the error occurs there is an error message like:

module.custom_scripts.null_resource.deploy_dns (remote-exec): Task 31904 | 12:51:59 | Preparing deployment: Preparing deployment
module.custom_scripts.null_resource.deploy_dns (remote-exec):  (00:00:00)
module.custom_scripts.null_resource.deploy_dns (remote-exec):                      L Error: Instance group 'opscontrol-dns-master' references an unknown network 'dmz'
module.custom_scripts.null_resource.deploy_dns (remote-exec): Task 31904 | 12:51:59 | Error: Instance group 'opscontrol-dns-master' references an unknown network 'dmz'


Error: Error applying plan:

1 error(s) occurred:

* module.custom_scripts.null_resource.deploy_dns: error executing "/tmp/terraform_1281010007.sh": Process exited with status 1

The description of the error is in most cases enough to find out which configuration is wrong. After fixing the problem you can re-run the terraform apply and it will continue from where it finished.

After successfull deployment there will be an information message with the password to the concourse. Next step is the environment deployment.