docs: update installation and getting started guides. (#108)

Update getting started and installation guidelines.

Co-authored-by: candonov <[email protected]>

website/docs/docs/getting-started/01-Installation.md

@@ -16,9 +16,12 @@ Before you begin, ensure you have the following:
 
 ## Installation Steps
 
-:::info[**Alpha Stage**] KRO is currently in alpha stage. While the images are
-publicly available, please note that the software is still under active
-development and APIs may change. :::
+:::info[**Alpha Stage**]
+
+KRO is currently in alpha stage. While the images are publicly available, please
+note that the software is still under active development and APIs may change.
+
+:::
 
 ### Install KRO using Helm
 
@@ -72,9 +75,12 @@ helm upgrade kro oci://public.ecr.aws/kro/kro \
   --version=${KRO_VERSION}
 ```
 
-:::info Helm does not support updating CRDs, so you may need to manually update
-or remove kro related CRDs. For more information, refer to the Helm
-documentation. :::
+:::info[**CRD Updates**]
+
+Helm does not support updating CRDs, so you may need to manually update or
+remove and re-apply kro related CRDs. For more information, refer to the Helm documentation.
+
+:::
 
 ## Uninstalling KRO
 

website/docs/docs/getting-started/02-deploy-a-resource-group.md

@@ -2,110 +2,234 @@
 sidebar_position: 2
 ---
 
-# Deploy a Resource Group
+# Deploy Your First ResourceGroup
 
-ResourceGroups are the core building blocks of KRO. They define the structure of
-your application and the resources it requires. In this guide, you'll learn how
-to deploy a ResourceGroup using KRO.
+This guide will walk you through creating your first Resource Group in **KRO**.
+We'll create a simple `ResourceGroup` that demonstrates key KRO features.
+
+## What is a **ResourceGroup**?
+
+A `ResourceGroup` lets you create new Kubernetes APIs that deploy multiple
+resources together as a single, reusable unit. In this example, we’ll create a 
+`ResourceGroup` that packages a reusable set of resources, including a `Deployment`, `Service`, 
+and `Ingress`. These resources are available in any Kubernetes cluster.
+Users can then call the API to deploy resources as a single unit, ensuring they're
+always created together with the right configuration.
+
+Under the hood, when you create a `ResourceGroup`, KRO:
+
+1. Treats your resources as a Directed Acyclic Graph (DAG) to understand their
+   dependencies
+2. Validates resource definitions and detects the correct deployment order
+3. Creates a new API (CRD) in your cluster
+4. Configures itself to watch and serve instances of this API
+
+:::tip[info]
+
+**KRO** is a Kubernetes-native tool that speaks **Kubernetes**! All you need
+to get started is a Kubernetes cluster that supports CRDs, version 1.16 or later. 
+KRO understands native Kubernetes resource as well as any custom resources your cluster supports.
+
+:::
 
 ## Prerequisites
 
-Before you begin, ensure you have the following:
+Before you begin, make sure you have the following:
+
+- **KRO** [installed](./01-Installation.md) and running in your Kubernetes
+  cluster.
+- `kubectl` installed and configured to interact with your Kubernetes cluster.
 
-- Installed KRO on your Kubernetes cluster
-- A ResourceGroup manifest file
+## Create your Application ResourceGroup
 
-For this examole, we'll use a simple ResourceGroup that defines a Deployment and
-a Service. Here's an example of a `ResourceGroup` manifest file:
+Let's create a Resource Group that combines a `Deployment`, a `Service` and
+`Ingress`. Save this as `resourcegroup.yaml`:
 
-```yaml title="deploymentservice-rg.yaml"
+```yaml title="resourcegroup.yaml"
 apiVersion: kro.run/v1alpha1
 kind: ResourceGroup
 metadata:
-  name: deployment-service
+  name: my-application
 spec:
-  apiVersion: v1alpha1
-  kind: DeploymentService
-  definition:
+  # KRO uses this simple schema to create your CRD schema and apply it
+  # The schema defines what users can provide when they instantiate the RG (create an instance).
+  schema:
+    apiVersion: v1alpha1
+    kind: Application
     spec:
+      # Spec fields that users can provide.
       name: string
+      image: string | default="nginx"
+      ingress:
+        enabled: boolean | default=false
+    status:
+      # Fields the controller will inject into instances status.
+      deploymentConditions: ${deployment.status.conditions}
+      availableReplicas: ${deployment.status.availableReplicas}
+
+  # Define the resources this API will manage.
   resources:
     - name: deployment
-      definition:
+      template:
         apiVersion: apps/v1
         kind: Deployment
         metadata:
-          name: ${schema.spec.name}
+          name: ${schema.spec.name} # Use the name provided by user
         spec:
-          replicas: 1
+          replicas: 3
           selector:
             matchLabels:
-              app: deployment
+              app: ${schema.spec.name}
           template:
             metadata:
               labels:
-                app: deployment
+                app: ${schema.spec.name}
             spec:
               containers:
-                - name: ${schema.spec.name}-deployment
-                  image: nginx
+                - name: ${schema.spec.name}
+                  image: ${schema.spec.image} # Use the image provided by user
                   ports:
                     - containerPort: 80
+
     - name: service
-      definition:
+      template:
         apiVersion: v1
         kind: Service
         metadata:
-          name: ${schema.spec.name}
+          name: ${schema.spec.name}-service
         spec:
-          selector:
-            app: deployment
+          selector: ${deployment.spec.selector.matchLabels} # Use the deployment selector
           ports:
             - protocol: TCP
               port: 80
               targetPort: 80
+
+    - name: ingress
+      includeWhen:
+        - ${schema.spec.ingress.enabled} # Only include if the user wants to create an Ingress
+      template:
+        apiVersion: networking.k8s.io/v1
+        kind: Ingress
+        metadata:
+          name: ${schema.spec.name}-ingress
+          annotations:
+            kubernetes.io/ingress.class: alb
+            alb.ingress.kubernetes.io/scheme: internet-facing
+            alb.ingress.kubernetes.io/target-type: ip
+            alb.ingress.kubernetes.io/healthcheck-path: /health
+            alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}]'
+            alb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=60
+        spec:
+          rules:
+            - http:
+                paths:
+                  - path: "/"
+                    pathType: Prefix
+                    backend:
+                      service:
+                        name: ${service.metadata.name} # Use the service name
+                        port:
+                          number: 80
 ```
 
-## Steps
+### Deploy the ResourceGroup
 
 1. **Create a ResourceGroup manifest file**: Create a new file with the
-   ResourceGroup definition. You can use the example above as a template.
+   `ResourceGroup` definition. You can use the example above.
 
-2. **Deploy the ResourceGroup**: Use the `kubectl` command to deploy the
+2. **Apply the `ResourceGroup`**: Use the `kubectl` command to deploy the
    ResourceGroup to your Kubernetes cluster:
 
    ```bash
-   kubectl apply -f deploymentservice-rg.yaml
+   kubectl apply -f resourcegroup.yaml
    ```
 
-3. **Verify the resources**: Check the status of the resources created by the
-   ResourceGroup using the `kubectl` command:
+3. **Inpsect the `ResourceGroup`**: Check the status of the resources created by
+   the ResourceGroup using the `kubectl` command:
 
    ```bash
-   kubectl get rg
+   kubectl get rg my-application -owide
    ```
 
-   You should see something like this:
+   You should see the ResourceGroup in the `Active` state, along with relevant
+   information to help you understand your application:
 
    ```bash
-   NAME                                   APIVERSION   KIND                STATE    AGE
-   deployment-service                     v1alpha1     DeploymentService   ACTIVE   16m
+   NAME             APIVERSION   KIND          STATE    TOPOLOGICALORDER                     AGE
+   my-application   v1alpha1     Application   Active   ["deployment","service","ingress"]   49
    ```
 
-4. **Install a resource group instance**: Create an instance for the resource group you
-   just deployed. Instances are used to define the desired state of the resources
-   in the ResourceGroup.
+### Create your Application Instance
+
+Now that your `ResourceGroup` is created, KRO has generated a new API
+(Application) that orchestrates creation of the a `Deployment`, a `Service`, and
+an `Ingress`. Let's use it!
 
-   Here's an example of an Instance for the `EKSCluster` ResourceGroup:
+1. **Create an Application instance**: Create a new file named `instance.yaml`
+   with the following content:
 
-   ```yaml
+   ```yaml title="instance.yaml"
    apiVersion: kro.run/v1alpha1
-   kind: DeploymentService
+   kind: Application
    metadata:
-     name: my-deployment-and-service
+     name: my-application-instance
    spec:
-     name: app1
+     name: my-awesome-app
+     ingress:
+       enabled: true
+   ```
+
+2. **Apply the Application instance**: Use the `kubectl` command to deploy the
+   Application instance to your Kubernetes cluster:
+
+   ```bash
+   kubectl apply -f instance.yaml
+   ```
+
+3. **Inspect the Application instance**: Check the status of the resources
+
+   ```bash
+   kubectl get applications
+   ```
+
+   After a few seconds, you should see the Application instance in the `Active`
+   state:
+
+   ```bash
+   NAME                      STATE    SYNCED   AGE
+   my-application-instance   ACTIVE   True     10s
+   ```
+
+4. **Inspect the resources**: Check the resources created by the Application
+   instance:
+
+   ```bash
+   kubectl get deployments,services,ingresses
+   ```
+
+   You should see the `Deployment`, `Service`, and `Ingress` created by the
+   Application instance.
+
+   ```bash
+   NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
+   deployment.apps/my-awesome-app   3/3     3            3           69s
+
+   NAME                             TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
+   service/my-awesome-app-service   ClusterIP   10.100.167.72   <none>        80/TCP    65s
+
+   NAME                                               CLASS    HOSTS   ADDRESS   PORTS   AGE
+   ingress.networking.k8s.io/my-awesome-app-ingress   <none>   *                 80      62s
+   ```
+
+### Delete the Application instance
+
+KRO can also help you clean up resources when you're done with them.
+
+1. **Delete the Application instance**: Clean up the resources by deleting the
+   Application instance:
+
+   ```bash
+   kubectl delete application my-application-instance
    ```
 
-   The spec fields of an Instance correspond to the parameters defined in the
-   ResourceGroup.
+   Now, the resources created by the Application instance will be deleted.

website/docs/docs/overview.md

@@ -5,13 +5,13 @@ sidebar_position: 1
 # What is KRO?
 
 **KRO** (Kube Resource Orchesrtator) is an open-source project that allows you
-to define custom **Kubernetes APIs** using straightforward configuration. With
-KRO, you can easily configure new custom APIs that create a group of Kubernetes
-objects and the logical operations between them. KRO automatically calculates
-the order in which objects should be created. You can pass values from one
-object to another, set default values for fields in the API specification, and
-incorporate conditionals into your custom API definitions. End users can easily
-call these custom APIs to create grouped resources.
+to define custom **Kubernetes APIs** using simple and straightforward
+configuration. With KRO, you can easily configure new custom APIs that create a
+group of Kubernetes objects and the logical operations between them. KRO
+automatically calculates the order in which objects should be created. You can
+pass values from one object to another, set default values for fields in the API
+specification, and incorporate conditionals into your custom API definitions.
+End users can easily call these custom APIs to create grouped resources.
 
 # How does KRO work?
 
@@ -25,13 +25,17 @@ create additional resources outside of your cluster.
 
 As depicted in the following diagram, the Developers call the Custom API, which
 creates resources such as the **Deployment**, **Ingress**, **ServiceAccount**,
-**Prometheus Monitor**, **Role**, **Policy**, and **Amazon S3**. This allows the
-Developers to easily manage and deploy their applications in a standardized and
-streamlined manner.
+**Prometheus Monitor**, **IAM Role**, **IAM Policy**, and **Amazon S3 Bucket**.
+This allows the Developers to easily manage and deploy their applications in a
+standardized and streamlined manner.
+
+<div align="center">
 
 ![End user interface - Custom API](../../../images/architecture-diagrams/KRO-Dev-Interface.png)
 _Fugure 1: End user interface - Custom API_
 
+</div>
+
 ### ResourceGroup
 
 When you install **Kro** in your cluster, it installs a Custom Resource
@@ -47,9 +51,13 @@ longer need to directly manage the underlying infrastructure complexities, as
 the custom API handles the deployment and configuration of the required
 resources.
 
+<div align="center">
+
 ![Platform Team Interface](../../../images/architecture-diagrams/KRO-Platform-Team.png)
 _Fugure 2: ResourceGroup (RG) - Platform Team Interface_
 
+</div>
+
 ### ResourceGroup Instance
 
 Developer teams can create multiple instances of the **Application Stack**, each
@@ -61,9 +69,13 @@ keep their service internal to the cluster. This flexibility allows each
 development team to customize their application stack based on their specific
 requirements.
 
+<div align="center">
+
 ![ResourceGroup Instance](../../../images/architecture-diagrams/KRO-Instance.png)
 _Fugure 3: ResourceGroup Instance (RGI)_
 
+</div>
+
 # Why KRO?
 
 ### Manage any group of resources as one unit

website/docusaurus.config.ts

@@ -4,7 +4,7 @@ import type * as Preset from "@docusaurus/preset-classic";
 
 const config: Config = {
   title: "KRO",
-  tagline: "Kube Resource Orchestrator",
+  tagline: "Kube Resources Orchestrator",
   // The Melodious Kubernetes Integrator
   // Cementing Your Kubernetes Infrastructure
   // Connecting the Dots in Your Kubernetes Environment