From 403a9e756deb2a8f51e9754d61ad4d73d028322f Mon Sep 17 00:00:00 2001 From: Amine Date: Sun, 10 Nov 2024 18:03:17 -0800 Subject: [PATCH] docs: minor UI tweaks and remove unused fields --- examples/application/Readme.md | 25 +++- .../docs/docs/concepts/00-resource-groups.md | 2 +- .../docs/docs/concepts/10-simple-schema.md | 11 +- website/docs/docs/concepts/15-instances.md | 40 +++--- website/docs/docs/concepts/20-collections.md | 118 ------------------ .../docs/docs/concepts/30-conditionals.mdx | 5 - website/docs/docs/concepts/40-imports.mdx | 7 -- website/docs/docs/concepts/50-validation.mdx | 7 -- .../docs/docs/concepts/60-managing-state.mdx | 7 -- website/docs/docs/concepts/_category_.json | 5 +- .../docs/docs/getting-started/_category_.json | 5 +- website/docusaurus.config.ts | 7 +- 12 files changed, 63 insertions(+), 176 deletions(-) delete mode 100644 website/docs/docs/concepts/20-collections.md delete mode 100644 website/docs/docs/concepts/30-conditionals.mdx delete mode 100644 website/docs/docs/concepts/40-imports.mdx delete mode 100644 website/docs/docs/concepts/50-validation.mdx delete mode 100644 website/docs/docs/concepts/60-managing-state.mdx diff --git a/examples/application/Readme.md b/examples/application/Readme.md index f6bb4559..1744c946 100644 --- a/examples/application/Readme.md +++ b/examples/application/Readme.md @@ -1,47 +1,66 @@ # KRO Application example -This example creates a ResourceGroup called `App` and then instaciates it with the default nginx container image. + +This example creates a ResourceGroup called `App` and then instaciates it with +the default nginx container image. ### Create ResourceGroup called App + Apply the RG to your cluster: + ``` kubectl apply -f rg.yaml ``` + Validate the RG status is Active: + ``` kubectl get rg app.kro.run ``` + Expected result: + ``` NAME APIVERSION KIND STATE AGE app.kro.run v1alpha1 App Active 6m ``` ### Create an Instance of kind App + Apply the provided instance.yaml + ``` kubectl apply -f instance.yaml ``` + Validate instance status: + ``` kubectl get apps test-app ``` + Expected result: + ``` NAME STATE SYNCED AGE test-app ACTIVE True 16m ``` ### Validate the app is working + Get the ingress url: + ``` kubectl get ingress test-app -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` Either navigate in the browser or curl it: + ``` curl -s $(kubectl get ingress test-app -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') | sed -n '//,/<\/body>/p' | sed -e 's/<[^>]*>//g' ``` + Expected result: + ``` Welcome to nginx! If you see this page, the nginx web server is successfully installed and @@ -56,11 +75,15 @@ Thank you for using nginx. ``` ### Clean up + Remove the instance: + ``` kubectl delete apps test-app ``` + Remove the resourcegroup: + ``` kubectl delete rg app.kro.run ``` diff --git a/website/docs/docs/concepts/00-resource-groups.md b/website/docs/docs/concepts/00-resource-groups.md index 12887b4a..888559fc 100644 --- a/website/docs/docs/concepts/00-resource-groups.md +++ b/website/docs/docs/concepts/00-resource-groups.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# 1. ResourceGroups +# ResourceGroups **ResourceGroups** are the fundamental building blocks in KRO. They provide a way to define, organize, and manage sets of related Kubernetes resources as a diff --git a/website/docs/docs/concepts/10-simple-schema.md b/website/docs/docs/concepts/10-simple-schema.md index 7fea8a3f..2fecd05e 100644 --- a/website/docs/docs/concepts/10-simple-schema.md +++ b/website/docs/docs/concepts/10-simple-schema.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# 2. Simple Schema +# Simple Schema KRO's Simple Schema provides a powerful yet intuitive way to define the structure of your ResourceGroup. Here is comprehensive example: @@ -173,13 +173,14 @@ Common condition types include: ### 2. State -The `state` field provides a high-level summary of the instance's current status. +The `state` field provides a high-level summary of the instance's current +status. ```yaml status: state: string | enum="Ready,Progressing,Degraded,Error,Terminating,Unknown" ``` -> These default status fields are automatically added to every instance's status, -> providing a consistent way to check the health and state of resources across -> different **ResourceGroups**. +> These default status fields are automatically added to every instance's +> status, providing a consistent way to check the health and state of resources +> across different **ResourceGroups**. diff --git a/website/docs/docs/concepts/15-instances.md b/website/docs/docs/concepts/15-instances.md index 0b7b603f..0d265f09 100644 --- a/website/docs/docs/concepts/15-instances.md +++ b/website/docs/docs/concepts/15-instances.md @@ -2,7 +2,7 @@ sidebar_position: 15 --- -# 3. Instances +# Instances Instances are a fundamental concept in **KRO** that represent instances of ResourceGroups. They define the desired state of a set of resources, which KRO @@ -37,8 +37,12 @@ spec: LOG_LEVEL: debug ``` -:::tip The spec fields of an Instance correspond to the parameters defined in the -ResourceGroup. ::: +::: + +tip The spec fields of an Instance correspond to the parameters defined in the +ResourceGroup. + +::: ## The reconciliation loop @@ -53,8 +57,8 @@ KRO manages Instances through a continuous reconciliation process: - **State Reconciliation**: KRO takes necessary actions to align the current state with the desired state. This may involve creating, updating, or deleting resources as needed. -- **Status Updates**: The Instance's status is updated to reflect the current state - of reconciliation and any issues encountered. +- **Status Updates**: The Instance's status is updated to reflect the current + state of reconciliation and any issues encountered. - **Continuous Loop**: This process repeats regularly, ensuring the cluster state always converges towards the desired state defined in the Instance. @@ -69,16 +73,18 @@ KRO manages Instances through a continuous reconciliation process: - **Auditability**: The Instance serves as a single source of truth for the application's desired state. -:::tip Best Practices +:::tip[Best Practices] -- Treat instances as declarative definitions of your application's desired state. - Use version control for your Instances to track changes over time. +- Treat instances as declarative definitions of your application's desired + state. Use version control for your Instances to track changes over time. - Leverage labels and annotations in Instances for organization and filtering. - Regularly review Instances to ensure they reflect current requirements. - Use KRO's dry-run feature to preview reconciliation actions before applying changes to Instances. -- Monitor Instance statuses to understand the current state of your applications. - ::: +- Monitor Instance statuses to understand the current state of your + applications. + +::: ## Common Status Fields @@ -93,8 +99,8 @@ detailed status information. Each condition represents a specific aspect of the instance's state. Common conditions include: - **Ready**: Indicates whether the instance is fully reconciled and operational. -- **Progressing**: Shows if the instance is in the process of reaching the desired - state. +- **Progressing**: Shows if the instance is in the process of reaching the + desired state. - **Degraded**: Signals that the instance is operational but not functioning optimally. - **Error**: Indicates that an error has occurred during reconciliation. @@ -121,8 +127,8 @@ status: ### 2. State -The State field provides a high-level summary of the instance's current status. It -is typically one of the following values: +The State field provides a high-level summary of the instance's current status. +It is typically one of the following values: - **Pending**: The instance is being processed, but resources are not yet fully created or configured. @@ -140,6 +146,6 @@ status: ``` These common status fields provide users with a consistent and informative way -to check the health and state of their instances across different ResourceGroups. -They are essential for monitoring, troubleshooting, and automating operations -based on the status of KRO-managed resources. +to check the health and state of their instances across different +ResourceGroups. They are essential for monitoring, troubleshooting, and +automating operations based on the status of KRO-managed resources. diff --git a/website/docs/docs/concepts/20-collections.md b/website/docs/docs/concepts/20-collections.md deleted file mode 100644 index 0bd19496..00000000 --- a/website/docs/docs/concepts/20-collections.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -sidebar_position: 20 ---- - -# 4. Collections - -Collections in KRO provide a powerful way to manage groups of similar resources -within a **ResourceGroup**. They allow for dynamic creation and management of -multiple instances of a resource type based on user input. - -## What are Collections? - -A collection is a special field in a **ResourceGroup** that defines a template -for creating multiple similar resources. Key features of collections include: - -- Dynamic creation of resources based on user input -- Consistent structure across multiple resource instances -- Simplified management of groups of related resources - -## Defining a Collection - -Here's an example of how to define a collection in a ResourceGroup: - -```yaml -apiVersion: kro.run/v1alpha1 -kind: ResourceGroup -metadata: - name: replica-set -spec: - kind: ReplicaSet - apiVersion: v1alpha1 - parameters: - spec: - clusterName: string - podCount: integer | minimum=1 maximum=5 - resources: - - name: nodesCollection - collection: - index: ${range(0, schema.spec.podCount)} - definition: - apiVersion: v1 - kind: Pod - metadata: - name: ${clusterName}-node-${index} - spec: - containers: - - name: db - image: nginx:latest -``` - -In this example, `nodes` is a collection that will create multiple Pod resources -based on the `podCount` parameter. - -## Key Concepts - -1. **index**: Specifies the range of values for the collection, allowing for - dynamic creation of multiple resources. - -2. **definition**: Defines the structure of each resource instance in the - collection. The `${index}` variable ensures uniqueness of each resource. - -## Using Collections in Instances - -When creating an instance, users can specify the count for the collection: - -```yaml -apiVersion: kro.run/v1alpha1 -kind: ReplicaSet -metadata: - name: my-db-cluster -spec: - clusterName: production-db - podCount: 3 -``` - -This instance will result in the creation of three Postgres Pods named -`production-db-node-0`, `production-db-node-1`, and `production-db-node-2`. - -## Deployment Strategy - -While defining collections is straightforward, it's essential to consider the -deployment strategy for managing multiple resources. KRO provides flexibility in -managing collections, allowing users to define how resources are created, -updated, and deleted based on the desired state. - -KRO provide two strategies for managing collections: - -- **RollingUpdate**: Creates, updates and deletes resources in an incremental - manner, ensuring that only one resource is updated at a time. -- **ParallelUpdate**: Creates, updates and deletes resources in parallel, - allowing for faster deployment of multiple resources. - -For examples you can add the following to the `spec` section of the -`ResourceGroup`: - -```yaml -spec: - kind: ReplicaSet - apiVersion: v1alpha1 - parameters: - spec: - clusterName: string - podCount: integer | minimum=1 maximum=5 - resources: - - name: nodes - strategy: RollingUpdate - collection: - index: ${range(0, schema.spec.podCount)} - definition: - apiVersion: v1 - kind: Pod - metadata: - name: ${clusterName}-node-${index} - spec: - containers: - - name: db - image: nginx:latest -``` diff --git a/website/docs/docs/concepts/30-conditionals.mdx b/website/docs/docs/concepts/30-conditionals.mdx deleted file mode 100644 index f49058b3..00000000 --- a/website/docs/docs/concepts/30-conditionals.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 30 ---- - -# 5. Conditionals diff --git a/website/docs/docs/concepts/40-imports.mdx b/website/docs/docs/concepts/40-imports.mdx deleted file mode 100644 index 354894eb..00000000 --- a/website/docs/docs/concepts/40-imports.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 40 ---- - -# 6. Imports - -Imports ... \ No newline at end of file diff --git a/website/docs/docs/concepts/50-validation.mdx b/website/docs/docs/concepts/50-validation.mdx deleted file mode 100644 index 9acf7dad..00000000 --- a/website/docs/docs/concepts/50-validation.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 40 ---- - -# 7. Validation - -Validation \ No newline at end of file diff --git a/website/docs/docs/concepts/60-managing-state.mdx b/website/docs/docs/concepts/60-managing-state.mdx deleted file mode 100644 index 49251aec..00000000 --- a/website/docs/docs/concepts/60-managing-state.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 40 ---- - -# 8. Managing State - -Validation \ No newline at end of file diff --git a/website/docs/docs/concepts/_category_.json b/website/docs/docs/concepts/_category_.json index 8727ac2d..d29b57ce 100644 --- a/website/docs/docs/concepts/_category_.json +++ b/website/docs/docs/concepts/_category_.json @@ -2,7 +2,8 @@ "label": "Concepts", "position": 40, "link": { - "type": "generated-index", "description": "Learn about the core concepts of KRO" - } + }, + "collapsible": true, + "collapsed": false } diff --git a/website/docs/docs/getting-started/_category_.json b/website/docs/docs/getting-started/_category_.json index 3fa7b957..723093d1 100644 --- a/website/docs/docs/getting-started/_category_.json +++ b/website/docs/docs/getting-started/_category_.json @@ -1,7 +1,6 @@ { "label": "Getting started", "position": 20, - "link": { - "type": "generated-index" - } + "collapsible": true, + "collapsed": false } diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 457318de..30575751 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -46,6 +46,7 @@ const config: Config = { label: "latest", }, }, + // sidebarCollapsed: false, // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: @@ -65,7 +66,7 @@ const config: Config = { docs: { sidebar: { hideable: false, - autoCollapseCategories: true, + autoCollapseCategories: false, }, }, navbar: { @@ -160,8 +161,8 @@ const config: Config = { textColor: "white", }, */ prism: { - theme: prismThemes.github, - darkTheme: prismThemes.github, + theme: prismThemes.oneLight, + darkTheme: prismThemes.oneDark, additionalLanguages: ["bash", "yaml"], }, } satisfies Preset.ThemeConfig,