Install with new cluster

Note: An environment administrator performs the steps on this page. See Plan Installation > Roles for the overview of the roles involved.

Prepare to run Terraform to create a new cluster and install the Developer Tools

The environment is installed by an environment administrator, who will run the scripts to create the environment in an IBM Cloud account. The scripts will run as the environment administrator’s user, so the user needs the permissions described in Plan Installation. These instructions explain how to configure and run the Terraform infrastructure-as-code (IasC) scripts to create the environment.

Prepare local system

To run the scripts, install the client tools needed to use the environment:

Install the Prerequisites

Optional: The environment administrator must be able to log into IBM Cloud, specifying the account, region, and resource group. That is effectively what the scripts will do when they run, using the environment administrator’s API key.

ibmcloud login -a cloud.ibm.com -r <region> -g <resource-group>

Confirm resources

Optional: To help confirm that the account has the resources the scripts will require (see Plan Installation), the environment administrator may log into the account view the resources:

Existing VLANs — Verify that the two VLANs specified are in the list and that they are defined in the proper data center
Existing resource groups — Having logged in using the environment’s resource group, it should certainly be in the list
Existing Kubernetes clusters — See what clusters (Kubernetes and OpenShift) already exist in the resource group and confirm one does not already exist for the environment you want to create

Confirm permissions

Optional: To help confirm that the scripts will have the permissions they’ll require (see the administrators access group in Plan Installation), the environment administrator may log into the account and test creating a couple of resources:

Create a cluster — Make it single-zone, and specify the proper data center and resource group
Create a namespace in the image registry
Create an instance of Cloudant — Select a paid plan and specify the proper region and resource group
Create an instance of Sysdig — Select a paid plan and specify the proper region and resource group

As long as the user can create these resources successfully, the scripts should be able to as well. You may delete these test resources.

Obtain the Terraform infrastructure-as-code (IasC) scripts that will create the tools environment

Clone the ibm-garage-iteration-zero Git repository to your local filesystem

git clone git@github.com:cloud-native-toolkit/ibm-garage-iteration-zero.git

Switch to the cloned directory

cd ibm-garage-iteration-zero

Configure the keys the CLI uses to authenticate

A Kubernetes or OpenShift cluster is a PaaS resource hosted on top IaaS resources. API keys authenticate an IBM Cloud CLI client—such as a Terraform script—to create these resources programmatically. Two keys will be needed:

The first key authorizes creating Classic Infrastructure (IaaS) resources
The second key authorizes creating IBM Cloud (PaaS) resources

The following steps create the required keys and put them into a file called credentials.properties.

The credentials.properties property file looks like this:

classic.username=<CLASSIC_USERNAME>
classic.api.key=<CLASSIC_API_KEY>
ibmcloud.api.key=<IBMCLOUD_API_KEY>

The installation scripts will use these keys to authenticate to IBM Cloud.

Step A. Create the credentials.properties file

Inside the iteration-zero-ibmcloud folder, copy credentials.template to a file named credentials.properties.

cd iteration-zero-ibmcloud
cp credentials.template credentials.properties

The credentials.properties file is already listed in the .gitignore file so that the file containing your private API keys will not be pushed to the server repository.

Step B. Set the Classic infrastructure API key

Follow these instructions to create a Classic infrastructure API key:
- In the IBM Cloud console, go to the IBM Cloud API Keys page
  To open the IBM Cloud API Keys page, select Manage -> Access (IAM), then select the IBM Cloud API keys tab.
- If your account already has a classic infrastructure API key, it will appear in the list of keys as Classic infrastructure API key. Otherwise, the page will have a Create a classic infrastructure API key button on the top. To crate the key, press that button and close the dialog.
- Find Classic infrastructure API key in the list and open its details.
Edit the credentials.properties file to set the values for the classic.username and classic.api.key properties.

Step C. Set the IBM Cloud API key

Follow these instructions to create an IBM Cloud API key:
- Managing user API keys
Edit the credentials.properties file to set the value for the ibmcloud.api.key property.

Configure the properties describing your environment

Configuring Properties files

The settings for creating the environment go in two properties files in the ./terraform/settings directory:

environment.tfvars — Properties for installing the environment
vlan.tfvars — Properties for creating the cluster

The next few steps will find the necessary resources and set them in the tfvars files. Along the way, if any of these resources don’t already exist, you’ll need to create them. There is a tool for optionally generating the VLAN variables.

Environment variables

The environment.tfvars properties will be used to install the Development Tools environment.

Typical values look like this:

# The type of cluster that will be created/used (kubernetes or openshift)
cluster_type="openshift"
# Flag indicating if we are using an existing cluster or creating a new one
cluster_exists="true"
# The prefix that should be applied to the cluster name and service names (if not provided
# explicitly). If not provided then the resource_group_name will be used as the prefix.
#name_prefix="<name prefix for cluster and services>"
#name_prefix="garage-cloud-surge"

Some of these values are given to you by the account manager:

resource_group_name — The resource group the cluster and environment will be created in
vlan_region — The region the cluster and environment will be created in

The other variables have reasonable defaults that you can change if desired:

