diff --git a/docs/concepts.md b/docs/concepts.md index 6fb463b..ea6c028 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,7 +1,7 @@ # Concepts -The following are brief descriptions of KubeFox constituents. For more details -and tutorials on their use checkout additional documentation under +The following are brief descriptions of KubeFox concepts. For more details and +tutorials on their use, checkout additional documentation under [topics](../topics). ## Event @@ -9,26 +9,25 @@ and tutorials on their use checkout additional documentation under : KubeFox operates on an event-driven architecture, where all requests and responses, including synchronous calls, are conceptualized as Events and communicated as messages among Components via Brokers. The KubeFox Event model -offers a straightforward and versatile interface to encapsulate distinct, and -optionally typed, state changes. +offers a straightforward and versatile interface to encapsulate distinct - and +optionally typed - state changes. : To illustrate, an HTTP request undergoes conversion by the HTTP Adapter into a KubeFox Event, which is subsequently transmitted to a Broker for routing to a specific Component. The Component can then utilize the Event in a generic manner -or, alternatively, inspect its type and access type-specific attributes as -needed. +and, optionally, inspect its type and access type-specific attributes as needed. ## Genesis Event : A Genesis Event is an originating Event for a request. It is often generated in response to an external request, such as an HTTP request. However, an -internal process, like a CRON trigger, could also give rise to a Genesis Event. -KubeFox dynamically determines the routing of a Genesis Event by matching it to -a registered Component Route associated with a Release. Conversely, the App +internal process, like a CRON trigger, could also yield a Genesis Event. KubeFox +dynamically determines the routing of a Genesis Event by matching it to a +registered Component Route associated with a Release. Alternatively, the App Deployment and Virtual Environment can be explicitly specified within the Genesis Event, allowing for testing of App Deployments before an official -Release is created. Once a match is established, the request context, including -the App Deployment and Virtual Environment, is attached to to the Genesis Event +Release is created. Once a match is established, the request context - including +the App Deployment and Virtual Environment - is attached to to the Genesis Event all subsequent child Events generated by the Components processing the request. ## Component @@ -41,80 +40,78 @@ Components. ## App -: An App is a collections of Components which together provide useful -capabilities to end users of the software. Apps serve as the deployable unit in -the context of KubeFox. That means all Components of an App are deployed, and -optionally versioned, together. +: An App is an application; a collection of Components which together provide +useful capabilities to end users of the software. Apps serve as the deployable +unit in the context of KubeFox. That means all Components of an App are deployed +(and optionally versioned) together. ## Repository -: A Repository is a Git repository housing one or more Apps. Components are -versioned through commits made to Git, enabling KubeFox to track modifications -to Components between App Deployments. +: A Repository is a Git repository housing one or more Apps. KubeFox tracks +modifications to Components by monitoring Git commits, and versions Components +when Apps are deployed. ## Route -: A Route matches Events to a handler implemented by a Component. They are +: A Route matches Events to a handler implemented by a Component. Routes are written in a straightforward predicate-based language that supports boolean -logic. Optionally, a Route can contain logic to extract Event attributes into +logic. A Route can optionally contain logic to extract Event attributes into named parameters, which are then passed to the handler. ## Broker -: A Broker serves as an Event router, responsible for matching and transporting -Events between components. It determines the context of an Event and scrutinizes -the corresponding App Deployment to ensure that the Event is authorized to be -passed to the matching Component. The Broker also injects Virtual Environment -variables and Adapter configurations into Events as necessary. +: Brokers serve as Event routers, and are responsible for matching and +transporting Events between components. Brokers determine the context of an +Event and evaluate the corresponding App Deployment to ensure that the Event is +authorized to be passed to the matching Component. Brokers also inject Virtual +Environment variables and Adapter configurations into Events as necessary. ## External Component -: An External Component refers to a third-party service that is not inherent to -KubeFox. Examples of External Components include PostgreSQL, Amazon S3, and -Kafka. Adapters provide connectivity with these Components by facilitating the -translation between the External Component's API and KubeFox Events. +: An External Component refers to a third-party service. Examples of External +Components include PostgreSQL, Amazon S3, and Kafka. Adapters provide +communication between KubeFox Components and External Components. ## Adapter -: An adapter is a service which bidirectionally converts KubeFox Events to an -External Component's API. Adapters facilitate the interaction of Components with -services that are not native to KubeFox. For instance, the HTTP Adapter -translates both incoming HTTP requests and outgoing HTTP calls to and from -KubeFox Events. +: An Adapter is a service which converts KubeFox Events to an External +Component's API and vice versa. Adapters facilitate the interaction of +Components with services that are not native to KubeFox. For instance, the HTTP +Adapter translates both incoming HTTP requests and outgoing HTTP calls to and +from KubeFox Events. ## App Deployment : An App Deployment comprises the definitions of both the App and its -Components. This encompasses the Component's Routes, OCI image name, and any -associated Virtual Environment variables or Adapters it depends on. Initiating -the creation of an App Deployment prompts the KubeFox operator to verify a -Kubernetes Pod exists for each specified Component. +Components. This includes the Component's Routes, OCI image name, and any +associated Virtual Environment variables or Adapters on which it depends. +Initiating the creation of an App Deployment prompts the KubeFox operator to +verify a Kubernetes Pod exists for each specified Component. -: Optionally, an App Deployment can be assigned a version with semantic -significance. Once versioned, an App Deployment becomes immutable, guaranteeing -a static App definition. This facilitates releasing the App Deployment while -preserving a consistent and unchanging configuration for the specified version -of the App. +: An App Deployment can optionally be assigned a version, e.g., a semantic +version. Once versioned, an App Deployment becomes immutable, guaranteeing a +stable, point-in-time App definition. Versioning the App facilitates Release and +preserves a consistent and unchanging configuration for the specified version, +enabling a return to the version at any point in the future. ## Virtual Environment -: A Virtual Environment is an object encompassing a collection of variables and -Adapter configurations. A Component can specify dependencies on both Virtual -Environment variables and Adapters. During runtime, the Broker extracts the -necessary variables from the Virtual Environment and attaches them to any Event -routed to the Component. Simultaneously, the Broker attaches the requisite -configuration to Events directed to an Adapter. +: A Virtual Environment is a collection of variables and Adapter configurations. +Virtual Environments enable capabilities like dynamic (at runtime) traffic +shaping, and the modification of App behavior without requiring new deployments. -: As Components explicitly define their dependencies, a Virtual Environment can -undergo validation at Release creation time. This ensures that the necessary -elements are in place for the proper functioning of Components within the -Virtual Environment. +: A Component can specify dependencies on Virtual Environment variables and +Adapters. At runtime, the Broker extracts required variables from the Virtual +Environment, attaches them to Events destined for the Component, and routes the +Event. Similarly, the Broker attaches required configuration for Events +directed to Adapters. + +: Because Components can explicitly define their dependencies, Virtual +Environments can be validated when Releases are created. Validation guarantees +that the required elements are present, thereby ensuring proper functioning of +the App Components within the context of that Virtual Environment. ## Release -: A Release binds an App Deployment and Virtual Environment together and -indicates to the Broker that Events matching the Component Routes of App -Deployment should be automatically routed to the matching Component. Once a -match is established, the request context, including the App Deployment and -Virtual Environment, is attached to all subsequent child Events generated by the -Components processing the request. +: A Release binds a versioned App Deployment and Virtual Environment together, +and defaults Genesis Events to the Routes specified in the App Deployment. diff --git a/docs/fox/fox.md b/docs/fox/fox.md index 7b7d56c..072f240 100644 --- a/docs/fox/fox.md +++ b/docs/fox/fox.md @@ -33,4 +33,4 @@ and release your KubeFox Apps. * [fox release](fox_release.md) - Release specified AppDeployment and VirtualEnvironment * [fox version](fox_version.md) - Show version information of 🦊 Fox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_build.md b/docs/fox/fox_build.md index 540aecd..75efde2 100644 --- a/docs/fox/fox_build.md +++ b/docs/fox/fox_build.md @@ -45,4 +45,4 @@ fox build (NAME) [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_completion.md b/docs/fox/fox_completion.md index 72fe2c4..b0c99e8 100644 --- a/docs/fox/fox_completion.md +++ b/docs/fox/fox_completion.md @@ -32,4 +32,4 @@ See each sub-command's help for details on how to use the generated script. * [fox completion powershell](fox_completion_powershell.md) - Generate the autocompletion script for powershell * [fox completion zsh](fox_completion_zsh.md) - Generate the autocompletion script for zsh -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_completion_bash.md b/docs/fox/fox_completion_bash.md index 676e6c2..2753ca8 100644 --- a/docs/fox/fox_completion_bash.md +++ b/docs/fox/fox_completion_bash.md @@ -51,4 +51,4 @@ fox completion bash * [fox completion](fox_completion.md) - Generate the autocompletion script for the specified shell -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_completion_fish.md b/docs/fox/fox_completion_fish.md index 922c0fa..826d71f 100644 --- a/docs/fox/fox_completion_fish.md +++ b/docs/fox/fox_completion_fish.md @@ -42,4 +42,4 @@ fox completion fish [flags] * [fox completion](fox_completion.md) - Generate the autocompletion script for the specified shell -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_completion_powershell.md b/docs/fox/fox_completion_powershell.md index c2a3265..db5e7f0 100644 --- a/docs/fox/fox_completion_powershell.md +++ b/docs/fox/fox_completion_powershell.md @@ -39,4 +39,4 @@ fox completion powershell [flags] * [fox completion](fox_completion.md) - Generate the autocompletion script for the specified shell -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_completion_zsh.md b/docs/fox/fox_completion_zsh.md index b3c9c18..44a25ec 100644 --- a/docs/fox/fox_completion_zsh.md +++ b/docs/fox/fox_completion_zsh.md @@ -53,4 +53,4 @@ fox completion zsh [flags] * [fox completion](fox_completion.md) - Generate the autocompletion script for the specified shell -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_config.md b/docs/fox/fox_config.md index 2a60b9c..311a76a 100644 --- a/docs/fox/fox_config.md +++ b/docs/fox/fox_config.md @@ -30,4 +30,4 @@ Use the config subcommand to help setup your local environment. * [fox config setup](fox_config_setup.md) - Run setup to configure 🦊 Fox * [fox config show](fox_config_show.md) - Show the current configuration -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_config_setup.md b/docs/fox/fox_config_setup.md index 4e401ac..d895d3d 100644 --- a/docs/fox/fox_config_setup.md +++ b/docs/fox/fox_config_setup.md @@ -26,4 +26,4 @@ fox config setup [flags] * [fox config](fox_config.md) - Configure 🦊 Fox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_config_show.md b/docs/fox/fox_config_show.md index e22ab0c..32c3401 100644 --- a/docs/fox/fox_config_show.md +++ b/docs/fox/fox_config_show.md @@ -26,4 +26,4 @@ fox config show [flags] * [fox config](fox_config.md) - Configure 🦊 Fox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_deploy.md b/docs/fox/fox_deploy.md index dc42310..0d2a164 100644 --- a/docs/fox/fox_deploy.md +++ b/docs/fox/fox_deploy.md @@ -32,4 +32,4 @@ fox deploy [NAME] [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_docs.md b/docs/fox/fox_docs.md index 83a8b75..5c9395a 100644 --- a/docs/fox/fox_docs.md +++ b/docs/fox/fox_docs.md @@ -33,4 +33,4 @@ fox docs [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_init.md b/docs/fox/fox_init.md index 422b31a..2c98e49 100644 --- a/docs/fox/fox_init.md +++ b/docs/fox/fox_init.md @@ -35,4 +35,4 @@ fox init [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_proxy.md b/docs/fox/fox_proxy.md index 2f1e233..f70e322 100644 --- a/docs/fox/fox_proxy.md +++ b/docs/fox/fox_proxy.md @@ -58,4 +58,4 @@ fox proxy (PORT) [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_publish.md b/docs/fox/fox_publish.md index d0cee07..30c4fa1 100644 --- a/docs/fox/fox_publish.md +++ b/docs/fox/fox_publish.md @@ -37,4 +37,4 @@ fox publish [NAME] [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_release.md b/docs/fox/fox_release.md index 9048ad4..35d183b 100644 --- a/docs/fox/fox_release.md +++ b/docs/fox/fox_release.md @@ -55,4 +55,4 @@ fox release (NAME | COMMIT | SHORT COMMIT | VERSION | TAG | BRANCH) [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023 diff --git a/docs/fox/fox_version.md b/docs/fox/fox_version.md index d8efa4b..4bb9b00 100644 --- a/docs/fox/fox_version.md +++ b/docs/fox/fox_version.md @@ -26,4 +26,4 @@ fox version [flags] * [fox](fox.md) - CLI for interacting with KubeFox -###### Auto generated by spf13/cobra on 5-Dec-2023 +###### Auto generated by spf13/cobra on 6-Dec-2023