From ff3d2406411af7be8936ea598310726e2ffa1708 Mon Sep 17 00:00:00 2001 From: Skylar Date: Mon, 30 Sep 2024 11:44:09 -0600 Subject: [PATCH] docs: update docs and README to replace "prod" with "baseline" (#260) closes #205 --------- Signed-off-by: Skylar --- README.md | 2 +- website/app/docs/concepts/flows/page.mdx | 6 +-- website/app/docs/concepts/plugins/page.mdx | 4 +- .../getting-started/fundamentals/page.mdx | 2 +- .../app/docs/getting-started/own-app/page.mdx | 42 +++++++++---------- .../app/docs/references/comparisons/page.mdx | 4 +- 6 files changed, 30 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index f1eaa158..b2263424 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ kardinal deploy -k ./obd-kardinal.yaml You can view the frontend of the demo app by going to: -`http://prod.app.localhost` +`http://baseline.app.localhost` Feel free to click around, add items to your cart, and shop! diff --git a/website/app/docs/concepts/flows/page.mdx b/website/app/docs/concepts/flows/page.mdx index 01dd8254..3a3a8e12 100644 --- a/website/app/docs/concepts/flows/page.mdx +++ b/website/app/docs/concepts/flows/page.mdx @@ -6,11 +6,11 @@ export const metadata = { In Kardinal, a flow is an ephemeral environment that developers can use for development, testing, or QA. -The default flow in Kardinal is called `stable`, and typically contains the latest versions of each service that you have in your staging cluster, i.e. the latest changes that are about to be promoted to production. +The default flow in Kardinal is called `baseline`, and typically contains the latest versions of each service that you have in your staging cluster, i.e. the latest changes that are about to be promoted to production. When Kardinal creates a flow, it will deploy the set of services that encompass the changes being made for a given feature. Kardinal will also create an ingress point for the developer to use. -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. +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 `baseline` flow. As your team onboards to Kardinal, you will be able to create flows with escalating levels of configurability: @@ -30,4 +30,4 @@ Getting more advanced flows requires defining more of your application's topolog 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 +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!) diff --git a/website/app/docs/concepts/plugins/page.mdx b/website/app/docs/concepts/plugins/page.mdx index 29913ac8..ebae4a7d 100644 --- a/website/app/docs/concepts/plugins/page.mdx +++ b/website/app/docs/concepts/plugins/page.mdx @@ -183,7 +183,7 @@ In order for Kardinal to guarantee data isolation and safety, Kardinal needs to The level of data isolation and semantics of "dev" version will be highly dependent on your service, application, and development needs. This is where we can leverage a plugin to encode this information. -For example, say we have a `postgres` database in our cluster. When creating dev flows, we'll avoid touching the "prod" postgres database by using the [`postgres-seed-plugin`](https://github.com/kurtosis-tech/postgres-seed-plugin) like so: +For example, say we have a `postgres` database in our cluster. When creating dev flows, we'll avoid touching the "baseline" postgres database by using the [`postgres-seed-plugin`](https://github.com/kurtosis-tech/postgres-seed-plugin) like so: ``` ... @@ -282,7 +282,7 @@ Using plugins to handle dev versions of external services works very similarly. The difference is that the plugin annotation gets added to the service spec of the service that depends on the external service. Accordingly, when writing the plugin, the plugin will be modifying the deployment spec of the dependent service. -For example, say we have a `cartservice` in our app that depends on an external [Neon](neon.tech) DB. When creating dev flows, we'll avoid touching the "prod" Neon database by using the [`neondb-plugin`](https://github.com/kurtosis-tech/neondb-plugin) like so: +For example, say we have a `cartservice` in our app that depends on an external [Neon](neon.tech) DB. When creating dev flows, we'll avoid touching the "baseline" Neon database by using the [`neondb-plugin`](https://github.com/kurtosis-tech/neondb-plugin) like so: ``` ... diff --git a/website/app/docs/getting-started/fundamentals/page.mdx b/website/app/docs/getting-started/fundamentals/page.mdx index 3f3ede63..8a5bf15e 100644 --- a/website/app/docs/getting-started/fundamentals/page.mdx +++ b/website/app/docs/getting-started/fundamentals/page.mdx @@ -9,7 +9,7 @@ Once Kardinal is installed and an application is deployed, developers can create kardinal flow create ``` -Kardinal will deploy the `` image alongside the stable version of the service, and that developer will be able to interact with the application as if it was using their version of their service. +Kardinal will deploy the `` image alongside the baseline version of the service, and that developer will be able to interact with the application as if it was using their version of their service. As your team onboards to Kardinal, you will be able to create flows with escalating levels of configurability: diff --git a/website/app/docs/getting-started/own-app/page.mdx b/website/app/docs/getting-started/own-app/page.mdx index acc1bfe3..30d7ab85 100644 --- a/website/app/docs/getting-started/own-app/page.mdx +++ b/website/app/docs/getting-started/own-app/page.mdx @@ -12,9 +12,9 @@ Getting started takes just a few minutes, assuming you have [installed Kardinal] To use Kardinal with your application, you will need a development Kubernetes cluster with Istio installed. -It's not important that your production cluster uses Istio. Kardinal will manage everything related to Istio on your development cluster, and your application should work just fine. +It's not important that your cluster uses Istio. Kardinal will manage everything related to Istio on your development cluster, and your application should work just fine. -Then, you'll need to install the Kardinal CLI and deploy the Kardinal Manager on your application, as described in the [install Kardinal guide](./getting-started/install) +Then, you'll need to install the Kardinal CLI and deploy the Kardinal Manager on your application, as described in the [install Kardinal guide](./getting-started/install) Then, make sure your application is using distributed tracing. Kardinal uses your trace IDs to route requests between different development versions of services to implement logical environment isolation. @@ -36,16 +36,16 @@ If you want to use a tracing system that isn't listed here, you can submit an [i ### Step 1: Annotate the application entrypoint -Kardinal can manage multiple entrypoints in your Kubernetes manifest that routes traffic into the cluster. You +Kardinal can manage multiple entrypoints in your Kubernetes manifest that routes traffic into the cluster. You can leverage access to your services either through the Kubernetes Ingress API or the Gateway API. -To get started, you just need to add the *`kardinal.dev.service/ingress`* or *`kardinal.dev.service/gateway`* -annotations to your Ingress or Gateway manifest to mark this entrypoint. The annotation should be set to `true` +To get started, you just need to add the *`kardinal.dev.service/ingress`* or *`kardinal.dev.service/gateway`* +annotations to your Ingress or Gateway manifest to mark this entrypoint. The annotation should be set to `true` for whichever Ingress or Gateway resource is the entrypoint into the cluster. ### Example using Kubernetes Ingress -Here’s an example using an Ingress resource to handle traffic, with Kardinal annotations to mark it as the +Here’s an example using an Ingress resource to handle traffic, with Kardinal annotations to mark it as the cluster entrypoint: ```yaml @@ -70,12 +70,12 @@ spec: number: 80 ``` -In this example, traffic to `web.admin.localhost` is routed to the `frontend` service on port 80 via the +In this example, traffic to `web.admin.localhost` is routed to the `frontend` service on port 80 via the Ingress resource. ### Example using Gateway API -Alternatively, you can use the Gateway API, which provides more flexibility and control over traffic routing. +Alternatively, you can use the Gateway API, which provides more flexibility and control over traffic routing. Here’s how the Gateway and HTTPRoute manifests would look, with Kardinal annotations: ```yaml @@ -97,7 +97,7 @@ spec: from: All ``` -In this example, the `Gateway` resource defines a listener on port 80, routing traffic for any subdomain +In this example, the `Gateway` resource defines a listener on port 80, routing traffic for any subdomain of `app.localhost`. ```yaml @@ -121,29 +121,29 @@ spec: port: 80 ``` -The `HTTPRoute` resource specifies that traffic to `baseline.app.localhost` should be routed to the `frontend` +The `HTTPRoute` resource specifies that traffic to `baseline.app.localhost` should be routed to the `frontend` service on port 80. ### Step 2: Deploy the main version of your application Okay, now that we've got Kardinal integrated, let's deploy our application. Run: - + ```bash kardinal deploy -k ``` - + You should now be able to view your application in the Kardinal dashboard with: - + ```bash kardinal dashboard ``` ### Step 3: Create a dev flow - + First, create a flow. Pick a service in your application to test a dev image on and run: - + ```bash kardinal flow create ``` @@ -151,8 +151,8 @@ kardinal flow create You should see some output like: ```bash kardinal flow create frontend kurtosistech/frontend:demo-frontend -INFO[0000] Using tenant UUID 483e3371-ec18-40ca-aaee-54df597d1fd2 -INFO[0000] Creating service frontend with image kurtosistech/frontend:demo-frontend in development mode... +INFO[0000] Using tenant UUID 483e3371-ec18-40ca-aaee-54df597d1fd2 +INFO[0000] Creating service frontend with image kurtosistech/frontend:demo-frontend in development mode... Flow "dev-qlm1214pgt" created. Access it on: 🌐 http://dev-qlm1214pgt.app.localhost ``` @@ -161,14 +161,14 @@ You can view all the flows in your cluster in the Kardinal dashboard: ```bash kardinal dashboard -``` +``` If you run `kardinal gateway `, Kardinal will open a gateway to the entrypoint of the flow - whatever service of your application was annotated with the `kardinal.dev.service/ingress` annotation. Whether the service is a frontend or a backend service, you will be able to access the dev flow by making requests to the returned endpoint. - + ```bash $ kardinal gateway dev-qlm1214pgt -INFO[0000] Using tenant UUID 483e3371-ec18-40ca-aaee-54df597d1fd2 +INFO[0000] Using tenant UUID 483e3371-ec18-40ca-aaee-54df597d1fd2 2024/08/07 13:50:52 Starting gateway for host: dev-qlm1214pgt.app.localhost -2024/08/07 13:50:52 All pods in namespace prod are ready and flowId dev-qlm1214pgt found +2024/08/07 13:50:52 All pods in namespace baseline are ready and flowId dev-qlm1214pgt found 2024/08/07 13:50:52 Proxy server for host dev-qlm1214pgt.app.localhost started on http://localhost:9060 ``` diff --git a/website/app/docs/references/comparisons/page.mdx b/website/app/docs/references/comparisons/page.mdx index 8f3a8278..ce23f64e 100644 --- a/website/app/docs/references/comparisons/page.mdx +++ b/website/app/docs/references/comparisons/page.mdx @@ -29,7 +29,7 @@ Devcontainers can connect your coding workflow into your Kardinal [flows](./conc Some teams create ephemeral development environments by deploying changed services into a new namespace into their Kubernetes cluster. -Then, they configure rules per namespace that defines what is shared between that development namespace, and the "stable" shared namespace. These shared resources include the state that backs the applciation (dbs, queues, caches), as well as shared microservices. +Then, they configure rules per namespace that defines what is shared between that development namespace, and the "baseline" shared namespace. These shared resources include the state that backs the applciation (dbs, queues, caches), as well as shared microservices. This is a sophisticated approach that can be very effective. Using this approach is similar to using Kardinal in "single-service" and "multi-service" mode, in the sense of creating flows that can contain one or more development versions of services. @@ -70,4 +70,4 @@ If you want to test custom CRDs, or other Kubernetes-specific things like oeprat 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 +