Set cluster_name to specify any valid cluster name that is not already in use or leave unset
Set cluster_type to specify whether the cluster is kubernetes or openshift
cluster_exists — Set to false to create a new cluster
cluster_type — Specify the new cluster’s type
- kubernetes — Kubernetes
- openshift — OpenShift v3
- ocp3 — OpenShift v3
- ocp4 — OpenShift v4
- crc — CodeReady Containers
cluster_name — The name for the new cluster
registry_namespace — The namespace that will be created with the IBM Container Registry. If not provided the value will default to the resource_group_name
logdna_exists — “true” or “false” flag indicating that the logdna instance already exists and a new one should not be provisioned
logdna_name — The name of the logdna instance, particularly if one already exists. If not provided the name will be generated as {prefix-name || resource-group-name}-logdna
sysdig_exists — “true” or “false” flag indicating that the sysdig instance already exists and a new one should not be provisioned
sysdig_name — The name of the sysdig instance, particularly if one already exists. If not provided the name will be generated as {prefix-name || resource-group-name}-sysdig

VLANs

The vlan.tfvars properties will be used to create the cluster that the Developer Tools will be installed into.

Typical values look like this:

vlan_region="us-south"
vlan_datacenter="dal10"
public_vlan_id="2366011"
private_vlan_id="2366012"

You must set all of these specifically for your cluster. Use the values provided by the account manager.

In vlan.tfvars, set the following properties:
- vlan_region — The region that the cluster will be in
- vlan_datacenter — The zone in that region that the cluster will be in
- public_vlan_id — The public VLAN that the cluster will use
- private_vlan_id — The private VLAN that the cluster will use

Optional: Generate the properties

The IGC CLI can be used to generate these settings, to make the configuration as simple as possible.

If your account has numerous VLANs and you want your Developer Tools cluster to use specific ones, then skip this step. This tool is for users who don’t know what these required settings should be and want a simple way to gather reasonable defaults for their particular account.

The IGC CLI has a command to gather this information for you, in a format that is easy to cut/paste into the vlan.tfvars properties file.

Install the IGC CLI
Log in to IBM Cloud using its CLI

Run the VLAN command

igc vlan

Copy the output values from the CLI Command into your vlan.tfvars files and Save and continue

Run the scripts that create the environment

Having configured the credentials.properties, environment.tfvars, and vlan.tfvars properties files, we are now ready to kick off the installation.

Launch a Developer Tools Docker container.
Run the following command to run the Docker container:
```
./launch.sh
```
This will install the Cloud Garage Tools Docker image and exec shell into the running container. The container will mount the filesystem’s ./terraform/ directory as /home/devops/src/. Once the Docker container has started and the script has exec shelled into it, you will see an IBM Garage banner. This will help you identify you are running inside the Docker image that has just mounted your file system.
For more information on the Developer Tools Image see the following guide link below.
Create the environment
The supplied Terraform script is ready to run using the settings in the properties files. You optionally can extend or modify the scripts and tailor them for your project’s specific needs.
Run this script in the container:
```
./runTerraform.sh
```
This script will create the environment.
If you executed the script previously for the current cluster configuration and the workspace directory still exists then you will be prompted to either keep or delete the workspace directory. Keep the workspace directory if you want to use the state from the previous run as a starting point to either add or remove configuration. Delete the workspace if you want to start with a clean install of the Toolkit.
The script will verify some basic settings and prompt if you want to proceed. After you select Y (for yes), the Terraform Apply process will begin to create the infrastructure and services for your environment.
Both of the prompts can be skipped via command-line arguments passed to the script. To bypass the workspace prompt, provided either --delete or --keep to either delete or keep the workspace, respectively. To bypass the verification prompt provide --auto-approve and the script will automatically answer Yes to the prompt and start the terraform process.
Creating a new cluster takes about 1.5 hours on average (but can also take considerably longer) and the rest of the process takes about 30 minutes.
You should now have your environment fully provisioned and configured. Enjoy!

environment

Once the Terraform scripts have finished, you can see the resources that the scripts created in IBM Cloud:

In the IBM Cloud console, open the Resource List
On the Resource List page, filter by your Resource Group (e.g. appdev-team)
You should see these resources listed:
- Clusters: 1, either Kubernetes or OpenShift
- Services: 5 or so, such as PostgreSQL, LogDNA, etc.
- Storage: 1, an instance of Cloud Object Storage
Select the cluster and open the Kubernetes dashboard or OpenShift web console. You should see:
- Namespaces: tools, dev, test, and staging
- Deployments in the tools namespace: developer-dashboard, jenkins, etc.

To get started with code use the following guides:

Possible issues

If you find that that the Terraform provisioning has failed, try re-running the runTerraform.sh script again. The state will be saved and Terraform will try and apply the configuration to match the desired end state.

If you find that some of the services have failed to create in the time allocated, you can try this:

Manually delete the service instances in your resource group
Delete the workspace directory (which will remove any state that has been created by Terraform)

Re-run the runTerraform.sh script

rm -rf workspace
./runTerraform.sh

Edit this page on GitHub