From 39146720fd6df40fd85db8edc3e36b36e5bead5d Mon Sep 17 00:00:00 2001 From: Charshy Date: Mon, 19 Dec 2016 14:14:29 +0000 Subject: [PATCH 1/2] Create setup_bluemix.md --- 1-Demo/setup_bluemix.md | 135 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 1-Demo/setup_bluemix.md diff --git a/1-Demo/setup_bluemix.md b/1-Demo/setup_bluemix.md new file mode 100644 index 0000000..ce14309 --- /dev/null +++ b/1-Demo/setup_bluemix.md @@ -0,0 +1,135 @@ +--- +layout: page +title: Setup Amalgam8 for Bluemix +permalink: /docs/demo-setup_bluemix.html +redirect_from: +category: Demo +order: 1 +--- + +## Before you begin + +Install the [Bluemix CLI](http://clis.ng.bluemix.net/ui/home.html) version 0.4.1 + or later with the IBM-Containers plugin 0.5.800 or later. + +## Setting up the Control Plane + +The Amalgam8 Control Plane consists of two components: the +[service registry](/docs/control-plane-registry.html) and the +[route controller](/docs/control-plane-controller.html). In addition to these two +components, for the purposes of this demo, a stock ELK stack is also +included as part of the control plane deployment scripts, to collect logs +from the microservices in the application. + +The Amalgam8 Control Plane contains an ELK stack. +Elasticsearch 5.0 [requires increasing the max map count](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html) +for certain linux environments such as Vagrant VMs, Docker Toolbox and Minikube. +If you are running any of these tools, please run the following command on those VMs: + +``` +bash +sudo sysctl -w vm.max_map_count=262144 +``` + +**Note:** You can ssh into the minikube virtual machine by running `minikube ssh` + +1. Login to Bluemix and initialize the container environment by running: + + ``` + bluemix login + bluemix ic init + ``` + +1. Create Bluemix routes (DNS names) for the registry, controller and the bookinfo app's gateway: + + ``` + bash + bluemix cf create-route mybluemix.net -n + bluemix cf create-route mybluemix.net -n + ``` + + where `` is the name of your Bluemix space and + `` is a unique route name for `registry` and + `controller`. For example `my-space-name-a8-registry` and + `my-space-name-a8-controller`. Make a note of the route names you + choose for the next step. + +1. Customize the _examples/bluemix.cfg_ in the downloaded folder as follows: + * BLUEMIX_REGISTRY_NAMESPACE should be your Bluemix registry namespace + obtained from the folowing command: + + ``` + bash + bluemix ic namespace-get + ``` + + * REGISTRY_HOSTNAME should be the route name assigned to the registry in the previous step + + * CONTROLLER_HOSTNAME should be the route name assigned to the controller in the previous step + +1. Deploy the control plane services (registry and controller) on bluemix. + + ``` + bash + examples/a8-bluemix create controlplane + ``` + + Verify that the controller and registry are running using the following commands: + + ``` + bash + bluemix ic groups + ``` + + You should see the groups `amalgam8_controller` and `amalgam8_registry` listed in the output. + +## Setting up the Amalgam8 CLI + +The `a8ctl` command line utility provides a convenient way to setup and +manage routes across microservices as well as inspect the state of the +system. The CLI can be installed via the `pip` tool (available as part of +standard Python installation) directly from Python's package repository or +from `a8ctl` [github repository](https://github.com/amalgam8/a8ctl). + +1. Run the folowing command to install the a8ctl into your home directory: + + ``` + bash + pip install --user a8ctl + ``` + +1. Add the location of the `a8ctl` command to the `PATH` environment +variable. On OS X, run: + +``` +bash +export PATH=$PATH:${HOME}/Library/Python/2.7/bin +``` + +On Linux, run: + +``` +bash +export PATH=$PATH:${HOME}/.local/bin +``` + +To use the Amalgam8 CLI (`a8ctl`) for the demo walkthroughs we need +to setup two environment variables: `A8_CONTROLLER_URL` and +`A8_REGISTRY_URL`. These variables should point to the publicly accessible +REST endpoints exposed by the Amalgam8 controller and registry respectively. + +The value of these variables depends on the environment where you setup the +control plane. + +1. Run the following commands: + +``` +bash +export A8_CONTROLLER_URL=http://.mybluemix.net +export A8_REGISTRY_URL=http://.mybluemix.net +``` + +where `` and `` correspond to the routes +that you set for the controller and registry respectively. + +Now that you've configured Amalgam8 for IBM Bluemix, let's move onto running the demo. From 6217f577d83f217bf0843e2798c2c2e70e139cd8 Mon Sep 17 00:00:00 2001 From: Charshy Date: Wed, 4 Jan 2017 12:03:23 +0000 Subject: [PATCH 2/2] Updated to include Bluemix structure and content - Updated to reflect Bluemix user persona (Bluemix content) - Formatted environment variables as a table - Added section links - Removed script file instructions to prevent mixing and confusion: let's put the script instructions with the script. --- 1-Demo/setup_bluemix.md | 179 +++++++++++++++++++++++++--------------- 1 file changed, 112 insertions(+), 67 deletions(-) diff --git a/1-Demo/setup_bluemix.md b/1-Demo/setup_bluemix.md index ce14309..76f9e1e 100644 --- a/1-Demo/setup_bluemix.md +++ b/1-Demo/setup_bluemix.md @@ -9,8 +9,46 @@ order: 1 ## Before you begin -Install the [Bluemix CLI](http://clis.ng.bluemix.net/ui/home.html) version 0.4.1 - or later with the IBM-Containers plugin 0.5.800 or later. +Amalgam8 on Bluemix uses the IBM Bluemix Container Service, which requires the Cloud Foundry (cf) and Bluemix (bluemix) plugins. If these are not already installed, then follow these steps. + +1. Install the Cloud Foundry (cf) plug-in. + + a) Download the latest version of the plug-in from the following GitHub repo: http://github.com/cloudfoundry/cli/releases + b) Follow the instructions that are available in http://docs.cloudfoundry.org/cf-cli/install-go-cli.html#linux to install the CF plug-in. + +2. Install the Bluemix (bluemix) plug-in. + + a) Download the latest version of the plug-in from http://plugins.ng.bluemix.net/ui/home.html. + b) Extract the file. + c) Change to the directory `Bluemix_CLI` and install the plug-in. Run the following command as `root`: `./install_bluemix_cli` + + For example, on Ubuntu, the following code installs the Bluemix plugin: + + ``` + # Run the install command as root + root@bluemix:~# tar -xvf Bluemix_CLI_0.4.2_amd64.tar.gz + Bluemix_CLI/ + Bluemix_CLI/bx/ + Bluemix_CLI/bx/zsh_autocomplete + Bluemix_CLI/bx/bash_autocomplete + Bluemix_CLI/bin/ + Bluemix_CLI/bin/bluemix + Bluemix_CLI/bin/NOTICE + Bluemix_CLI/bin/LICENSE + Bluemix_CLI/bin/bluemix-analytics + Bluemix_CLI/install_bluemix_cli + + # Change directory + #root@bluemix:~# cd Bluemix_CLI + + # Install the Bluemix CLI + root@bluemix:~/Bluemix_CLI# ./install_bluemix_cli + The Cloud Foundry CLI version 6.22 is already installed. + Copying files ... + The Bluemix Command Line Interface (Bluemix CLI) is installed successfully. + To get started, open a new Linux terminal and enter "bluemix help", or enter "bx help" as short name. + ``` + ## Setting up the Control Plane @@ -24,66 +62,74 @@ from the microservices in the application. The Amalgam8 Control Plane contains an ELK stack. Elasticsearch 5.0 [requires increasing the max map count](https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html) for certain linux environments such as Vagrant VMs, Docker Toolbox and Minikube. -If you are running any of these tools, please run the following command on those VMs: +If you are running any of these tools, run the following command on those VMs: ``` bash sudo sysctl -w vm.max_map_count=262144 ``` -**Note:** You can ssh into the minikube virtual machine by running `minikube ssh` +To deploy the control plane in the IBM Bluemix Container Service, complete the following steps. -1. Login to Bluemix and initialize the container environment by running: +1. Log in to the Bluemix org and space in which you want to deploy the Amalgam8 control plane, and add the IBM Bluemix Container Service plugin by running the following command: - ``` - bluemix login - bluemix ic init - ``` + ``` + bluemix login + bluemix plugin repo-add Bluemix https://plugins.ng.bluemix.net + bluemix plugin install IBM-Containers -r Bluemix + ``` -1. Create Bluemix routes (DNS names) for the registry, controller and the bookinfo app's gateway: + You can verify the installation by running ``bluemix plugin list``. The command return resembles the following output: - ``` - bash - bluemix cf create-route mybluemix.net -n - bluemix cf create-route mybluemix.net -n - ``` + ``` + Listing installed plug-ins... + Plugin Name Version + IBM-Containers 1.0.0 + ``` - where `` is the name of your Bluemix space and - `` is a unique route name for `registry` and - `controller`. For example `my-space-name-a8-registry` and - `my-space-name-a8-controller`. Make a note of the route names you - choose for the next step. +2. Start the IBM Bluemix Container Service in the space in which you want to deploy the Amalgam8 control plane by running the following command: -1. Customize the _examples/bluemix.cfg_ in the downloaded folder as follows: - * BLUEMIX_REGISTRY_NAMESPACE should be your Bluemix registry namespace - obtained from the folowing command: + ``` + bluemix ic init + ``` - ``` - bash - bluemix ic namespace-get - ``` + If you are requested to enter a namespace value, be aware that this value is set once for an organization and after it is created it cannot be changed. You might want to check with your organization's administrator before you proceed. Refer to the [IBM Bluemix Container Service](https://console.bluemix.net/docs/containers/container_index.html) documentation for more information. - * REGISTRY_HOSTNAME should be the route name assigned to the registry in the previous step + For the purposes of running the Amalgam8 demos, you can customize the downloaded _examples/bluemix.cfg_ file to set your environment variables, and then run the a8-bluemix script. After you run the script, skip to [Setting up the Amalgam8 CLI](#a8cli). To learn how to set your environment variables by using the Bluemix CLI, continue following the steps. - * CONTROLLER_HOSTNAME should be the route name assigned to the controller in the previous step +3. Collect the information that is required to set values for the Amalgam8 environment variables: -1. Deploy the control plane services (registry and controller) on bluemix. + | Command to set environment variable | What it is | Command to get the value | + |--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| + | ``` export ROUTES_DOMAIN=example.bluemix.net ``` | An available domain in your Bluemix org. In the command, replace `example.bluemix.net` with your chosen Bluemix domain. | ``` bluemix cf domains ``` | + | ``` export BLUEMIX_SPACE=example ``` | The space in your org that you want to deploy Amalgam8 to. In the command, replace `example` with the name of the space. | ``` bluemix cf target ``` | + | ``` export BLUEMIX_REGISTRY_NAMESPACE= example ``` | The namespace for your org. In the command, replace `example` with the namespace. | ``` bluemix ic namespace-get ``` | + | ``` export BLUEMIX_REGISTRY_HOST=registry.ng.bluemix.net ``` | The IBM Bluemix Container Service registry. The BLUEMIX_REGISTRY_HOST defaults to the container image registry that is associated with the region and organization that your are working on in Bluemix. For example, in US South the value is `registry.ng.bluemix.net`. | ``` bluemix ic info ``` | - ``` - bash - examples/a8-bluemix create controlplane - ``` - Verify that the controller and registry are running using the following commands: - ``` - bash - bluemix ic groups - ``` +4. Run the following commands to create the other required environment variables: + + ``` + export CONTROLLER_IMAGE=a8-controller:latest + export REGISTRY_IMAGE=a8-registry:latest + export DOCKERHUB_NAMESPACE=amalgam8 + ``` + + The Amalgam8 registry and controller components are deployed to the Bluemix space as container groups. Each container group must be assigned a route so that the components can be accessed. In the environment variables, the route defaults to the name of the Bluemix space that is appended with -a8-registry and -a8-controller. If you want to use different routes, change these environment variables: + + ``` + export REGISTRY_HOSTNAME=$BLUEMIX_SPACE-a8-registry + export CONTROLLER_HOSTNAME=$BLUEMIX_SPACE-a8-controller + export REGISTRY_URL=http://$REGISTRY_HOSTNAME.$ROUTES_DOMAIN + export CONTROLLER_URL=http://$CONTROLLER_HOSTNAME.$ROUTES_DOMAIN + ``` + +Your local system is set up for Amalgam8. Next, install the Amalgam8 CLI. - You should see the groups `amalgam8_controller` and `amalgam8_registry` listed in the output. -## Setting up the Amalgam8 CLI + +##Setting up the Amalgam8 CLI The `a8ctl` command line utility provides a convenient way to setup and manage routes across microservices as well as inspect the state of the @@ -91,45 +137,44 @@ system. The CLI can be installed via the `pip` tool (available as part of standard Python installation) directly from Python's package repository or from `a8ctl` [github repository](https://github.com/amalgam8/a8ctl). -1. Run the folowing command to install the a8ctl into your home directory: + +1. Run the following command to install the a8ctl into your home directory: ``` bash pip install --user a8ctl ``` -1. Add the location of the `a8ctl` command to the `PATH` environment -variable. On OS X, run: +1. Add the location of the `a8ctl` command to the `PATH` environment variable. -``` -bash -export PATH=$PATH:${HOME}/Library/Python/2.7/bin -``` + * On OS X, run: -On Linux, run: + ``` + bash + export PATH=$PATH:${HOME}/Library/Python/2.7/bin + ``` -``` -bash -export PATH=$PATH:${HOME}/.local/bin -``` + * On Linux, run: -To use the Amalgam8 CLI (`a8ctl`) for the demo walkthroughs we need -to setup two environment variables: `A8_CONTROLLER_URL` and -`A8_REGISTRY_URL`. These variables should point to the publicly accessible -REST endpoints exposed by the Amalgam8 controller and registry respectively. + ``` + bash + export PATH=$PATH:${HOME}/.local/bin + ``` -The value of these variables depends on the environment where you setup the -control plane. + So that the a8ctl command can communicate with the Amalgam8 control plane, you must set the a8ctl command environment variables for the registry and controller components of the control plane. + You need to set up two environment variables: `A8_CONTROLLER_URL` and + `A8_REGISTRY_URL`. These variables should point to the publicly accessible + REST endpoints exposed by the Amalgam8 controller and registry respectively. -1. Run the following commands: + The value of these variables depends on the environment where you set up the + control plane. -``` -bash -export A8_CONTROLLER_URL=http://.mybluemix.net -export A8_REGISTRY_URL=http://.mybluemix.net -``` +1. Run the following commands: -where `` and `` correspond to the routes -that you set for the controller and registry respectively. + ``` + bash + export A8_CONTROLLER_URL=$CONTROLLER_URL + export A8_REGISTRY_URL=$REGISTRY_URL + ``` Now that you've configured Amalgam8 for IBM Bluemix, let's move onto running the demo.