Kubernetes

README.md

@@ -1,7 +1,7 @@
 # Launchr
 
 Launchr is a versatile CLI action runner that executes tasks defined in local or embeded yaml files across multiple runtimes:
-- Short-lived container (docker)
+- Short-lived container (docker or kubernetes)
 - Shell (host)
 - Golang (as plugin)
 
@@ -15,7 +15,7 @@ Actions are defined in `action.yaml` files:
 - either on local filesystem: Useful for project-specific actions
 - or embeded as plugin: Useful for common and shared actions
 
-You can find action examples [here](example), here and in the [documentation](docs).
+You can find action examples [here](example) and in the [documentation](docs).
 
 Launchr has a plugin system that allows to extend its functionality. See [core plugins](plugins), [official plugins](https://github.com/launchrctl#org-repositories) and [documentation](docs).
 
@@ -31,7 +31,7 @@ Launchr has a plugin system that allows to extend its functionality. See [core p
 ## Usage
 
 Build `launchr` from source locally. Build dependencies:
-1. `go >=1.20`, see [installation guide](https://go.dev/doc/install)
+1. `go >=1.24`, see [installation guide](https://go.dev/doc/install)
 2. `make`
 
 Build the `launchr` tool:
@@ -52,7 +52,7 @@ If you face any issues with `launchr`:
 ### Installation from source
 
 Build dependencies:
-1. `go >=1.20`, see [installation guide](https://go.dev/doc/install)
+1. `go >=1.24`, see [installation guide](https://go.dev/doc/install)
 2. `make`
 
 **Global installation**
@@ -81,7 +81,7 @@ bin/launchr --version
 
 ## Development
 
-The `launchr`  can be built with a `make` to `bin` directory:
+The `launchr` can be built with a `make` to `bin` directory:
 ```shell
 make
 ```

app.go

@@ -128,7 +128,7 @@ func (app *appImpl) init() error {
 	// @todo consider home dir for global config.
 	config := launchr.ConfigFromFS(os.DirFS(app.cfgDir))
 	actionMngr := action.NewManager(
-		action.WithDefaultRuntime,
+		action.WithDefaultRuntime(config),
 		action.WithContainerRuntimeConfig(config, name+"_"),
 	)
 

docs/README.md

@@ -1,6 +1,30 @@
 # Launchr documentation
 
-1. [Launchr](launchr.md)
-2. [Launchr configuration](config.md)
+1. [Built-in functionality](#built-in-functionality)
 2. [Actions](actions.md)
-3. [Actions Schema](actions.schema.md)
+3. [Actions Schema](actions.schema.md)
+4. [Global configuration](config.md)
+5. [Development](development)
+
+## Build plugin
+
+There are the following build options:
+1. `-o, --output OUTPUT` - result file. If empty, application name is used.
+2. `-n, --name NAME` - application name.
+3. `-p, --plugin PLUGIN[@v1.1]` - use plugin in the built launchr. The flag may be specified multiple times.
+    ```shell
+    launchr build \
+      -p github.com/launchrctl/launchr \ 
+      -p github.com/launchrctl/launchr@v0.1.0
+    ```
+4. `-r, --replace OLD=NEW` - replace go dependency, see [go mod edit -replace](https://go.dev/ref/mod#go-mod-edit). The flag may be specified multiple times.
+
+   The directive may be used to replace a private repository with a local path or to set a specific version of a module. Example:
+    ```shell
+    launchr build --replace github.com/launchrctl/launchr=/path/to/local/dir
+    launchr build --replace github.com/launchrctl/launchr=github.com/launchrctl/launchr@v0.2.0
+    ```
+
+5. `-d, --debug` - include debug flags into the build to support go debugging like [Delve](https://github.com/go-delve/delve).
+   Without the flag, all debugging info is trimmed.
+6. `-h, --help` - output help message

docs/actions.md

@@ -2,9 +2,43 @@
 
 Actions give an ability to run arbitrary commands in containers.
 
-## Supported container engines
-1. `docker`, see [installation guide](https://docs.docker.com/engine/install/)
-2. TBD
+## Supported runtimes
+
+  * Container runtimes (docker, kubernetes)
+  * Shell (host)
+  * Go language (launchr plugin)
+
+## Supported container runtimes
+
+  * `docker` (default)
+  * `kubernetes`
+
+Container runtime is configured globally for all actions of type container. See [Global Configuration](config.md#container-runtime) definition.  
+If not specified, the action will use **Docker** as a default runtime.
+
+Docker or Kubernetes are not required to be installed to use containers. But the configuration must be present.
+
+### Docker
+
+Runtime tries to connect using the following configuration:
+
+1. `unix:///run/docker.sock` - default docker socket path
+2. Via [Docker environment variables](https://docs.docker.com/reference/cli/docker/#environment-variables), see the following variables: 
+   * `DOCKER_HOST`
+   * `DOCKER_API_VERSION`
+   * `DOCKER_CERT_PATH`
+   * `DOCKER_TLS_VERIFY`
+
+Normally, if the Docker installed locally, `unix:///run/docker.sock` will be present and used by default.  
+**NB!** If the docker is not running locally, you may have incorrect mounting of the paths. Consider using a flag `--remote-runtime`.
+
+### Kubernetes
+
+Runtime tries to connect using the following configuration:
+
+1. `~/.kube/config` - default kubectl configuration directory.
+2. `KUBECONFIG` environment variable, see [kuberenetes documentation](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable)
+    Usage example: `export KUBECONFIG="/etc/rancher/k3s/k3s.yaml"`
 
 ## Action definition
 
@@ -27,6 +61,9 @@ action:
     - name: optStr
       title: Option string
       description: Some additional info for option
+
+runtime:
+  type: container
   image: python:3.7-slim
   command: 
     - python3 
@@ -35,86 +72,107 @@ action:
     - ${ENV_VAR}
 ```
 
-See more examples of action definition in [actions.schema.md](actions.schema.md)
+For more detailed specification and examples of action definition, see [actions.schema.md](actions.schema.md)
 
 ## Actions discovery
 
-The action files must preserve a tree structure like `**/**/actions/*/action.yaml` to be discovered.  
+The action files must preserve a tree structure like `**/**/actions/*/action.yaml` or `actions/*/action.yaml` to be discovered.  
 Example:
 ```
-foundation
-└── software
-    └── flatcar
+actions:
+└── foo
+    └── action.yaml
+foo
+└── bar
+    └── buz
         └── actions
-            └── bump
+            └── waldo
                 └── action.yaml
-integration
-└── application
-    └── bus
-        └── actions
-            └── watch
-                └── action.yaml
-platform
+bar
 └── actions
-    ├── build
+    ├── foo
     │   ├── build.sh
     │   └── action.yaml
-    └── bump
+    └── buz
         ├── bump.py
         └── action.yaml
 ```
 
 The example structure produces the following commands:
+
 ```shell
 $ launchr --help
+launchr is a versatile CLI action runner that executes tasks defined in local or embeded yaml files across multiple runtimes
 ...
-Discovered actions:
-  foundation.software.flatcar:bump  Verb: Handles some logic
-  integration.application.bus:watch Verb: Handles some logic
-  platform:build                    Verb: Handles some logic
-  platform:bump                     Verb: Handles some logic
+Actions:
+  foo                foo: foo description
+  foo.bar.buz:waldo  foo bar buz waldo: foo.bar.buz:waldo description
+  bar:foo            bar foo: bar:foo description
+  bar:buz            bar buz: bar:buz description
 ...
 ```
 
 ### Action execution
 
 To run the command simply run:
 ```shell
-$ launchr platform:build ...
+$ launchr foo:bar [args...] [--options...]
 ```
 
 To get more help for the action:
+
+
 ```shell
-$ launchr platform:build --help
-Verb: Handles some logic
+$ launchr foo:bar --help
 
-Usage:
-  launchr platform:build args[1] args[2] [flags]
+Foo Bar: foo:bar description
 
-Flags:
-  -h, --help             help for platform:build
-      --opt1 string      Option 1: Some additional info for option
-      --opt2             Option 2: Some additional info for option
-      --opt3 int         Option 3: Some additional info for option
-      --opt4 float       Option 4: Some additional info for option
-      --optarr strings   Option 4: Some additional info for option
+Usage:
+  launchr foo:bar argStr [argInt] [flags]
+
+Arguments:
+      argInt int      Argument Integer: This is an optional integer argument
+      argStr string   Argument String: This is a required implicit string argument
+
+Options:
+      --optArray strings     Option Array String: This is an optional array<string> option with a default value
+      --optArrayBool bools   Option Array Boolean: This is an optional enum<boolean> option with a default value (default [])
+      --optBoolean           Option Boolean: This is an optional boolean option with a default value
+      --optEnum string       Option Enum: This is an optional enum<string> option with a default value (default "enum1")
+      --optIP string         Option String IP: This is an optional string option with a format validation (ipv4) (default "1.1.1.1")
+      --optInteger int       Option Integer: This is an optional boolean option with a default value
+      --optNumber float      Option Number: This is an optional number option with a default value (default 3.14)
+      --optString string     Option String: This is an optional string option with a default value
+
+Action runtime options:
+      --entrypoint string   Image Entrypoint: Overwrite the default ENTRYPOINT of the image. Example: --entrypoint "/bin/sh"
+      --exec                Exec command: Overwrite the command of the action. Argument and options are not validated, sets container CMD directly. Example usage: --exec -- ls -lah
+      --no-cache            No cache: Send command to build container without cache
+      --remote-copy-back    Remote copy back: Copies the working directory back from the container. Works only if the runtime is remote.
+      --remote-runtime      Remote runtime: Forces the container runtime to be used as remote. Copies the working directory to a container volume. Local binds are not used.
+      --remove-image        Remove Image: Remove an image after execution of action
 
 Global Flags:
-  -q, --quiet           log only fatal errors
-  -v, --verbose count   log verbosity level, use -vvv DEBUG, -vv WARN, -v INFO
+      --log-format LogFormat    log format, can be: pretty, plain or json (default pretty)
+      --log-level logLevelStr   log level, same as -v, can be: DEBUG, INFO, WARN, ERROR or NONE (default NONE)
+  -q, --quiet                   disable output to the console
+  -v, --verbose count           log verbosity level, use -vvvv DEBUG, -vvv INFO, -vv WARN, -v ERROR
 ```
 
-### Container environment flags
+### Mounts/Volumes in container runtime
 
- * `--entrypoint`      Entrypoint: Overwrite the default ENTRYPOINT of the image
- * `--exec`            Exec: Overwrite CMD definition of the container
- * `--no-cache`        No cache: Send command to build container without cache
- * `--remove-image`    Remove Image: Remove an image after execution of action
- * `--use-volume-wd`   Use volume as a WD: Copy the working directory to a container volume and not bind local paths. Usually used with remote environments.
+To follow the context on action execution, 2 mounts are passed to the execution environment:
+1. `/host`
+2. `/action`
 
+If run in the local runtime (docker):
 
-### Mounts in execution environment
+1. Current working directory is mounted to `/host`, Docker equivalent `$(pwd):/host`
+2. Action directory is mounted to `/action`, Docker equivalent `./action/dir:/action`
 
-To follow the context on action execution, 2 mounts are passed to the execution environment:
-1. `/host` - current working directory
-2. `/action` - action directory
+If run in the remote runtime (docker, kubernetes) or with a flag `--remote-runtime`:
+
+1. Current working directory is copied to a new volume `volume_host:/host`
+2. Action directory is copied to a new volume `volume_action:/action`
+
+To copy back the result of the execution, use `--remote-copy-back` flag.