Skip to content

Commit 966d4be

Browse files
a-hilalya-hilaly
authored
Merge pull request #253 from barney-s/docs-examples
Update website/docs/examples to split into sections and include gcp examples
2 parents f40bd51 + 95b8131 commit 966d4be

24 files changed

+724
-141
lines changed

‎examples/gcp/cloud-sql/README.md‎

Lines changed: 30 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,53 @@
1-
# CloudSQL example
1+
# CloudSQL
22

3-
This example creates a ResourceGraphDefinition called `CloudSQL` to deploy Cloud SQL instance in 2 regions as a primary replica pair.
3+
This example show how you can use KRO to deploy GCP Cloud SQL instance in 2 regions as a primary and replica instances.
44

5-
## Create ResourceGraphDefinitions
65

7-
Apply the RGD to your cluster:
6+
## End User: CloudSQL
7+
The administrator needs to install the RGD first.
8+
The end user creates a `CloudSQL` resource that looks like this:
89

10+
```yaml
11+
apiVersion: kro.run/v1alpha1
12+
kind: CloudSQL
13+
metadata:
14+
name: demo
15+
namespace: config-connector
16+
spec:
17+
name: demo
18+
project: my-gcp-project
19+
primaryRegion: us-central1
20+
replicaRegion: us-west1
921
```
10-
kubectl apply -f rgd.yaml
11-
```
12-
13-
Validate the RGD:
1422
15-
```
16-
> kubectl get rgd cloudsql.kro.run
17-
NAME APIVERSION KIND STATE AGE
18-
cloudsql.kro.run v1alpha1 CloudSQL Active 44m
19-
```
23+
The status of the applied resource can be checked using:
2024
21-
## Create an Instance of CloudSQL
22-
Set the env variables used in the instance template:
2325
```
24-
export CLOUDSQL_NAME=demo
25-
export GCP_PROJECT=myproject
26-
export PRIMARY_REGION=us-central1
27-
export REPLICA_REGION=us-west1
26+
kubectl get cloudsqls
27+
kubectl get cloudsql demo -n config-connector -o yaml
2828
```
2929

30-
Run the following command to replace the env variables in `instance-template.yaml` file and create
31-
a new file called instance.yaml.
32-
```shell
33-
envsubst < "instance-template.yaml" > "instance.yaml"
34-
```
30+
Navigate to CloudSQL page in the GCP Console and verify the creation of primary and replica instances.
3531

36-
Apply the `instance.yaml`
32+
Once done, the user can delete the `CloudSQL` instance:
3733

3834
```
39-
kubectl apply -f instance.yaml
35+
kubectl delete cloudsql demo -n config-connector
4036
```
4137

42-
Validate instance status:
38+
## Administrator: ResourceGraphDefinition
39+
The administrator needs to install the RGD in the cluster first before the user can consume it:
4340

4441
```
45-
kubectl get cloudsqls
42+
kubectl apply -f rgd.yaml
4643
```
4744

48-
## Validate
49-
50-
Navigate to CloudSQL page in the GCP Console and verify the creation of primary and replica instances.
51-
52-
## Clean up
53-
54-
Remove the instance:
45+
Validate the RGD is installed correctly:
5546

5647
```
57-
kubectl delete cloudsql $CLOUDSQL_NAME
48+
> kubectl get rgd cloudsql.kro.run
49+
NAME APIVERSION KIND STATE AGE
50+
cloudsql.kro.run v1alpha1 CloudSQL Active 44m
5851
```
5952

60-
Remove the ResourceGraphDefinitions:
61-
62-
```
63-
kubectl delete rgd cloudsql.kro.run
64-
```
53+
Once all user created instances are deleted, the administrator can choose to deleted the RGD.

‎examples/gcp/cloud-sql/instance-template.yaml‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎examples/gcp/gke-cluster/README.md‎

Lines changed: 26 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# GKE cluster definition
1+
# GKECluster
22

33
A **Platform Administrator** wants to give end users in their organization self-service access to create GKE clusters. The platform administrator creates a kro ResourceGraphDefinition called *gkecluster.kro.run* that defines the required Kubernetes resources and a CRD called *GKEcluster* that exposes only the options they want to be configurable by end users. The ResourceGraphDefinition would define the following resources (using [KCC](https://github.com/GoogleCloudPlatform/k8s-config-connector) to provide the mappings from K8s CRDs to Google Cloud APIs):
44

@@ -9,74 +9,53 @@ A **Platform Administrator** wants to give end users in their organization self-
99
* KMSKeyRing - Encrypt BootDisk
1010
* KMSCryptoKey - Encrypt BootDisk
1111

12-
The platform administrator would define the schema for `GKECluster` CRD which the end user creates:
13-
* name: same for all GCP resources created
14-
* location: region to be used for the GCP resources
15-
* maxnodes: Max scaling limit for the nodes in the node pool
16-
1712
Everything related to these resources would be hidden from the end user, simplifying their experience.
1813

1914
![GKE Cluster Stack](gke-cluster.png)
2015

16+
## End User: GKECluster
2117

22-
# GKECluster example
23-
24-
This example creates a ResourceGraphDefinition called `GKECluster` to deploy a GKE cluster.
25-
26-
## Create ResourceGraphDefinitions
18+
The administrator needs to install the RGD first.
19+
The end user creates a `GKECluster` resource something like this:
2720

28-
Apply the RGD to your cluster:
29-
30-
```
31-
kubectl apply -f rgd.yaml
21+
```yaml
22+
apiVersion: kro.run/v1alpha1
23+
kind: GKECluster
24+
metadata:
25+
name: krodemo
26+
namespace: config-connector
27+
spec:
28+
name: krodemo # Name used for all resources created as part of this RGD
29+
location: us-central1 # Region where the GCP resources are created
30+
maxnodes: 4 # Max scaling limit for the nodes in the new nodepool
3231
```
3332
34-
Validate the RGD:
33+
They can then check the status of the applied resource:
3534
3635
```
37-
kubectl get rgd
36+
kubectl get gkeclusters
37+
kubectl get gkeclusters krodemo -n config-connector -o yaml
3838
```
3939

