diff --git a/website/app/docs/concepts/flows/page.mdx b/website/app/docs/concepts/flows/page.mdx index a18d459d..01dd8254 100644 --- a/website/app/docs/concepts/flows/page.mdx +++ b/website/app/docs/concepts/flows/page.mdx @@ -12,10 +12,22 @@ When Kardinal creates a flow, it will deploy the set of services that encompass Any communication made through the ingress point will be routed to the versions of the services that are a part of the flow. Any services that are a part of the application, but aren't being changed as a part of the feature, will still be available from the `stable` flow. -This basic use case is similar to deploying new versions of services in a separate namespace and sharing everything else with a shared dev cluster. However, Kardinal gets more interesting once you're fully onboarded and have defined your entire service dependency graph. +As your team onboards to Kardinal, you will be able to create flows with escalating levels of configurability: -Once your service dependency graph is defined, Kardinal can provide state isolation between flows via [stateful service plugins](./concepts/plugins). +1. **Single-service flows**: deploy a single service to test a new version of a service, sharing application state with all other flows +2. **Multi-service flows**: deploy a set of services together to test a larger feature change involving multiple services, sharing application state with all other flows +3. **State-isolated flows**: deploy a set of services together with new, isolated state (dbs, caches, queues) to test database migrations or other state-layer changes +4. **Full application flows**: deploy an independent, full application with its own state layer for completely isolated end-to-end testing -The cost savings of this use case (isolating state between flows) can reach into the millions of dollars for large organizations who use ephemeral environments or isolated dev sandboxes. +Getting more advanced flows requires defining more of your application's topology in Kardinal: -With Kardinal, for every dev, test, or QA need, you will only ever deploy the minimum possible resources needed to test the feature, and you will reuse everything else across your development team. \ No newline at end of file +| Flow Type | Onboarding Requirements | +|-----------|-------------------| +| Single-service flows | Your service implements distributed tracing | +| Multi-service flows | A subset of your services implement distributed tracing | +| State-isolated flows | A subset of your services implement distributed tracing, explicitly define their service dependencies, and you use [state isolation plugins](./concepts/plugins) for all state and managed services | +| Full application flows | All of your services implement distributed tracing, explicitly define their service dependencies, and you use [state isolation plugins](./concepts/plugins) for all state and managed services | + +The cost savings of the final two use cases (isolating state between flows) can reach into the millions of dollars for large organizations who use isolated dev sandboxes for ephemeral environments. + +To see how, and to calculate savings for your own organization, check out our [cost savings dashboard](https://kardinal.streamlit.app) hosted on Streamlit. (If the dashboard is "sleeping", just click to wake it up!) \ No newline at end of file diff --git a/website/app/docs/concepts/plugins/page.mdx b/website/app/docs/concepts/plugins/page.mdx index f1282610..a7d426b6 100644 --- a/website/app/docs/concepts/plugins/page.mdx +++ b/website/app/docs/concepts/plugins/page.mdx @@ -2,7 +2,7 @@ export const metadata = { title: "Kardinal Docs | Plugins", }; -# Plugins +# Plugins for State Isolation Kardinal leverages a plugin system that allows developers to encode logic of how dev versions of stateful services (databases, queues, APIs) and external services (Stripe API, Mailchimp, managed database like Amazon RDS or Neon DB) should be handled. Plugins work by offering developers an api to write Python-based scripts that can dynamically alter Kubernetes deployment specs, providing a way to handle stateful and external services in a safer manner. diff --git a/website/app/docs/page.mdx b/website/app/docs/page.mdx index aee6b9f5..7c70ed7e 100644 --- a/website/app/docs/page.mdx +++ b/website/app/docs/page.mdx @@ -8,7 +8,12 @@ Kardinal is a framework for creating extremely lightweight ephemeral development In Kardinal, an environment is called a "[flow](concepts/flows)" because it represents a path that a request takes through the cluster. Versions of services that are under development are deployed on-demand, and then shared across all development work that depends on that version. -To test a new feature, Kardinal will deploy the set of services that are changing that feature. Then, when you create a flow, any requests related to testing that feature are routed to those versions. +When you create a [flow](concepts/flows) to test a feature, Kardinal will deploy only the set of services that are changing for that feature. Then, any requests related to testing that feature are routed to those versions. -To get started, [install Kardinal](getting-started/install) and then [create your first flow](getting-started/own-app). +As you onboard deeper into Kardinal, you will be able to set up isolated state for [flows](concepts/flows) when desired (i.e. for testing database migrations or write-intensive workloads on shared state). +Even with isolated state per [flow](concepts/flows), Kardinal will still deploy the absolute minimum resources necessary to test the changes. Isolation is done at the level of the request route, not by duplicating services in your cluster unnecessarily. + +To see how Kardinal compares to other tools, and to get an idea of how would fit into your workflow, check out the [comparisons to alternatives](references/comparisons) section. + +To get started, [install Kardinal](getting-started/install) and then [create your first flow](getting-started/own-app). \ No newline at end of file diff --git a/website/app/docs/references/comparisons/page.mdx b/website/app/docs/references/comparisons/page.mdx index 9a183dbc..8f3a8278 100644 --- a/website/app/docs/references/comparisons/page.mdx +++ b/website/app/docs/references/comparisons/page.mdx @@ -4,8 +4,18 @@ import Collapsible from '@/components/Collapsible'; This page is updated with comparisons to other techniques for developing and testing applications in Kubernetes, to give you a better understanding of how Kardinal fits into the picture. + +Kardinal has some similarities to [Capsule](https://capsule.clastix.io/), in the sense that both enable multitenancy with isolation with a single Kubernetes cluster. + +However, Capsule is focused on providing multitenancy through a collection of namespaces in the cluster, which use shared configurations like Network and Security policies, Resource Quotas, Limit Ranges, and RBAC. + +Kardinal does not configure these Kubernetes-level components, and instead focuses on providing multitenancy at the "application" level, with the ability to reuse things like microservices, database, queues, and caches between tenants when necessary and isolating them between tenats when necessary. + +You could use Capsule alongside Kardinal - Capsule would provision Kubernetes-level tenants, and then within those tenants, you could use Kardinal to further do multiple application deploys for dev or test purposes. + + -Using Kardinal in "single-service" mode is also similar to using [Devcontainers](https://code.visualstudio.com/docs/devcontainers/attach-container) with the Kubernetes extension to deploy the developmentcontainer directly into your Kubernetes cluster. +Using Kardinal in "single-service" mode is also similar to using [Devcontainers](https://code.visualstudio.com/docs/devcontainers/attach-container) with the Kubernetes extension to deploy the devcontainer directly into your Kubernetes cluster. Going further with Kardinal gives you capabilities that are more difficult to achieve with Devcontainers, such as: - Multi-service isolated development environments @@ -46,4 +56,18 @@ Going further with Kardinal gives you capabilities that are more difficult to ac If you're already using Telepresence, or you're looking for a way to connect your local machine to a Kubernetes cluster, we recommend using Kardinal along with Telepresence to get the best possible experience. Telepresence can connect your laptop into your Kardinal [flows](./concepts/flows), and Kardinal can provide multi-service routing and state isolation for a more robust development and testing experience. + + + +Kardinal has some similarities to [vclusters](https://www.vcluster.com/), in the sense that both enable multitenancy with isolation with a single Kubernetes cluster. + +However, vclusters are targeted towards providing the full Kubernetes experience within each tenant. This means each tenant gets their own API server, control plane, syncer, and other Kubernetes-level components. + +Kardinal does not provide these Kubernetes-level components, and instead focuses on providing multitenancy at the "application" level. + +If you want to test custom CRDs, or other Kubernetes-specific things like oeprators, vclusters are the best fit. Or, if you do really want a stronger isolation guarantees between tenants without deploying separate clusters, vclusters will work great. + +However if you're just testing application-level changes, Kardinal will provide the deploys you need in an lighter-weight way. + +You could use vclusters alongside Kardinal - vclusters would provision virtual Kubernetes clusters, and then within those virtual clusters, you could use Kardinal to further do multiple application deploys for dev or test purposes. \ No newline at end of file diff --git a/website/components/DocsNav.tsx b/website/components/DocsNav.tsx index 587f4d43..dfeb81e4 100644 --- a/website/components/DocsNav.tsx +++ b/website/components/DocsNav.tsx @@ -35,7 +35,7 @@ const navItems: NavItem[] = [ title: "Concepts", children: [ { path: "flows", title: "Flows" }, - { path: "plugins", title: "Stateful Service Plugins" }, + { path: "plugins", title: "Plugins for State Isolation" }, ], }, {