Google Git
Sign in
apache / openserverless-cli / 72ca8f50451e94b3d0e5e95a8c6b30a1404f3939
commit72ca8f50451e94b3d0e5e95a8c6b30a1404f3939[log] [tgz]
authorMichele Sciabarra <michele@sciabarra.com>Fri Aug 02 16:29:19 2024 +0200
committerMichele Sciabarra <michele@sciabarra.com>Fri Aug 02 16:29:19 2024 +0200
tree1a395d7e833fad6509d7627e45ddc8177e65810f
parent143401b3f4f3a43d80b1dd6adcaf8ed6ed50fbe5 [diff]
~/.nuv and Nuv
29 files changed
tree: 1a395d7e833fad6509d7627e45ddc8177e65810f
  1. .git-hook/
  2. .github/
  3. _patches/
  4. auth/
  5. bin/
  6. cmd/
  7. config/
  8. docs/
  9. tests/
  10. tools/
  11. .envrc
  12. .gitattributes
  13. .gitignore
  14. .goreleaser.yaml
  15. .licenserc.yaml
  16. branch.txt
  17. cli.code-workspace
  18. common.go
  19. difftest.py
  20. go.mod
  21. go.sum
  22. LICENSE
  23. main.go
  24. main_test.go
  25. nuv.go
  26. nuv_test.go
  27. plugin.go
  28. plugin_test.go
  29. preflight.go
  30. preflight_test.go
  31. prepare.go
  32. prepare_test.go
  33. prereq.go
  34. prereq_test.go
  35. README.md
  36. runtimes.json
  37. serve.go
  38. serve_test.go
  39. shell.nix
  40. task.go
  41. Taskfile.yml
  42. updates_check.go
  43. updates_check_test.go
  44. version.txt
README.md

WARNING: this is still work in progress

The code may not build, there can be errors, and it can even destroy your hard disk or send you in another dimension.

Documentation is also work in progress....

ops, the OpenServerless all-mighty CLI tool.

Ops is a task executor on steroids.

  • it embeds Task)
  • it embeds wsk
  • it embeds many other utility commands (check with ops -help)
  • automatically download other commad line tools he neeeds as prerequisites
  • automatically download a predefined set of tasks downloaded from github
  • taskfiles are organized in commands and subcommands, hiearachally
  • taskfiles have options powered by docopt
  • it supports plugins

The predefined set of tasks are all you need to install and manage an OpenServerless cluster.

You can also use for your own purposes, if you want.

Where to look for external documetation

Because ops is built on task, docopt and wsk you have to consult the following website for:

  • details on nuvfile.yml: taskfiles
  • details on nuvopts.txt: docopts
  • details on the OpenWhisk cli: wsk

Where ops looks for tasks

Ops is able either to run local tasks or download them from github.

Tasks also can contains prerequisite binaries, and task will download them automatically and put then in the PATH.

Se below for details

Local Taks

When you run ops [<args>...] it will first look for its ops root.

The olaris root is a folder with two files in it: nuvfile.yml (a yaml taskfile) and nuvroot.json (a json file with release information).

The first step is to locate the root folder. The algorithm to find the tools is the following.

If the environment variable OPS_ROOT is defined, it will look there first, and will check if there are the two files.

Then it will look in the current folder if there is a nuvfile.yml. If there is, it will also look for nuvroot.json. If it is not there, it will go up one level looking for a directory with nuvfile.yml and nuvtools.json, and selects it as the nuv root.

If there is not a nuvfile.yml it will look for a folder called olaris with both a nuvfile.yml and nuvtools.json in it and will select it as the ops root.

Then it will look in ~/.ops if there is an olaris folder with nuvfile.yml and nuvroot.json.

Download Tasks

If the local task resolution fails, it will download its tasks from github.

It is the same process that you can trigger manually with the command ops -update.

Where ops download tasks from GitHub

The repo to use is defined by the environment variable OPS_REPO, and defaults to https://github.com/apache/openserverless-task

The branch to use is defined at build time. It is noramlly named as the base version of the CLI. It can be overriden with the enviroment variable OPS_BRANCH.

When you run ops -update, if there is not a ~/.ops/<branch>/olaris it will clone the current branch, otherwise it will update it.

How ops execute tasks

Ops will look to the command line parameters ops <arg1> <arg2> <arg3> and will consider them as directory names. The list can be empty.

If there is a directory name <arg1> it will change to that directory. If there is then a subdirectory <arg2> it will change to that and so on until it finds a argument that is not a directory name.

If the last argument is a directory name, will look for a nuvopts.txt. If it is there, it will show this. If it's not there, it will execute a ops -task -t nuvfile.yml -l showing tasks with description.

If it finds an argument not corresponding to a directory, it will consider it a task to execute,

If there is not a nuvopts.txt, it will execute as a task, passing the other arguments (equivalent to ops -task -t nuvfile.yml <arg> -- <the-other-args>).

