Skip to content

Latest commit

 

History

History
221 lines (156 loc) · 6.53 KB

README.md

File metadata and controls

221 lines (156 loc) · 6.53 KB
Raw

🕊️ peace – zero stress automation

Crates.io docs.rs CI Coverage Status

peace is a framework to build empathetic and forgiving software automation.

See:

  • peace.mk for the project vision.
  • Background for the motivation to create this framework.
  • Operations UX for a book about the dimensions considered during peace's design and development.

Guiding Principles

  • A joy to use.
  • Ergonomic API and guidance to do the right thing.
  • Understandable output.

Features

Symbol Meaning
🟢 Works well
🟡 Partial support
⚫ Planned
🔵 Compatible by design
🟣 Works, "fun idea"
  • 🟢 Idempotent: Multiple invocations result in the goal outcome.
  • 🟢 Clean: Every item creation is paired with how it is cleaned up.
  • 🟢 Understandable: Progress is shown at an understandable level of detail.
  • 🔵 Understandable: Error reporting is compatible with miette.
  • 🟢 Interruptible: Execution can be interrupted.
  • 🟢 Resumable: Automation resumes where it was interrupted.
  • 🟢 Diffable: States and diffs are serialized as YAML.
  • 🟢 Efficient: Tasks are concurrently executed via fn_graph.
  • 🟢 Namespaced: Profile directories isolate environments from each other.
  • 🟢 Type Safe: Items and parameters are defined in code, not configuration.

Roadmap

  • 🟢 Define items to manage with automation.
  • 🟢 Define dependencies between items.
  • 🟢 Define "apply" logic.
  • 🟢 Define "clean up" logic.
  • 🟢 Discover current and goal states.
  • 🟢 Define diff calculation between states.
  • 🟢 Store and recall parameters across commands.
  • 🟢 Diff states between multiple profiles.
  • 🟢 Type-safe referential parameters -- specify usage of values generated during automation as parameters to subsequent items.
  • 🟢 Cancel-safe interruption.
  • 🟡 Feature-gated incremental functionality.
  • 🟡 Off-the-shelf support for common items.
  • 🟡 Dry run.
  • 🟣 WASM support.
  • 🟡 Web based UI with interactive graph.
  • ⚫ Run command with subset of items.
  • ⚫ Params specification: Read values from other flows.
  • ⚫ Flow versions: Support migrating environment deployed using previous flow version.
  • ⚫ Secure-by-design Support: Encrypted value storage, decrypted per execution / time based agent.
  • ⚫ Tutorial for writing a software lifecycle management tool.
  • ⚫ Built-in application execution methods -- CLI, web service.
  • ⚫ peace binary for configuration based workflows.
  • ⚫ Agent mode to run peace on servers (Web API invocation).

Further ideas:

  • Back up current state.
  • Restore previous state.
  • Telemetry / metrics logging for analysis.

Examples

Examples are run using --package instead of --example, as each example is organized as its own crate.

download example 
cargo run --package $example_name --all-features

# e.g.
cargo build --package download --all-features
cargo run -q --package download --all-features -- init https://ifconfig.me ip.json

for cmd in status goal diff ensure ensure diff clean clean diff
do
    printf "=== ${cmd} ===\n"
    cargo run -q --package download --all-features -- --format text $cmd
    printf '\n'
done

# Look at metadata that Peace has saved
find .peace -type f -exec bash -c 'echo \# {}; cat {}; echo' \;

# Clean up the metadata directory
rm -rf .peace

WASM

The download example can be built as a web assembly application using wasm-pack:

cd examples/download
wasm-pack build --target web

In the examples/download directory, start an HTTP server, and open http://localhost:8000/:

python3 -m http.server 8000 # or
simple-http-server --nocache --port 8000 -i
envman example

  1. Install cargo-leptos.

    cargo install --locked cargo-leptos

  2. Build the envman example:

    # defined in .cargo/config.toml
cargo envman_build_debug

  3. Copy artifacts to a temporary directory:

    demo_dir=/tmp/demo/envman
test -d "${demo_dir}" || mkdir -p "${demo_dir}"
cp ./target/debug/envman "${demo_dir}"
cp ./target/web/envman/pkg "${demo_dir}"

  4. Switch to the demo directory:

    demo_dir=/tmp/demo/envman
cd "${demo_dir}"

  5. Make sure you have AWS credentials set up in ~/.aws/credentials.

  6. Run the appropriate envman commands:

    1. Initialize a project:

      # initialize a project to download from `azriel91/web_app`
./envman init \
  --type development \
  --flow deploy \
  demo_1 azriel91/web_app 0.1.1

    2. Status / Goal / Diff:

      ./envman status
./envman goal
./envman diff

    3. Deploy / Clean

      ./envman deploy
./envman deploy --format json
./envman deploy --format none

./envman clean
./envman clean --format json
./envman clean --format none

    4. You can also interrupt the deploy/clean process.

  7. Run the web interface:

    ./envman web

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.