Install into existing 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 install the Development Tools into an existing IBM Cloud managed cluster

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.

Note: The Terraform scripts will clean up the cluster to remove any existing resources that overlap with the resources provisioned by the scripts. You will need to remember to remove any IBM Cloud services that were previously created.

Use the helper script terraform/scripts/destroy-service.sh to help automate the deletion You can also run it to remove all the services beside PostgreSQL ./destroy-services.sh postgres

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 install the tools into your IBM Cloud managed cluster

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 key the CLI uses to create cloud services

The installation scripts need an API key to authenticate to IBM Cloud. The following steps create the required API key and put them into a properties file.

The credentials.properties property file looks like this:

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

Since the cluster already exists, we’ll only need to set the ibmcloud.api.key property.

Step A. Create the credentials.properties file

Inside the ibm-garage-iteration-zero folder, copy credentials.template to a file named credentials.properties.
```
cd ibm-garage-iteration-zero
cp credentials.template credentials.properties
```
The credentials.properties file is already listed in the .gitignore file so that the file containing your private API key will not be pushed to the server repository.

Step B. 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 the environment

The settings for installing the Developer Tools go in a single property file in the ./terraform/settings directory:

environment.tfvars — Properties for installing the Developer Tools

Follow the instructions below to set the existing cluster’s details in the environment.tfvars file.

Environment variables

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

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"

Set them based on the existing cluster:

resource_group_name — The existing cluster’s resource group
vlan_region — The existing cluster’s region
cluster_exists — Set to true for an existing cluster
cluster_type — Specify the existing cluster’s type
- kubernetes — Kubernetes
- openshift — OpenShift v3
- ocp3 — OpenShift v3
- ocp4 — OpenShift v4
- crc — CodeReady Containers
cluster_name — The existing cluster’s name
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

Note: The values for resource_group_name and cluster_name can be found on the Resource List page in the IBM Cloud Console - https://cloud.ibm.com/resources

Run the scripts that create the environment

Having configured the credentials.properties and environment.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.

Note: If you run this approach multiple times remember to delete any pre existing cloud services that were created previously

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.
Installing the tools into an existing cluster 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