You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openwhisk.apache.org by ra...@apache.org on 2020/09/16 13:08:46 UTC
[openwhisk] branch master updated: Update Ansible README.md [noci]
(#4976)
This is an automated email from the ASF dual-hosted git repository.
rabbah pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/openwhisk.git
The following commit(s) were added to refs/heads/master by this push:
new f788d09 Update Ansible README.md [noci] (#4976)
f788d09 is described below
commit f788d095565c14d3a2908cdf71215498a5512b36
Author: Travis DePrato <77...@users.noreply.github.com>
AuthorDate: Wed Sep 16 06:08:31 2020 -0700
Update Ansible README.md [noci] (#4976)
The use of `<environment>` instead of a variable really hurts the copy-paste-ability and makes it harder to follow along, so I replaced it with `$ENVIRONMENT` which is defined at the top of the file.
Also added languages to some of the code fences for highlighting.
---
ansible/README.md | 115 ++++++++++++++++++++++++++++--------------------------
1 file changed, 60 insertions(+), 55 deletions(-)
diff --git a/ansible/README.md b/ansible/README.md
index 5a685e6..d08b688 100644
--- a/ansible/README.md
+++ b/ansible/README.md
@@ -25,14 +25,14 @@ Deploying OpenWhisk using Ansible
If you want to deploy OpenWhisk locally using Ansible, you first need to install Ansible on your development environment:
#### Ubuntu users
-```
+```shell script
sudo apt-get install python-pip
sudo pip install ansible==2.5.2
sudo pip install jinja2==2.9.6
```
#### Docker for Mac users
-```
+```shell script
sudo easy_install pip
sudo pip install ansible==2.5.2
pip install jinja2==2.9.6
@@ -51,7 +51,7 @@ The OpenWhisk deployment via Ansible uses the `docker0` network interface to dep
An expedient workaround is to add alias for `docker0` network to loopback interface.
-```
+```shell script
sudo ifconfig lo0 alias 172.17.0.1/24
```
@@ -59,7 +59,12 @@ sudo ifconfig lo0 alias 172.17.0.1/24
**Caveat:** All Ansible commands are meant to be executed from the `ansible` directory.
This is important because that's where `ansible.cfg` is located which contains generic settings that are needed for the remaining steps.
-In all instructions, replace `<environment>` with your target environment. The default environment is `local` which works for Ubuntu and
+Set the environment for the commands below by running
+```shell script
+ENVIRONMENT=local # or docker-machine or jenkins or vagrant
+```
+
+The default environment is `local` which works for Ubuntu and
Docker for Mac. To use the default environment, you may omit the `-i` parameter entirely. For older Mac installation using Docker Machine,
use `-i environments/docker-machine`.
@@ -83,7 +88,7 @@ This will configure your deployment with multiple instances (e.g., two Kafka ins
In addition to the host file generation, you need to configure the database for your deployment. This is done
by modifying the file `ansible/db_local.ini` to provide the following properties.
-```bash
+```
[db_creds]
db_provider=
db_username=
@@ -96,7 +101,7 @@ db_port=
This file is generated automatically for an ephemeral CouchDB instance during `setup.yml`. If you want to use Cloudant, you have to modify the file.
For convenience, you can use shell environment variables that are read by the playbook to generate the required `db_local.ini` file as shown below.
-```
+```shell script
export OW_DB=CouchDB
export OW_DB_USERNAME=<your couchdb user>
export OW_DB_PASSWORD=<your couchdb password>
@@ -104,12 +109,12 @@ export OW_DB_PROTOCOL=<your couchdb protocol>
export OW_DB_HOST=<your couchdb host>
export OW_DB_PORT=<your couchdb port>
-ansible-playbook -i environments/<environment> setup.yml
+ansible-playbook -i environments/$ENVIRONMENT setup.yml
```
Alternatively, if you want to use Cloudant as your datastore:
-```
+```shell script
export OW_DB=Cloudant
export OW_DB_USERNAME=<your cloudant user>
export OW_DB_PASSWORD=<your cloudant password>
@@ -117,7 +122,7 @@ export OW_DB_PROTOCOL=https
export OW_DB_HOST=<your cloudant user>.cloudant.com
export OW_DB_PORT=443
-ansible-playbook -i environments/<environment> setup.yml
+ansible-playbook -i environments/$ENVIRONMENT setup.yml
```
#### Install Prerequisites
@@ -126,7 +131,7 @@ This step is not required for local environments since all prerequisites are alr
This step needs to be done only once per target environment. It will install necessary prerequisites on all target hosts in the environment.
```
-ansible-playbook -i environments/<environment> prereq.yml
+ansible-playbook -i environments/$ENVIRONMENT prereq.yml
```
**Hint:** During playbook execution the `TASK [prereq : check for pip]` can show as failed. This is normal if no pip is installed. The playbook will then move on and install pip on the target machines.
@@ -134,28 +139,28 @@ ansible-playbook -i environments/<environment> prereq.yml
### Deploying Using CouchDB
- Make sure your `db_local.ini` file is [setup for](#setup) CouchDB then execute:
-```
+```shell script
cd <openwhisk_home>
./gradlew distDocker
cd ansible
-ansible-playbook -i environments/<environment> couchdb.yml
-ansible-playbook -i environments/<environment> initdb.yml
-ansible-playbook -i environments/<environment> wipe.yml
-ansible-playbook -i environments/<environment> openwhisk.yml
+ansible-playbook -i couchdb.yml
+ansible-playbook -i environments/$ENVIRONMENT initdb.yml
+ansible-playbook -i environments/$ENVIRONMENT wipe.yml
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml
# installs a catalog of public packages and actions
-ansible-playbook -i environments/<environment> postdeploy.yml
+ansible-playbook -i environments/$ENVIRONMENT postdeploy.yml
# to use the API gateway
-ansible-playbook -i environments/<environment> apigateway.yml
-ansible-playbook -i environments/<environment> routemgmt.yml
+ansible-playbook -i environments/$ENVIRONMENT apigateway.yml
+ansible-playbook -i environments/$ENVIRONMENT routemgmt.yml
```
- You need to run `initdb.yml` **every time** you do a fresh deploy CouchDB to initialize the subjects database.
- The `wipe.yml` playbook should be run on a fresh deployment only, otherwise actions and activations will be lost.
- Run `postdeploy.yml` after deployment to install a catalog of useful packages.
- To use the API Gateway, you'll need to run `apigateway.yml` and `routemgmt.yml`.
-- Use `ansible-playbook -i environments/<environment> openwhisk.yml` to avoid wiping the data store. This is useful to start OpenWhisk after restarting your Operating System.
+- Use `ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml` to avoid wiping the data store. This is useful to start OpenWhisk after restarting your Operating System.
#### Limitation
@@ -167,21 +172,21 @@ To deploy multiple CouchDB nodes, they should be placed on different machines re
- Make sure your `db_local.ini` file is set up for Cloudant. See [Setup](#setup).
- Then execute:
-```
+```shell script
cd <openwhisk_home>
./gradlew distDocker
cd ansible
-ansible-playbook -i environments/<environment> initdb.yml
-ansible-playbook -i environments/<environment> wipe.yml
-ansible-playbook -i environments/<environment> apigateway.yml
-ansible-playbook -i environments/<environment> openwhisk.yml
+ansible-playbook -i environments/$ENVIRONMENT initdb.yml
+ansible-playbook -i environments/$ENVIRONMENT wipe.yml
+ansible-playbook -i environments/$ENVIRONMENT apigateway.yml
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml
# installs a catalog of public packages and actions
-ansible-playbook -i environments/<environment> postdeploy.yml
+ansible-playbook -i environments/$ENVIRONMENT postdeploy.yml
# to use the API gateway
-ansible-playbook -i environments/<environment> apigateway.yml
-ansible-playbook -i environments/<environment> routemgmt.yml
+ansible-playbook -i environments/$ENVIRONMENT apigateway.yml
+ansible-playbook -i environments/$ENVIRONMENT routemgmt.yml
```
- You need to run `initdb` on Cloudant **only once** per Cloudant database to initialize the subjects database.
@@ -189,7 +194,7 @@ ansible-playbook -i environments/<environment> routemgmt.yml
- The `wipe.yml` playbook should be run on a fresh deployment only, otherwise actions and activations will be lost.
- Run `postdeploy.yml` after deployment to install a catalog of useful packages.
- To use the API Gateway, you'll need to run `apigateway.yml` and `routemgmt.yml`.
-- Use `ansible-playbook -i environments/<environment> openwhisk.yml` to avoid wiping the data store. This is useful to start OpenWhisk after restarting your Operating System.
+- Use `ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml` to avoid wiping the data store. This is useful to start OpenWhisk after restarting your Operating System.
### Using ElasticSearch to Store Activations
@@ -211,24 +216,24 @@ elasticsearch_connect_string="x.x.x.x:9200,y.y.y.y:9200" // if you want to use a
- Then execute:
-```
+```shell script
cd <openwhisk_home>
./gradlew distDocker
cd ansible
# couchdb is still needed to store subjects and actions
-ansible-playbook -i environments/<environment> couchdb.yml
-ansible-playbook -i environments/<environment> initdb.yml
-ansible-playbook -i environments/<environment> wipe.yml
+ansible-playbook -i environments/$ENVIRONMENT couchdb.yml
+ansible-playbook -i environments/$ENVIRONMENT initdb.yml
+ansible-playbook -i environments/$ENVIRONMENT wipe.yml
# this will deploy a simple ES cluster, you can skip this to use external ES cluster
-ansible-playbook -i environments/<environment> elasticsearch.yml
-ansible-playbook -i environments/<environment> openwhisk.yml -e db_activation_backend=ElasticSearch
+ansible-playbook -i environments/$ENVIRONMENT elasticsearch.yml
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml -e db_activation_backend=ElasticSearch
# installs a catalog of public packages and actions
-ansible-playbook -i environments/<environment> postdeploy.yml
+ansible-playbook -i environments/$ENVIRONMENT postdeploy.yml
# to use the API gateway
-ansible-playbook -i environments/<environment> apigateway.yml
-ansible-playbook -i environments/<environment> routemgmt.yml
+ansible-playbook -i environments/$ENVIRONMENT apigateway.yml
+ansible-playbook -i environments/$ENVIRONMENT routemgmt.yml
```
### Configuring the installation of `wsk` CLI
@@ -249,7 +254,7 @@ Let's assume your OpenWhisk CLI home directory is
the CLI repository, use the gradle command to build the binaries (you can omit
the `-PnativeBuild` if you want to cross-compile for all supported platforms):
-```
+```shell script
cd "$OPENWHISK_HOME/../openwhisk-cli"
./gradlew releaseBinaries -PnativeBuild
```
@@ -258,7 +263,7 @@ The binaries are generated and put into a tarball in the folder
`../openwhisk-cli/release`. Then, use the following Ansible command
to (re-)configure the CLI installation:
-```
+```shell script
export OPENWHISK_ENVIRONMENT=local # ... or whatever
ansible-playbook -i environments/$OPENWHISK_ENVIRONMENT edge.yml -e mode=clean
ansible-playbook -i environments/$OPENWHISK_ENVIRONMENT edge.yml \
@@ -276,15 +281,15 @@ Once the CLI is installed, you can [use it to work with Whisk](../docs/cli.md).
### Hot-swapping a Single Component
The playbook structure allows you to clean, deploy or re-deploy a single component as well as the entire OpenWhisk stack. Let's assume you have deployed the entire stack using the `openwhisk.yml` playbook. You then make a change to a single component, for example the invoker. You will probably want a new tag on the invoker image so you first build it using:
-```
+```shell script
cd <openwhisk_home>
gradle :core:invoker:distDocker -PdockerImageTag=myNewInvoker
```
Then all you need to do is re-deploy the invoker using the new image:
-```
+```shell script
cd ansible
-ansible-playbook -i environments/<environment> invoker.yml -e docker_image_tag=myNewInvoker
+ansible-playbook -i environments/$ENVIRONMENT invoker.yml -e docker_image_tag=myNewInvoker
```
**Hint:** You can omit the Docker image tag parameters in which case `latest` will be used implicitly.
@@ -293,9 +298,9 @@ ansible-playbook -i environments/<environment> invoker.yml -e docker_image_tag=m
You can remove a single component just as you would remove the entire deployment stack.
For example, if you wanted to remove only the controller you would run:
-```
+```shell script
cd ansible
-ansible-playbook -i environments/<environment> controller.yml -e mode=clean
+ansible-playbook -i environments/$ENVIRONMENT controller.yml -e mode=clean
```
**Caveat:** In distributed environments some components (e.g. Invoker, etc.) exist on multiple machines. So if you run a playbook to clean or deploy those components, it will run on **all** of the hosts targeted by the component's playbook.
@@ -304,27 +309,27 @@ ansible-playbook -i environments/<environment> controller.yml -e mode=clean
### Cleaning an OpenWhisk Deployment
Once you are done with the deployment you can clean it from the target environment.
-```
-ansible-playbook -i environments/<environment> openwhisk.yml -e mode=clean
+```shell script
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml -e mode=clean
```
### Removing all prereqs from an environment
This is usually not necessary, however in case you want to uninstall all prereqs from a target environment, execute:
-```
-ansible-playbook -i environments/<environment> prereq.yml -e mode=clean
+```shell script
+ansible-playbook -i environments/$ENVIRONMENT prereq.yml -e mode=clean
```
### Lean Setup
To have a lean setup (no Kafka, Zookeeper and no Invokers as separate entities):
At [Deploying Using CouchDB](ansible/README.md#deploying-using-cloudant) step, replace:
-```
-ansible-playbook -i environments/<environment> openwhisk.yml
+```shell script
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml
```
by:
-```
-ansible-playbook -i environments/<environment> openwhisk.yml -e lean=true
+```shell script
+ansible-playbook -i environments/$ENVIRONMENT openwhisk.yml -e lean=true
```
### Troubleshooting
@@ -339,7 +344,7 @@ ERROR! Unexpected Exception: ... Requirement.parse('setuptools>=11.3'))
your `setuptools` package is likely out of date. You can upgrade the package using this command:
-```
+```shell script
pip install --upgrade setuptools --user python
```
@@ -362,13 +367,13 @@ ansible | FAILED! => {
An expedient workaround is to create a link to the expected location:
-```
+```shell script
ln -s $(which python) /usr/local/bin/python
```
Alternatively, you can also configure the location of Python interpreter in `environments/<environment>/group_vars`.
-```
+```shell script
ansible_python_interpreter: "/usr/local/bin/python"
```