feat: added documentation highlighting how to play around with cdk8s …

.github/workflows/golangci-lint.yml

@@ -27,6 +27,5 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 # tag=v8.0.0
         with:
-          version: v2.1.6
           working-directory: ${{matrix.working-directory}}
           args: --timeout=5m

examples/cdk8s-sample-deployment/KUBERNETES_GUIDE.md

@@ -0,0 +1,95 @@
+# Kubernetes Guide - CDK8s Go Example
+
+## What This Example Creates
+
+### 1. Kubernetes Deployment
+
+The Go code generates a **Deployment** that:
+- Runs 1 instance of nginx
+- Manages high availability
+- Automatically restarts on failure
+
+### 2. Pod Template
+
+Each pod contains:
+- **Container**: nginx:1.19.10
+- **Port**: 80 (HTTP)
+- **Labels**: app=my-app
+
+## Understanding the Go Code
+
+### NewChart Function
+```go
+func NewChart(scope constructs.Construct, id string, ns string, appLabel string) cdk8s.Chart
+```
+- Creates a CDK8s "chart" (group of resources)
+- Parameters: scope, id, namespace, label
+
+### Deployment Creation
+```go
+k8s.NewKubeDeployment(chart, jsii.String("deployment"), &k8s.KubeDeploymentProps{
+    Spec: &k8s.DeploymentSpec{
+        Replicas: jsii.Number(1),  // 1 instance
+        // ... configuration ...
+    },
+})
+```
+
+## Complete Workflow
+
+1. **Go Code** → Defines the application
+2. **cdk8s synth** → Generates Kubernetes YAML
+3. **kubectl apply** → Deploys to cluster
+4. **Port-forward** → Local access
+
+## Understanding the Generated YAML
+
+### Deployment Spec
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: getting-started-deployment-c80c7257
+  namespace: default
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - image: nginx:1.19.10
+          name: app-container
+          ports:
+            - containerPort: 80
+```
+
+## Troubleshooting
+
+### Application won't start
+```bash
+kubectl describe pod <pod-name>
+kubectl logs <pod-name>
+```
+
+### Port-forward not working
+```bash
+kubectl get pods
+kubectl port-forward deployment/<deployment-name> 8080:80
+```
+
+### Manifest not generated
+```bash
+cdk8s synth
+ls -la dist/
+```
+
+### Check deployment status
+```bash
+kubectl get deployments
+kubectl describe deployment getting-started-deployment-<hash>
+```

examples/cdk8s-sample-deployment/README.md

@@ -0,0 +1,63 @@
+# CDK8s Sample Deployment - Go
+
+## Quick Start
+
+This example demonstrates how to create and deploy a Kubernetes application using CDK8s in Go.
+
+### Prerequisites
+- Go 1.19+
+- CDK8s CLI (`npm install -g cdk8s-cli`)
+- kubectl
+- Kubernetes cluster (minikube, kind, or Docker Desktop)
+
+### Deploy in 3 Steps
+
+```bash
+# 1. Install dependencies
+go mod tidy
+
+# 2. Generate Kubernetes manifests
+cdk8s synth
+
+# 3. Deploy to your cluster
+kubectl apply -f dist/
+```
+
+### Verify Deployment
+
+```bash
+# View deployments
+kubectl get deployments
+
+# View pods
+kubectl get pods
+
+# Access the application
+kubectl port-forward deployment/getting-started-deployment-<hash> 8080:80
+```
+
+Open http://localhost:8080 in browser.
+
+Check out [KUBERNETES_GUIDE.md](./KUBERNETES_GUIDE.md) for detailed explanations of the concepts used in this example.
+
+## Project Structure
+
+- `main.go` - CDK8s code that defines the application
+- `cdk8s.yaml` - CDK8s configuration
+- `dist/` - Generated Kubernetes manifests
+- `imports/k8s/` - Generated Go types for Kubernetes
+
+## Kubernetes Resources Created
+
+- **Deployment**: `getting-started-deployment-<hash>`
+    - 1 replica
+    - Image: nginx:1.19.10
+    - Port: 80
+    - Labels: app=my-app
+
+## Cleanup
+
+Remove the application
+```bash
+kubectl delete -f dist/
+```

examples/cdk8s-sample-deployment/go.mod

@@ -3,24 +3,23 @@ module example.com/cdk8s-test
 go 1.24.4
 
 require (
-	github.com/aws/constructs-go/constructs/v10 v10.3.0
-	github.com/aws/jsii-runtime-go v1.98.0
-	github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.68.70
+	github.com/aws/constructs-go/constructs/v10 v10.4.2
+	github.com/aws/jsii-runtime-go v1.114.1
+	github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.70.15
 )
 
 require (
-	github.com/Masterminds/semver/v3 v3.3.1 // indirect
+	github.com/Masterminds/semver/v3 v3.4.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/fatih/color v1.18.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
-	github.com/stretchr/testify v1.10.0 // indirect
 	github.com/yuin/goldmark v1.4.13 // indirect
 	golang.org/x/lint v0.0.0-20210508222113-6edffad5e616 // indirect
-	golang.org/x/mod v0.24.0 // indirect
-	golang.org/x/sync v0.14.0 // indirect
-	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/tools v0.33.0 // indirect
+	golang.org/x/mod v0.27.0 // indirect
+	golang.org/x/sync v0.16.0 // indirect
+	golang.org/x/sys v0.35.0 // indirect
+	golang.org/x/tools v0.36.0 // indirect
 )

examples/cdk8s-sample-deployment/go.sum

@@ -1,11 +1,11 @@
-github.com/Masterminds/semver/v3 v3.3.1 h1:QtNSWtVZ3nBfk8mAOu/B6v7FMJ+NHTIgUPi7rj+4nv4=
-github.com/Masterminds/semver/v3 v3.3.1/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
-github.com/aws/constructs-go/constructs/v10 v10.3.0 h1:LsjBIMiaDX/vqrXWhzTquBJ9pPdi02/H+z1DCwg0PEM=
-github.com/aws/constructs-go/constructs/v10 v10.3.0/go.mod h1:GgzwIwoRJ2UYsr3SU+JhAl+gq5j39bEMYf8ev3J+s9s=
-github.com/aws/jsii-runtime-go v1.98.0 h1:ulW8WgW9xchCkGc8SBKSQwpm+4/MwoFkYuCsOD8NnMU=
-github.com/aws/jsii-runtime-go v1.98.0/go.mod h1:30XYoqvHizeedL8KNra3DBZ9w+NtJDQpbU4o1bN9lVc=
-github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.68.70 h1:0sS7tHQraB3OtVpS6IElkwwb0XJcCIapo6brFs3IGoQ=
-github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.68.70/go.mod h1:Pkx19GlJctsR6wchtjV81yKCwdj4K/i+5dRKt6i4HTw=
+github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
+github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/aws/constructs-go/constructs/v10 v10.4.2 h1:+hDLTsFGLJmKIn0Dg20vWpKBrVnFrEWYgTEY5UiTEG8=
+github.com/aws/constructs-go/constructs/v10 v10.4.2/go.mod h1:cXsNCKDV+9eR9zYYfwy6QuE4uPFp6jsq6TtH1MwBx9w=
+github.com/aws/jsii-runtime-go v1.114.1 h1:Js3HVbe5k+HiCxc2rqkuNhcpw9RK8T5/PWzWyeu81Vs=
+github.com/aws/jsii-runtime-go v1.114.1/go.mod h1:67f+oydH0cMr//tkmNNj9QpKk02hNEEVu4CByxkpGB0=
+github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.70.15 h1:xAF64IjIS3NpZGSm4yjcvyrJXvpVTnYuOD5PSH0N2gA=
+github.com/cdk8s-team/cdk8s-core-go/cdk8s/v2 v2.70.15/go.mod h1:ECTLtKJGhV23Oh28jXqusLUTAAZe6oYU6ij1F9xe3qs=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
@@ -19,31 +19,32 @@ github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWE
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
-github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/yuin/goldmark v1.4.13 h1:fVcFKWvrslecOb/tg+Cc05dkeYx540o0FuFt3nUVDoE=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/lint v0.0.0-20210508222113-6edffad5e616 h1:VLliZ0d+/avPrXXH+OakdXhpJuEoBZuwh1m2j7U6Iug=
 golang.org/x/lint v0.0.0-20210508222113-6edffad5e616/go.mod h1:3xt1FjdF8hUf6vQPIChWIBhFzV8gjjsPE/fR3IyQdNY=
 golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
-golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU=
-golang.org/x/mod v0.24.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
+golang.org/x/mod v0.27.0 h1:kb+q2PyFnEADO2IEF935ehFUXlWiNjJWtRNgBLSfbxQ=
+golang.org/x/mod v0.27.0/go.mod h1:rWI627Fq0DEoudcK+MBkNkCe0EetEaDSwJJkCcjpazc=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ=
-golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/sync v0.16.0 h1:ycBJEhp9p4vXvUZNszeOq0kGTPghopOL8q0fq3vstxw=
+golang.org/x/sync v0.16.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
-golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/sys v0.35.0 h1:vz1N37gP5bs89s7He8XuIYXpyY0+QlsKmzipCbUtyxI=
+golang.org/x/sys v0.35.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
-golang.org/x/tools v0.33.0 h1:4qz2S3zmRxbGIhDIAgjxvFutSvH5EfnsYrRBj0UI0bc=
-golang.org/x/tools v0.33.0/go.mod h1:CIJMaWEY88juyUfo7UbgPqbC8rU2OqfAV1h2Qp0oMYI=
+golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
+golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=