Add a getting started doc for swck (#100)

CHANGES.md

@@ -5,6 +5,9 @@ Release Notes.
 0.9.0
 ------------------
 
+#### Features
+- Add a getting started document about how to deploy swck on the kubernetes cluster.
+
 #### Bugs
 
 - Fix the bug that the java agent is duplicated injected when update the pod.

README.md

@@ -21,9 +21,7 @@ SWCK is a platform for the SkyWalking user that provisions, upgrades, maintains
 
 # Quick Start
 
-There are two ways to install swck.
-* Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) to download the latest release binary, `skywalking-swck-<SWCK_VERSION>-bin.tgz`. Unarchive the package to a folder named `skywalking-swck-<SWCK_VERSION>-bin`
-* Apply the kustomization directory from github.
+You can follow the [Getting Started](docs/getting-started.md) to deploy swck on a testing Kubernetes cluster quickly and try out the skywalking components end to end.
 
 ## Java Agent Injector
 

docs/getting-started.md

@@ -0,0 +1,371 @@
+## Getting Started
+
+This document introduces how to create a kubernetes cluster locally using kind and how to deploy the basic skywalking components to the cluster.
+
+### Prerequisites
+- [docker](https://docs.docker.com/get-docker/) >= v20.10.6
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) >= v1.21.0
+- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) >= v0.20.0
+- [swctl](https://github.com/apache/skywalking-cli?tab=readme-ov-file#install) >= v0.10.0
+
+### Step1: Create a kubernetes cluster locally using kind
+
+> Note: If you have a kubernetes cluster (> v1.21.10) already, you can skip this step.
+
+Here we create a kubernetes cluster with 1 control-plane node and 1 worker nodes.
+
+```shell
+$ cat <<EOF | kind create cluster --config=-
+kind: Cluster
+apiVersion: kind.x-k8s.io/v1alpha4
+nodes:
+- role: control-plane
+ image: kindest/node:v1.21.10
+- role: worker
+ image: kindest/node:v1.21.10
+EOF
+```
+
+<details>
+ <summary>Expected output</summary>
+
+```shell
+Creating cluster "kind" ...
+ ✓ Ensuring node image (kindest/node:v1.21.10) 🖼
+ ✓ Preparing nodes 📦 📦
+ ✓ Writing configuration 📜
+ ✓ Starting control-plane 🕹️
+ ✓ Installing CNI 🔌
+ ✓ Installing StorageClass 💾
+ ✓ Joining worker nodes 🚜
+Set kubectl context to "kind-kind"
+You can now use your cluster with:
+
+kubectl cluster-info --context kind-kind
+
+Not sure what to do next? 😅 Check out https://kind.sigs.k8s.io/docs/user/quick-start/
+```
+</details>
+
+Check all pods in the cluster.
+
+```shell
+$ kubectl get pods -A
+```
+
+<details>
+ <summary>Expected output</summary>
+
+```shell
+NAMESPACE NAME READY STATUS RESTARTS AGE
+kube-system coredns-558bd4d5db-h5gxt 1/1 Running 0 106s
+kube-system coredns-558bd4d5db-lhnvz 1/1 Running 0 106s
+kube-system etcd-kind-control-plane 1/1 Running 0 116s
+kube-system kindnet-fxlkm 1/1 Running 0 106s
+kube-system kindnet-vmcvl 1/1 Running 0 91s
+kube-system kube-apiserver-kind-control-plane 1/1 Running 0 116s
+kube-system kube-controller-manager-kind-control-plane 1/1 Running 0 116s
+kube-system kube-proxy-nr4f4 1/1 Running 0 91s
+kube-system kube-proxy-zl4h2 1/1 Running 0 106s
+kube-system kube-scheduler-kind-control-plane 1/1 Running 0 116s
+local-path-storage local-path-provisioner-74567d47b4-kmtjh 1/1 Running 0 106s
+```
+</details>
+
+### Step2: Build the operator image
+
+Check into the root directory of SWCK and build the operator image as follows.
+
+```shell
+$ cd operator
+# Build the operator image
+$ make docker-build
+```
+
+You will get the operator image `controller:latest` as follows.
+
+```shell
+$ docker images 
+REPOSITORY TAG IMAGE ID CREATED SIZE
+controller latest 84da7509092a 22 seconds ago 53.6MB
+```
+
+Load the operator image into the kind cluster or push the image to a registry that
+your kubernetes cluster can access.
+
+```shell
+$ kind load docker-image controller
+```
+or
+```shell
+$ docker push $(YOUR_REGISTRY)/controller
+```
+
+### Step3: Deploy operator on the kubernetes cluster
+
+Install the CRDs as follows.
+
+```shell
+$ make install
+```
+
+Check the CRDs are installed successfully.
+
+<details>
+ <summary>Expected output</summary>
+
+```shell
+kubectl get crd | grep skywalking
+banyandbs.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+fetchers.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+javaagents.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+oapserverconfigs.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+oapserverdynamicconfigs.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+oapservers.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+satellites.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+storages.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+swagents.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+uis.operator.skywalking.apache.org 2023-11-05T03:30:43Z
+```
+</details>
+
+Deploy the SWCK operator to the cluster.
+
+```shell
+$ make deploy
+```
+
+Or deploy the SWCK operator to the cluster with your own image.
+
+```shell
+$ make deploy OPERATOR_IMG=$(YOUR_REGISTRY)/controller
+```
+
+Get the status of the SWCK operator pod.
+
+```shell
+$ kubectl get pod -n skywalking-swck-system
+NAME READY STATUS RESTARTS AGE
+skywalking-swck-controller-manager-5f5bbd4fd-9wdw6 2/2 Running 0 34s
+```
+
+### Step4: Deploy skywalking componentes on the kubernetes cluster
+
+Create the `skywalking-system` namespace.
+
+```shell
+$ kubectl create namespace skywalking-system
+```
+
+Deploy the skywalking components to the cluster.
+
+```shell
+$ cat <<EOF | kubectl apply -f -
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: OAPServer
+metadata:
+ name: skywalking-system
+ namespace: skywalking-system
+spec:
+ version: 9.5.0
+ instances: 1
+ image: apache/skywalking-oap-server:9.5.0
+ service:
+ template:
+ type: ClusterIP
+---
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: UI 
+metadata:
+ name: skywalking-system
+ namespace: skywalking-system
+spec:
+ version: 9.5.0
+ instances: 1
+ image: apache/skywalking-ui:9.5.0
+ OAPServerAddress: http://skywalking-system-oap.skywalking-system:12800
+ service:
+ template:
+ type: ClusterIP
+ ingress:
+ host: demo.ui.skywalking
+EOF
+```
+
+Check the status of the skywalking components.
+
+```shell
+$ kubectl get pod -n skywalking-system 
+NAME READY STATUS RESTARTS AGE
+skywalking-system-oap-68bd877f57-fhzdz 1/1 Running 0 6m23s
+skywalking-system-ui-6db8579b47-rphtl 1/1 Running 0 6m23s
+```
+
+### Step5: Use the java agent injector to inject the java agent into the application pod
+
+Label the namespace where the application pod is located with `swck-injection=enabled`.
+
+```shell
+$ kubectl label namespace skywalking-system swck-injection=enabled
+```
+
+Create the application pod.
+
+> Note: The application pod must be labeled with `swck-java-agent-injected=true` and the `agent.skywalking.apache.org/collector.backend_service` annotation must be set to the address of the OAP server. For more configurations, please refer to the [guide](./java-agent-injector.md#use-annotations-to-overlay-default-agent-configuration). 
+
+```shell
+$ cat <<EOF | kubectl apply -f -
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: demo
+ namespace: skywalking-system
+spec:
+ selector:
+ matchLabels:
+ app: demo
+ template:
+ metadata:
+ labels:
+ # enable the java agent injector
+ swck-java-agent-injected: "true"
+ app: demo
+ annotations:
+ agent.skywalking.apache.org/collector.backend_service: "skywalking-system-oap.skywalking-system:11800"
+ spec:
+ containers:
+ - name: demo1
+ imagePullPolicy: IfNotPresent
+ image: ghcr.io/apache/skywalking-swck-spring-demo:v0.0.1
+ command: ["java"]
+ args: ["-jar","/app.jar"]
+ ports:
+ - containerPort: 8085
+ readinessProbe:
+ httpGet:
+ path: /hello
+ port: 8085
+ initialDelaySeconds: 3
+ periodSeconds: 3
+ failureThreshold: 10
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: demo
+ namespace: skywalking-system
+spec:
+ type: ClusterIP
+ ports:
+ - name: 8085-tcp
+ port: 8085
+ protocol: TCP
+ targetPort: 8085
+ selector:
+ app: demo
+EOF
+```
+
+Check the status of the application pod and make
+sure the java agent is injected into the application pod.
+
+
+```shell
+$ kubectl get pod -n skywalking-system -l app=demo -ojsonpath='{.items[0].spec.initContainers[0]}'
+```
+
+<details>
+ <summary>Expected output</summary>
+
+```shell
+{"args":["-c","mkdir -p /sky/agent \u0026\u0026 cp -r /skywalking/agent/* /sky/agent"],"command":["sh"],"image":"apache/skywalking-java-agent:8.16.0-java8","imagePullPolicy":"IfNotPresent","name":"inject-skywalking-agent","resources":{},"terminationMessagePath":"/dev/termination-log","terminationMessagePolicy":"File","volumeMounts":[{"mountPath":"/sky/agent","name":"sky-agent"},{"mountPath":"/var/run/secrets/kubernetes.io/serviceaccount","name":"kube-api-access-4qk26","readOnly":true}]}
+```
+</details>
+
+Also, you could check the final java agent configurations with the following command.
+
+```shell
+$ kubectl get javaagent -n skywalking-system -l app=demo -oyaml
+```
+
+<details>
+ <summary>Expected output</summary>
+
+```shell
+apiVersion: v1
+items:
+- apiVersion: operator.skywalking.apache.org/v1alpha1
+ kind: JavaAgent
+ metadata:
+ creationTimestamp: "2023-11-19T05:34:03Z"
+ generation: 1
+ labels:
+ app: demo
+ name: app-demo-javaagent
+ namespace: skywalking-system
+ ownerReferences:
+ - apiVersion: apps/v1
+ blockOwnerDeletion: true
+ controller: true
+ kind: ReplicaSet
+ name: demo-75d8d995cc
+ uid: 8cb64abc-9b50-4f67-9304-2e09de476168
+ resourceVersion: "21515"
+ uid: 6cbafb3d-9f43-4448-95e8-bda1f7c72bc3
+ spec:
+ agentConfiguration:
+ collector.backend_service: skywalking-system-oap.skywalking-system:11800
+ optional-plugin: webflux|cloud-gateway-2.1.x
+ backendService: skywalking-system-oap.skywalking-system:11800
+ podSelector: app=demo
+ serviceName: Your_ApplicationName
+ status:
+ creationTime: "2023-11-19T05:34:03Z"
+ expectedInjectiedNum: 1
+ lastUpdateTime: "2023-11-19T05:34:46Z"
+ realInjectedNum: 1
+kind: List
+metadata:
+ resourceVersion: ""
+ selfLink: ""
+```
+</details>
+
+If you want to check the logs of the java agent, you can run the following command.
+
+```shell
+$ kubectl logs -f -n skywalking-system -l app=demo -c inject-skywalking-agent
+```
+
+
+### Step6: Check the application metrics in the skywalking UI
+
+First, port-forward the demo service to your local machine.
+
+```shell
+$ kubectl port-forward svc/demo 8085:8085 -n skywalking-system
+```
+
+Then, trigger the application to generate some metrics.
+
+```shell
+$ for i in {1..10}; do curl http://127.0.0.1:8085/hello && echo ""; done
+```
+
+After that, you can port-forward the skywalking UI to your local machine.
+
+```shell
+$ kubectl port-forward svc/skywalking-system-ui 8080:80 -n skywalking-system
+```
+
+Open the skywalking UI in your browser and navigate to `http://127.0.0.1:8080` to check the application metrics.
+
+<details>
+ <summary>Expected output</summary>
+
+![ui](https://skywalking.apache.org/doc-graph/swck/demo-ui.png)
+</details>
+
+
+Also, if you want to expose the external metrics to the kubernetes HPA, you can follow the [guide](./custom-metrics-adapter.md) to deploy the custom metrics adapter and you may get some inspiration from the 
+[e2e test](../test/e2e/oap-agent-adapter-hpa/e2e.yaml).