diff --git a/_data/docs_nav.yml b/_data/docs_nav.yml index 4ae06cb..e1d8f11 100644 --- a/_data/docs_nav.yml +++ b/_data/docs_nav.yml @@ -11,11 +11,12 @@ - title: Quick Start Guide url: /docs/getting-started/quick-start-guide/ - title: Installation Guide - children: - - title: Single-cluster Setup - url: /docs/getting-started/single-cluster/ - - title: Multi-cluster Setup - url: /docs/getting-started/multi-cluster/ + url: /docs/getting-started/single-cluster/ + # children: + # - title: Single-cluster Setup + # url: /docs/getting-started/single-cluster/ + # - title: Multi-cluster Setup + # url: /docs/getting-started/multi-cluster/ - title: Deploy Your First Component url: /docs/getting-started/deploy-your-first-component/ - title: Learn from Examples @@ -32,12 +33,12 @@ url: /docs/core-concepts/resource-relationship/ - title: Navigating OpenChoreo url: /docs/core-concepts/navigating-openchoreo/ -- title: Integrating with OpenChoreo - children: +# - title: Integrating with OpenChoreo +# children: # - title: CI Integration # url: /docs/integrating-with-openchoreo/ci-integration/ - - title: GitOps - url: /docs/integrating-with-openchoreo/gitops/ + # - title: GitOps + # url: /docs/integrating-with-openchoreo/gitops/ - title: Reference children: - title: Frequently Asked Questions (FAQ) diff --git a/docs/getting-started/deploy-your-first-component.md b/docs/getting-started/deploy-your-first-component.md index 6d0b2f8..bc4841b 100644 --- a/docs/getting-started/deploy-your-first-component.md +++ b/docs/getting-started/deploy-your-first-component.md @@ -5,346 +5,134 @@ title: Deploy Your First Component # Deploy Your First Component -This guide walks you through deploying your first component on OpenChoreo. By the end of this tutorial, you'll have a running web service accessible through the internet, complete with monitoring and security configured automatically. +This guide walks you through deploying your first component on OpenChoreo. By the end of this tutorial, you'll have a running web service accessible through the platform, complete with monitoring and security configured automatically. ## Prerequisites Before you begin, ensure you have: -- ✅ **OpenChoreo installed** in your Kubernetes cluster ([Installation Guide](/docs/getting-started/install-in-your-cluster/)) +- ✅ **OpenChoreo installed** in your Kubernetes cluster ([Single Cluster Setup](/docs/getting-started/single-cluster/)) - ✅ **kubectl** configured to access your cluster -- ✅ **choreo CLI** installed and authenticated -- ✅ **A sample application** (we'll provide one if you don't have your own) +- ✅ **OpenChoreo context** set to your cluster (should be `kind-openchoreo` if following the setup guide) ## Step 1: Verify Your Setup -First, let's confirm OpenChoreo is running correctly: +First, make sure you have setup choreo on your local cluster following the [guide](./single-cluster.md) -```bash -# Check OpenChoreo installation -kubectl get pods -n openchoreo-system - -# Verify CLI connection -choreo system status -``` - -You should see all OpenChoreo components running and the CLI connecting successfully. - -## Step 2: Create Your First Project - -Every component in OpenChoreo belongs to a project. Let's create one: - -```bash -# Create a new project -choreo project create my-first-project \ - --description "My first OpenChoreo project" - -# Verify project creation -choreo project list -``` - -## Step 3: Prepare Your Application - -For this tutorial, we'll use a simple Node.js web service. You can either: - -### Option A: Use Our Sample Application - -Clone the OpenChoreo sample repository: - -```bash -git clone https://github.com/openchoreo/samples.git -cd samples/hello-world-nodejs -``` - -### Option B: Use Your Own Application - -If you have your own application, ensure it: -- Listens on a configurable port (via environment variable) -- Has a health check endpoint -- Is containerizable - -## Step 4: Create Component Definition - -Create a component definition file that tells OpenChoreo how to deploy your application: - -```yaml -# component.yaml -apiVersion: choreo.dev/v1 -kind: Component -metadata: - name: hello-world - namespace: my-first-project -spec: - # Component type - determines how it's deployed - type: service - - # Runtime environment - runtime: nodejs - - # Source code location - source: - git: - repository: https://github.com/openchoreo/samples.git - path: hello-world-nodejs - branch: main - - # Build configuration - build: - buildpacks: true - - # Network endpoints - endpoints: - - name: web - port: 3000 - path: / - visibility: public - health: - path: /health - initialDelaySeconds: 10 - periodSeconds: 5 - - # Resource requirements - resources: - requests: - cpu: "100m" - memory: "128Mi" - limits: - cpu: "500m" - memory: "256Mi" - - # Environment variables - env: - - name: PORT - value: "3000" - - name: NODE_ENV - value: "production" -``` +You should see all OpenChoreo components running with the control plane and data plane pods in `Running` status. -## Step 5: Deploy Your Component +## Step 2: Deploy the Go Greeter Service -Apply the component definition to deploy your application: +For this tutorial, we'll use the Go Greeter Service sample that comes with OpenChoreo. This is a simple web service that demonstrates OpenChoreo's core capabilities. ```bash -# Deploy the component -kubectl apply -f component.yaml - -# Watch the deployment progress -choreo component status hello-world --watch +# Deploy the greeter service (Component, Workload, Service) +kubectl apply -f https://raw.githubusercontent.com/openchoreo/openchoreo/main/samples/from-image/go-greeter-service/greeter-service.yaml ``` -You'll see OpenChoreo: -1. **Building** your application using Cloud Native Buildpacks -2. **Creating** Kubernetes resources (Deployment, Service, etc.) -3. **Configuring** network policies and security -4. **Setting up** monitoring and observability +This single command creates: +- **Component**: Defines the application and its requirements +- **Workload**: Specifies the container image and runtime configuration +- **Service**: Configures the API endpoint and network access -## Step 6: Monitor the Deployment +## Step 3: Monitor the Deployment Track your component's deployment progress: ```bash -# Check component status -choreo component status hello-world - -# View deployment events -kubectl get events -n my-first-project --sort-by=.metadata.creationTimestamp - -# Check pod status -kubectl get pods -n my-first-project -l choreo.dev/component=hello-world -``` - -## Step 7: Access Your Application +# Check that all resources are created +kubectl get component,workload,service,api -A -Once deployed, get the access URL for your component: +# Check the component status +kubectl get component greeter-service -```bash -# Get component endpoint information -choreo component get hello-world --show-endpoints - -# Or check via kubectl -kubectl get httproutes -n my-first-project +# Monitor the workload deployment +kubectl get workload greeter-service ``` -Your application will be accessible via a URL like: -`https://hello-world.my-first-project.your-domain.com` +## Step 4: Verify the Deployment -## Step 8: Verify Everything Works - -Test your deployed application: +Wait for the service to be ready (this may take 1-2 minutes): ```bash -# Test the application endpoint -curl https://hello-world.my-first-project.your-domain.com +# Check the actual Kubernetes deployment +kubectl get deployment -A | grep greeter -# Test the health check -curl https://hello-world.my-first-project.your-domain.com/health +# Verify pods are running +kubectl get pods -A | grep greeter -# Check application logs -choreo logs component hello-world --tail 50 +# Check HTTP routes are configured +kubectl get httproute -A -o wide ``` -## Step 9: Explore What OpenChoreo Created +## Step 5: Test Your Application -Let's examine what OpenChoreo automatically created for your component: +Test the greeter service from inside the cluster: ```bash -# View all resources created for your component -kubectl get all -n my-first-project -l choreo.dev/component=hello-world - -# Check network policies (security) -kubectl get networkpolicies -n my-first-project - -# View service monitor (observability) -kubectl get servicemonitors -n my-first-project - -# Check ingress configuration -kubectl get httproutes -n my-first-project +# Test the greeter service endpoint +kubectl run test-curl --image=curlimages/curl --rm -i --restart=Never -- \ + curl -v -k https://gateway-external.openchoreo-data-plane.svc.cluster.local/default/greeter-service/greeter/greet \ + -H "Host: development.choreoapis.localhost" ``` -You'll see that OpenChoreo automatically created: -- **Deployment** - Manages your application pods -- **Service** - Provides stable networking -- **HTTPRoute** - Configures ingress routing -- **NetworkPolicy** - Enforces security boundaries -- **ServiceMonitor** - Enables metrics collection -- **HorizontalPodAutoscaler** - Handles automatic scaling - -## Step 10: Make Changes and Redeploy - -Let's make a change to see OpenChoreo's update capabilities: - -```yaml -# Update component.yaml - change replica count -spec: - replicas: 2 # Add this line - # ... rest of configuration +You should receive a successful response: ``` - -```bash -# Apply the update -kubectl apply -f component.yaml - -# Watch the rolling update -kubectl rollout status deployment/hello-world -n my-first-project +Hello, Stranger! ``` -## Understanding What Happened - -Congratulations! You've successfully deployed your first component. Here's what OpenChoreo did behind the scenes: - -### 🏗️ **Build Process** -- Detected your Node.js application -- Used Cloud Native Buildpacks to create a container image -- Stored the image in the configured registry - -### 🚀 **Deployment** -- Created Kubernetes Deployment with your specifications -- Applied security contexts and resource limits -- Configured health checks and readiness probes +This confirms that: +- ✅ Your component is deployed and running +- ✅ The API gateway is properly configured +- ✅ Network routing is working correctly +- ✅ Security policies are applied automatically -### 🔒 **Security** -- Implemented network policies for zero-trust networking -- Configured service-to-service mTLS encryption -- Applied Pod Security Standards +## Step 6: Explore What OpenChoreo Created -### 🌐 **Networking** -- Created HTTPRoute for external access -- Configured load balancing and traffic routing -- Set up TLS termination - -### 📊 **Observability** -- Enabled metrics collection via Prometheus -- Configured log aggregation -- Set up distributed tracing hooks - -## Next Steps - -Now that you've deployed your first component, explore these next steps: +Let's examine what OpenChoreo automatically created for your component: -### 🔄 **Add More Components** ```bash -# Create a database component -choreo component create database \ - --type stateful \ - --runtime postgres \ - --project my-first-project -``` +# View the OpenChoreo resources +kubectl get component,workload,service,api -n default -### 🔗 **Connect Components** -Learn how to establish secure connections between components: -```yaml -# In your web service component -spec: - connections: - - name: database - target: postgres - port: 5432 -``` +# Check the underlying Kubernetes resources +kubectl get deployment,pod,svc -A | grep greeter -### 🌍 **Multiple Environments** -Deploy to different environments: -```bash -# Create staging environment -choreo environment create staging --project my-first-project +# View the HTTP routing configuration +kubectl describe httproute -A | grep -A 20 greeter -# Deploy to staging -choreo component deploy hello-world --environment staging +# Check the API definition +kubectl get api greeter-service -n default -o yaml ``` -### 📈 **Advanced Configuration** -Explore advanced features: -- Custom build configurations -- Advanced networking rules -- Scaling policies -- Monitoring dashboards +OpenChoreo automatically created: +- **Component** - High-level application definition +- **Workload** - Container deployment specification +- **Service** - API service configuration +- **API** - OpenAPI specification and routing +- **Deployment** - Kubernetes deployment managing pods +- **Service** - Kubernetes service for networking +- **HTTPRoute** - Gateway API routing configuration -## Troubleshooting +## Summary -### Common Issues +You've successfully: +- ✅ Deployed your first OpenChoreo component from a container image +- ✅ Tested API access through the OpenChoreo gateway +- ✅ Explored the resources OpenChoreo created automatically -**Component Stuck in "Building" State** -```bash -# Check build logs -choreo logs build hello-world +Your application is now running in a production-ready environment with enterprise-grade security, networking, and observability—all configured automatically by OpenChoreo! -# Verify source repository access -git clone -``` +**Ready for more?** Try deploying additional samples or start building your own components using OpenChoreo's powerful abstractions. -**Application Not Accessible** -```bash -# Check ingress configuration -kubectl describe httproute hello-world -n my-first-project +## Clean Up -# Verify DNS resolution -nslookup hello-world.my-first-project.your-domain.com -``` +To remove the sample application: -**Pod CrashLoopBackOff** ```bash -# Check application logs -kubectl logs -l choreo.dev/component=hello-world -n my-first-project +# Remove the greeter service +kubectl delete -f https://raw.githubusercontent.com/openchoreo/openchoreo/main/samples/from-image/go-greeter-service/greeter-service.yaml -# Verify health check endpoint -kubectl exec -it -n my-first-project -- curl localhost:3000/health +# Remove the build sample (if deployed) +kubectl delete -f https://raw.githubusercontent.com/openchoreo/openchoreo/main/samples/from-source/services/go-google-buildpack-reading-list/reading-list-service.yaml ``` - -### Getting Help - -- **Documentation**: [Core Concepts](/docs/core-concepts/) -- **Examples**: [Learn from Examples](/docs/learn-from-examples/) -- **Community**: [GitHub Discussions](https://github.com/openchoreo/openchoreo/discussions) -- **Support**: [support@openchoreo.dev](mailto:support@openchoreo.dev) - -## Summary - -You've successfully: -- ✅ Created your first OpenChoreo project -- ✅ Deployed a component from source code -- ✅ Configured networking and security automatically -- ✅ Set up monitoring and observability -- ✅ Learned about OpenChoreo's automated resource management - -Your application is now running in a production-ready environment with enterprise-grade security, networking, and observability—all configured automatically by OpenChoreo! - -**Ready for more?** Check out our [Learn from Examples](/docs/learn-from-examples/) section for more complex scenarios and use cases. \ No newline at end of file diff --git a/docs/getting-started/quick-start-guide.md b/docs/getting-started/quick-start-guide.md index 352ab20..e3fde87 100644 --- a/docs/getting-started/quick-start-guide.md +++ b/docs/getting-started/quick-start-guide.md @@ -3,4 +3,188 @@ layout: docs title: Quick Start Guide --- -# Quick Start Guide \ No newline at end of file +# Quick Start Guide + +Setting up OpenChoreo in a Kubernetes cluster involves multiple steps and tools. This guide provides a fast and simple way to install a fully functional OpenChoreo instance on your local machine with minimal prerequisites and effort by using a pre-configured dev container. +This dev container has all the necessary tools installed for setting up OpenChoreo and is ready to be used. Once the installation is complete, you can explore the underlying setup to understand how it works. +When you're done, you can fully clean up the setup, leaving your machine clutter-free. + +### Prerequisites + +To get started, you’ll need: + +- **Docker** – Just have it installed on your machine, and you're good to go. + - We recommend using [Docker Engine version 26.0+](https://docs.docker.com/engine/release-notes/26.0/). +- **5–10 minutes of your time** – Setup is quick and depends on your internet connection speed. + +## Start the Dev Container + +Run the following command to start the dev container and launch a terminal session within it: + +```shell +docker run --rm -it --name openchoreo-quick-start \ +-v /var/run/docker.sock:/var/run/docker.sock \ +-v openchoreo-state:/state \ +-v tf-state:/app/terraform \ +--network bridge \ +-p 8443:8443 \ +-p 7007:7007 \ +ghcr.io/openchoreo/quick-start:latest-dev + +``` + +### Install OpenChoreo +This process sets up a [KinD](https://kind.sigs.k8s.io/) (Kubernetes-in-Docker) cluster in your Docker environment and installs OpenChoreo along with its dependencies. + +To begin the installation, run: + +```shell +TF_VAR_openchoreo_version="0.0.0-latest-dev" ./install.sh +``` + +**💡 Tip:** If you previously used this setup and encounter errors during installation, ensure you perform the proper cleanup as outlined in the [Cleaning up](#cleaning-up) section before starting again. + +Once the installation is complete, you will see the following confirmation message: +```text +====================================================================== + OpenChoreo Component Status +====================================================================== + ++- Networking (Infrastructure) -----------------------------------+ +| cilium [READY] | ++-----------------------------------------------------------------+ + ++- Control Plane (Core) ------------------------------------------+ +| cert_manager_cp [READY] | +| controller_manager [READY] | +| api_server [READY] | ++-----------------------------------------------------------------+ + ++- Data Plane (Core) ---------------------------------------------+ +| vault [READY] | +| registry [READY] | +| redis [READY] | +| envoy_gateway [READY] | +| external_gateway [READY] | +| internal_gateway [READY] | +| fluent_bit_dp [READY] | ++-----------------------------------------------------------------+ + ++- Build Plane (Optional) ----------------------------------------+ +| build_plane [READY] | ++-----------------------------------------------------------------+ + ++- Identity Provider (Optional) ----------------------------------+ +| identity_provider [READY] | ++-----------------------------------------------------------------+ + ++- Observability Plane (Optional) --------------------------------+ +| opensearch [NOT_INSTALLED] | +| opensearch_dashboard [NOT_INSTALLED] | +| observer [NOT_INSTALLED] | ++-----------------------------------------------------------------+ + ++- Backstage Demo (Optional) -------------------------------------+ +| backstage [READY] | ++-----------------------------------------------------------------+ + +====================================================================== +``` + +**📝 Note:** If you see any components are still in the `pending` state, you can check the status again in few minutes. Run the following command to check the installation status of components: +```shell +./check-status.sh +``` + +### Deploying a Web Application with OpenChoreo + +You now have OpenChoreo fully setup in your docker environment. +Next, lets deploy a sample Web Application by running the following command: + +```shell +./deploy_web_application.sh +``` + +Once the deployment is complete, you will receive the following message together with a URL to access the application: + +```text +✅ Endpoint is ready! +🌍 You can now access the Sample Web Application at: https://react-starter-image-development.choreoapps.localhost:8443 +``` + +### Understanding What Happens Behind the Scenes +By following the install and deploy web application commands, you first, setup OpenChoreo and then, successfully deployed and accessed a fully functional Web Application. + +Let’s now explore what happens after each command. + +#### 1. The Install Command +- A dev container with all the necessary tools for OpenChoreo to run is set up in a local Docker environment. +- A KinD Kubernetes cluster is created, where the OpenChoreo IDP and its dependencies were installed using Helm charts. + +#### Foundation Resources Created by OpenChoreo + +The installation process, by default, sets up several essential abstractions. These are: +- Organization +- Dataplane +- Buildplane +- Environments (e.g., Development, Staging, Production) +- Deployment Pipeline for the environments +- Project + +To access the artifacts created in OpenChoreo you can use choreoctl as shown in the following commands: + +You can check each resource type + +```shell +kubectl get organizations +``` +```shell +kubectl get dataplanes +``` +```shell +kubectl get environments +``` +```shell +kubectl get projects +``` +To get more details on any of these abstractions, you can use a similar command to the following command: + +```shell +kubectl get project default-project -oyaml +``` + +#### 2. The Deploy Web Application Command +The deploy script creates a sample Web Application Component, along with a Deployment for the sample web application. + +To inspect these resources in more detail, run the following commands: + +```shell +kubectl get components +``` + +**💡 Tip:** You can try out more samples on this setup. Check out our [Samples](../samples/README.md) for more details. The samples are also available in the dev container at `/samples`. + +**⚠️ Important:** If you try out samples in the dev container, you don't need to expose the OpenChoreo Gateway to your host machine. The OpenChoreo gateway is already exposed to host machine via dev container port 8443. + +### Cleaning up +After finishing your work, you have two options: + +1. **Exit and return later**: If you plan to return, simply exit the dev container by running: + ```shell + exit + ``` +2. **Full cleanup**: To remove all resources and clean up the environment completely, run: + ```shell + ./uninstall.sh + ``` + ```shell + exit + ``` + ```shell + docker volume rm openchoreo-state tf-state + ``` +**📝 Note:** The `tf-state` Docker volume is used to persist the installation state, so if you exit the dev container before completing the uninstallation and return later, your installation progress will still be there. The `openchoreo-state` volume is used to store the kubeconfig of the created KinD cluster, ensuring that the cluster configuration remains available even after restarting the container. + +That's it! + +Now you understand how OpenChoreo simplifies the deployment and management of cloud-native applications. diff --git a/docs/getting-started/single-cluster.md b/docs/getting-started/single-cluster.md index ba61698..c6d20fd 100644 --- a/docs/getting-started/single-cluster.md +++ b/docs/getting-started/single-cluster.md @@ -4,3 +4,374 @@ title: Single Cluster Setup --- # Single Cluster Setup + +This guide provides step-by-step instructions for setting up a local development environment for OpenChoreo using Kind (Kubernetes in Docker). + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) v20.10+ installed and running +- [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) v0.20+ installed +- [kubectl](https://kubernetes.io/docs/tasks/tools/) v1.32+ installed +- [Helm](https://helm.sh/docs/intro/install/) v3.12+ installed + +### Verify Prerequisites + +Before proceeding, verify that all tools are installed and meet the minimum version requirements: + +```bash +# Check Docker (should be v20.10+) +docker --version + +# Check Kind (should be v0.20+) +kind --version + +# Check kubectl (should be v1.32+) +kubectl version --client + +# Check Helm (should be v3.12+) +helm version --short +``` + +Make sure Docker is running: + +```bash +docker info +``` + +## Quick Setup + +This setup uses pre-built images and Helm charts from the OpenChoreo registry. + + +### 1. Create OpenChoreo Kind Cluster + +Create a new Kind cluster using the provided configuration: + +```bash +kind create cluster --config https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/kind/kind-config.yaml +``` + +This will: +- Create a cluster named "openchoreo" +- Set up control plane and worker nodes +- Configure the worker node with OpenChoreo-specific labels +- Set kubectl context to "kind-openchoreo" + +### 2. Install Cilium CNI + +Install Cilium as the Container Network Interface (CNI). This will create the `cilium` namespace automatically: + +```bash +helm install cilium oci://ghcr.io/openchoreo/helm-charts/cilium --version 0.0.0-latest-dev --create-namespace --namespace cilium --wait +``` + +Wait for Cilium pods to be ready: + +```bash +kubectl wait --for=condition=Ready pod -l k8s-app=cilium -n cilium --timeout=300s +``` + +Verify that the nodes are now Ready: + +```bash +kubectl get nodes +``` + +You should see both nodes in `Ready` status. + +### 3. Install OpenChoreo Control Plane + +Install the OpenChoreo control plane using the following helm install command. This will create the `openchoreo-control-plane` namespace automatically: + +```bash +helm install control-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-control-plane \ + --create-namespace --namespace openchoreo-control-plane \ + --timeout=10m +``` + +Wait for the installation to complete and verify all pods are running: + +```bash +kubectl get pods -n openchoreo-control-plane +``` + +You should see pods for: +- `controller-manager` (Running) +- `api-server` (Running) +- `cert-manager-*` (3 pods, all Running) + +### 4. Install OpenChoreo Data Plane + +Install the OpenChoreo data plane using the following helm install command. This will create the `openchoreo-data-plane` namespace automatically: + +```bash +helm install data-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-data-plane \ + --create-namespace --namespace openchoreo-data-plane \ + --timeout=10m \ + --set cert-manager.enabled=false \ + --set cert-manager.crds.enabled=false +``` + +Note: We disable cert-manager since it's already installed by the control plane. + +Wait for dataplane components to be ready: + +```bash +kubectl get pods -n openchoreo-data-plane +``` + +You should see pods for: +- `hashicorp-vault-0` (Running) +- `secrets-store-csi-driver-*` (Running on each node) +- `gateway-*` (Running) +- `registry-*` (Running) +- `redis-*` (Running) +- `envoy-gateway-*` (Running) +- `envoy-ratelimit-*` (Running) +- `fluent-bit-*` (Running) + +### 5. Install OpenChoreo Build Plane (Optional) + +Install the OpenChoreo build plane using the following helm install command for CI/CD capabilities using Argo Workflows. This will create the `openchoreo-build-plane` namespace automatically: + +```bash +helm install build-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-build-plane \ + --create-namespace --namespace openchoreo-build-plane --timeout=10m +``` + +Wait for the build plane components to be ready: + +```bash +kubectl get pods -n openchoreo-build-plane +``` + +You should see pods for: +- `argo-workflow-controller-*` (Running) + +#### Configure BuildPlane + +Register the build plane with the control plane by running: + +```bash +curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/add-build-plane.sh | bash +``` + +This script will: +- Detect single-cluster mode automatically +- Extract cluster credentials from your kubeconfig +- Create a BuildPlane resource in the default namespace +- Configure the build plane connection to the control plane + +Verify that the BuildPlane was created: + +```bash +kubectl get buildplane -n default +``` + +### 6. Configure DataPlane + +Register the data plane with the control plane by running: + +```bash +curl -s https://raw.githubusercontent.com/openchoreo/openchoreo/main/install/add-default-dataplane.sh | bash +``` + +This script will: +- Detect single-cluster mode automatically +- Extract cluster credentials from your kubeconfig +- Create a DataPlane resource in the default namespace +- Configure the registry and gateway endpoints + +Verify the DataPlane was created: + +```bash +kubectl get dataplane -n default +``` + +### 7. Install OpenChoreo Observability Plane (Optional) + +Install the OpenChoreo observability plane using the following helm install command for monitoring and logging capabilities. This will create the `openchoreo-observability-plane` namespace automatically: + +```bash +helm install observability-plane oci://ghcr.io/openchoreo/helm-charts/openchoreo-observability-plane \ + --create-namespace --namespace openchoreo-observability-plane \ + --timeout=10m +``` + +Wait for the observability plane components to be ready: + +```bash +kubectl get pods -n openchoreo-observability-plane +``` + +You should see pods for: +- `opensearch-0` (Running) - Log storage backend +- `opensearch-dashboard-*` (Running) - Visualization dashboard +- `observer-*` (Running) - Log processing service + +Note: The OpenSearch pod may take several minutes. + +Verify that all pods are ready: + +```bash +kubectl wait --for=condition=Ready pod --all -n openchoreo-observability-plane --timeout=600s +``` + +Verify FluentBit is sending logs to OpenSearch: + +```bash +# Check if kubernetes indices are being created +kubectl exec -n openchoreo-observability-plane opensearch-0 -- curl -s "http://localhost:9200/_cat/indices?v" | grep kubernetes + +# Check recent log count +kubectl exec -n openchoreo-observability-plane opensearch-0 -- curl -s "http://localhost:9200/kubernetes-*/_count" | jq '.count' +``` + +If the indices exist and the count is greater than 0, FluentBit is successfully collecting and storing logs. + +#### Configure Observer Integration +Configure the DataPlane and BuildPlane to use the observer service. + +```bash +# Configure DataPlane to use observer service +kubectl patch dataplane default -n default --type merge -p '{"spec":{"observer":{"url":"http://observer.openchoreo-observability-plane:8080","authentication":{"basicAuth":{"username":"dummy","password":"dummy"}}}}}' + +# Configure BuildPlane to use observer service +kubectl patch buildplane default -n default --type merge -p '{"spec":{"observer":{"url":"http://observer.openchoreo-observability-plane:8080","authentication":{"basicAuth":{"username":"dummy","password":"dummy"}}}}}' +``` + +**Important**: Without this configuration, build logs will not be pushed to the observability plane and application logs will not be visible in the Backstage portal, significantly impacting the developer experience. + +This configuration enables: +- Application logs to appear in Backstage portal +- Enhanced logging and monitoring across build and data planes +- Integration with the observability plane for comprehensive platform monitoring +- Centralized log publishing and access through the observer service + +Verify the observer configuration: + +```bash +# Check DataPlane observer config +kubectl get dataplane default -n default -o jsonpath='{.spec.observer}' | jq '.' + +# Check BuildPlane observer config +kubectl get buildplane default -n default -o jsonpath='{.spec.observer}' | jq '.' +``` + +### 8. Install OpenChoreo Backstage Portal (Optional) + +Install the OpenChoreo Backstage developer portal to visualize and manage your deployed components. The portal provides a unified interface for viewing all your services, APIs, and other components in the platform. + +```bash +helm install openchoreo-backstage-demo oci://ghcr.io/openchoreo/helm-charts/backstage-demo \ + --namespace openchoreo-control-plane +``` + +Wait for the Backstage pod to be ready: + +```bash +kubectl wait --for=condition=Ready pod -l app.kubernetes.io/name=backstage -n openchoreo-control-plane --timeout=300s +``` + +Verify the installation: + +```bash +# Check pod status +kubectl get pods -l app.kubernetes.io/name=backstage -n openchoreo-control-plane + +# Check service +kubectl get svc openchoreo-backstage-demo -n openchoreo-control-plane +``` + +To access the Backstage portal: + +```bash +# Port forward the Backstage service in background and open browser +kubectl port-forward -n openchoreo-control-plane svc/openchoreo-backstage-demo 7007:7007 > /dev/null 2>&1 & sleep 2 && open http://localhost:7007 + +# Or if you prefer to manually open the browser: +kubectl port-forward -n openchoreo-control-plane svc/openchoreo-backstage-demo 7007:7007 > /dev/null 2>&1 & sleep 2 +# Then access in browser at http://localhost:7007 + +# To stop the port-forward when done: +pkill -f "kubectl port-forward.*openchoreo-backstage-demo.*7007:7007" +``` + +You can verify the portal is working correctly with curl: + +```bash +curl -s http://localhost:7007 | head -20 +``` + +The OpenChoreo plugin will automatically detect and display any components you deploy to the platform. + + +### 9. Verify OpenChoreo Installation + +#### Check that default OpenChoreo resources were created: + +```bash +# Check default organization and project +kubectl get organizations,projects,environments -A + +# Check default platform classes +kubectl get serviceclass,apiclass -n default + +# Check all OpenChoreo CRDs +kubectl get crds | grep openchoreo + +# Check gateway resources +kubectl get gateway,httproute -n openchoreo-data-plane +``` + +#### Check that all components are running: + +```bash +# Check cluster info +kubectl cluster-info --context kind-openchoreo + +# Check control plane pods +kubectl get pods -n openchoreo-control-plane + +# Check data plane pods +kubectl get pods -n openchoreo-data-plane + +# Check build plane pods (if installed) +kubectl get pods -n openchoreo-build-plane + +# Check observability plane pods (if installed) +kubectl get pods -n openchoreo-observability-plane + +# Check Cilium pods +kubectl get pods -n cilium + +# Check nodes (should be Ready) +kubectl get nodes +``` + +## Next Steps + +After completing this setup you can: + +1. [Deploy your first component](/docs/getting-started/deploy-your-first-component.md) +2. Test the [GCP microservices demo](https://github.com/openchoreo/openchoreo/tree/main/samples/gcp-microservices-demo) +3. Deploy additional sample applications from the [OpenChoreo samples](https://github.com/openchoreo/openchoreo/tree/main/samples) +4. Develop and test new OpenChoreo features +5. Explore the Backstage portal to manage your deployed components + +## Cleaning Up + +To completely remove the development environment: + +```bash +# Delete the Kind cluster +kind delete cluster --name openchoreo + +# Remove kubectl context (optional) +kubectl config delete-context kind-openchoreo + +# Clean up cert-manager leader election leases (for future reinstalls) +kubectl delete lease cert-manager-controller -n kube-system --ignore-not-found +kubectl delete lease cert-manager-cainjector-leader-election -n kube-system --ignore-not-found +``` + diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md index 47b4e1a..cf1c781 100644 --- a/docs/overview/roadmap.md +++ b/docs/overview/roadmap.md @@ -22,9 +22,9 @@ OpenChoreo follows [Semantic Versioning](https://semver.org/): - **Minor versions** (1.1.0): New features and enhancements (backward compatible) - **Patch versions** (1.0.1): Bug fixes and security updates -## Current Version: v0.2 +## Current Version: v0.3 -**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)** +**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)** ## Upcoming Releases diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index bd62827..9cf4022 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -9,58 +9,20 @@ This document tracks all notable changes, new features, breaking changes, and im ## Current Release -### [v0.2.0] - 2025-06-06 +### [v0.3.0] - 2025-07-31 -**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)** +**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.3.0)** --- ## Previous Releases ---- - -## Breaking Changes (sample) - -### v0.2.0 → v0.3.0 (Planned) - -#### API Changes -```yaml -# DEPRECATED: v1.0.x format -apiVersion: choreo.dev/v1 -kind: Component -spec: - endpoints: - - port: 8080 - path: /api - -# NEW: v1.1.x format (backward compatible) -apiVersion: choreo.dev/v1 -kind: Component -spec: - endpoints: - - name: api - port: 8080 - path: /api - protocol: HTTP -``` +### [v0.2.0] - 2025-06-06 -#### Configuration Changes -- **Environment Variables**: `CHOREO_NAMESPACE` renamed to `CHOREO_SYSTEM_NAMESPACE` -- **Helm Values**: `controller.replicas` moved to `controlPlane.controller.replicas` -- **RBAC**: Additional permissions required for new multi-cluster features +**[📋 View Full Release Notes](https://github.com/openchoreo/openchoreo/releases/tag/v0.2.0)** --- -## Deprecated Features(sample) - -### Scheduled for Removal - -#### v1.2.0 (March 2025) -- **Legacy API**: `choreo.dev/v1alpha1` API version -- **Old CLI Commands**: `choreo component create` (use `choreo create component`) -- **Environment Variables**: `CHOREO_LEGACY_MODE` support - ---- ## Upcoming Releases and Release Schedule Track our development progress and upcoming features on our [GitHub Project Board](https://github.com/orgs/openchoreo/projects/1). See also our [Roadmap](/docs/overview/roadmap/) for detailed version planning.