The following instructions were tested on Mac OS X El Capitan, Ubuntu 16.04 LTS.
tools/vagrantgit clone --depth=1 https://github.com/apache/incubator-openwhisk.git openwhisk cd openwhisk/tools/vagrant
Important We advise that you use this method for development of OpenWhisk.
# Configure with couchdb docker container running inside the VM ./hello
Note: Follow instructions tools/db/README.md on how to configure the remote DB for OpenWhisk.
# Provide credentials for cloudant database with admin permissions OW_DB=cloudant OW_DB_USERNAME=xxxxx OW_DB_PASSWORD=yyyyyy ./hello
# Provide credentials for couchdb database with admin permissions export OW_DB=couchdb export OW_DB_USERNAME=<username> export OW_DB_PASSWORD=<password> export OW_DB_PROTOCOL=http export OW_DB_HOST=<ip_address> export OW_DB_PORT=5984 ./hello
Note: Data will persist after safe re-deploy, but will be destroyed if you initialze the DB. For more information on data store configurations see tools/db/README.md.
wsk action invoke /whisk.system/utils/echo -p message hello --result
{
"message": "hello"
}
Tip: The very first build may take 30 minutes or more depending on network speed. If there are any build failures, it might be due to network timeouts, to recover follow the manual process to build and deploy in ansible/README.md
Tip: By default, each docker command will timeout after 840 seconds (14 minutes). If you're on a really slow connection, this might be too short. You can modify the timeout value in docker.gradle.
You can use the CLI from the host machine as well as from inside the virtual machine. The IP address of the virtual machine accessible from outside is 192.168.33.16. If you start another Vagrant VM take into account that the IP address will conflict, use vagrant suspend before starting another VM with the same IP address.
The CLI is available in ../../bin. The CLI ../../bin/wsk is for Linux amd64. The CLI for other operating systems and architectures can be found under ../../bin/openwhisk-cli/build/
When using the CLI with a local deployment of OpenWhisk (which provides an insecure/self-signed SSL certificate), you must use the argument -i to permit an insecure HTTPS connection to OpenWhisk. This should be used for development purposes only.
Call the binary directly or setup your environment variable PATH to include the location of the binary that corresponds to your environment.
From your host, configure wsk to use your Vagrant-hosted OpenWhisk deployment and run the “echo” action again to test. The following commands assume that you have wsk setup correctly in your PATH.
# Set your OpenWhisk Authorization Key.
wsk property set --apihost 192.168.33.16 --auth `vagrant ssh -- cat openwhisk/ansible/files/auth.guest`
# Run the hello sample action
wsk -i action invoke /whisk.system/utils/echo -p message hello --result
{
"message": "hello"
}
Tip: You need to use the -i switch as the default SSL certificate used by the Vagrant installation is self-signed. Alternatively, you can configure your apihost to use the non-SSL interface:
wsk property set --apihost http://192.168.33.16:10001 --auth `vagrant ssh -- cat openwhisk/ansible/files/auth.guest`
You do not need to use the -i switch to wsk now. Note, however, that wsk sdk will not work, so you need to pass use wsk -i --apihost 192.168.33.16 sdk {command} in this case.
Note: To connect to a different host API (i.e. openwhisk.example.com) with the CLI, you will need to configure the CLI with new values for apihost, and auth key.
For your convenience, a wsk wrapper is provided inside the VM which delegates CLI commands to $OPENWHISK_HOME/bin/linux/amd64/wsk and adds the -i parameter that is required for insecure access to the local OpenWhisk deployment.
Calling the wsk CLI via vagrant ssh directly
vagrant ssh -- wsk action invoke /whisk.system/utils/echo -p message hello --result
Calling the wsk CLI by login into the Vagrant VM
vagrant ssh wsk action invoke /whisk.system/utils/echo -p message hello --result
vagrant ssh
cd ${OPENWHISK_HOME}
# run all tests
./gradlew tests:test
# or run a subset of tests using the --tests flag
./gradlew tests:test --tests system.basic.ConsoleTests
Use gradle to build docker images from inside the VM, this is done automatically once at VM creation.
vagrant ssh
cd ${OPENWHISK_HOME}
./gradlew distDocker
Only for experimental use: To use docker-runc in the invoker, the version of docker-runc needs to match the version of docker engine on the host. Get the version of the docker engine on the host like the following:
$ docker version | grep Version Version: 18.03.0-ce
You need to use the same version for docker-runc in the Invoker, to use a newer version of docker-runc in the invoker, update the invoker Dockerfile.
Edit the core/invoker/Dockefile Update the variable with the version
ENV DOCKER_VERSION 18.03.0-ce
Then update line with the curl download command like
RUN curl -sSL -o docker-${DOCKER_VERSION}.tgz https://download.docker.com/linux/static/stable/x86_64/docker-${DOCKER_VERSION}.tgz && \
Notice that the hostname where to download the cli is different for newer versions.
Then update the ansible configuration to enable the use of runc, edit
invoker_use_runc: true
Then rebuild and redeploy the invoker component
wskdev invoker
The following commands are helpful to deploy a fresh OpenWhisk and data store
vagrant ssh
cd ${ANSIBLE_HOME}
# teardown all containers
wskdev teardown
# deploy openwhisk containers
wskdev fresh
Tip Do not restart the VM using Virtual Box tools, and always use vagrant from the command line: vagrant up to start the VM and vagrant reload to restart it. This allows the $HOME/openwhisk folder to be available inside the VM.
Tip If you have problems with data stores check that ansible/db_local.ini.
Tip To initialize the data store from scratch run ansible-playbook -i environments/local initdb.yml inside the VM as described in ansible setup.
Once deployed, several Docker containers will be running in your virtual machine. You can check that containers are running by using the docker cli with the command vagrant ssh -- docker ps.
An OpenWhisk user, also known as a subject, requires a valid authorization key. OpenWhisk is preconfigured with a guest key located in ansible/files/auth.guest.
You may use this key if you like, or use wskadmin inside the VM to create a new key.
vagrant ssh wskadmin user create <subject>
For more information on wskadmin check the documentation.
OpenWhisk includes a self-signed SSL certificate and the wsk CLI allows untrusted certificates via -i on the command line. The certificate is generated during setup and stored in ansible/roles/nginx/files/openwhisk-cert.pem.
Do not use these certificates in production: replace with your own and modify the configuration to use trusted certificates instead.
# Suspend Vagrant VM when done having fun vagrant suspend # Resume Vagrant VM to have fun again vagrant up # Do not restart via Virtual Box, use Vagrant reload to mount $HOME/openwhisk as a shared directory vagrant reload # Read the help for wsk CLI vagrant ssh -- wsk -h vagrant ssh -- wsk <command> -h
Tip: Don't use vagrant resume. See here for related issue.
By default the Vagrant VM will use ubuntu/xenial64 if you want to use ubuntu/trusty64 you can override with an environment variable BOX_OS.
BOX_OS="ubuntu/trusty64" ./hello
Create VM with Desktop GUI. The username and password are both set to vagrant by default.
gui=true ./hello gui=true vagrant reload
Tip: Ignore error message Sub-process /usr/bin/dpkg returned an error code (1) when creating Vagrant VM using gui-true. Remember to use gui=true every time you do vagrant reload. Or, you can enable the GUI directly by editing the Vagrant file.