40-
## Create an Instance of CloudSQL
41-
Set the env variables used in the instance template:
42-
```
43-
export CLUSTER_NAME=krodemo
44-
export GCP_REGION=us-central1
45-
export MAX_NODES=4
46-
```
40+
Navigate to GKE Cluster page in the GCP Console and verify the cluster creation.
4741

48-
Run the following command to replace the env variables in `instance-template.yaml` file and create
49-
a new file called instance.yaml.
50-
```shell
51-
envsubst < "instance-template.yaml" > "instance.yaml"
52-
```
53-
54-
Apply the `instance.yaml`
42+
Once done, the user can delete the `GKECluster` instance:
5543

5644
```
57-
kubectl apply -f instance.yaml
45+
kubectl delete gkecluster krodemo -n config-connector
5846
```
5947

60-
Validate instance status:
48+
## Administrator: ResourceGraphDefinition
49+
The administrator needs to install the RGD in the cluster first before the user can consume it:
6150

6251
```
63-
kubectl get gkeclusters
52+
kubectl apply -f rgd.yaml
6453
```
6554

66-
## Validate
67-
68-
Navigate to GKE Cluster page in the GCP Console and verify the cluster.
69-
70-
## Clean up
71-
72-
Remove the instance:
55+
Validate the RGD is installed correctly:
7356

7457
```
75-
kubectl delete gkecluster $CLUSTER_NAME
58+
kubectl get rgd gkecluster.kro.run
7659
```
7760

78-
Remove the ResourceGraphDefinitions:
79-
80-
```
81-
kubectl delete rgd gkecluster.kro.run
82-
```
61+
Once all user created instances are deleted, the administrator can choose to deleted the RGD.

