From 5b6503f78b1682217804359a972dd07afd018ceb Mon Sep 17 00:00:00 2001 From: Galen Marchetti Date: Wed, 24 Jul 2024 11:49:24 -0400 Subject: [PATCH] docs: Update README.md (#40) Signed-off-by: Galen Marchetti --- README.md | 389 +++--------------------------------------------------- 1 file changed, 18 insertions(+), 371 deletions(-) diff --git a/README.md b/README.md index 0f324913..1365d3a8 100644 --- a/README.md +++ b/README.md @@ -4,395 +4,42 @@ ![Kardi B](https://kardinal.dev/_next/static/media/kardinal-orange.65ea335b.png) -The lightest-weight Kubernetes development environments in the world. Stop duplicating everything in your Kubernetes clusters. Deploy the minimum resources necessary to develop and test directly in one production-like environment. +The lightest-weight Kubernetes development environments in the world. Stop duplicating everything across your dev, test, and QA Kubernetes clusters. Deploy the minimum resources necessary to develop and test directly in one production-like environment. -## Quick install +## Can't wait to get started? -```bash -curl get.kardinal.dev -sL | sh -``` +Visit the [Kardinal playground](https://github.com/kurtosis-tech/kardinal-playground/) to experience a simple demonstration of how Kardinal can enhance your development workflow. ## What is Kardinal? -Kardinal is a traffic control and data isolation layer for Kubernetes that enables engineers to efficiently do development and QA work within a single stable cluster. Instead of implementing isolation at the cluster level, Kardinal implements isolation by deploying development versions of services side-by-side with their "staging" versions, and defining isolated traffic routes through the cluster. +Kardinal is a traffic control and state isolation layer for Kubernetes that enables engineers to efficiently do development and QA work within a single stable cluster. Instead of implementing isolation at the cluster level, Kardinal implements isolation by deploying development versions of services side-by-side with their "staging" versions, and defining isolated traffic routes through the cluster. -These traffic routes connect development versions to their appropriate dependencies, and to development versions of any databases, queues, caches, and external APIs that you may need. - -These traffic routes are effectively "logical environments" or "views" on top of a single cluster. In Kardinal, these are called "flows". Flows enable isolation for the purpose of development, testing, and QA with the lowest possible resource footprint. +These traffic routes connect development versions to their appropriate dependencies, and to development versions of any databases, queues, caches, and external APIs that you may need. They are effectively "logical environments" or "views" on top of a single cluster. In Kardinal, these are called "flows". Flows enable isolation for the purpose of development, testing, and QA with the lowest possible resource footprint. It all happens in one cluster, with the absolute minimum duplication of resources necessary. ## How it Works -Kardinal is implemented as a set of sidecars that are deployed next to your stateless services, and proxies that set on top of your stateful services. It's easy to install and easy to uninstall - just deploy the the sidecars in your staging cluster, and use the Kardinal control plane to manage your development and test environments. If you want to uninstall Kardinals, just remove the sidecars. - -To use Kardinal, just drop the Kardinal sidecars into your staging environment. Then run: - -```bash -# Create a dev flow -kardinal create-dev-flow -``` - -This creates a dev flow for your service with access to all the dependencies in your staging environment, while ensuring complete isolation of your development and testing work. - -## Join the Beta Program - -Our beta program for a select group of developers is coming soon! Be among the first to experience the future of software development: - -- Email us at: [hello@kardinal.dev](mailto:hello@kardinal.dev) to learn more about joining the beta -- Get early access to Kardinal -- Provide valuable feedback to shape the future of the product - -## Try the Kardinal Playground - -Can't wait to get started? Check out our proof of concept: - -- Visit the [Kardinal playground](https://github.com/kurtosis-tech/kardinal-playground/) -- Experience a simple demonstration of how Kardinal can enhance your development workflow -- Get a taste of developing directly in production, risk-free - -## Get Support - -Have questions or need assistance? We're here to help: - -- Email us at: [hello@kardinal.dev](mailto:hello@kardinal.dev) -- Check out our documentation: [https://kardinal.dev/docs](https://kardinal.dev/docs) - ---- - -## Architecture - -Kardinal main components are the Kardinal CLI and the Kardinal Manager. The Kardinal CLI allows the user to manage the development flows. The Kardinal Manager retrieves the latest configuration from the Kardinal Cloud and applies changes to the K8S user services topology. - -![kardinal-dev-overview](./img/kardinal-dev-overview.png?raw=true) - -The Kardinal Cloud code is not open-source. - -### Kardinal CLI - -The Kardinal CLI is a standalone tool interacting with the Kardinal Cloud to manage the dev flows. - -### Kardinal Manager - -The Kardinal Manager retrieves the latest user services topology from the Kardinal Cloud and applies the changes by interacting with the Istio client and K8S client. The Manager manages traffic using Istio objects such as virtual services and destination rules. The Manager also updates the K8S services and deployments. - -## Quickstart - -### How to run Kardinal and use the voting app example to test the dev flow - -#### Prerequisites - -You will need the following tools installed (they will be already available if you are using the nix shell provided by this repository): - -- A local Kubernetes cluster ([Minikube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Fx86-64%2Fstable%2Fbinary+download) used in this example) -- Istio resources installed in the local cluster (use the [getting started doc](https://istio.io/latest/docs/setup/getting-started/#download)) - -```bash -minikube start --driver=docker --cpus=10 --memory 8192 --disk-size 32g -minikube addons enable ingress -minikube addons enable metrics-server -istioctl install --set profile=default -y -minikube dashboard -``` - -- Both `prod.app.localhost` and `dev.app.localhost` defined in the host file - -```bash -# Add these entries in the '/private/etc/hosts' file -127.0.0.1 prod.app.localhost -127.0.0.1 dev.app.localhost -``` - -#### Steps - -##### Deploy the production voting app - -1. Use the `kardinal` provided by the Nix shell (enter using `nix develop`) or follow [this to build and run the cli][run-build-cli] -2. Deploy `Kardinal Manager` in the local kubernetes cluster and set the `Kardinal Control` location (we are going to use the cloud version on these steps) - -```bash -kardinal manager deploy kloud-kontrol -``` - -3. Copy the tenant UUID generated while running this command - -```bash -# This log line will be printed in the terminal, copy the generated UUID -INFO[0000] Using tenant UUID 58d33536-3c9e-4110-aa83-bf112ae94a49 -``` - -3. Deploy the voting-app application with Kardinal - -```bash -kardinal deploy --k8s-manifest ./examples/voting-app/k8s-manifest.yaml -``` - -4. Check the current topology in the cloud Kontrol FE using this URL: https://app.kardinal.dev/{use-your-tenant-UUID-here}/traffic-configuration -5. Start the tunnel to access the services (you may have to provide you password for the underlying sudo access) - -```bash -minikube tunnel -``` - -6. Open the [production page in the browser](http://prod.app.localhost/) to see the production `voting-app` - -##### Deploy the voting app development version in the same cluster - -1. Create a new flow to test a development `voting-app-ui-v2` version in production - -```bash -kardinal flow create voting-app-ui kurtosistech/demo-voting-app-ui-v2 --k8s-manifest ./examples/voting-app/k8s-manifest.yaml -``` - -2. Check how the topology has changed, to reflect both prod and the dev version, in the cloud Kontrol FE using this URL: https://app.kardinal.dev/{use-your-tenant-UUID-here}/traffic-configuration -3. Open the [development voting-app-ui-v2 page in the browser](http://dev.app.localhost/) to see the development `voting-app-ui-v2` - -##### Remove the voting app development version from the same cluster - -1. Remove the flow created for the `voting-app-ui-v2` - -```bash -kardinal flow delete --k8s-manifest ./examples/voting-app/k8s-manifest.yaml -``` - -2. Check the topology again to, it's showing only the production version as the beginning, in the cloud Kontrol FE using this URL: https://app.kardinal.dev/{use-your-tenant-UUID-here}/traffic-configuration -3. Open the [development voting-app-ui-v2 page in the browser](http://dev.app.localhost/) to check that it was successfully removed -4. Open the [production page in the browser](http://prod.app.localhost/) to check that it didn't change - -##### Clean - -1. Remove `Kardinal Manager` from the cluster - -```bash -kardinal manager remove -``` - -2. Remove the `voting-app` application from the cluster - -```bash -kubectl delete ns prod -``` - -## Deploying Kardinal on a Kubernetes Cluster - -These instructions provide a guide for deploying Kardinal on any Kubernetes cluster, whether it's a local setup like Minikube, a managed cloud service, or your own self-hosted cluster. We'll use kubectl port-forwarding to access the services, which works universally across different Kubernetes setups. - -### Prerequisites - -- A Kubernetes cluster (e.g., Minikube, EKS, GKE, AKS, or any other Kubernetes distribution) -- kubectl installed and configured to access your cluster - -### Steps - -1. Install the Kardinal CLI: - -```bash -curl https://raw.githubusercontent.com/kurtosis-tech/kardinal/main/scripts/install_cli.sh -s | sh -``` - -2. Install Istio (if not already installed): - -If you don't already have Istio installed in your cluster, follow these steps to install it: - -```bash -curl -L https://istio.io/downloadIstio | ISTIO_VERSION=1.22.1 TARGET_ARCH=x86_64 sh - -cd istio-1.22.1 -export PATH=$PWD/bin:$PATH -echo 'export PATH=$PATH:'"$PWD/bin" >> ~/.bashrc -istioctl install --set profile=demo -y -cd .. -``` - -If you already have Istio installed, you can skip this step. - -3. Deploy the Kardinal Manager: - -```bash -kardinal manager deploy kloud-kontrol -``` - -4. Note the tenant UUID generated during this process. You'll need this to check your traffic configuration. - -5. Clone the Kardinal Playground repository to get the voting app demo: - -```bash -git clone https://github.com/kurtosis-tech/kardinal-playground.git -cd kardinal-playground/voting-app-demo -``` - -6. Deploy the voting-app application with Kardinal: - -```bash -kardinal deploy --k8s-manifest k8s-manifest.yaml -``` - -7. Check the initial Kardinal traffic configuration: - Visit https://app.kardinal.dev/{your-tenant-id} (replace {your-tenant-id} with the UUID from step 4) - You should see only the production version of your application in the traffic configuration. - -8. Download the port-forwarding script: - -```bash -curl -o kardinal-port-forward.sh https://raw.githubusercontent.com/kurtosis-tech/kardinal/main/scripts/kardinal-port-forward.sh -``` - -This script sets up port-forwarding for accessing the services. - -9. Make the script executable: - -```bash -chmod +x kardinal-port-forward.sh -``` - -10. Run the script to set up port-forwarding for the production version: - -```bash -./kardinal-port-forward.sh prod -``` - -This will set up port-forwarding for the production version of the voting app. - -11. Access the production application: - - Production version: http://localhost:8090 - -12. To create a new development flow: - -```bash -kardinal flow create voting-app-ui voting-app-ui-dev --k8s-manifest k8s-manifest.yml -``` - -13. After creating the development flow, check the Kardinal traffic configuration again: - Visit https://app.kardinal.dev/{your-tenant-id} - You should now see both the production and development versions of your application in the traffic configuration. - -14. Run the port-forwarding script again to include the new development version: - -```bash -./kardinal-port-forward.sh all -``` - -Now you can access both the production and development versions: - - Production version: http://localhost:8090 - - Development version: http://localhost:8091 - -15. To remove the development flow: - -```bash -kardinal flow delete --k8s-manifest k8s-manifest.yml -``` - -16. After deleting the development flow, check the Kardinal traffic configuration once more: - Visit https://app.kardinal.dev/{your-tenant-id} - You should now see only the production version of your application in the traffic configuration, confirming that the development flow has been removed. - -17. Clean up: - - Stop the port-forwarding: `pkill -f "kubectl port-forward.*voting-app"` - - Remove Kardinal Manager: `kardinal manager remove` - - Remove the voting-app: `kubectl delete ns prod` - -By following these steps, you can deploy and manage Kardinal on any Kubernetes cluster, using kubectl port-forwarding to access the services. This method works universally across different Kubernetes setups, including Minikube, cloud-managed Kubernetes services, and self-hosted clusters. - -Remember to check the Kardinal traffic configuration at https://app.kardinal.dev/{your-tenant-id} before and after creating or deleting development flows to verify the changes in your application's topology. - -## Development instructions - -1. Enter the dev shell and start the local cluster: - -```bash -nix develop -``` - -2. You're also likely to use a local k8s, in this case minikube is available to use: - -```bash -kubectl config set-context minikube -minikube start --driver=docker --cpus=10 --memory 8192 --disk-size 32g -minikube addons enable ingress -minikube addons enable metrics-server -istioctl install --set profile=demo -y -minikube dashboard -``` - -On a second terminal, start the tunnel: - -```bash -minikube tunnel -``` - -## Deploying Kardinal Manager to local cluster - -You can use tilt deploy and keeping the image hot-reloading: - -```bash -tilt up -``` - -Or you can use the Kardinal CLI to deploy it - -Option 1: Using Kloud Kardinal Kontrol - -```bash -# the Kloud Kontrol will always pull the latest image version from Docker Hub -kardinal manager deploy kloud-kontrol -``` - -Option 2: Using the local Kardinal Kontrol with Minikube (better for the dev flow) - -```bash -# First build the image - -# set the docker context to minikube -eval $(minikube docker-env) -docker load < $(nix build ./#kardinal-manager-container --no-link --print-out-paths) - -# the local-minikube Kontrol will use the image builded -kardinal manager deploy local-minikube -``` - -## Deploying Redis Overlay Service to local cluster - -Building and loading image into minikube: - -```bash -# First set the docker context to minikube -eval $(minikube docker-env) -docker load < $(nix build ./#redis-proxy-overlay-container --no-link --print-out-paths) -``` - -To build and run the service directly: - -```bash -nix run ./#redis-proxy-overlay -``` - -## Publishing multi-arch images - -To publish multi-arch images, you can use the following command: +A cluster with multiple logical environments (”dev flows”) running in it may look like the following image. -```bash -$(nix build .#publish--container --no-link --print-out-paths)/bin/push +![infographic](https://github.com/user-attachments/assets/343a44bc-2119-4368-a338-f27dc2271d8f) -# For instance, to publish the redis proxy overlay image: -$(nix build .#publish-redis-proxy-overlay-container --no-link --print-out-paths)/bin/push -``` +Some services have multiple distinct versions (5 for `order-service`, 8 for `analytics-service`), because there are many version requirements for that service across the set of logical environments. Others only have one version deployed (`entity-service` ), because in this example, every single logical environment only depends on the stable version of `entity-service`. Because isolation is implemented at the level of traffic routing, you can maximally reuse shared resources, and you can spin up a new logical environment by only deploying the absolute minimum number of changes resources necessary. -## Running Kardinal CLI +The same multi-version deploy and de-duplication mechanism works for stateful services like Postgres or state-bearing external services like Stripe. If an isolated version of Postgres is required in a logical environment, seeded with new test data or a snapshot of data in the stable environment, it will spin up automatically for the logical environments that need it. In the case of external service like Stripe, a proxy that switches requests between dev API keys will serve to provide the necessary isolation between logical environments. -To build and run the service directly: +Stateful services like databases and managed services like external APIs are supported via an open-source plugin ecosystem, so its easy to add support for the set of dependencies you have in your architecture. -```bash -nix run ./#kardinal-cli -``` +Kardinal is implemented as a set of sidecars that are deployed next to your stateless services, and proxies that sit on top of those stateful services or external, managed services (like Stripe or an external API hosted outside of Kubernetes). -### Regenerate gomod2nix.toml +It's easy to install and easy to uninstall - just deploy the the sidecars in your staging cluster, and use the Kardinal control plane to manage your development and test environments. If you want to uninstall Kardinal, just remove the sidecars. -You will need to do this every time a `go.mod` file is edited +## Quick start -```bash -nix develop -gomod2nix generate -``` +Steps needed to get up and running with Kardinal will be published when we release a version that works on generic cluster topologies. Estimated release data is August 2nd, 2024. - +## Resources -[run-build-cli]: #running-kardinal-cli +- Explore our [docs](https://kardinal.dev) to learn more about how Kardinal works +- Ask questions and get help in our community [forum](https://discuss.kardinal.dev). +- Read our [blog](https://blog.kardinal.dev/) for tips from developers and creators.