mistletoe_api/lib.rs
1//! This is the main crate for the API objects that are passed back and forth between the engine
2//! and the packages. They roughly follow the same pattern as Kubernetes resource definititions.
3//! Some examples of the output are provided below.
4//!
5//! ## MistPackage
6//!
7//! ```yaml
8//! apiVersion: mistletoe.dev/v1alpha1
9//! kind: MistPackage
10//! metadata:
11//! name: nginx-example
12//! labels:
13//! mistletoe.dev/group: mistletoe-examples
14//! ```
15//!
16//! This is provided by the `info` method of the package getting called. It contains some of the
17//! usual metadata, notably the `name` and `labels`. Some of the labels are used by
18//! **Mistletoe** itself when returning information about the package to the end user.
19//!
20//! ## MistInput
21//!
22//! This is passed into the package as the main input it receives when generating output:
23//!
24//! ```yaml
25//! apiVersion: mistletoe.dev/v1alpha1
26//! kind: MistInput
27//! data:
28//! name: my-nginx
29//! namespace: my-namespace
30//! ```
31//!
32//! The important part is the `data`, and the `data` is completely freeform. This could be
33//! considered roughly equivalent to Helm's values. The objects provided by this package have
34//! methods to convert the `data` into any Deserialize objects the package has defined.
35//!
36//! ## MistResult
37//!
38//! ```yaml
39//! apiVersion: mistletoe.dev/v1alpha1
40//! kind: MistResult
41//! data:
42//! result: Ok
43//! message: 'nothing went wrong' # This line is optional
44//! files:
45//! namespace.yaml: |
46//! apiVersion: v1
47//! kind: Namespace
48//! metadata:
49//! name: my-namespace
50//! ```
51//!
52//! Or...
53//!
54//! ```yaml
55//! apiVersion: mistletoe.dev/v1alpha1
56//! kind: MistResult
57//! data:
58//! result: Err
59//! message: 'something went wrong'
60//! ```
61//!
62//! This is what the package returns to the engine, and contains the output of the package execution.
63//! The required fields when returning an error are `result: Err` as well as a package-supplied
64//! `message` describing what went wrong. The required fields when returning successful output
65//! are `result: Ok` and a map of `files` that can be output in the form of a directory structure.
66//! A `message` may also be provided in an `Ok` case if there's info to convey.
67//!
68//! It's worth noting in either case, the `message` field may also be multiple lines long if there
69//! is a lot of info the package wishes to provide to the end user.
70
71/// Module containing API objects for the 0.1 version of the mistletoe-api.
72/// The versions of the Kubernetes definitions are `mistletoe.dev/v1alpha1`.
73pub mod v1alpha1;