‎examples/gcp/gke-cluster/instance-template.yaml‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎scripts/update-doc-examples.sh‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/bin/bash
2+
3+
create_example() {
4+
out_file=$1
5+
position=$2
6+
readme_file=$3
7+
rgd_file=$4
8+
9+
# Verify all parameters are valid
10+
if [ -z "$out_file" ] || [ -z "$position" ] || [ -z "$readme_file" ] || [ -z "$rgd_file" ]; then
11+
echo "Error: Missing required parameters"
12+
echo "Usage: create_example <out_file> <position> <readme_file> <rgd_file>"
13+
return 1
14+
fi
15+
16+
17+
cat > "$out_file" << EOF
18+
---
19+
sidebar_position: $position
20+
---
21+
22+
$(cat $readme_file)
23+
24+
<details>
25+
<summary>ResourceGraphDefinition</summary>
26+
\`\`\`yaml title="rgd.yaml"
27+
$(cat "$yaml_file")
28+
\`\`\`
29+
</details>
30+
EOF
31+
32+
}
33+
34+
update_gcp_example_docs() {
35+
# Create the GCP examples directory if it doesn't exist
36+
mkdir -p website/docs/examples/gcp
37+
# Initialize position counter
38+
position=405
39+
# Find all rgd.yaml files in examples/gcp directory and its subdirectories
40+
find examples/gcp -name "rgd.yaml" | while read -r yaml_file; do
41+
# Extract the directory name as the example name
42+
example_path=$(dirname "$yaml_file")
43+
dir_name=$(basename $example_path)
44+
readme_file=$example_path/README.md
45+
out_file="website/docs/examples/gcp/${dir_name}.md"
46+
47+
# Convert directory name to title case (e.g., gke-cluster -> GKE Cluster)
48+
# title=$(echo "$dir_name" | sed -E 's/-/ /g' | awk '{for(i=1;i<=NF;i++)sub(/./,toupper(substr($i,1,1)),$i)}1')
49+
50+
# copy all images
51+
cp $example_path/*.png website/docs/examples/gcp/ 2>/dev/null
52+
# Generate the markdown content
53+
create_example "$out_file" "$position" "$readme_file" "$yaml_file"
54+
55+
# Increment position for next file
56+
((position+=1))
57+
58+
echo "Generated documentation for ${dir_name} at ${out_file}"
59+
done
60+
}
61+
62+
update_aws_example_docs() {
63+
echo "TODO: implement aws examples"
64+
}
65+
update_azure_example_docs() {
66+
echo "TODO: implement azure examples"
67+
}
68+
update_kubernetes_example_docs() {
69+
echo "TODO: implement kubernetes examples"
70+
}
71+
72+
update_gcp_example_docs
73+
update_aws_example_docs
74+
update_azure_example_docs
75+
update_kubernetes_example_docs

website/docs/examples/ack-eks-cluster.md renamed to website/docs/examples/aws/ack-eks-cluster.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 10
2+
sidebar_position: 302
33
---
44

55
# EKS Cluster

website/docs/examples/ack-networking-stack.md renamed to website/docs/examples/aws/ack-networking-stack.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 10
2+
sidebar_position: 303
33
---
44

55
# Networking Stack

website/docs/examples/ack-valkey-cachecluster.md renamed to website/docs/examples/aws/ack-valkey-cachecluster.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 10
2+
sidebar_position: 304
33
---
44

55
# Valkey cluster

‎website/docs/examples/aws/aws-examples.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
sidebar_position: 301
3+
---
4+
5+
# AWS Examples
6+
- [Deploying a Controller](./deploying-controller.md) Discover how to deploy a
7+
Kubernetes controller using kro ResourceGraphDefinitions, including the necessary
8+
Deployment, ServiceAccount, and CRDs.
9+
10+
- [AWS Networking Stack](./ack-networking-stack.md) Learn how to define and
11+
manage an AWS networking stack using kro ResourceGraphDefinitions, including VPCs,
12+
subnets, and security groups.
13+
14+
- [EKS Cluster with ACK CRDs](./ack-eks-cluster.md) Explore how to define and
15+
manage an EKS cluster using AWS Controllers for Kubernetes (ACK) CRDs within a
16+
kro ResourceGraphDefinition.
17+
18+
- [Valkey CacheCluster with ACK CRDs](./ack-valkey-cachecluster.md) Learn how to
19+
create and configure a Valkey CacheCluster using ACK CRDs in a kro
20+
ResourceGraphDefinition.
21+
22+
- [Pod and RDS DBInstance](./pod-rds-dbinstance.md) Deploy a Pod and an RDS
23+
DBInstance in a kro ResourceGraphDefinition, showcasing the use of multiple resources
24+
with dependencies.

‎website/docs/examples/aws/category.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"label": "AWS Examples",
3+
"position": 300,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Examples of using Kro with AWS"
7+
},
8+
"collapsible": true,
9+
"collapsed": true
10+
}

0 commit comments

Comments
 (0)