If there is a nuvopts.txt, it will interpret it as a docopt to parse the remaining arguments as parameters. The result of parsing is a sequence of <key>=<value> that will be fed to task. So it is equivalent to invoking task -t nuvfile.yml <arg> <key>=<value> <key>=<value>...

Example

A command like ops setup kubernetes install --context=k3s will look in the folder setup/kubernetes in the ops root, if it is there, then select install as task to execute and parse the --context=k3s. It is equivalent to invoke cd setup/kubernetes ; task install -- context=k3s.

If there is a nuvopts.txt with a command <name> --flag --fl=<val> the passed parameters will be: _name_=<name> __flag=true __fl=true _val_=<val>.

Note that also this will also use the downloaded tools and the embedded commands of ops.

Embedded tools

Currently task embeds the following tools, and you can invoke them directly prefixing them with -: (ops -task, nuv -basename etc). Use nuv -help to list them.

This is the list of the tools (it could be outdated, check with ops -help):

Available tools:
-awk
-base64
-config
-datefmt
-die
-echoif
-echoifempty
-echoifexists
-empty
-envsubst
-extract
-filetype
-gron
-help
-info
-jj
-jq
-login
-needupdate
-plugin
-random
-remove
-rename
-replace
-retry
-serve
-sh
-task
-update
-urlenc
-validate
-version
-wsk

Environment variables

The following environment variables allows to ovverride certain defaults.

  • OPS_HOME is the home dir, defaults to ~/.ops if not defined
  • OPS_ROOT is the folder where ops looks for its tasks. If not defined, if will first look in current directory for an olaris folder otherwise download it from githut fron the OPS_REPO with a git clone
  • OPS_BIN is the folder where ops looks for binaries (external command line tools). If not defined, it defaults to ~/.ops/<os>-<arch>/bin. All the prerequisites are downloaded in this directory
  • OPS_CMD is the actual command executed - defaults to the absolute path of the target of the symbolic link but it can be overriden.
  • OPS_REPO is the github repo where ops downloads its tasks. If not defined, it defaults to https://github.com/apache/openserverless-task.
  • OPS_BRANCH is the branch where nuv looks for its tasks. The branch to use is defined at build time and it is the base version (without the patch level). Chech branch.txt for the current value
  • OPS_VERSION can be defined to set nuv's version value. It is useful to override version validations when updating tasks (and you know what you are doing). Current value is in version.txt
  • OPS_TMP is a temporary folder where you can store temp files - defaults to ~/.ops/tmp
  • OPS_APIHOST is the host for nuv -login. It is used in place of the first argument of nuv -login. If empty, the command will expect the first argument to be the apihost.
  • OPS_USER: set the username for nuv -login. The default is nuvolaris. It can be overriden by passing the username as an argument to nuv -login or by setting the environment variable.
  • OPS_PASSWORD: set the password for nuv -login. If not set, nuv -login will prompt for the password. It is useful for tests and non-interactive environments.
  • OPS_PWD is the folder where ops is executed (the current working directory). It is used to preserve the original working directory when ops is used again in tasks (e.g. nuv -realpath to retrieve the correct path). Change it only if you know what you are doing!
  • OPS_ROOT_PLUGIN is the folder where nuv looks for plugins. If not defined, it defaults to the same directory where ops is located.
  • OPS_OLARIS holds the head commit hash of the used olaris repo. You can see the hash with nuv -info.
  • OPS_PORT is the port where ops will run embedde web server for the configurator. If not defined, it defaults to 9678.
  • OPS_NO_NUVOPTS can be defined to disable nuvopts parsing. Useful to test hidden tasks. When this is enabled it also shows all the tasks instead of just those with a description.
  • OPS_NO_PREREQ disable downloading of prerequisites - you have to ensure at least coreutils is in the path to make things work

Internal environment variables

The following variables have a special purpose and used for test and debug

  • DEBUG if set enable debugging messages
  • TRACE when set gives mode detailes tracing informations, also enable DEBUG=1
  • EXTRA appends extra arguments to the task invocation - useful when you need to set extra variables with a nuvopts active.
  • __OS overrides the value of the detected operating system - useful to test prereq scripts
  • __ARCH overrides the value of the detected architecture - useful to test prereq scripts
  • OPS_RUNTIMES_JSON is used for the values of the runtimes json if the system is unable to read in other ways the current runtimes json. It is normally compiled in when you buid from the current version of the runtimes.json. It can be overriden
  • OPS_COREUTILS is a string, a space separated list, which lists all the commands the coreutils binary provided. It should be kept updated with the values of the current version used. It can be overriden
  • OPS_TOOLS is a string, a space separated list, which lists all the commands provided as internal tool by the ops binary. It shold be kept updated with the current list of tools provided. It can be overriden defining externally